---
title: PM Calendar Overlay
---

# PM Calendar Overlay

## What it is

Shows project due dates and sprint timelines on the Google Calendar panel alongside real calendar
events -- read from the local SQLite mirror, not fetched from the cloud. PM items with date or
timeline columns appear as calendar events alongside your Google Calendar entries.

## Where to find it

On the Google Calendar panel, in the same views as your real Google events. Clicking a PM event opens
the ordinary event popover; its PM branch shows the board name and an **Open in PM** button that
navigates to the Mission Control virtual project.

## How it behaves

Each PM event is color-coded by board (deterministic hash of board ID to one of 8 palette colors) and
highlighted when overdue (using the semantic `--status-error-rgb` token).

The overlay is read-only -- PM events have no Edit/Delete actions. The popover's PM branch also shows
an overdue warning when applicable.

PM events are fetched in parallel with Google Calendar events (`Promise.all`). A PM fetch failure
degrades gracefully (empty array) and never breaks Google Calendar display.

### Which items appear, and where they land

Date columns are matched by `json_extract(value,'$.date') BETWEEN rangeStart AND rangeEnd`. Timeline
columns use range overlap. The query filters to the visible calendar window in SQL, so the 500-row cap
bounds only in-window rows. Results are deterministically ordered.

Timelines extending beyond the visible window are clamped to `[rangeStart, rangeEnd]` so they don't
paint across adjacent months.

### Settings

| Key | Type | Default | Effect |
|-----|------|---------|--------|
| `pmCalendarOverlayEnabled` | boolean | true | Master toggle |
| `pmCalendarBoardIds` | string[] | [] | Empty = all boards; non-empty = filter |

Both require `missionControlEnabled` to be true.

## For agents

- Contract: `pm-calendar-overlay-contract.md`.

## Related

The dates and timelines the overlay paints come from [mission-control.md](mission-control.md), the
project-management system this panel reads from. If the items behind an entry are not what you expect,
[pm-my-work.md](pm-my-work.md) is the cross-board personal task view built on the same items, and
[pm-sprints.md](pm-sprints.md) explains the sprint timelines that show up here. Adding a date quickly
from outside the board is covered by [calendar-quick-add.md](calendar-quick-add.md). Every page in this
library is listed in [INDEX.md](INDEX.md).