joplin-plugin-gtd-calendar/SPEC.md

GTD Calendar — Project Specification

Status: living document, current through v0.5.0. Sections 1–5 describe the shipped design; §9 tracks what's still ahead.

A fork of WeMakeMachines/joplin-plugin-event-calendar (MIT) that inverts the plugin's data model: instead of events living as YAML inside the calendar note, the plugin's views are populated by real Joplin notes and todos in the surrounding folder tree, with clickable drilldown to the source note. What started as a single calendar view has grown into three composable views — calendar, kanban, and a priorities matrix — sharing one data layer and one tag/date vocabulary.

Package name: joplin-plugin-gtd-calendar (npm) Manifest id: com.victorwiebe.joplin.plugin.gtd-calendar

---

1. Concept

A note anywhere in a folder contains a ```gtd-calendar fenced block. That block renders as a Day/Week/Month calendar populated by notes and todos in scope. Items opt in (by default) via a ```gtd fenced block in their body. Clicking a calendar event opens the underlying note.

Dateless items are not lost — they collect in an Unscheduled section below the calendar grid, functioning as a GTD next-actions / someday-maybe bucket.

---

2. Schema Reference

2.1 The gtd-calendar block (lives in the calendar note)

```gtd-calendar
view: month            # day | week | month | month-grid   (default: day)
title: Editorial Schedule
scope: this-folder     # this-folder | children | <integer depth> | all   (default: this-folder)
notebook: Work/Ideas   # notebook name | Parent/Child path | folder id   (default: this note's folder)
notes: gtd-only        # gtd-only | all | none     (default: gtd-only)
todos: gtd-only        # gtd-only | all | none     (default: gtd-only)
sort: asc              # asc | desc                (default: asc)
sort-type: title       # title | modified_date    (default: title)

Key	Values	Default	Notes
view	day, week, month (also d/w/m), month-grid (also grid)	day	Grouping granularity. day/week/month render the compact tile strip spanning all events; month-grid renders a classic 7-column grid of the entire current calendar month with weekday headers, dimmed adjacent-month days, today highlighted, and clickable event chips in each day cell. Events outside the displayed month are counted in a footnote.
title	string	none	Rendered as a heading above the calendar.
scope	this-folder, children, an integer, or all	this-folder	children = unlimited recursion into subfolders. An integer n = this folder plus n levels of descendants (0 ≡ this-folder). all = every notebook in the profile, ignoring the root folder and tree position entirely — an explicit, deliberately expensive opt-in for a global dashboard. Guardrails: the stats footnote reports scanned notebooks/notes and is marked scope: all; a soft ⚠ warning appears when more than ~2000 notes are scanned (advisory, never blocks). notebook: is ignored under scope: all (with a warning). Documentation cautions that broad scopes scan every note body in the tree.
notebook	notebook title, Parent/Child title path, or 32-char folder id	this note's folder	Roots the folder scan at a chosen notebook, possibly outside the host note's tree; scope then applies relative to it. Resolution order: (1) a raw folder id; (2) a Parent/Child/… case-insensitive title path; (3) a bare title, used only if unique. Any miss — unknown id, unresolvable path, ambiguous or absent title — appends a ⚠ warning and falls back to the host note's own folder (warn-don't-fail).
notes	gtd-only, all, none	gtd-only	Which plain notes participate. all includes notes without a gtd block (they receive default styling and are Unscheduled unless... see §3.2).
todos	gtd-only, all, none	gtd-only	Same semantics for todos.
sort	asc, desc	asc	Order of events within each day/week/month grouping and within Unscheduled. Groupings themselves always run chronologically.
sort-type	title, modified_date	title	Field used by sort. modified_date maps to Joplin's updated_time.
unscheduled-todos	yes/no (also true/false, show/hide)	yes	Whether the Unscheduled to-dos sub-section is shown.
unscheduled-notes	yes/no (also true/false, show/hide)	yes	Whether the Unscheduled notes sub-section is shown. Independent of unscheduled-todos — lets a dashboard split the two lists across stacked calendar blocks instead of duplicating both.

Unscheduled items (no resolvable date) are split into two labelled sub-sections — to-dos first, then notes — each hidden when empty or toggled off.

Unknown keys are ignored with a warning. A malformed block renders an inline warning above the calendar rather than failing silently.

2.2 The gtd block (lives in participating notes/todos)

```gtd
date: 2026-07-04       # required for notes to be scheduled; optional override for todos
bg-colour: teal        # any CSS color value
fg-colour: white
icon: 🦴
title: Override title  # optional; defaults to the note's own title
text: Hover text       # optional; tooltip detail, as upstream

