Org Chart DSL — Notes (inline notes)

# Org Chart DSL — Notes (inline notes)

A **note** is a light-yellow inline note pinned to a **person box** on an org
chart. Like the topology's notes it is authored **inside the document it
annotates**, in a doc-level `notes:` section, and it follows the established
**marker + shared drawer** pattern: a compact marker on the box, the full text in
the drawer's **"Notes"** bucket, never a readable note square on the canvas.

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

## The `notes:` section

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

```dwsd.orgchart
mode: declared
individuals:
  - { name: Mara Holt, role: Owner & Head Baker }
  - { name: Jonas Keller, role: Head of Operations }
reports-to:
  - { from: Jonas Keller, to: Mara Holt }
notes:
  - on: "[[Jonas Keller]]"
    text: "Takes over the wholesale accounts in Q4 — **check the load**."
  - on: "[[Mara Holt]]"
    text: "Succession conversation held."
    resolved: true
```

| Field | Required | Format | Meaning |
|-------|----------|--------|---------|
| `on` | yes | inline (position-only) locator | Which person on **this** chart the note pins — see the locator forms below. No `[[file]]` head for the same-doc pin. |
| `text` | yes | string (inline markdown-lite) | The note content. The drawer renders the safe, non-nesting `**bold**` / `*italic*` / `` `code` `` subset — never raw HTML, never links. |
| `resolved` | no | boolean (default `false`) | The open/resolved lifecycle flag: a resolved note's marker fades and the note moves to the drawer's **"Resolved"** subsection. |
| `author` | no | string | Optional, drawer-only convenience label. Git blame is the authorship record. |

An absent or malformed `notes:` value degrades to *no notes* — the chart still
renders (the shared *"never blank, never break"* contract).

## The org-chart locator — the person

A note pins to a **person** by name, matched **case-insensitively**. Two
spellings address the same box:

| Form | Example | Notes |
|------|---------|-------|
| `[[Name]]` | `on: "[[Jonas Keller]]"` | The canonical form — the same bare **entity wikilink** the [locator grammar](../locator-grammar.md#entity-wikilinks--resolution-by-target-type-the-role-bridge-the-path-form-phase-42) uses for signals, agreements, interactions and agents on a person. The person's entity name (file basename). |
| `Name` | `on: "Jonas Keller"` | A bare name — the same thing without the brackets. |

Resolution is **exact-one** against the people that actually render: the declared
`individuals` **and**, in `mode: infer` / `mixed`, the people the workspace index
contributed. A note on a purely-inferred person therefore resolves and renders
its marker. Any typed segment — `col:` / `lane:` / `stage:` and the like — is not
an org-chart address and orphans; so does a leftover type-prefix spelling (a
type word, a colon, the name), which the grammar no longer knows — write the
wikilink.

## No `.` document-root note

The org chart paints the shared document header (`title:` / `tags:` — see the
[reference](./index.md#design-notes)), but neither structure view has a
document-note bubble yet, so the document-root locator `.` has nowhere to land:
`on: "."` is an **orphan** on an org chart. Anchor the note on the root person
instead.

## Orphan behavior — never silently dropped

When a note's `on:` no longer resolves (the person was renamed, left the cut-out,
or the name never matched), the note is **not** lost. It is surfaced both ways:

1. **In the drawer** — under the **"Orphaned notes"** tray inside the Notes
   bucket, text preserved.
2. **At the source** — an **`orgchart.note-orphan`** warning (a squiggle) on the
   offending `notes:` entry.

## See also

- [Locator grammar](../locator-grammar.md) — the authoritative locator reference;
  the inline (position-only) form is §2, the entity wikilink is in §3.
- [Org chart reference](./index.md) — the person box this note pins to.
- [Units notes](../units/notes.md) · [Topology notes](../topology/notes.md) ·
  [Board notes](../board/notes.md) · [Route notes](../route/notes.md) — the same
  `notes:` surface on the other DSLs.