Board DSL — Notes (inline notes)

# Board DSL — Notes (inline notes)

A **note** is a light-yellow inline note pinned to a board position — a column,
a lane, a group, or a split section. Unlike every prior annotation type
(agreements, interactions, the Navigation pins, ODRs), which are **external**
Markdown entities that point *into* the board from their own frontmatter, a
note is authored **inside the board document it annotates**, in a doc-level
`notes:` section. It is the **first inline annotation surface** — the note and
the thing it annotates live in the same file.

Notes are for the *conversation around the board* — a facilitation note, a
reviewer's remark, an open question. They follow the established **marker +
shared drawer** pattern ("weniger note als mehr Marker"): a compact
light-yellow marker at the anchored position, its full text in the shared drawer,
never a readable note square painted on the canvas.

> **This page documents the authoring surface. It POINTS TO the shared
> [locator grammar](../locator-grammar.md) — it does not restate it.** The
> note's `locator:` is the **inline (position-only) form** defined there
> (§2 — no `[[file]]` head, resolved against the same document).

## The `notes:` section

`notes:` is a **doc-level** key holding a **list** of note entries. Each entry
is a `{ locator, text, resolved? }` object:

```dwsd-board
title: Sprint Board
columns:
  - ToDo
  - Doing
  - Done
notes:
  - on: "col:Doing::in"
    text: "Are we pulling too much here? Revisit WIP."
  - on: "col:Done::before"
    text: "Agreed at the retro to auto-archive after 2 weeks."
    resolved: true
```

| Field | Required | Format | Meaning |
|-------|----------|--------|---------|
| `locator` | yes | inline (position-only) locator | Where on **this** board the note pins — a `col:` / `lane:` / `group:` / `split:` path + optional `::before` / `::in` / `::after` (bare = `::in`). **No `[[file]]` head** (D-02). |
| `text` | yes | string (inline markdown-lite) | The note content. The drawer renders a **safe, non-nesting** `**bold**` / `*italic*` / `` `code` `` subset (parsed to `<strong>`/`<em>`/`<code>` — never raw HTML). Links (`[[wikilink]]` / `[text](url)`) are **not** rendered in a note (unlike the agreement/interaction chips): a note row is already navigable to its locator, and note text is untrusted (G5). |
| `resolved` | no | boolean (default `false`) | The open/resolved lifecycle flag (see below). |
| `author` | no | string | **Optional, drawer-only** (D-04). Git blame is the authorship record — `author:` is a convenience label shown in the drawer, never required. |

An empty `text` is preserved (it is still a note); an absent or malformed
`notes:` value degrades to *no notes* rather than throwing — the rest of
the board still renders (the shared *"never blank, never break"* contract).

## The board locator (position-only)

A board note pins to one board position via the **same** typed path segments
the board anchor surface uses, minus the head:

- `col:Name` — a column
- `lane:Name` — a lane (swimlane)
- `group:Name` — a group
- `split:Name` — a split section (e.g. `col:Build/split:QA`)
- chained: `lane:Alice/col:Review::before`

Matching is **case-insensitive** and resolution is **exact-one** (D-07) — a path
that matches more than one node, or none, does **not** resolve (it becomes an
*orphan*, see below). See the [locator grammar](../locator-grammar.md#3-typed-path-segments)
for the full segment reference.

## The `.` document-root note (whole board)

A note can anchor to the **whole board** instead of a single position by using
the document-root locator `.`:

```dwsd-board
title: Sprint Board
columns:
  - ToDo
  - Doing
  - Done
notes:
  - on: "."
    text: "This whole board is under review this sprint."
```

`on: "."` resolves to **document scope** (an empty path), so the note is not
pinned to any column, lane, group, or split — it renders as **one marker in the
board header**, to the **left of the doc-tag chips**. When two or more `.`
doc-notes exist, they **collapse to a single header marker with a count badge** —
the same rule every anchor follows: two or more notes on ONE anchor always
collapse to one marker showing how many. A leading
`.` on a longer path (`./col:Doing`) is a path *from* the document root and is
**equivalent to the bare path** (`col:Doing`) — see the
[locator grammar](../locator-grammar.md#3-typed-path-segments).

## Open / resolved lifecycle (D-10)

A note is **open** by default. Setting `resolved: true` marks it done — and,
unlike the ODR `status` field (which stayed drawer-only), the **marker itself
changes**:

- **On the canvas** — a resolved note **fades / desaturates** (lower opacity,
  muted yellow) so open notes stand out from settled ones at a glance.
- **In the drawer** — resolved notes group under a dedicated **"Resolved"**
  subsection, separated from the still-open notes.

The lifecycle state lives **where the entry is authored** — right on the inline
`notes:` entry — so toggling `resolved` is a one-line edit in the same
document.

## Orphan behavior — never silently dropped (D-11)

When a note's `locator:` no longer resolves (the column was renamed, the lane
removed, the split deleted), the note is **not** silently lost. This is the
deliberate departure from every other annotation type's silent
degrade-to-no-marker: *a reviewer's note is data, not decoration.* An orphaned
note is surfaced **both** ways:

1. **In the drawer** — it drops into a dedicated **"Orphaned notes"** tray inside
   the Notes bucket, with its **text preserved**, so the preview reader still
   sees the note and what it said.
2. **At the source** — an **authoring diagnostic** (a squiggle) is raised on the
   offending `notes:` entry, so the author sees the broken locator directly in
   the editor.

Belt-and-suspenders: the preview reader *and* the author both see an orphan.

## The "Notes" drawer bucket (D-13)

Notes render into their **own** top-level drawer bucket labeled **"Notes"**
(single type = own bucket, the ODR precedent — not a Navigation-style
super-group). The "Orphaned notes" tray is a subsection **within** the Notes
bucket. The marker is styled with a **light-yellow note anmutung** on both the
pill and the drawer entries so it reads as a note.

> The exact marker shade, glyph, and DV-3 treatment are locked by Thomas at the
> EDH walk (D-09) — this page deliberately hard-codes **no** hex value that could
> drift from the anchor registry.

## Worked example

A board with one open note on `Doing` and one resolved note before `Done`:

```dwsd-board
title: Team Board
lanes:
  - name: Platform
    columns:
      - ToDo
      - Doing
      - Review
      - Done
notes:
  - on: "col:Doing::in"
    text: "Blocked item sitting here 4 days — **swarm** it?"
  - on: "lane:Platform/col:Review::before"
    text: "Reviewer capacity agreed: pair review on Fridays."
    resolved: true
    author: "Thomas"
```

- The first note renders a light-yellow marker **in** the `Doing` column, open.
- The second renders a **faded** marker **before** the `Review` column in the
  `Platform` lane, and appears in the drawer's **"Resolved"** subsection.
- If `lane:Platform` were later renamed, the second note would move to the
  **"Orphaned notes"** tray (text preserved) and raise a diagnostic on its entry.

## See also

- [Locator grammar](../locator-grammar.md) — the authoritative locator reference;
  the inline (position-only) form is §2.
- [Board anchors](./anchors.md) — the external agreement / interaction / pin
  surface (the outside-in direction) this inline surface complements.
- [Route notes](../route/notes.md) · [Topology notes](../topology/notes.md)
  — the same `notes:` surface on the other two DSLs.