@diagrammo/dgmo 0.52.0 → 0.53.0

package/docs/language-reference.md

@@ -46,12 +46,13 @@
 The universal core: the cross-cutting anti-patterns (highest value per token) and the one-line index of all 46 chart types. The blocks below are machine-extracted (HTML-comment anchors) and embedded verbatim into every AI surface — IDE rule files, the Claude skill, the CLAUDE.md snippet — by `scripts/gen-ai-core.mjs`. Edit them here; never hand-edit a generated surface.
 
 <!-- AI-CORE:ANTIPATTERNS start -->
+
 ### Disambiguation — where DGMO diverges from LLM priors
 
 LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the most common parse errors:
 
 - **No colons in declarations, directives, tags, or data rows.** `bar Revenue` (not `bar: Revenue`); `series Cloud blue, Legacy red` (not `series: ...`); `North 850` (not `North: 850`); `tag Team as t` (not `tag: Team`). A colon binds a value only in metadata (`key: value`), class/function type separators, and a few scoped spots — see §26.
-- **No Mermaid arrow-labels.** Put the label *between* the dashes: `A -Login-> B`, never `A -> B: Login`. Sequence: `->` sync, `~>` async; left-to-right only — no `<-` / `<~`.
+- **No Mermaid arrow-labels.** Put the label _between_ the dashes: `A -Login-> B`, never `A -> B: Login`. Sequence: `->` sync, `~>` async; left-to-right only — no `<-` / `<~`.
 - **No indented edges on a map.** Every map connection is ONE full line — `JFK ~daily~> LAX`; for a hub repeat the origin per spoke (`JFK ~daily~> LHR`, …). A bare source with indented `-> dest` legs errors as `Malformed edge`; indented legs are valid ONLY inside a `route` block (an ordered stop→stop voyage). Edge endpoints auto-create their POIs — don't add separate `poi` lines for places already in an edge.
 - **No `|` metadata delimiter** (removed 0.18.0 → `E_PIPE_OPERATOR_REMOVED`). Use same-line `Name key: value, k2: v2` or indented `key: value`. (`|` survives only in wireframe `{A | B}` dropdowns, in-arrow label text, and quoted names.)
 - **No removed participant keywords.** Do not write `X is a service` / `external` / `frontend` / `networking` / `gateway` — these were removed and error. A bare name renders the default shape; for a typed glyph use `is a person` / `is a database` / `is a queue`.
@@ -63,7 +64,7 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 - **Declare before reference.** An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid `Duplicate node` warnings.
 - **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `<!-- … -->` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.)
 
-Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):
+Two traps in the _other_ direction (DGMO wants a colon / a space where you might not expect):
 
 - **Infra node properties REQUIRE the colon** — `cache-hit: 80%`, `instances: 3`, `max-rps: 8000`, `latency-ms: 45`. But top-level infra **options** are space-separated (`default-rps 100`). Don't conflate them.
 - **ER columns are space-separated** — `id int pk`, `email varchar` (the one SQL-DDL carve-out; everything else indented-typed uses a colon).
@@ -83,18 +84,21 @@ API Gateway t: Platform
 Orders t: Product
 Billing t: Product
 ```
+
 <!-- AI-CORE:ANTIPATTERNS end -->
 
 <!-- AI-CORE:STYLING start -->
+
 ### Make it look good — authoring guidance
 
 Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:
 
 <!-- TITLE start -->
+
 - **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
-<!-- TITLE end -->
-<!-- CATEGORIZE start -->
-- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have *fewer* values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+  <!-- TITLE end -->
+  <!-- CATEGORIZE start -->
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have _fewer_ values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
 <!-- CATEGORIZE end -->
 - **Keep labels short.** A few words per node. Move detail into notes or metadata, never a full sentence inside a label.
 - **Let the defaults show.** Don't add `no-*` opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color.
@@ -102,64 +106,66 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 <!-- AI-CORE:STYLING end -->
 
 <!-- AI-CORE:TYPE-INDEX start -->
+
 ### Chart-type index (45) — pick the type, then fetch its section
 
-| id | when to use |
-| -- | ----------- |
-| `sequence` | message / interaction flows over time |
-| `flowchart` | decision trees and process flows |
-| `state` | state-machine / lifecycle transitions |
-| `class` | UML class hierarchies |
-| `er` | database schemas and relationships |
-| `c4` | system architecture (context / container / component / deployment) |
-| `infra` | infrastructure traffic flow with RPS computation |
-| `boxes-and-lines` | general-purpose node-edge diagrams with groups and tags |
-| `sitemap` | site / app navigation structure |
-| `mindmap` | radial hierarchy of ideas from a central topic |
-| `org` | reporting hierarchy |
-| `family` | family tree / genealogy: unions (couples), children, remarriage, adoption, GEDCOM-style metadata |
-| `bracket` | single-elimination tournament bracket: winners auto-advance; seed the field for a day-0 skeleton or list results casually; two sides mirror to a championship |
-| `kanban` | task-board columns |
-| `gantt` | project scheduling with task dependencies and milestones |
-| `pert` | project network with three-point estimates and critical path |
-| `swimlane` | cross-functional process flow with lanes, phases and gateways (BPMN-style) |
-| `version-control` | git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style) |
-| `timeline` | events, eras, and date ranges |
-| `event-line` | annotated narrative timeline — events on a line with descriptions, optionally not to scale (NOT the date-scaled `timeline`) |
-| `body` | human anatomy figure annotated by muscle name — for medical, exercise, and educational diagrams |
-| `journey-map` | UX flow with emotion scores, phases, annotations |
-| `cycle` | cyclical process (PDCA, OODA, DevOps loops) |
-| `raci` | tasks × roles responsibility matrix; variant (RACI / RASCI / DACI) is inferred from the markers used |
-| `tech-radar` | technology adoption quadrants (adopt / trial / assess / hold) |
-| `quadrant` | 2×2 positioning matrix |
-| `pyramid` | stacked hierarchy of layers (Maslow, DIKW) |
-| `ring` | concentric rings of nested categories |
-| `treemap` | nested rectangles sized by value (budgets, disk usage, portfolios) |
-| `block` | author-controlled grid of nested, collapsible blocks (system / architecture layouts) |
-| `sketch` | GUI-first free-placement canvas: uniform shapes on a snap grid, arrows, tags (markup is app-generated) |
-| `goal` | single progress-toward-a-target value (`now` vs `target`) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas |
-| `countdown` | live "N days until X" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type |
-| `clock` | live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line |
-| `map` | geographic concept map: regions, points, routes |
-| `wireframe` | low-fidelity UI layout with panels and controls |
-| `bar` | categorical comparisons (multi-series via `stack` / `group`) |
-| `line` | trends over time (multiple series via a `series` block; filled via `fill`; dual y-axes via `y-label` / `y-right-label`) |
-| `pie` | part-to-whole proportions (ring/doughnut via `hole`) |
-| `radar` | multi-dimensional metrics |
-| `polar-area` | radial bar chart |
-| `scatter` | 2D points or bubble chart |
-| `heatmap` | matrix intensity |
-| `funnel` | conversion pipeline |
-| `sankey` | flow / allocation |
-| `arc` | network relationships (linear, or circular via `layout chord`) |
-| `slope` | change between two periods |
-| `venn` | set overlaps |
-| `wordcloud` | term-frequency |
-| `function` | mathematical expressions (colon required: `f(x): x^2`) |
+| id                | when to use                                                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sequence`        | message / interaction flows over time                                                                                                                         |
+| `flowchart`       | decision trees and process flows                                                                                                                              |
+| `state`           | state-machine / lifecycle transitions                                                                                                                         |
+| `class`           | UML class hierarchies                                                                                                                                         |
+| `er`              | database schemas and relationships                                                                                                                            |
+| `c4`              | system architecture (context / container / component / deployment)                                                                                            |
+| `infra`           | infrastructure traffic flow with RPS computation                                                                                                              |
+| `boxes-and-lines` | general-purpose node-edge diagrams with groups and tags                                                                                                       |
+| `sitemap`         | site / app navigation structure                                                                                                                               |
+| `mindmap`         | radial hierarchy of ideas from a central topic                                                                                                                |
+| `org`             | reporting hierarchy                                                                                                                                           |
+| `family`          | family tree / genealogy: unions (couples), children, remarriage, adoption, GEDCOM-style metadata                                                              |
+| `bracket`         | single-elimination tournament bracket: winners auto-advance; seed the field for a day-0 skeleton or list results casually; two sides mirror to a championship |
+| `kanban`          | task-board columns                                                                                                                                            |
+| `gantt`           | project scheduling with task dependencies and milestones                                                                                                      |
+| `pert`            | project network with three-point estimates and critical path                                                                                                  |
+| `swimlane`        | cross-functional process flow with lanes, phases and gateways (BPMN-style)                                                                                    |
+| `version-control` | git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style)                                    |
+| `timeline`        | events, eras, and date ranges                                                                                                                                 |
+| `event-line`      | annotated narrative timeline — events on a line with descriptions, optionally not to scale (NOT the date-scaled `timeline`)                                   |
+| `body`            | human anatomy figure annotated by muscle name — for medical, exercise, and educational diagrams                                                               |
+| `journey-map`     | UX flow with emotion scores, phases, annotations                                                                                                              |
+| `cycle`           | cyclical process (PDCA, OODA, DevOps loops)                                                                                                                   |
+| `raci`            | tasks × roles responsibility matrix; variant (RACI / RASCI / DACI) is inferred from the markers used                                                          |
+| `tech-radar`      | technology adoption quadrants (adopt / trial / assess / hold)                                                                                                 |
+| `quadrant`        | 2×2 positioning matrix                                                                                                                                        |
+| `pyramid`         | stacked hierarchy of layers (Maslow, DIKW)                                                                                                                    |
+| `ring`            | concentric rings of nested categories                                                                                                                         |
+| `treemap`         | nested rectangles sized by value (budgets, disk usage, portfolios)                                                                                            |
+| `block`           | author-controlled grid of nested, collapsible blocks (system / architecture layouts)                                                                          |
+| `sketch`          | GUI-first free-placement canvas: uniform shapes on a snap grid, arrows, tags (markup is app-generated)                                                        |
+| `goal`            | single progress-toward-a-target value (`now` vs `target`) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas                                |
+| `countdown`       | live "N days until X" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type                    |
+| `clock`           | live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line           |
+| `map`             | geographic concept map: regions, points, routes                                                                                                               |
+| `wireframe`       | low-fidelity UI layout with panels and controls                                                                                                               |
+| `bar`             | categorical comparisons (multi-series via `stack` / `group`)                                                                                                  |
+| `line`            | trends over time (multiple series via a `series` block; filled via `fill`; dual y-axes via `y-label` / `y-right-label`)                                       |
+| `pie`             | part-to-whole proportions (ring/doughnut via `hole`)                                                                                                          |
+| `radar`           | multi-dimensional metrics                                                                                                                                     |
+| `polar-area`      | radial bar chart                                                                                                                                              |
+| `scatter`         | 2D points or bubble chart                                                                                                                                     |
+| `heatmap`         | matrix intensity                                                                                                                                              |
+| `funnel`          | conversion pipeline                                                                                                                                           |
+| `sankey`          | flow / allocation                                                                                                                                             |
+| `arc`             | network relationships (linear, or circular via `layout chord`)                                                                                                |
+| `slope`           | change between two periods                                                                                                                                    |
+| `venn`            | set overlaps                                                                                                                                                  |
+| `wordcloud`       | term-frequency                                                                                                                                                |
+| `function`        | mathematical expressions (colon required: `f(x): x^2`)                                                                                                        |
 
 **Need more than the index gives you?** Fetch the per-type section: MCP `get_language_reference(type)` / `get_examples(type)`, or read that type's section below. The `suggest_chart_type` tool returns the chosen type's section automatically.
 
 **When the type isn't obvious, ask — don't guess.** Call `suggest_chart_type` first. If it returns an `⚠️ ASK THE USER` directive (the request is ambiguous between candidates, or nothing matched), present those candidate options to the user and wait for their pick before generating — never silently choose. A confident result (high/medium) you can proceed with.
