DWSD.md

Units DSL — Notes (inline notes)

A note is a light-yellow inline note pinned to a unit box on a units view. 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 (in the nested layout: in the parent’s header strip, never over its children), the full text in the drawer’s “Notes” bucket, never a readable note square on the canvas.

This page documents the units delta only. It POINTS TO the shared locator grammar — 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 a units view the locator addresses a unit.

The notes: section

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

mode: declared
units:
  - { name: Goldcrust Bakery, unit-type: company }
  - { name: Deliveries, unit-type: team }
member-of:
  - { from: Deliveries, to: Goldcrust Bakery }
notes:
  - on: "[[Deliveries]]"
    text: "Second van from October — **re-plan the routes**."
  - on: "[[Goldcrust Bakery]]"
    text: "Structure reviewed at the autumn offsite."
    resolved: true
FieldRequiredFormatMeaning
onyesinline (position-only) locatorWhich unit on this view the note pins — see the locator forms below. No [[file]] head for the same-doc pin.
textyesstring (inline markdown-lite)The note content. The drawer renders the safe, non-nesting **bold** / *italic* / `code` subset — never raw HTML, never links.
resolvednoboolean (default false)The open/resolved lifecycle flag: a resolved note’s marker fades and the note moves to the drawer’s “Resolved” subsection.
authornostringOptional, drawer-only convenience label. Git blame is the authorship record.

An absent or malformed notes: value degrades to no notes — the view still renders (the shared “never blank, never break” contract).

The units locator — the unit

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

FormExampleNotes
[[Name]]on: "[[Deliveries]]"The canonical form — the same bare entity wikilink the locator grammar uses for signals, agreements, interactions and agents on a unit. The unit’s entity name (file basename).
Nameon: "Deliveries"A bare name — the same thing without the brackets.

Resolution is exact-one against the units that actually render: the declared units and, in mode: infer / mixed, the units the workspace index contributed. A note on a purely-inferred unit therefore resolves and renders its marker. Any typed segment — col: / lane: / stage: and the like — is not a units 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.

The . document-root note

The units view paints the shared document header, but it has no doc-note bubble in that header yet: on: "." is currently an orphan on a units view (deferred — see the phase’s deferred items). Anchor the note on the root unit instead.

Orphan behavior — never silently dropped

When a note’s on: no longer resolves (the unit 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 — a units.note-orphan warning (a squiggle) on the offending notes: entry.

See also

Like what you see? → Start — build your own org folder in ~2 min

notes.md
# Units DSL — Notes (inline notes)


A **note** is a light-yellow inline note pinned to a **unit box** on a units
view. 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 (in the nested
layout: in the parent's header strip, never over its children), the full text
in the drawer's **"Notes"** bucket, never a readable note square on the canvas.


> **This page documents the units 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 a units view the locator
> addresses a **unit**.


## The `notes:` section


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


```dwsd.units
mode: declared
units:
  - { name: Goldcrust Bakery, unit-type: company }
  - { name: Deliveries, unit-type: team }
member-of:
  - { from: Deliveries, to: Goldcrust Bakery }
notes:
  - on: "[[Deliveries]]"
    text: "Second van from October — **re-plan the routes**."
  - on: "[[Goldcrust Bakery]]"
    text: "Structure reviewed at the autumn offsite."
    resolved: true
```


| Field | Required | Format | Meaning |
|-------|----------|--------|---------|
| `on` | yes | inline (position-only) locator | Which unit on **this** view 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 view still
renders (the shared *"never blank, never break"* contract).


## The units locator — the unit


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


| Form | Example | Notes |
|------|---------|-------|
| `[[Name]]` | `on: "[[Deliveries]]"` | 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 unit. The unit's entity name (file basename). |
| `Name` | `on: "Deliveries"` | A bare name — the same thing without the brackets. |


Resolution is **exact-one** against the units that actually render: the declared
`units` **and**, in `mode: infer` / `mixed`, the units the workspace index
contributed. A note on a purely-inferred unit therefore resolves and renders its
marker. Any typed segment — `col:` / `lane:` / `stage:` and the like — is not a
units 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.


## The `.` document-root note


The units view paints the shared document header, but it has **no doc-note
bubble** in that header yet: `on: "."` is currently an **orphan** on a units
view (deferred — see the phase's deferred items). Anchor the note on the root
unit instead.


## Orphan behavior — never silently dropped


When a note's `on:` no longer resolves (the unit 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** — a **`units.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.
- [Units reference](./index.md) — the unit box this note pins to.
- [Org chart notes](../orgchart/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.