Key	Applies to	Behavior
date	notes	Required for the item to appear in the grid; without it the note goes to Unscheduled. Accepts yyyy-mm-dd (and mm-dd-yyyy for upstream parity).
date	todos	Optional. If present, overrides todo_due (explicit beats implicit).
bg-colour / bgColor	both	Event tile background. Both spellings accepted; bg-colour is canonical for this fork.
fg-colour	both	Event tile text color (new vs. upstream).
icon	both	Emoji/short string, as upstream. Defaults: type indicator (see §4).
title	both	Overrides the note title on the tile.
text	both	Tooltip body.

An empty ```gtd block is valid and meaningful: it is the opt-in signal with all defaults.

2.3 The gtd-kanban block (lives in the board note)

```gtd-kanban
title: Editorial Board
scope: this-folder             # this-folder | children | N | all — same semantics as gtd-calendar
notebook: Work/Ideas           # same semantics as gtd-calendar (default: this note's folder)
todos: gtd-only                # gtd-only | all | none    (default: gtd-only)
sort-type: due-date            # due-date | title | modified-date   (default: due-date)
sort: asc                      # asc | desc                (default: asc)
in-progress-tag: in-progress   # default: "in-progress"
card-detail: hover             # hover | always | none     (default: hover)
done-window: 7                 # days, or "all"             (default: 7)

Three columns, always shown: Backlog, In Progress, Done. To-dos only — plain notes never appear. Bucketing: todo_completed > 0 → Done (wins regardless of tags); else the in-progress-tag → In Progress; else → Backlog. Backlog shows everything uncompleted and untagged, dated or not. Done is filtered to to-dos completed within done-window days (all for full history), preventing unbounded growth. Sorting is per-column; under due-date, cards without a due date sort after all dated ones regardless of direction. Read-only in the current version — reflects to-do state, does not change it.

2.4 The gtd-matrix block (lives in the matrix note)

```gtd-matrix
mode: skeleton                 # skeleton | eisenhower     (default: skeleton)
title: Priorities
scope: this-folder             # this-folder | children | N | all — same semantics as gtd-calendar
notebook: Work/Ideas           # same semantics as gtd-calendar (default: this note's folder)
todos: gtd-only
sort-type: due-date
sort: asc
urgent-tag: urgent             # default: "urgent"
important-tag: important       # Eisenhower mode only; default: "important"
in-progress-tag: in-progress   # Skeleton mode only; default: "in-progress"
urgent-window: 3               # Skeleton mode only, days; default: 3
card-detail: hover

A 2×2 grid with labelled axes. To-dos only; completed to-dos are excluded entirely in both modes (a prioritisation view, not a tracking view — the kanban's Done column is where completions live). The board is internally positional (top-left / top-right / bottom-left / bottom-right); each mode supplies its own axis and quadrant labels.

mode: skeleton (default) — rows = active (in-progress-tag, the same tag the kanban uses); columns = due soon (due date within urgent-window days, overdue included, or the urgent-tag as a manual override for dateless items). Quadrants: Do Next (active + due soon), Scheduled (active, not due soon — includes dateless in-progress work), On Deck (not active + due soon — the early-warning quadrant), Backlog (neither). Designed to complement the calendar and kanban directly: same in-progress tag, dates drive urgency instead of a second opinion-tag, and nothing is ever condemned as "Eliminate" — a Backlog item is simply low priority. In-progress + urgent-tag + no date resolves to Do Next (the urgent tag is an explicit override, so it wins over the absence of a date).

mode: eisenhower — the classic: rows = important-tag; columns = urgent-tag. Quadrants: Do First (both), Schedule (important only), Delegate (urgent only), Eliminate (neither).

A warning is raised if urgent-tag and important-tag resolve to the same tag (Eisenhower mode only — the axes would collapse). Read-only.

2.5 The gtd-gantt block (dual-role: chart and item declaration)

Unlike the other views, gantt items opt in through their own gtd-gantt block rather than the shared gtd block, and every item carries a project: that groups items into swimlanes. The same fence name therefore serves two roles, disambiguated by a single rule:

A gtd-gantt block containing a non-empty project: key is an ITEM declaration; one without is the CHART config block.

The markdown-it content script applies this rule with a cheap line scan (no YAML lib): an item block renders in place as a small inline badge (gantt: <project>) and is never drawn as a chart; a chart block emits the usual webview placeholder. collectGantt applies the identical rule when scanning (empty/whitespace project ⇒ treated as a chart block, i.e. not an item).

Item block (lives in any participating note/todo):

```gtd-gantt
project: bluesky           # REQUIRED — the swimlane; its presence marks this an item
begin-date: 2026-07-01     # notes only — bar span start (yyyy-mm-dd or mm-dd-yyyy)
end-date: 2026-07-14       # notes only — bar span end
bg-colour: teal            # optional styling, mirroring the gtd block
fg-colour: white
title: Design phase        # optional; defaults to the note title
text: Hover detail         # optional; tooltip