+
 <!-- AI-CORE:TYPE-INDEX end -->
 
 <!-- The grouped data-chart / matrix ids share one documented section. This map is the single source of truth for which TYPE block each id resolves to (read by gen-ai-core.mjs and the MCP slicer). -->
@@ -208,7 +214,7 @@ tag GroupName as <alias>
 - Must appear before diagram content
 - Legacy bare shorthand (`tag Priority p`) and `alias` keyword (`tag Priority alias p`) emit `E_TAG_SHORTHAND_REMOVED` per TD-18
 
-**Diagram types that support tags**: sequence, infra, org, c4, er, kanban, gantt, sitemap, timeline, boxes-and-lines
+**Diagram types that support tags**: the tag model is near-universal across the structural types — sequence, infra, org, c4, er, kanban, gantt, sitemap, timeline, boxes-and-lines, state (§5.7), pert, swimlane, mindmap, journey-map, event-line, treemap, map, block, sketch, bracket, family, and wireframe all accept `tag <Group> as <alias>` blocks. Check the per-type Options section for the exact directive set; if a type draws a tag legend, it takes tags.
 
 ### 1.4 Same-Line Metadata
 
@@ -289,14 +295,17 @@ no-option-name       // off
 
 **Cross-cutting boolean directives** (recognized in every chart type that has the corresponding rendering surface):
 
-| Directive    | Effect                                                                                  |
-| ------------ | --------------------------------------------------------------------------------------- |
-| `fill-tint` | The default, spelled explicitly — shapes get the canonical 25% tint fill with a solid intent-color outline |
-| `fill-solid` | Render nodes/bars at full intent saturation instead of the canonical 25% tint           |
-| `fill-outline` | No fill — shapes take the theme background fill; the intent color is carried entirely by the outline |
-| `no-title`   | Hide the diagram banner title in the rendered output (does not mutate the parsed model) |
+| Directive      | Effect                                                                                                                  |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `fill-tint`    | The default, spelled explicitly — shapes get the canonical 25% tint fill with a solid intent-color outline              |
+| `fill-solid`   | Render nodes/bars at full intent saturation instead of the canonical 25% tint                                           |
+| `fill-outline` | No fill — shapes take the theme background fill; the intent color is carried entirely by the outline                    |
+| `no-title`     | Hide the diagram banner title in the rendered output (does not mutate the parsed model)                                 |
+| `no-legend`    | Hide the legend and collapse the vertical band reserved for it — accepted by **every** chart type that renders a legend |
+
+`no-legend` is universal: any chart that draws a legend suppresses it, including the data charts (multi-series `bar` / `line` / `radar`, `scatter`, `function`) whose legend was previously always shown, and the tag-legend charts (`sequence`, `kanban`, `timeline`, `org`, `c4`, `gantt`, `er`, `state`, …). Charts that render no legend at all accept the token as a harmless no-op, so authors never have to remember which types honour it.
 
-Examples: `no-legend` (journey-map), `no-color` (flowchart, state), `no-title` (all chart types with a banner title).
+Examples: `no-legend` (universal), `no-title` (all chart types with a banner title), `no-value` (boxes-and-lines, treemap, and the data-chart label family).
 
 ### 1.9 In-Arrow Message Labels
 
@@ -538,10 +547,10 @@ no full date at all; emits a soft `year 20XX` hint).
 
 **Directives** (any date-bearing chart; position-independent):
 
-| Directive | Effect |
-| --------- | ------ |
-| `year 2026` | base year for bare month-days |
-| `date-order dmy` | numeric slash/dash dates read day-first (default `mdy`) |
+| Directive         | Effect                                                  |
+| ----------------- | ------------------------------------------------------- |
+| `year 2026`       | base year for bare month-days                           |
+| `date-order dmy`  | numeric slash/dash dates read day-first (default `mdy`) |
 | `no-current-year` | a fully-bare chart errors instead of assuming this year |
 
 **TIPS (AI authoring):**
@@ -549,7 +558,7 @@ no full date at all; emits a soft `year 20XX` hint).
 - Prefer `Jul 4` or `07-04` + one `year 2026` line over repeating the ISO year
   on every row — shorter and reproducible.
 - `7/4` is **Jul 4** (US month-first). For day-first documents add `date-order
-  dmy` once at the top; then `7/4` is **Apr 7**.
+dmy` once at the top; then `7/4` is **Apr 7**.
 - Month-name forms (`Jul 4`) are never ambiguous and ignore `date-order` — use
   them when a mixed audience will read the source.
 - Existing ISO dates keep working unchanged; this is a superset, not a
@@ -823,15 +832,16 @@ tag Team as t
   APIServer t: Backend
   BookDB t: Data
 ```
+
 - Optional `as <alias>` postfix and same-line metadata.
 - **No nesting.** A group cannot contain another `[...]` group; only indented components.
-- Group properties (indented under the bracket line):
-  - `instances N` or `instances N-M` — capacity multiplier on children (auto-scaling)
-  - `collapsed true` — start collapsed; renders as a single node showing the worst child health
+- **Collapse:** a bare `collapsed` trailing flag on the group line (`[Backend] collapsed`, §1.8) starts the group collapsed — it renders as a single node showing the worst child health. (Legacy: indented `collapsed true` / `collapsed: true`.)
+- Group properties (indented under the bracket line, colon-keyed like node properties):
+  - `instances: N` or `instances: N-M` — capacity multiplier on children (auto-scaling). The space forms `instances N` / `instances N-M` are accepted legacy.
 
 ### 4.7 Infra Options (Space-Separated, NO Colon)
 
-- `direction-tb` (boolean; default is LR)
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is LR)
 - `default-latency-ms N`
 - `default-rps N` — fallback edge RPS when no `rps` is declared on the edge node
 - `default-uptime DECIMAL`
@@ -933,13 +943,11 @@ Bracket syntax only.
 
 ### 4.6 Options
 
-- `direction-lr` (boolean; default is TB)
-- `orientation-vertical` (boolean; default is horizontal)
-- `no-color` (boolean; default off — when on, all nodes resolve to the muted neutral fill instead of their default intent color)
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is TB). The key+value form `direction LR|TB` is accepted legacy.
 - `fill-solid` / `fill-outline` (fill family; default is the 25% tint — `fill-solid` renders shapes at full intent color, `fill-outline` drops the fill and carries color on the outline alone)
 - `no-notes` (boolean; default off — suppress all note boxes, see §4.7)
 
-`no-color` + `fill-solid` precedence: `no-color` wins for nodes with no explicit color (the muted neutral path bypasses `fill-solid`). Nodes with an explicit color survive `no-color` and are then rendered at full saturation if `fill-solid` is also on.
+`no-color` was removed — node colors are assigned automatically by shape, and the parser raises a warning if the line is still present. Delete it.
 
 ### 4.7 Notes (Nodes)
 
@@ -960,7 +968,7 @@ node; an unknown id is an error, a duplicate note on a node is a warning
 
 Notes work on **flowchart**, **state**, **class** (`note <ClassName>`),
 **er** (`note <Table>`), and **boxes-and-lines** (`note <Box>`). Org and
-sitemap are excluded — their indentation *is* the tree structure, which
+sitemap are excluded — their indentation _is_ the tree structure, which
 collides with the indented-body grammar.
 
 ---
@@ -983,10 +991,11 @@ state [Title]
 
 ```
 StateName
-StateName color
 [*]                    // initial/final pseudostate
 ```
 
+States have no color slot — color comes from the tag system (§5.7).
+
 ### 5.3 Transitions
 
 | Type      | Syntax                      |
@@ -1009,23 +1018,45 @@ references, and the `no-notes` opt-out (see §4.7).
 
 ### 5.6 Options
 
-- `direction-tb` (boolean; default is LR)
-- `no-color` (boolean; default off — when on, all states resolve to the muted neutral fill instead of their default intent color)
-
-**Color by state category** — declare a `tag <Name> as <alias>` group (§1.3), then assign each state `<alias>: <Value>` same-line (declare the assignments before the transitions):
-
-```
-tag Phase as p
-  Active blue
-  Done green
-Pending p: Active
-Shipped p: Done
-Pending -ship-> Shipped
-```
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is LR)
 - `fill-solid` / `fill-outline` (fill family; default is the 25% tint — collapsed groups follow the same mode, e.g. full saturation under `fill-solid`)
 - `no-notes` (boolean; default off — suppress all note boxes, see §4.7)
-
-`no-color` + `fill-solid` precedence: `no-color` wins for states with no explicit color (the muted neutral path bypasses `fill-solid`). Group colors survive `no-color` and are then rendered at full saturation if `fill-solid` is also on.
+- `active-tag GroupName` / `active-tag none` (§5.7)
+
+### 5.7 Tags
+
+State diagrams support the universal tag system (§1.3). Declare
+`tag <Group> as <alias>` blocks above the diagram body and apply values with
+same-line `key: value` metadata on a **state** line (tags describe states,
+not transitions — put the assignment on its own line):
+
+```
+state Document Lifecycle
+tag Phase as ph
+  Intake blue
+  Review orange
+  Terminal green
+
+Draft ph: Intake
+Draft -submit-> In Review
+In Review ph: Review
+In Review -publish-> Published
+Published ph: Terminal
+```
+
+- Either the alias (`ph:`) or the canonical group name (`phase:`) works as
+  the metadata key.
+- Tagged states get the standard treatment — 25% tint fill + solid
+  intent-color outline — and the `fill-*` family (§1.8) applies as usual.
+- Untagged states take the group's **first** value per §1.3. State is not in
+  the neutral-gray carve-out.
+- Declaring a tag group renders the standard legend. With several groups the
+  first declared one colors the diagram; `active-tag <Group>` picks another
+  and `active-tag none` turns tag coloring off (states fall back to the
+  default intent color).
+- Group colors (`[Group Name] color`) and collapsed-group stand-ins keep
+  their explicit color — the tag channel never overrides one.
+- The `[*]` pseudostate is never tagged.
 
 ---
 
@@ -1092,7 +1123,7 @@ This is key-value metadata assignment, consistent with same-line metadata syntax
 
 ### 6.5 Options
 
-- `direction-tb` (boolean; default is LR)
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is TB)
 - `sub-node-label Text`
 - `show-sub-node-count`
 - `hide`
@@ -1194,7 +1225,7 @@ Database is a container description: PostgreSQL with read replicas
 
 ### 7.8 Options
 
-- `direction-tb` (boolean; default is LR)
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is TB)
 
 ---
 
@@ -1461,7 +1492,7 @@ Blog
 
 ### 11.6 Options
 
-- `direction-tb` (boolean; default is LR)
+- `direction-lr` / `direction-tb` (booleans, last one wins; default is LR)
 
 ---
 
@@ -1482,7 +1513,7 @@ gantt [Title]
 ### 12.2 Options (Space-Separated, NO Colon)
 
 ```
-start 2026-03-15
+start-date 2026-03-15
 today-marker
 today-marker 2026-03-27
 critical-path
@@ -1570,7 +1601,7 @@ Design Review start: 2026-04-01
 ```
 
 A task line MUST have `duration:` or `start:` (or both) in its metadata.
-Duration units: `min`, `h`, `d`, `bd` (business days), `w`, `m`, `q`, `y`, `s` (sprints)
+Duration units: `min`, `h`, `d`, `bd` (business days), `w`, `m`, `q`, `y`, `sp` (sprints)
 Uncertain: `duration: 10bd?` (trailing `?` on the value)
 Progress: `progress: 80` in metadata (integer 0–100)
 
@@ -1638,24 +1669,24 @@ divvy shares 1 2 3
 
 ### Directives
 
-| Directive                     | Effect                                                                                                                                                                                                |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `time-unit <unit>`            | Unit for bare-number durations (default `d`); accepts `min`, `h`, `d`, `bd`, `w`, `s` (sprints)                                                                                                       |
-| `default-confidence <level>`  | M-only heuristic: `high`, `medium`, `low`, or a custom `O/P` factor pair (e.g. `0.6/2.5`)                                                                                                             |
-| `direction <LR\|TB>`          | Layout direction (default `LR`)                                                                                                                                                                       |
-| `node-detail <compact\|full>` | Visual density; `full` adds slack bars and σ-as-border-thickness                                                                                                                                      |
-| `no-analysis`                 | Bare flag — hide the analysis layer (tornado + S-curve). The layer renders by default whenever Monte Carlo ran; this suppresses it. An explicit `viewState.an` (app toggle / share link) overrides it |
-| `trials <N>`                  | Canonical Monte Carlo trial count (`< 100` clamps to analytical)                                                                                                                                      |
-| `seed <N>`                    | Mulberry32 PRNG seed for deterministic runs                                                                                                                                                           |
-| `scrubber-trials <N>`         | Fast-MC trials for the interactive duration scrubber                                                                                                                                                  |
-| `start-date <YYYY-MM-DD>`     | Anchor the forward pass — accepts the literal `now`                                                                                                                                                   |
-| `end-date <YYYY-MM-DD>`       | Anchor the backward pass (mutually exclusive with `start-date`)                                                                                                                                       |
-| `sprint-length <duration>`    | Sprint length when sprint mode is active (default `2w`)                                                                                                                                               |
-| `sprint-number <N>`           | Starting sprint label N — cells render as `S<N+offset>` (default `1`)                                                                                                                                 |
-| `sprint-start <YYYY-MM-DD>`   | Optional ISO date the starting sprint begins on                                                                                                                                                       |
-| `active-tag <GroupName>`      | Pre-expand a tag group + drive node fill                                                                                                                                                              |
-
-Sprint mode activates automatically when `time-unit s` is set, or explicitly when any `sprint-*` directive appears. ES/EF/LS/LF cells then render as `S5`, `S7`, etc.
+| Directive                       | Effect                                                                                                                                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `time-unit <unit>`              | Unit for bare-number durations (default `d`); accepts `min`, `h`, `d`, `bd`, `w`, `sp` (sprints)                                                                                                      |
+| `default-confidence <level>`    | M-only heuristic: `high`, `medium`, `low`, or a custom `O/P` factor pair (e.g. `0.6/2.5`)                                                                                                             |
+| `direction-lr` / `direction-tb` | Layout direction booleans (last one wins; default `LR`); key+value `direction LR\|TB` accepted legacy                                                                                                 |
+| `node-detail <compact\|full>`   | Visual density; `full` adds slack bars and σ-as-border-thickness                                                                                                                                      |
+| `no-analysis`                   | Bare flag — hide the analysis layer (tornado + S-curve). The layer renders by default whenever Monte Carlo ran; this suppresses it. An explicit `viewState.an` (app toggle / share link) overrides it |
+| `trials <N>`                    | Canonical Monte Carlo trial count (`< 100` clamps to analytical)                                                                                                                                      |
+| `seed <N>`                      | Mulberry32 PRNG seed for deterministic runs                                                                                                                                                           |
+| `scrubber-trials <N>`           | Fast-MC trials for the interactive duration scrubber                                                                                                                                                  |
+| `start-date <YYYY-MM-DD>`       | Anchor the forward pass — accepts the literal `now`                                                                                                                                                   |
+| `end-date <YYYY-MM-DD>`         | Anchor the backward pass (mutually exclusive with `start-date`)                                                                                                                                       |
+| `sprint-length <duration>`      | Sprint length when sprint mode is active (default `2w`)                                                                                                                                               |
+| `sprint-number <N>`             | Starting sprint label N — cells render as `S<N+offset>` (default `1`)                                                                                                                                 |
+| `sprint-start <YYYY-MM-DD>`     | Optional ISO date the starting sprint begins on                                                                                                                                                       |
+| `active-tag <GroupName>`        | Pre-expand a tag group + drive node fill                                                                                                                                                              |
+
+Sprint mode activates automatically when `time-unit sp` is set, or explicitly when any `sprint-*` directive appears. ES/EF/LS/LF cells then render as `S5`, `S7`, etc.
 
 ### Activities
 
@@ -1722,14 +1753,14 @@ Bracketed `[group-name]` blocks cluster activities. Whether a group renders as a
 sail to atoll 3 5 8
 ```
 
-Groups can author `collapsed: true` to start collapsed.
+Groups can author a bare `collapsed` trailing flag (§1.8) to start collapsed (legacy: `collapsed: true`).
 
 ### Same-line metadata
 
 | Key                             | Where           | Meaning                                                                           |
 | ------------------------------- | --------------- | --------------------------------------------------------------------------------- |
 | `confidence`                    | activity        | Per-activity override of `default-confidence` (`high` / `medium` / `low` / `O/P`) |
-| `collapsed`                     | group           | `true` to start the group collapsed                                               |
+| `collapsed`                     | group           | bare trailing flag (§1.8) — start the group collapsed (legacy: `collapsed: true`) |
 | tag aliases (e.g. `c: Captain`) | activity, group | Resolves to the declared tag group; drives node fill when the group is active     |
 
 ### Tags
@@ -1806,7 +1837,7 @@ Henry Turner + Carina Smyth m: 1751
 - **`generations`** (option): draws a left gutter of Roman-numeral generation labels (`Gen I`, `Gen II`, …) plus subtle zebra shading behind alternating generations.
 - **`highlight <name>`** (directive): dims everyone outside that person's bloodline (ancestors + descendants + spouses stay lit).
 - **Sex → color:** `sex: m` → blue, `sex: f` → purple, unset → gray (25% tint). An explicit `tag`/inline color overrides the sex color.
-- The union split cuts `m:` metadata first, THEN splits ` + ` within the name region — so a `+` inside a quoted name (`"Anne + Jack"`) or a metadata value never mis-splits. Per-side `key: value` metadata on a union line is not supported — declare the person standalone.
+- The union split cuts `m:` metadata first, THEN splits `+` within the name region — so a `+` inside a quoted name (`"Anne + Jack"`) or a metadata value never mis-splits. Per-side `key: value` metadata on a union line is not supported — declare the person standalone.
 
 ---
 
@@ -1818,11 +1849,11 @@ Henry Turner + Carina Smyth m: 1751
 **Styling tips:** Give each lane a color and let nodes inherit it — reach for a `tag` group only when you need a *second* dimension (e.g. risk) that deliberately breaks lane color. Echo the gateway/terminal delimiters (`<Review>`, `(Paid) success`) even though bare names also resolve — it keeps the source self-documenting. Put every edge label *inside* the arrow (`-invalid->`), never as a trailing word.
 <!-- TIPS end -->
 
-Swimlane diagrams model a cross-functional process: actors/systems are **lanes**, the process flows along the flow axis (`direction LR` default, `TB` transposes), and optional `[Phase]` columns group steps into stages. Nodes are tasks (bare), exclusive gateways (`<X>`), parallel gateways (`<+ X>`), terminals (`(X)`), and subprocesses (`[[X]]`). A `lane` block **owns its edges** — nodes and their outgoing `->` edges are written inline, no separate flow block. A back-edge to an earlier node draws a routed loop.
+Swimlane diagrams model a cross-functional process: actors/systems are **lanes**, the process flows along the flow axis (`direction-lr` default, `direction-tb` transposes; key+value `direction LR|TB` accepted legacy), and optional `[Phase]` columns group steps into stages. Nodes are tasks (bare), exclusive gateways (`<X>`), parallel gateways (`<+ X>`), terminals (`(X)`), and subprocesses (`[[X]]`). A `lane` block **owns its edges** — nodes and their outgoing `->` edges are written inline, no separate flow block. A back-edge to an earlier node draws a routed loop.
 
 ```
 swimlane Weekly Publishing
-direction LR
+direction-lr
 
 lane Writer gray
   Draft Post -> Review
@@ -1846,15 +1877,15 @@ lane Social green
 
 ### Node tokens
 