| Key | Applies to | Behavior |
|---|---|---|
| `project` | both | Required. Groups the item into a swimlane (case-insensitive; first-seen casing is the display name). Empty/absent ⇒ this is a chart block, not an item. |
| `begin-date` / `end-date` | notes → bars | Both required and valid, `end-date` ≥ `begin-date`, else the item is **excluded with a warning**. |
| (native due date) | todos → milestones | A to-do becomes a ◆ **milestone** on its own `todo_due`. `begin-date`/`end-date` on a to-do are ignored (warning). No due date ⇒ excluded with a warning. |
| `bg-colour`/`fg-colour`/`title`/`text` | both | As the gtd block. Bars default to the stable pastel hash when no colour is set. |

Completed to-do milestones render dimmed and struck through; recurring to-dos get the ↻ mark. There is **no Unscheduled section** — an item with no usable date is simply excluded (the warning explains why).

**Chart block** (lives where the timeline is drawn):

title: Roadmap
scope: children                # this-folder | children | N | all — same semantics as gtd-calendar
notebook: Work/Ideas           # same semantics as gtd-calendar; ignored under scope: all
filter-project: bluesky        # optional — limit to a single project (case-insensitive)
sort-type: begin-date          # begin-date | title | modified-date   (default: begin-date)
sort: asc                      # asc | desc                            (default: asc)
card-detail: hover             # hover | always | none                 (default: hover)

There is deliberately **no `notes`/`todos` inclusion option**: items opt in solely via their `project:` block, so those keys are unknown here (and warn as such). Projects render alphabetically; within each project, rows sort by `sort-type`/`sort`. The renderer draws a month tick header, a "today" line when today falls within the chart's date envelope, and scrolls horizontally for wide ranges. The host note is always excluded from its own scan (as with every view). Bars and milestones are clickable (open the source note); hover detail uses a native tooltip, suppressed by `card-detail: none`. Read-only.

---

## 3. Data Model Rules

### 3.1 Date resolution

1. **Todos:** `todo_due` from the Joplin API. A `date:` in the `gtd` block overrides it.
2. **Notes:** `date:` from the `gtd` block only. No fallback to created/updated time — those are not event dates and would produce misleading calendars.
3. **No resolvable date** → item is rendered in the **Unscheduled** section below the grid.

### 3.2 Inclusion matrix

An item appears on the calendar iff its type's mode admits it:

| Mode | Has `gtd` block | No `gtd` block |
|---|---|---|
| `gtd-only` (default) | ✅ included | ❌ excluded |
| `all` | ✅ included | ✅ included (default styling) |
| `none` | ❌ excluded | ❌ excluded |

The calendar note itself is always excluded from results, as is any note whose only `gtd-calendar` block makes it a calendar (a note may, however, be both an event and contain a calendar if it has both block types — edge case, supported, documented).

### 3.3 Completed todos

**v1 decision:** completed todos (`todo_completed > 0`) render with strikethrough + checked indicator, and a future `completed: show | hide` calendar option is reserved. (Logged as decision D3 below; cheap to change.)

---

## 4. Rendering