-| Token | Meaning |
-| ----- | ------- |
-| `Submit Claim` | task |
-| `<Validate>` | exclusive (XOR) gateway |
-| `<+ Fork>` | parallel (AND) gateway |
-| `(Start)` | terminal (neutral) |
-| `(!Rejected)` | error terminal (`!` prefix → red) |
-| `(Paid) success` | success terminal (trailing word → green); also `terminate` |
-| `[[Inspect Property]]` | subprocess (collapsible) |
+| Token                  | Meaning                                                    |
+| ---------------------- | ---------------------------------------------------------- |
+| `Submit Claim`         | task                                                       |
+| `<Validate>`           | exclusive (XOR) gateway                                    |
+| `<+ Fork>`             | parallel (AND) gateway                                     |
+| `(Start)`              | terminal (neutral)                                         |
+| `(!Rejected)`          | error terminal (`!` prefix → red)                          |
+| `(Paid) success`       | success terminal (trailing word → green); also `terminate` |
+| `[[Inspect Property]]` | subprocess (collapsible)                                   |
 
 ### Flow & color
 
@@ -1962,9 +1993,9 @@ Indented shorthand also supports groups (place arrow directly after group header
 
 ### 13.6 Directives
 
-- `direction TB` — top-to-bottom layout (default: `LR`)
+- `direction-tb` — top-to-bottom layout; `direction-lr` restates the `LR` default (booleans, last one wins; key+value `direction LR|TB` accepted legacy)
 - `heat <Label> [low] [high]` — name a numeric colour ramp (see §13.8); one trailing color sets the high hue over a neutral low, two set explicit `low high` ramp endpoints (pairs with the `heat:` key)
-- `show-values` — print each box's numeric value as text (off by default)
+- `no-value` — suppress the per-box numeric value labels (values render by default; legacy `show-values` is accepted as a no-op)
 
 ### 13.7 Options
 
@@ -1981,7 +2012,6 @@ choropleth-style "heat dimension" alongside the categorical tag groups.
 ```
 boxes-and-lines Fleet Crews
 heat Crew blue
-show-values
 
 Flagship heat: 120
 Frigate heat: 40
@@ -1995,7 +2025,7 @@ Flagship -> Sloop
 - `heat <Label> [low] [high]` names the dimension and optionally sets the
   ramp endpoint colors: no color → primary hue / neutral low; one color → that
   high hue / neutral low; two → explicit `low high` (e.g. `heat Risk green
-  red`). Order is literal — polarity (good vs bad) is your choice. A wide-hue-gap
+red`). Order is literal — polarity (good vs bad) is your choice. A wide-hue-gap
   pair routes through a neutral midpoint (so green→red mid values stay clean);
   analogous pairs blend directly.
 - The ramp anchors at `0` for all-non-negative data, else at the data minimum.
@@ -2006,7 +2036,7 @@ Flagship -> Sloop
   between a tag group and the heat label, the tag group wins.
 - When the heat ramp is active, every box tints along the min→max ramp and the
   legend shows a gradient capsule; boxes without a `heat:` get a neutral fill.
-- `show-values` additionally prints each box's number as text.
+- Each box's number also prints as text by default; suppress with `no-value`.
 
 ### 13.9 Tag groups (categorical color)
 
@@ -2243,7 +2273,6 @@ Q1 400 700 300 500
 **Options (space-separated, NO colon):**
 
 ```
-title My Chart
 x-label X Label
 y-label Y Label
 orientation-horizontal   // bar: horizontal bars
@@ -2262,7 +2291,11 @@ no-auto-y                // line: anchor the y-axis at 0 (opt out of auto-fit)
   padded window around the data (min→max across all series, not a forced 0
   baseline), so a tight high-valued series fills the plot. `no-auto-y` restores
   the 0 baseline. Bars always anchor at 0 and ignore the flag.
-- Legend is always shown (no option needed)
+- `title` directive removed — the chart title is line 1 (`bar My Chart`). Using
+  `title` raises an error diagnostic.
+- Legend shows by default whenever the chart is multi-series; suppress it with
+  the universal `no-legend` flag (§1.8). Single-series charts render no legend,
+  and take the flag as a no-op.
 
 **Value-display flags — show-everything default.** Every renderable part is on by default. Suppress with `no-*`:
 
@@ -2557,12 +2590,12 @@ Group a run of events into a labeled section with a `[Name]` bracket, then **ind
     Tim Berners-Lee publishes the first site.
   1993 Mosaic  t: Browser
 
-[The App Era] collapsed: true
+[The App Era] collapsed
   2005 Ajax  t: Platform
 ```
 
-- **Trailing metadata** after `]` — optional `collapsed: true` and/or a named color (`[The 1960s] collapsed: true blue`).
-- **`collapsed: true`** folds the era into a single summary card (its name + a bulleted list of member events) while a bracket stays on the spine; in the app a reader toggles it live.
+- **Trailing tokens** after `]` — an optional bare `collapsed` flag (§1.8) and/or a named color, in either order (`[The 1960s] collapsed blue`). Legacy: `collapsed: true`.
+- **`collapsed`** folds the era into a single summary card (its name + a bulleted list of member events) while a bracket stays on the spine; in the app a reader toggles it live.
 
 #### Directives
 
@@ -2672,7 +2705,7 @@ main
 
 #### Directives
 
-- `direction LR|TB|BT` — `LR` default (newest right); `TB`/`BT` is the git-log column view.
+- `direction-lr` / `direction-tb` — booleans, last one wins; `direction-lr` is the `LR` default (newest right), `direction-tb` the git-log column view. Key+value `direction LR|TB` accepted legacy.
 - `no-labels` (hide messages), `no-lanes` (hide branch lanes), `no-head`.
 
 ### 16.5 Venn Diagrams
@@ -2751,7 +2784,7 @@ Development p: High
     Auth System
       description: Login, signup, OAuth
     Dashboard
-  Nice-to-haves p: Low, collapsed: true
+  Nice-to-haves p: Low collapsed
     Dark Mode
 ```
 
@@ -2810,16 +2843,16 @@ Auth System
 
 Same-line metadata uses the universal `key: value, key2: value2` form (§1.4). Recognized keys:
 
-| Key                         | Effect                                   |
-| --------------------------- | ---------------------------------------- |
-| `description`               | Description text (see above).            |
-| `collapsed`                 | `true` collapses the subtree by default. |
-| Tag alias (e.g. `p:`, `d:`) | Assigns the node to a tag-group value.   |
+| Key                         | Effect                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------- |
+| `description`               | Description text (see above).                                                      |
+| `collapsed`                 | Legacy `collapsed: true` — canonical is the bare trailing `collapsed` flag (§1.8). |
+| Tag alias (e.g. `p:`, `d:`) | Assigns the node to a tag-group value.                                             |
 
 ```
 Task p: High, d: Engineering
 Demo Video description: 2-min product walkthrough
-Nice-to-haves p: Low, collapsed: true
+Nice-to-haves p: Low collapsed
 ```
 
 ### Node color
@@ -2840,19 +2873,19 @@ Polish UX p: Medium
 
 ### Collapse
 
-Any node with children may be collapsed. Set `collapsed: true` in same-line metadata to make a subtree start collapsed; collapsed nodes render with an accent drill-bar so they remain discoverable. Collapse is **portable view-state** — because `collapsed: true` lives in the source, every renderer (app, `dgmo` CLI, remark-dgmo, Obsidian, code-fence embeds) reproduces the collapsed view from the `.dgmo` alone; in the app, collapsing/expanding a node writes/removes the marker in the source (source stays the single source of truth), and a runtime `viewState.cg` from a share-link is applied in addition to source markers.
+Any node with children may be collapsed. Add a bare `collapsed` trailing flag to the node line (§1.8) to make a subtree start collapsed (legacy: `collapsed: true` in same-line metadata); collapsed nodes render with an accent drill-bar so they remain discoverable. The flag is case-sensitive lowercase — a node actually named "… Collapsed" (capitalized) or a quoted name keeps the word as label text. Collapse is **portable view-state** — because the `collapsed` marker lives in the source, every renderer (app, `dgmo` CLI, remark-dgmo, Obsidian, code-fence embeds) reproduces the collapsed view from the `.dgmo` alone; in the app, collapsing/expanding a node writes/removes the marker in the source (source stays the single source of truth), and a runtime `viewState.cg` from a share-link is applied in addition to source markers.
 
 ```