- **Calendar** reuses upstream's grouping/renderer architecture (`DayGrouping`/`WeekGrouping`/`MonthGrouping` + DOM renderers + CSS asset), including the empty-grouping placeholders and current-date highlight, plus the fork's own `month-grid` (a 7-column grid of the entire current month).
- **Fixed upstream bug:** `Calendar/index.ts` imported `WeekGrouping` from `Month/MonthGrouping`, so the week view silently grouped by month. Corrected in the fork.
- **Type distinction:** todos render with a checkbox glyph (☐ / ☑ when completed); notes render with a document glyph. Glyphs are suppressed if the item supplies its own `icon`. Recurring to-dos (per the `recurring` tag) get a ↻ suffix to the right of any icon, across every view.
- **Unscheduled section:** below the calendar grid, split into two labelled sub-sections — to-dos first, then notes — each hidden when empty or switched off (`unscheduled-todos` / `unscheduled-notes`).
- **Kanban** renders three fixed columns (Backlog / In Progress / Done) of compact cards; a "hover" mode shows due date and hover text only on mouseover (`card-detail`).
- **Matrix** renders a 2×2 grid with axis and quadrant labels supplied per-mode by the plugin process; cards are visually and behaviourally identical to kanban cards.
- **Drilldown:** every tile, card, hover-card row, and chip across all three block types is clickable and opens the source note.

---

## 5. Architecture

Upstream is a single synchronous markdown-it content script with no data API access. The fork is a three-part plugin, now serving three fence types (`gtd-calendar`, `gtd-kanban`, `gtd-matrix`) through the same pipeline:

┌─────────────────────────────┐ │ 1. Markdown-it content │ Intercepts gtd-calendar / gtd-kanban / │ script (renderer) │ gtd-matrix fences. Parses YAML config, │ │ emits a placeholder <div> tagged with │ │ data-block-type and the config as a │ │ data attribute. └──────────────┬──────────────┘ │ (rendered HTML) ┌──────────────▼──────────────┐ │ 2. Webview asset script │ Finds placeholders, calls │ (runs in rendered note) │ webviewApi.postMessage(config) with │ │ getEvents / getKanban / getMatrix │ │ depending on block type. Builds the │ │ calendar / board / matrix DOM from the │ │ returned payload. Click → postMessage │ │ ({type: "openNote", noteId}). └──────────────┬──────────────┘ │ postMessage / onMessage ┌──────────────▼──────────────┐ │ 3. Main plugin process │ joplin.contentScripts.onMessage routes │ (index.ts) │ by message type to a handler per block │ │ type, each of which: │ │ • resolves current note's folder │ │ (joplin.workspace.selectedNote) │ │ • builds folder tree, applies scope │ │ (src/Gtd/folderScope.ts) │ │ • fetches notes/todos, paginated │ │ • parses gtd blocks from bodies │ │ (src/Gtd/gtdBlock.ts) │ │ • fetches tag titles per to-do │ │ (getNoteTagTitles) for recurrence / │ │ in-progress / urgent / important │ │ detection │ │ • applies the inclusion matrix, date │ │ resolution, and view-specific │ │ bucketing (collectEvents.ts / │ │ collectKanban.ts / collectMatrix.ts) │ │ • handles openNote via │ │ joplin.commands.execute └─────────────────────────────┘

All three collectors (`collectEvents`, `collectKanban`, `collectMatrix`) share `folderScope.ts`, `gtdBlock.ts`, and `resolveDate.ts` — the inclusion-matrix and date-resolution logic is written once and reused by every view.

### Performance notes

- Folder tree and note list fetched per render request; paginated API calls (`page`/`has_more`).
- Body scanning is limited to items in scope. Kanban and matrix additionally fetch tag titles per to-do (one call each) for recurrence/state detection. For large scopes, pre-filter with Joplin's search API before fetching full bodies; cache by `updated_time` if needed — not yet required at observed real-world scales (largest tested: ~285 notes, single folder scope), but worth revisiting if a `children`-scope board on a large tree feels slow, especially with Persistent Layout keeping several boards rendered at once.
- Refresh model: re-render occurs on note switch (Joplin behavior); no live refresh on background data changes. Fine for a read-only plugin; becomes a sharper question once the authoring axis (§9) lands, where a write on one rendered board should ideally refresh others.

### Platform caveats

- Desktop is the target. Mobile plugin support is partial and this plugin's core mechanisms (custom fence rendering, webview↔plugin messaging) are not expected to work there; documented explicitly in the README. Underlying to-dos still sync and appear in Joplin's native mobile views. The "Embed Search" plugin pairing remains a documented pattern for cross-scope aggregation generally, not specifically a mobile workaround.

---

## 6. Implementation Phases

1. **Phase 0 — Scaffolding.** Fork, rename (manifest id, plugin name, file names), build pipeline verified (`npm install && npm run dist`), upstream week-view bug fixed, upstream tests green.
2. **Phase 1 — Plumbing.** Placeholder rendering for `gtd-calendar` fences; webview ⇄ plugin message round-trip proven with a hardcoded payload.
3. **Phase 2 — Data layer.** Folder tree + scope resolution; note/todo fetching; `gtd` block parsing; inclusion matrix; date resolution; unit tests for all of it (the upstream Jest setup carries over).
4. **Phase 3 — Rendering.** Wire real data into the reused renderers; Unscheduled section; type glyphs; fg-colour support; sort options.
5. **Phase 4 — Drilldown & polish.** Click-to-open; error boxes for malformed YAML; docs/README; scope-performance warnings.

---

## 7. Decision Log / Open Items

| # | Decision | Status |
|---|---|---|
| D1 | Defaults: `notes: gtd-only`, `todos: gtd-only` | ⚠️ **Confirm** — earlier discussion said todos are *always* included (i.e. `todos: all` default); the final message specified `gtd-only` as default for both. Spec follows the final message. |
| D2 | `gtd` `date:` overrides `todo_due` (vs. emitting a warning) | Adopted; revisit if confusing in practice. |
| D3 | Completed todos: shown struck-through in v1; `completed:` option reserved | Proposed, unconfirmed. |
| D4 | `sort`/`sort-type` act within groupings only; grid is always chronological | Confirmed. |
| D5 | Colour key spelling: `bg-colour`/`fg-colour` canonical, `bgColor` accepted for upstream parity | Proposed. |
| D6 | Future options parked: `completed:`, tag-based filtering, week-start day, live refresh | Backlog. |

---

## 8. Licensing & Attribution

Upstream is MIT (© Franco Speziali / WeMakeMachines). The fork retains the MIT license, preserves the original copyright notice, and credits upstream in the README per standard practice.
---

## 9. Roadmap (post-1.0 / post-launch)

Recorded direction, not commitments. Each gets a focused design pass before work begins; real-world use of the shipped plugin may reorder this.

### v0.2.0 — Repeating to-dos (visualisation) — SHIPPED · strip horizon — NOT YET BUILT