-Nice-to-haves p: Low, collapsed: true
+Nice-to-haves p: Low collapsed
   Dark Mode
   Export PDF
 ```
 
 ### Options
 
-| Option                 | Effect                             |
-| ---------------------- | ---------------------------------- |
-| `active-tag GroupName` | Sets the default active tag group. |
+| Option                 | Effect                                                               |
+| ---------------------- | -------------------------------------------------------------------- |
+| `active-tag GroupName` | Sets the default active tag group.                                   |
 | `color-by-depth`       | Bare flag; colour nodes by depth instead of by tag (off by default). |
 
 Universal options (`palette`, `theme`) apply as elsewhere.
@@ -3067,6 +3100,10 @@ Further-indented lines below a blip. Supports inline markdown (bold, italic, cod
 
 Blips receive sequential global numbers. Order: quadrants clockwise (top-left → top-right → bottom-right → bottom-left), then by ring (innermost first), then declaration order.
 
+### Directives
+
+- `no-blip-legend` — suppress the four-column blip listing. The listing renders by default on every surface (export and live/interactive alike). Legacy `show-blip-legend` is accepted as a no-op.
+
 ---
 
 ## 21. Cycle Diagrams
@@ -3459,8 +3496,8 @@ Indented lines under a layer are description text. Markdown inline formatting is
 
 ### Directives
 
-| Directive    | Effect                                                               |
-| ------------ | -------------------------------------------------------------------- |
+| Directive                     | Effect                                                                                               |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
 | `fill-solid` / `fill-outline` | Render rings with full intent color, or outline-only, instead of the default 25% tint (fill family). |
 
 `inverted` is **not** valid on ring diagrams (rings are rotationally symmetric). Using it emits an error-severity diagnostic and the line is discarded.
@@ -3526,13 +3563,13 @@ Operations t: Ops
 
 ### Color modes
 
-Three modes, with the source-declared default selected as **tag → heat → branch** (the desktop app adds a runtime switcher that previews the others without editing source):
+Three modes, with the source-declared default selected as **heat → tag → branch** — the universal precedence shared with map and boxes-and-lines. The `active-tag` directive pre-selects a dimension from source; the desktop app adds a runtime switcher that previews the others without editing source:
 
-| Mode       | When it's the default       | Coloring                                                      |
-| ---------- | --------------------------- | ------------------------------------------------------------ |
-| **tag**    | a `tag` group is declared   | categorical color per tag value (legend hover-dims)          |
-| **heat**   | any `heat:` value / `heat` directive | value ramp over a second per-node `heat:` metric    |
-| **branch** | neither tags nor heat        | each top-level branch a distinct hue, tinted with depth      |
+| Mode       | When it's the default                   | Coloring                                                |
+| ---------- | --------------------------------------- | ------------------------------------------------------- |
+| **heat**   | any `heat:` value / `heat` directive    | value ramp over a second per-node `heat:` metric        |
+| **tag**    | a `tag` group is declared (and no heat) | categorical color per tag value (legend hover-dims)     |
+| **branch** | neither tags nor heat                   | each top-level branch a distinct hue, tinted with depth |
 
 ### Tags
 
@@ -3544,29 +3581,29 @@ Add a per-node `heat:` number (a second metric, distinct from size; negatives/fl
 
 ### Node Metadata
 
-| Key     | Type            | Default | Description                                  |
-| ------- | --------------- | ------- | -------------------------------------------- |
-| `heat`  | number          | —       | Color-by-value metric (signed / float ok)    |
-| `<tag>` | declared value  | —       | Tag value via the group's alias or name      |
+| Key     | Type           | Default | Description                               |
+| ------- | -------------- | ------- | ----------------------------------------- |
+| `heat`  | number         | —       | Color-by-value metric (signed / float ok) |
+| `<tag>` | declared value | —       | Tag value via the group's alias or name   |
 
 ### Directives
 
-| Directive       | Effect                                                                                  |
-| --------------- | --------------------------------------------------------------------------------------- |
-| `heat <Label>`  | Name (and optionally color) the value ramp; pairs with the `heat:` key.                 |
-| `depth N`       | Render N levels; deeper subtrees collapse to a drillable solid block (a render budget).  |
-| `other-below N` | Roll children under N% of their parent into a single hatched **Other** bucket (opt-in).  |
-| `no-values`     | Hide value labels.                                                                       |
-| `no-percent`    | Hide percentage labels.                                                                  |
-| `no-headers`    | Hide parent header bars (a no-op in `radial` mode).                                       |
-| `no-legend`     | Hide the legend.                                                                          |
-| `radial`        | Render as a **sunburst / hierarchical pie** (concentric rings) instead of rectangles.    |
+| Directive                             | Effect                                                                                                                                                                                                                                             |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `heat <Label>`                        | Name (and optionally color) the value ramp; pairs with the `heat:` key.                                                                                                                                                                            |
+| `active-tag <GroupName \| HeatLabel>` | Pre-select the resting color dimension from source: a tag group name for categorical fill, or the heat ramp's label (`Value` if unnamed) for the ramp. `active-tag none` forces branch mode. The app's runtime switcher still previews the others. |
+| `depth N`                             | Render N levels; deeper subtrees collapse to a drillable solid block (a render budget).                                                                                                                                                            |
+| `no-value`                            | Hide value labels.                                                                                                                                                                                                                                 |
+| `no-percent`                          | Hide percentage labels.                                                                                                                                                                                                                            |
+| `no-headers`                          | Hide parent header bars (a no-op in `radial` mode).                                                                                                                                                                                                |
+| `no-legend`                           | Hide the legend.                                                                                                                                                                                                                                   |
+| `radial`                              | Render as a **sunburst / hierarchical pie** (concentric rings) instead of rectangles.                                                                                                                                                              |
 
 Numbers auto-compact (1.2M, 940k). Units live in the title — there is no format/currency directive.
 
 ### Radial mode (sunburst / hierarchical pie)
 
-Add a bare `radial` flag and the same hierarchy renders as a sunburst: the center disc is the whole (chart title + grand total), the first ring is the top-level groups, and each outer ring breaks a group into its parts. Tags, `heat`, and `no-values`/`no-percent`/`no-legend` all carry over; `no-headers` is a no-op. An arc's angle is its share of the whole; radius is depth only, so slices stay in **source order** and very thin arcs drop their inline label. Best for shallow trees (≈3 levels); for deep trees or precise magnitude, prefer the rectangular treemap.
+Add a bare `radial` flag and the same hierarchy renders as a sunburst: the center disc is the whole (chart title + grand total), the first ring is the top-level groups, and each outer ring breaks a group into its parts. Tags, `heat`, and `no-value`/`no-percent`/`no-legend` all carry over; `no-headers` is a no-op. An arc's angle is its share of the whole; radius is depth only, so slices stay in **source order** and very thin arcs drop their inline label. Best for shallow trees (≈3 levels); for deep trees or precise magnitude, prefer the rectangular treemap.
 
 ```dgmo
 treemap Plunder Spend ($k)
@@ -3656,18 +3693,18 @@ For an **uneven** span (a block covering some but not all columns), use the same
 
 ### Node Metadata
 
-| Key       | Type           | Default | Description                                   |
-| --------- | -------------- | ------- | --------------------------------------------- |
-| `span`    | integer ≥ 1    | 1       | Column span (clamps to the column count)      |
-| `collapsed` | flag         | —       | Start this container folded (collapse-bar)    |
-| `<tag>`   | declared value | —       | Tag value via the group's alias or name       |
+| Key         | Type           | Default | Description                                |
+| ----------- | -------------- | ------- | ------------------------------------------ |
+| `span`      | integer ≥ 1    | 1       | Column span (clamps to the column count)   |
+| `collapsed` | flag           | —       | Start this container folded (collapse-bar) |
+| `<tag>`     | declared value | —       | Tag value via the group's alias or name    |
 
 ### Directives
 
-| Directive    | Effect                                                             |
-| ------------ | ----------------------------------------------------------------- |
-| `columns N`  | Override the inferred column count for a grid.                     |
-| `no-legend`  | Hide the tag legend.                                               |
+| Directive   | Effect                                         |
+| ----------- | ---------------------------------------------- |
+| `columns N` | Override the inferred column count for a grid. |
+| `no-legend` | Hide the tag legend.                           |
 
 ### Interactivity vs export
 