Recurrence itself is delegated to an existing community plugin (open-environment approach; we don't reimplement it). Candidates evaluated: BeatLink's original *Repeating To-Dos* (unmaintained), the *[Revived]* fork (maintained, GitHub issues only), and *Repeating To-dos v2* by TheScriptingGuy (`com.github.TheScriptingGuy.joplin-plugin-repeating-todos`, best-documented). All share the same mechanic: on completion the to-do's alarm date is reset to the next occurrence and the to-do is unmarked — so at any moment a recurring to-do is a **single** to-do at its next due date, with the recurrence rule stored in the note body.

- **Option A (shipped in 0.2.0):** detect recurrence and mark those events with a ↻ glyph. *Implementation note:* v2 of the plugin stores recurrence in Joplin's `userData` (not the note body) and maintains a `recurring` **tag** as its query index — so detection is by tag presence on to-dos (constant `RECURRING_TAG`), not body-scanning. Cleaner than the originally-planned body parse, and reuses the tag-fetching the kanban work will need. No series projection — the to-do shows at its next due date.
- **Option B (in pocket):** parse the recurrence rule and project all future occurrences across the visible window. Deferred because the body format has proven to be a moving target across forks; promote to a 0.2.x only if Option A's single-occurrence view proves insufficient, and target a specific fork's format at that time.
- **README:** recommend the maintained fork (v2 first, Revived as fallback); warn about the known "recurrence block injected into all notes" failure mode; note coexistence (their plugin moves the anchor, ours draws the marker).

**Configurable strip horizon.** `day`/`week`/`month` strip views currently span first-event to last-event (plus today). Add a horizon option to `gtd-calendar` (working name `weeks:` or `horizon:`, default ~8 weeks forward) controlling how far ahead the strip extends — relevant both generally and for how many future occurrences Option B would draw. **`month-grid` is explicitly excluded**: it always shows the entire current calendar month, by design, and that is not configurable.

*Note: multiple `gtd-calendar` blocks in one note already work as of 0.1.0 (each fence renders independently) — e.g. a "week ahead" strip plus a "month grid" in a single dashboard note. No work required; document as a recommended pattern.*

### v0.3.0 — Kanban board (read-only) — SHIPPED

Decision: a **second block type within this plugin**, not a separate plugin. Rationale: a kanban needs the entire existing data layer (`folderScope`, `collectEvents` inclusion matrix, `getNoteTagTitles`, config parsing, recurrence detection, webview messaging); a separate plugin would duplicate all of it or require a shared-library split whose overhead isn't justified for "three tag-driven columns." One plugin also serves the intended use — a calendar and a kanban in one dashboard note — with a single install and a unified config/tag vocabulary.

**The `gtd-kanban` block.** Parallel to `gtd-calendar`; lives in its own note or stacked beneath a calendar (multiple blocks already render independently).

title: Editorial Board
scope: this-folder        # this-folder | children | N — same semantics as gtd-calendar
todos: gtd-only           # gtd-only (default) | all | none
sort-type: due-date       # due-date (default) | title | modified-date
sort: asc                 # asc | desc
in-progress-tag: in-progress   # configurable; default "in-progress"
card-detail: hover        # hover (default) | always | none
done-window: 7            # days; integer or "all"; default 7

Columns (always three, always shown even when empty): Backlog · In Progress · Done.

Bucketing rules:

• Done wins. Any to-do with todo_completed > 0 → Done, regardless of tags.
• Else, carrying the in-progress tag → In Progress.
• Else → Backlog.
• Backlog shows everything uncompleted and untagged — dated or not, near or far. (Acknowledged: can grow long; compact cards mitigate.)

Sorting (within each column):

• sort-type: due-date | title | modified-date, with sort: asc | desc.
• Under due-date, to-dos without a due date sort after all dated ones.

Done column window: shows only to-dos completed within done-window days (default 7); all shows the full history. Prevents unbounded growth.

Cards: compact by default — title, due date, ↻ if recurring, click-to-open. card-detail controls the hover panel: hover (default), always (details inline), none (no panel). Notes are excluded entirely (to-dos only).

Read-only in 0.3.0: reflects state, never mutates it. Proves columns/bucketing cheaply before write-back.

Architecture: reuses the calendar's pipeline. New gtd-kanban markdown-it fence → placeholder → webview requests data → plugin runs scope + inclusion + tag fetch (already built) + bucketing → returns three columns → webview renders. IN_PROGRESS_TAG constant mirrors RECURRING_TAG, exposed via in-progress-tag: config from the start.

sort-type vocabulary reconciliation: the calendar block's sort-type (currently title | modified_date) is unified toward due-date | title | modified-date across both blocks so they read consistently. For the calendar, due-date is accepted but falls back to chronological where less meaningful. (Note the spelling shift modified_date → modified-date for cross-block consistency; the old spelling stays accepted as an alias to avoid breaking existing calendars.)

v0.4.0 — Eisenhower Matrix (gtd-matrix block) — SHIPPED

v0.5.0 — Skeleton Matrix (mode: on gtd-matrix) — SHIPPED

Real-world feedback: Eisenhower's opinion axes (and "Eliminate" in particular) fit triage, not a vault of already-committed work. The Skeleton Matrix replaces them with two derived axes the system already maintains: rows = active (in-progress-tag, shared with the kanban); columns = due soon (urgent-window days, default 3, overdue included; urgent tag as manual override — in-progress + urgent + dateless is Do Next by design). Quadrants: Do Next / Scheduled / On Deck / Backlog; dateless active work → Scheduled; nothing is ever "Eliminate". Implemented as mode: skeleton | eisenhower on the same block — positional MatrixBoard (topLeft…bottomRight), labels supplied per mode via payload, shared rendering. Skeleton is the default (it matches the plugin's own tag/date vocabulary); classic Eisenhower preserved via mode: eisenhower.

A fourth display block: a 2×2 prioritisation matrix, tag-driven like the kanban. Chosen ahead of drag-and-drop deliberately: it is on the views axis (another rendering of tagged to-dos, reusing the whole data layer, read-only) rather than the authoring axis (vault mutation), so it deepens what the plugin already is without committing to write-back.

• Quadrants from two configurable tags (urgent-tag: default urgent; important-tag: default important):
  • urgent + important → Do First
  • important only → Schedule
  • urgent only → Delegate
  • neither → Eliminate (the default bucket for untagged to-dos — a deliberately pointed default)