@@ -3733,18 +3770,18 @@ Indented under the source shape, targeting an alias (or an unambiguous bare labe
 
 ### Node Metadata
 
-| Key       | Type           | Default   | Description                                     |
-| --------- | -------------- | --------- | ----------------------------------------------- |
-| `shape`   | closed set     | rectangle | `database` / `queue` / `cloud` / `person` / `document` / `note` |
-| `at`      | `C R` integers | flow-placed | Half-slot position (origin-normalized)        |
-| `collapsed` | flag         | —         | Box only — start folded (collapse-bar)          |
-| `<tag>`   | declared value | untagged (neutral gray) | Tag value (cascades from box; edge tails color the line) |
+| Key         | Type           | Default                 | Description                                                     |
+| ----------- | -------------- | ----------------------- | --------------------------------------------------------------- |
+| `shape`     | closed set     | rectangle               | `database` / `queue` / `cloud` / `person` / `document` / `note` |
+| `at`        | `C R` integers | flow-placed             | Half-slot position (origin-normalized)                          |
+| `collapsed` | flag           | —                       | Box only — start folded (collapse-bar)                          |
+| `<tag>`     | declared value | untagged (neutral gray) | Tag value (cascades from box; edge tails color the line)        |
 
 ### Directives
 
-| Directive    | Effect                  |
-| ------------ | ----------------------- |
-| `no-legend`  | Hide the tag legend.    |
+| Directive   | Effect               |
+| ----------- | -------------------- |
+| `no-legend` | Hide the tag legend. |
 
 ### Interactivity vs export
 
@@ -3757,7 +3794,7 @@ In the desktop and web app a sketch opens in the **canvas editor** (the code pan
 <!-- TYPE:goal -->
 
 <!-- TIPS start -->
-**Styling tips:** A single progress-toward-a-target reading — one `now` against one `target`, answering "how close am I?". Reach for it for a KPI tile, a fundraising thermometer, a quarterly quota, or a completion percentage; there is no time axis, series, or milestones (use `line` for a trend, `countdown` for a live deadline). Put the **unit in the title** (`Marathon Fund ($)`, `Grog Barrel Fill (L)`) — there is no format/currency directive. `now` and `target` are **space-separated `key value`** directives, no colon (`now 6400` / `target 10000`); the percent is `now / target` and values auto-compact (`6.4k`, `1.2M`). Pick the face for the story with a bare flag on its own line: the default progress **bar** for a plain KPI, `thermometer` for fundraising/fill-the-tank framings, `gauge` for a speedometer/quota dial — all three read the same value pair. The fill is **auto traffic-light** by completion (`< 50%` red, `50–80%` orange, `≥ 80%` green; over-target stays green) so the color already reads the number's health — leave it unless you have reason to override with a trailing color on the title line (`goal Marathon Fund ($) green`) or `no-auto-color` (flat palette color). Over-target clamps the fill at 100% while the `%` label stays truthful (`120%`). Add a `note` — inline (`note Still waiting on three crews`) or a block header on its own line with an indented body — to caption the number with context (who's still owed, what's left); it takes simple markdown (`**bold**`, `*italic*`, `` `code` ``) and `- ` bullets. `fill-solid` for a bolder fill; `no-percent` / `no-value` / `no-title` / `no-note` to drop labels.
+**Styling tips:** A single progress-toward-a-target reading — one `now` against one `target`, answering "how close am I?". Reach for it for a KPI tile, a fundraising thermometer, a quarterly quota, or a completion percentage; there is no time axis, series, or milestones (use `line` for a trend, `countdown` for a live deadline). Put the **unit in the title** (`Marathon Fund ($)`, `Grog Barrel Fill (L)`) — there is no format/currency directive. `now` and `target` are **space-separated `key value`** directives, no colon (`now 6400` / `target 10000`); the percent is `now / target` and values auto-compact (`6.4k`, `1.2M`). Pick the face for the story with a bare flag on its own line: the default progress **bar** for a plain KPI, `thermometer` for fundraising/fill-the-tank framings, `gauge` for a speedometer/quota dial — all three read the same value pair. The fill is **auto traffic-light** by completion (`< 50%` red, `50–80%` orange, `≥ 80%` green; over-target stays green) so the color already reads the number's health — leave it unless you have reason to override with a trailing color on the title line (`goal Marathon Fund ($) green`) or `no-auto-color` (flat palette color). Over-target clamps the fill at 100% while the `%` label stays truthful (`120%`). Add a `note` — inline (`note Still waiting on three crews`) or a block header on its own line with an indented body — to caption the number with context (who's still owed, what's left); it takes simple markdown (`**bold**`, `*italic*`, `` `code` ``) and `- ` bullets. `fill-solid` for a bolder fill; `no-percent` / `no-value` / `no-title` / `no-notes` to drop labels.
 <!-- TIPS end -->
 
 A single progress-toward-a-target value: one `now` measured against one `target`, drawn in one of three static faces. No time axis, no series, no milestones — just "how close am I?". The face is a bare-flag mode directive under the title (like treemap's `radial`); all three faces consume the same value pair.
@@ -3785,18 +3822,18 @@ target 10000
 
 ### Directives
 
-| Directive              | Effect                                                        |
-| ---------------------- | ------------------------------------------------------------- |
-| `thermometer` / `gauge`| Select the render face (bare flag; omit for the progress bar). |
-| `now <number>`         | Current value (required; may exceed the target).              |
-| `target <number>`      | Goal value (required; must be > 0).                           |
-| `no-percent`           | Hide the `%` label.                                           |
-| `no-value`             | Hide the raw `now / target` label.                            |
-| `fill-solid`           | Full-saturation fill instead of the default 25% tint (`fill-outline` hollows the meter — color on the rim). |
-| `no-title`             | Hide the banner title.                                        |
-| `no-note`              | Suppress the `note` block even if one is authored.           |
-| `no-auto-color`        | Disable the traffic-light bands; use the flat palette color.  |
-| `note <text>` / `note` + indented body | Free-text caption beside/below the face (§ note block). |
+| Directive                              | Effect                                                                                                      |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `thermometer` / `gauge`                | Select the render face (bare flag; omit for the progress bar).                                              |
+| `now <number>`                         | Current value (required; may exceed the target).                                                            |
+| `target <number>`                      | Goal value (required; must be > 0).                                                                         |
+| `no-percent`                           | Hide the `%` label.                                                                                         |
+| `no-value`                             | Hide the raw `now / target` label.                                                                          |
+| `fill-solid`                           | Full-saturation fill instead of the default 25% tint (`fill-outline` hollows the meter — color on the rim). |
+| `no-title`                             | Hide the banner title.                                                                                      |
+| `no-notes`                             | Suppress the `note` block even if one is authored.                                                          |
+| `no-auto-color`                        | Disable the traffic-light bands; use the flat palette color.                                                |
+| `note <text>` / `note` + indented body | Free-text caption beside/below the face (§ note block).                                                     |
 
 ### Note block
 
@@ -3813,7 +3850,7 @@ note
   - Columbus — *almost there!*
 ```
 
-The body supports inline `**bold**` / `*italic*` / `` `code` ``, `- `/`* ` bullets, and blank-line gaps. It renders in the left column for `thermometer`/`gauge` and under the bar for the default face. `no-note` hides it even when authored.
+The body supports inline `**bold**` / `*italic*` / `` `code` ``, `- `/`* ` bullets, and blank-line gaps. It renders in the left column for `thermometer`/`gauge` and under the bar for the default face. `no-notes` hides it even when authored.
 
 ### Values & color
 
@@ -3830,10 +3867,10 @@ Percent is `now / target`. Over-target clamps the fill at 100% while the `%` lab
 <!-- TYPE:countdown -->
 
 <!-- TIPS start -->
-**Styling tips:** The only dynamic chart — it ticks every second and is accurate on every load, so use it for a live "N days until X" widget, not a static report. Keep the title to the event (`Trip to Japan`); the target date renders as a caption automatically. `target` is a space-separated `key value` directive (no colon): a bare date (`2026-08-21`) counts to midnight, a datetime or offset is honored. By default those times are **viewer-local** — each person sees their own; add `tz America/New_York` (any IANA zone, no colon) to **pin** the count so a shared launch/livestream page shows everyone the same remaining time and it doesn't shift when you carry the laptop to another zone. Default `units days` reads best for weeks/months out; use `units full` for a launch-day `Nd HH:MM:SS` clock. Set `expired` to the celebration text (`🚀 Shipped!`); after the target passes every live surface shows it and the tick stops. On images (PNG export, `.svg` via `<img>`, GitHub camo) it can't tick and shows the whole-day count baked at export time — the correct fallback.
+**Styling tips:** The only dynamic chart — it ticks every second and is accurate on every load, so use it for a live "N days until X" widget, not a static report. Keep the title to the event (`Trip to Japan`); the target date renders as a caption automatically. `target` is a space-separated `key value` directive (no colon): a bare date (`2026-08-21`) counts to the viewer's local midnight, a datetime or offset is honored. Default `units days` reads best for weeks/months out; use `units full` for a launch-day `Nd HH:MM:SS` clock. Set `expired` to the celebration text (`🚀 Shipped!`); after the target passes every live surface shows it and the tick stops. On images (PNG export, `.svg` via `<img>`, GitHub camo) it can't tick and shows the whole-day count baked at export time — the correct fallback.
 <!-- TIPS end -->
 
-The only *dynamic* dgmo chart: a single "N days until X" recomputed against the viewer's clock on every load and ticking every second on any live surface. Distinct from `goal` (static) — a countdown has no `now`/`target` pair, just one future instant. The renderer bakes a whole-day fallback number (the no-JS floor); a tiny page-level ticker overwrites it live and, in `units full`, upgrades it to `Nd HH:MM:SS`.
+The only _dynamic_ dgmo chart: a single "N days until X" recomputed against the viewer's clock on every load and ticking every second on any live surface. Distinct from `goal` (static) — a countdown has no `now`/`target` pair, just one future instant. The renderer bakes a whole-day fallback number (the no-JS floor); a tiny page-level ticker overwrites it live and, in `units full`, upgrades it to `Nd HH:MM:SS`.
 
 ### Declaration
 
@@ -3855,12 +3892,12 @@ target 2026-08-21
 
 ### Directives
 
-| Directive               | Effect                                                                 |
-| ----------------------- | ---------------------------------------------------------------------- |
-| `target <iso>`          | The future instant (required). `2026-08-21`, `2026-08-21T18:00`, or with a tz offset. The literal `now` resolves at render (→ immediately expired; for testing). |
-| `tz <IANA>`             | Pin authored times to a zone (`America/New_York`, `Asia/Kolkata`, `UTC`) so the count is the **same for every viewer** and doesn't drift when the host moves zones. Default viewer-local. Footer then shows the in-zone time + a `UTC±` tag. |
-| `units <days\|full>`    | `days` (default) shows whole days (ceil); `full` ticks `Nd HH:MM:SS` on live surfaces. |
-| `expired <text>`        | Shown once the target passes; the tick stops. Default `"Now!"`.        |
+| Directive            | Effect                                                                                                                                                                                                                                       |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `target <iso>`       | The future instant (required). `2026-08-21`, `2026-08-21T18:00`, or with a tz offset. The literal `now` resolves at render (→ immediately expired; for testing).                                                                             |
+| `tz <IANA>`          | Pin authored times to a zone (`America/New_York`, `Asia/Kolkata`, `UTC`) so the count is the **same for every viewer** and doesn't drift when the host moves zones. Default viewer-local. Footer then shows the in-zone time + a `UTC±` tag. |
+| `units <days\|full>` | `days` (default) shows whole days (ceil); `full` ticks `Nd HH:MM:SS` on live surfaces.                                                                                                                                                       |
+| `expired <text>`     | Shown once the target passes; the tick stops. Default `"Now!"`.                                                                                                                                                                              |
 
 ### Values & color
 
@@ -3868,7 +3905,7 @@ A bare `YYYY-MM-DD` counts to **midnight** and a datetime with no offset to that
 
 ### Semantics
 
-Days mode uses `ceil` — a target later *today* reads "1 day", not "0". Full mode floors the days and shows `HH:MM:SS` for the remainder. Once the target passes, the `expired` text replaces the number and that node stops ticking (no negative counts). Live surfaces recompute from the absolute target on every load/route-change/note-open, so there is **no persisted state** and no drift; image surfaces (PNG, `.svg`-as-image, GitHub camo) show the whole-day count baked at export time.
+Days mode uses `ceil` — a target later _today_ reads "1 day", not "0". Full mode floors the days and shows `HH:MM:SS` for the remainder. Once the target passes, the `expired` text replaces the number and that node stops ticking (no negative counts). Live surfaces recompute from the absolute target on every load/route-change/note-open, so there is **no persisted state** and no drift; image surfaces (PNG, `.svg`-as-image, GitHub camo) show the whole-day count baked at export time.
 
 ---
 
@@ -3877,10 +3914,10 @@ Days mode uses `ceil` — a target later *today* reads "1 day", not "0". Full mo
 <!-- TYPE:clock -->
 
 <!-- TIPS start -->
-**Styling tips:** A live world clock — one panel per person or place, each showing the CURRENT time in its zone and ticking every second, accurate the instant the page loads. Reach for it to answer "what time is it for the crew right now": a distributed team's local times, a single collaborator's clock, or the overlap window for scheduling a call. The first line declares the type and a title (`Crew standups`). Each entry is one line, `<anchor> [as <label>] [color]`: name the zone once as the anchor — a plain **city name** (`London`, `NYC`, `Bombay`, `Los Angeles` — easiest, resolved through the bundled gazetteer to its canonical zone and displayed as the canonical city), a full **IANA id** (the token containing `/`, like `Europe/London` or `America/New_York`), or a **UTC/GMT offset** (`UTC`, `UTC+1`, `UTC+5:30`, `GMT+2`) which pins a **fixed** offset with no daylight-saving shift (bare `UTC`/`GMT` = +00:00, and no sun line). Use `as <label>` to name the person or role behind a zone (`New York as Dani (NY)`); the label becomes the caption and defaults to the resolved city (or the offset label for a fixed row). The single-clock case is common and encouraged — one title, one entry (`clock Dani` / `New York`). Global directives are flat, no colon: `analog` for analog dials (digital is the default face), `time-24` for a 24-hour readout (12h am/pm is the default), and optional context bands `hours 9-17` + `days mon-fri` (the window accepts `HH:MM` and am/pm, e.g. `hours 8:30-17:15`) to shade each zone's working window so out-of-hours people read at a glance. `no-sun` hides the sunrise/sundown indicator (on by default). Add `hours`/`days` only when the point is scheduling overlap; drop them for a plain "current time" widget. Zones are **colorized by default** (`color-by`, default `place` — a distinct palette accent per place); reach for a semantic mode when color should *mean* something: `color-by time` or `color-by daylight` make an at-a-glance world board read as day-vs-night (order the zones west→east so the daylight sweeps across), and `color-by work` turns a standup/team board green/amber/grey by availability — it needs `hours` set. A hand-set per-zone color (`London as UK team purple`, or just `London purple`) is a **defined** shade that always wins over the dimension, so you can pin one zone and let the rest follow. `color-by none` goes neutral. On image surfaces (PNG, `.svg` via `<img>`, GitHub camo) it can't tick and bakes the time at export — the correct graceful fallback.
+**Styling tips:** A live world clock — one panel per person or place, each showing the CURRENT time in its zone and ticking every second, accurate the instant the page loads. Reach for it to answer "what time is it for the crew right now": a distributed team's local times, a single collaborator's clock, or the overlap window for scheduling a call. The first line declares the type and a title (`Crew standups`). Each entry is one line, `<anchor> [as <label>]`, where the **anchor** names the zone in one of three forms (first match wins): (1) a **city name** resolved through a built-in gazetteer — just write it the way you'd say it (`London`, `New York`, `Los Angeles`, `Tokyo`, and aliases like `NYC`/`LA`/`Bombay`) — this is the easiest and preferred form; (2) an explicit **IANA id** containing a `/` (`Europe/London`, `America/New_York`) for anything ambiguous or obscure; (3) a raw **UTC offset** (`UTC`, `UTC+5:30`, `UTC-7`, `GMT+2`) — a FIXED offset that does not track daylight saving, so it renders with a small "no DST" marker and no sunrise line (use it for `UTC` itself or regions that don't shift, e.g. India `UTC+5:30`). You name the zone ONCE — do NOT write a place and an IANA zone as two tokens. Use `as <label>` to name the person or role (`New York as Dani (NY)`); the label becomes the caption and defaults to the resolved city. The single-clock case is common and encouraged — one title, one entry (`clock Dani` / `New York`). An ambiguous city (e.g. `San Jose`) errors listing the candidate zones; an unknown place is skipped with a did-you-mean. Global directives are flat, no colon: `analog` for analog dials (digital is the default face), `time-24` for a 24-hour readout (12h am/pm is the default), and optional context bands `hours 9-17` + `workweek mon-fri` (the window accepts `HH:MM` and am/pm, e.g. `hours 8:30-17:15`) to shade each zone's working window so out-of-hours people read at a glance. `no-sun` hides the sunrise/sundown indicator (on by default). Add `hours`/`workweek` only when the point is scheduling overlap; drop them for a plain "current time" widget. Zones are **colorized by default** (`color-by`, default `place` — a distinct palette accent per place); reach for a semantic mode when color should *mean* something: `color-by time` or `color-by daylight` make an at-a-glance world board read as day-vs-night (order the zones west→east so the daylight sweeps across), and `color-by work` turns a standup/team board green/amber/grey by availability — it needs `hours` set. A hand-set per-zone color (`London as UK team purple`) is a **defined** shade that always wins over the dimension, so you can pin one zone and let the rest follow. `color-by none` goes neutral. On image surfaces (PNG, `.svg` via `<img>`, GitHub camo) it can't tick and bakes the time at export — the correct graceful fallback.
 <!-- TIPS end -->
 
-The second *dynamic* dgmo chart (with `countdown`): a live board of world clocks recomputed against the viewer's clock every second. Flat syntax — the first line is `clock <Title>`; every other non-blank line is either a board-level directive (its first token is an option keyword) or a place row. Order-independent; no colons anywhere.
+The second _dynamic_ dgmo chart (with `countdown`): a live board of world clocks recomputed against the viewer's clock every second. Flat syntax — the first line is `clock <Title>`; every other non-blank line is either a board-level directive (its first token is an option keyword) or a place row. Order-independent; no colons anywhere.
 
 ### Declaration
 
@@ -3889,11 +3926,11 @@ clock [Title]
 
 analog                      // analog dials; digital is the default face
 hours <start>-<end>         // optional working window (24h, HH:MM or am/pm)
-days <mon-fri | mon,wed,fri> // optional working days (default mon-fri)
+workweek <mon-fri | mon,wed,fri> // optional working days (default mon-fri)
 no-sun                      // hide the sundown/sunrise line (on by default)
 time-24                     // 24-hour readout (12h am/pm is the default)
 no-title                    // suppress the board title
-direction lr                // lay the panels out in a row
+direction-lr                // lay the panels out in a row (columns); direction-tb restates the default rows
 color-by <place|work|daylight|time|none> // zone coloring; default place
 
 <anchor> [as <label…>] [color]
@@ -3904,7 +3941,7 @@ color-by <place|work|daylight|time|none> // zone coloring; default place
 ```
 clock Crew standups
 hours 9-17
-days mon-fri
+workweek mon-fri
 
 London        as UK team
 New York      as Dani (NY)
@@ -3924,15 +3961,15 @@ UTC           as Servers
 
 ### Directives
 
-| Directive              | Effect                                                                 |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `analog`               | Analog dials for the WHOLE board. Digital is the default face. |
-| `hours <start>-<end>`  | Working window (e.g. `9-17`, `8:30-17:15`, or am/pm); drives the status chip, evaluated in each row's own zone. |
-| `days <range\|list>`   | Working days: `mon-fri` or `mon,wed,fri`. Default Mon–Fri. No effect without `hours`. |
-| `no-sun`               | Hide the sundown/sunrise line (on by default when the zone's city coordinates are known). |
-| `time-24`              | 24-hour readout (12-hour am/pm is the default).                        |
-| `no-title`             | Suppress the board title.                                              |
-| `direction lr`         | Lay the panels out in a row (columns) instead of stacked.             |
+| Directive                                      | Effect                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `analog`                                       | Analog dials for the WHOLE board. Digital is the default face.                                                                                                                                                                                                                                                                                                 |
+| `hours <start>-<end>`                          | Working window (e.g. `9-17`, `8:30-17:15`, or am/pm); drives the status chip, evaluated in each row's own zone.                                                                                                                                                                                                                                                |
+| `workweek <range\|list>`                       | Working days: `mon-fri` or `mon,wed,fri`. Default Mon–Fri. No effect without `hours`.                                                                                                                                                                                                                                                                          |
+| `no-sun`                                       | Hide the sundown/sunrise line (on by default when the zone's city coordinates are known).                                                                                                                                                                                                                                                                      |
+| `time-24`                                      | 24-hour readout (12-hour am/pm is the default).                                                                                                                                                                                                                                                                                                                |
+| `no-title`                                     | Suppress the board title.                                                                                                                                                                                                                                                                                                                                      |
+| `direction-lr`                                 | Lay the panels out in a row (columns) instead of stacked; `direction-tb` restates the default rows. Key+value `direction lr                                                                                                                                                                                                                                    | tb`(and`direction columns`) accepted legacy. |
 | `color-by <place\|work\|daylight\|time\|none>` | Which dimension colors the zones. Default `place`; `color-by none` goes neutral. `place` = identity accent per place; `work` = green/amber/grey by the `hours` window; `daylight` = warm sun-up / cool sun-down; `time` = local-hour dawn→night ramp (order zones west→east). A hand-set (**defined**) per-zone trailing color always wins over the dimension. |
 
 ### Entry grammar
@@ -3985,18 +4022,18 @@ Black Pearl beats Salty Dog 6-5
 
 ### Directives
 
-| Directive                      | Effect                                                                       |
-| ------------------------------ | ---------------------------------------------------------------------------- |
-| `rounds A, B, C`               | Name the columns entry-round → inner (or an indented block with per-round `Name color`); absent → generic `Round N` / `Final`. |
-| `seed N [Name] [k: v]`         | Declare a seeded entrant → seeded mode + day-0 skeleton (top seeds get byes); trailing `k: v` tags the team. |
-| `tag Group [as g]`             | Tag group (block/kanban idiom) — a competitor's tag value colors its box outline; a legend renders. |
-| `[Side] [color]`               | A bracket column (kanban idiom); two sides mirror to a center championship.   |
-| `[Winner] beats [Loser] [score] [@ Home]` | A decided match — the left name advances; score is cosmetic; `@ Home` marks the host. Indent prose under it for commentary. |
-| `[A] vs [B]`                   | A pending, undecided match (both boxes drawn, no winner emphasis).            |
-| `accent <color>`               | Winner accent color override (default blue). Tags/sides still win per-box.    |
-| `no-round`                     | Suppress the round/column labels.                                            |
-| `no-legend`                    | Hide the tag legend (outlines still colored).                               |
-| `single-elim` / `double-elim` / `seeded` | Format flags. `double-elim` reserved — not yet supported; `seeded` forces seeded mode. |
+| Directive                                 | Effect                                                                                                                                                                                                                           |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rounds A, B, C`                          | Name the columns entry-round → inner (or an indented block with per-round `Name color`); absent → generic `Round N` / `Final`.                                                                                                   |
+| `seed N [Name] [k: v]`                    | Declare a seeded entrant → seeded mode + day-0 skeleton (top seeds get byes); trailing `k: v` tags the team.                                                                                                                     |
+| `tag Group [as g]`                        | Tag group (block/kanban idiom) — a competitor's tag value colors its box outline; a legend renders.                                                                                                                              |
+| `[Side] [color]`                          | A bracket column (kanban idiom); two sides mirror to a center championship.                                                                                                                                                      |
+| `[Winner] beats [Loser] [score] [@ Home]` | A decided match — the left name advances; score is cosmetic; `@ Home` marks the host. Indent prose under it for commentary.                                                                                                      |
+| `[A] vs [B]`                              | A pending, undecided match (both boxes drawn, no winner emphasis).                                                                                                                                                               |
+| trailing color on the title line          | Winner accent color override (default blue), e.g. `bracket Champions Cup red` (§1.5 title-line accent slot). Legacy `accent <color>` directive is accepted; the title-line token wins on conflict. Tags/sides still win per-box. |
+| `no-round`                                | Suppress the round/column labels.                                                                                                                                                                                                |
+| `no-legend`                               | Hide the tag legend (outlines still colored).                                                                                                                                                                                    |
+| `single-elim` / `double-elim` / `seeded`  | Format flags. `double-elim` reserved — not yet supported; `seeded` forces seeded mode.                                                                                                                                           |
 
 ### Semantics
 
@@ -4104,7 +4141,7 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 <!-- TYPE:map -->
 
 <!-- TIPS start -->
-**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map-search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin. **For a "what time is it at each office" map**, flag each POI with `clock` — the zone comes from the place automatically, so just `poi Denver clock`; add `hours 9-17` + `days mon-fri` for open/closed dots, and `clock: <IANA>` only on bare-coordinate pins. Use `label:` (not `as`) for a multi-word office name.
+**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map-search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
 <!-- TIPS end -->
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
@@ -4185,15 +4222,15 @@ Flag a POI with `clock` and it grows a **live local-time card** above the marker
 ```
 map Team offices
 hours 9-17                          # per-pin availability window (open/closed dot)
-days mon-fri
+workweek mon-fri
 poi San Francisco clock             # zone auto-derived from the place
 poi London clock
 poi Bengaluru clock
 poi 1.29 103.85 as SG clock: Asia/Singapore   # bare-coord pin names its zone
 ```
 
-- **The place picks the zone — don't type it.** A named city derives its IANA zone from the gazetteer (correct by construction, e.g. Austin → Central). Only a **bare-coordinate** pin needs the valued form `clock: <zone>` — an IANA id (`Asia/Tokyo`) or a fixed offset (`clock: UTC+9`, no DST). The valued form also *overrides* a city, but a mismatch warns (you almost never want it).
-- `hours 9-17` + `days mon-fri` (map-level) give a status dot per pin — green open / amber opening soon / hollow closed·weekend — evaluated in **each pin's own zone**.
+- **The place picks the zone — don't type it.** A named city derives its IANA zone from the gazetteer (correct by construction, e.g. Austin → Central). Only a **bare-coordinate** pin needs the valued form `clock: <zone>` — an IANA id (`Asia/Tokyo`) or a fixed offset (`clock: UTC+9`, no DST). The valued form also _overrides_ a city, but a mismatch warns (you almost never want it).
+- `hours 9-17` + `workweek mon-fri` (map-level) give a status dot per pin — green open / amber opening soon / hollow closed·weekend — evaluated in **each pin's own zone**.
 - Use `label:` for a multi-word office name (`poi Los Angeles clock, label: El Segundo`); the `as` alias is a single word and doesn't render.
 - The card ticks every second on live surfaces and bakes a snapshot for PNG/SVG. It shows the weekday only when the pin's day differs from the viewer's.
 
@@ -4212,12 +4249,12 @@ There is no header `style:` — bow a whole voyage by using `~>` on every leg.
 
 Native edges handle any other connection (no `link`/`leg` keyword). A token draws an arrowhead iff it ends in `>`, an arc iff it starts with `~`; drop the `>` for a plain line when an arrow would mislead. The label always sits between the delimiters:
 
-| | no label | labeled |
-|---|---|---|
-| directed straight | `A -> B` | `A -ships-> B` |
-| directed arc | `A ~> B` | `A ~trade~> B` |
-| undirected straight | `A -- B` | `A -ferry- B` |
-| undirected arc | `A ~~ B` | `A ~cable~ B` |
+|                     | no label | labeled        |
+| ------------------- | -------- | -------------- |
+| directed straight   | `A -> B` | `A -ships-> B` |
+| directed arc        | `A ~> B` | `A ~trade~> B` |
+| undirected straight | `A -- B` | `A -ferry- B`  |
+| undirected arc      | `A ~~ B` | `A ~cable~ B`  |
 
 ```
 A -> B                  # one-off, directed
@@ -4254,7 +4291,7 @@ cove -> hav l: March    # the LINE turns green
 - Title is the declaration line; `caption` (data-source attribution, travels with the exported PNG) is the only chrome directive. There is no `subtitle`.
 - Legend auto-composes below the title: the heat ramp + `region-heat` and each tag group are **selectable colouring groups** (collapse/activate to flip the fill); POI size (`poi-size`) and edge thickness (`flow-width`) are self-evident from scale and carry no legend key in v1. `no-legend` suppresses all of it.
 - **Region and POI labels are on by default.** Region labels auto-fit **full → abbrev → hide** (a US-state 2-letter abbreviation is tried when the full name doesn't fit; other regions degrade full → hide); POI labels are collision-managed. Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move. A wide map in a narrow column (< ~480px) prefers abbreviations and drops reference relief, as if zoomed out.
-- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`, `no-colorize`. A plain look = the four basemap flags together (`no-colorize` is **not** one of the four — it toggles region *fill style*, not a basemap backdrop layer).
+- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`, `no-colorize`. A plain look = the four basemap flags together (`no-colorize` is **not** one of the four — it toggles region _fill style_, not a basemap backdrop layer).
 - **Colorize (distinct political fills) is the default for any map without region data.** Unless a region carries data (a `heat:` or a tag), every region drawn at the resolved extent is filled a **distinct light pastel** such that no two bordering regions share a hue — the conventional "colour the countries/states so neighbours separate" look, with zero config. It applies to named-region maps, POI/route-only maps, and even a bare `map` (the whole world colours as the backdrop). The fills are **non-semantic** (no legend entry) and **extent-independent** (a region's colour is the same at any width and in an inset). A direct trailing colour (`Texas red`) paints on top as a highlight and does not suppress colorize; adding any `heat:`/tag flips the map to the data dress (colorize auto-suppressed, no error). `no-colorize` forces the plain green-land + blue-water dress — useful when many POIs/routes should pop against a calm map.
 
 ### Name resolution
@@ -4268,7 +4305,7 @@ cove -> hav l: March    # the LINE turns green
   - **Name + scope** (readable): `Georgia US heat: 5` → the state, `Georgia GE heat: 5` → the country.
   - The redundant `Georgia US-GA` still works but isn't needed (a mismatched code like `Georgia US-CA` is rejected). A bare ambiguous `Georgia` follows the inferred US-scope signal and warns with both fixes named.
 - **IATA airport codes** resolve to airport coordinates — `poi JFK`, `route JFK -> LAX` — with no new syntax (large international hubs + all US scheduled-commercial airports). Case-insensitive (`jfk`/`JFK`). Airports are the **lowest-precedence** identifier: a token that is both a city and a code resolves to the **city** (`Ufa` → the city, not UFA airport), with a hint naming the airport. Resolution is by **code only** (never by airport name); the POI label is the typed code. An unknown three-letter code errors with an `as <CODE>` coordinates hint.
-- **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that *did* resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
+- **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that _did_ resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
 - **Discover the exact token** with the lookup surface rather than guessing — `dgmo map-search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
 - Positional coordinates are the escape hatch for anything missing/ambiguous (including forcing an airport over a colliding city: `poi 54.56 55.87 as UFA`).
 
@@ -4301,23 +4338,23 @@ The directive set is **13, all colon-free**: six naming intent the renderer can'
 
 ### Colons NOT USED
 
-| Construct              | Diagram Type     | Example                               |
-| ---------------------- | ---------------- | ------------------------------------- |
-| Chart type declaration | all              | `bar Title`                           |
-| Tag declarations       | all              | `tag Name as x`                       |
-| Boolean options        | all              | `activations`, `no-activations`       |
-| Key-value options      | all              | `start 2026-03-15`, `active-tag Team` |
-| Series declarations    | data charts      | `series A B C`                        |
-| Data rows              | bar/line/pie/etc | `Label 100`                           |
-| ER columns             | er               | `id int pk`                           |
-| Sequence messages      | sequence         | `A -msg-> B`                          |
-| Groups/containers      | all              | `[Group Name]`                        |
-| Section dividers       | sequence         | `== Phase ==`                         |
-| Comments               | all              | `// comment`                          |
-| Wordcloud data         | wordcloud        | `swordsmanship 95`                    |
-| Slope data rows        | slope            | `Blackbeard 40 4`                     |
-| Slope period directive | slope            | `period 1715 1725`                    |
-| Venn intersections     | venn             | `sw + nav Sea Raiders`                |
+| Construct              | Diagram Type     | Example                                    |
+| ---------------------- | ---------------- | ------------------------------------------ |
+| Chart type declaration | all              | `bar Title`                                |
+| Tag declarations       | all              | `tag Name as x`                            |
+| Boolean options        | all              | `activations`, `no-activations`            |
+| Key-value options      | all              | `start-date 2026-03-15`, `active-tag Team` |
+| Series declarations    | data charts      | `series A B C`                             |
+| Data rows              | bar/line/pie/etc | `Label 100`                                |
+| ER columns             | er               | `id int pk`                                |
+| Sequence messages      | sequence         | `A -msg-> B`                               |
+| Groups/containers      | all              | `[Group Name]`                             |
+| Section dividers       | sequence         | `== Phase ==`                              |
+| Comments               | all              | `// comment`                               |
+| Wordcloud data         | wordcloud        | `swordsmanship 95`                         |
+| Slope data rows        | slope            | `Blackbeard 40 4`                          |
+| Slope period directive | slope            | `period 1715 1725`                         |
+| Venn intersections     | venn             | `sw + nav Sea Raiders`                     |
 
 ### The Rule
 
@@ -4332,7 +4369,7 @@ A colon binds a value, and it appears in exactly **four syntactic positions**
 
 **Colons never appear in:**
 
-- Directives and options — space-separated (`start 2026-03-15`, `x-label Low, High`, `region`)
+- Directives and options — space-separated (`start-date 2026-03-15`, `x-label Low, High`, `region`)
 - Tag declarations and chart type declarations
 - Series declarations and data rows for simple/data charts (incl. sankey/arc links `Source -> Target value` and quadrant data; space-delimited — a comma in a data-row value raises `E_DATA_COMMA_REMOVED`)
 - Structural syntax (groups, sections, arrows, comments)
@@ -4379,16 +4416,16 @@ API description: Main gateway
 
 Some constructs _look_ universal but are scoped to specific chart types. Don't transplant them across charts.
 
-| Construct                                     | Scope                                                                                                                    |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `collapsed: true` metadata                    | sequence, infra, mindmap, pert                                                                                           |
-| Same-line / indented metadata on declarations | all chart types except flowchart, state, data charts (§1.4)                                                              |
-| Trailing-keyword flag list                    | wireframe only (§19)                                                                                                     |
-| `progress: <N>` key                           | gantt only (§13)                                                                                                         |
-| `score: <N>` + `emotion: <Word>` keys         | journey-map only (§22)                                                                                                   |
-| `description: <text>` shorthand for layers    | pyramid, ring (§23, §24)                                                                                                 |
-| `milestone` keyword                           | **removed** — use `<name> 0` (§13A)                                                                                      |
-| `\|` operator as metadata delimiter           | **removed** (§1.4). Surviving uses: wireframe `{A \| B}` braces, in-arrow `A -file\|name-> B`, quoted `"Order \| Items"` |
+| Construct                                     | Scope                                                                                                                                     |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Bare `collapsed` trailing flag (§1.8)         | sequence, infra, gantt, kanban, mindmap, pert, state, c4, event-line (eras), block, sketch, wireframe. Legacy: `collapsed: true` metadata |
+| Same-line / indented metadata on declarations | all chart types except flowchart, state, data charts (§1.4)                                                                               |
+| Trailing-keyword flag list                    | wireframe only (§19)                                                                                                                      |
+| `progress: <N>` key                           | gantt only (§13)                                                                                                                          |
+| `score: <N>` + `emotion: <Word>` keys         | journey-map only (§22)                                                                                                                    |
+| `description: <text>` shorthand for layers    | pyramid, ring (§23, §24)                                                                                                                  |
+| `milestone` keyword                           | **removed** — use `<name> 0` (§13A)                                                                                                       |
+| `\|` operator as metadata delimiter           | **removed** (§1.4). Surviving uses: wireframe `{A \| B}` braces, in-arrow `A -file\|name-> B`, quoted `"Order \| Items"`                  |
 
 ### 26.4 Quoted Names + Aliases — Pick One
 
@@ -4417,7 +4454,7 @@ Before considering DGMO output complete, mentally verify:
 3. Metadata uses §1.4 — same-line `key: value, ...` after the name region, or indented `key: value` for reserved keys. No `|` delimiter anywhere except wireframe dropdowns, in-arrow label characters, and quoted name characters.
 4. Wireframe flags are written as space-separated lowercase trailing keywords from the closed enum (§19).
 5. Journey-map steps use `score: N, emotion: Word`; gantt tasks use `progress: N`; pyramid/ring layers use `description: <text>` (quote when the value contains commas).
-6. All chart types use `collapsed: true` metadata for collapse (§27.3).
+6. Collapse is the bare `collapsed` trailing flag on the group/container line (§1.8; legacy: `collapsed: true` metadata).
 7. Quoted names don't carry `as <alias>` on the same line.
 8. Sequence participants with alias or quoted names use `is a <type>`.
 9. No `milestone` keyword in PERT — use `<name> 0`.