• Completed to-dos are excluded entirely — the matrix is a prioritisation view, not a tracking view; kanban's Done column is where completions live.
• To-dos only; same scope / todos / sort-type / sort / card-detail options as the kanban; same compact clickable cards with ↻.
• Own block (gtd-matrix), not a kanban mode — different layout, different tag semantics.

v0.6.0 — Notebook targeting & profile-wide scope — SHIPPED

Two scope-axis additions shared across all four view blocks (see §2.1 / §2.5 for the normative schema):

• notebook: roots the folder scan at a chosen notebook rather than the host note's own folder, so a dashboard note can live anywhere and aggregate a different tree. Resolution order: raw 32-char folder id → Parent/Child case-insensitive title path → unique bare title. Any miss (unknown id, unresolvable path, ambiguous or absent title) warns and falls back to the host folder (warn-don't-fail). scope applies relative to the resolved notebook. Implemented as a pure resolveNotebook.ts (folders + spec → id + warning) plus a shared parseNotebookOption; resolution lives in index.ts (needs the folder tree), collectors stay unchanged.
• scope: all scans every notebook in the profile, ignoring root and depth — an explicit, deliberately expensive opt-in ("very dangerous, yes"). Represented as a scopeAll flag (not a scopeDepth sentinel); folderScope returns all folder ids when set. Guardrails: the stats footnote reports scan size and is marked scope: all; a soft ⚠ appears past ~2000 scanned notes (advisory, never blocks). notebook: + scope: all → all wins, with a warning.
• Body-fetch optimisation (groundwork the profile-wide scan leans on): the data adapter fetches note bodies only when a view's inclusion mode actually scans the gtd block, via an includeBody hint; behaviour-preserving.

v0.7.0 — Gantt chart (gtd-gantt block) — SHIPPED

A fifth view: a project-grouped timeline, on the views axis like the matrix (another read-only rendering of existing notes/to-dos), not the authoring axis. Unlike the other blocks, gantt items opt in through their own gtd-gantt block carrying a project:, and the same fence name is disambiguated by that key (item vs chart — see §2.5). Notes become bars (begin-date→end-date), to-dos become ◆ milestones on their due date; grouped into per-project swimlanes, no Unscheduled section (dateless/invalid items are excluded with a warning). Data layer is pure and unit-tested (ganttBlock.ts, parseGanttConfig.ts, collectGantt.ts); rendering is a CSS-grid timeline (month ticks, today line, horizontal scroll, click-to-open). Item blocks render in place as a small gantt: <project> badge. Read-only. Open follow-ups (deferred): richer hover cards (currently native tooltips), card-detail: always inline text on bars, an optional Unscheduled strip.

v0.5.0+ — The authoring axis (drag-and-drop + create-from-view) — one deliberate epic

Clustered because they share write-back machinery, and adopting any of them commits the plugin to mutating the vault:

Drag-and-drop kanban (write-back). The first feature making the plugin a controller of data rather than a viewer — warrants its own design pass.

• Dragging a card writes back to Joplin via the existing webview→plugin channel:
  • → In Progress: add the in-progress tag (create the tag if absent; resolve its id; associate).
  • → Done: set todo_completed.
  • → Backlog: remove the tag / clear completion.
• Open design questions for that pass: optimistic UI vs. wait-for-confirmation; behaviour on write failure; whether drops need undo; re-query/refresh of kanban and any affected calendars after a successful write; the trust implications of a rendered view mutating other notes.
• Feasibility: confirmed possible (we already execute openNote from the webview; data writes use the same channel with more responsibility). Complexity lives in tag management and the write/refresh cycle, not the dragging.
• Multi-board refresh: with Persistent Layout keeping several dashboards rendered, a write from one board leaves others stale until re-render — the refresh question is sharper in the fractal-dashboard architecture than for single-board use.

Create-to-do from kanban. A "+" affordance per column creates a to-do with that column's state (In Progress column → in-progress tag; Backlog → no tag). Easier than create-from-calendar: the column is the metadata, no date geometry. Open: target notebook (leaf dashboards obvious, cockpit murky), trigger reliability in the rendered viewer.

Create-to-do from calendar. Click/affordance on a day cell creates a to-do due that day. Open questions: trigger mechanism in the read-only viewer (double-click/right-click may be claimed by Joplin; per-cell "+" affordance likelier), target notebook rule, whether created to-dos get an empty gtd block so they appear under todos: gtd-only. Prototype the trigger before designing the rest.