@diagrammo/dgmo 0.95.0 → 0.97.0

package/docs/language-reference.md

@@ -98,7 +98,7 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 - **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>` in the header — after the tag group and before the first element, because a type such as c4 refuses it after content — then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). **Bracket, block, body, event-line, family, sketch and whiteboard** take the tag group but no `active-tag` line — declare the group and stop there; on event-line, family and sketch the line would be drawn as an element. **Class, flowchart, wireframe, raci, cycle, pyramid, ring, sankey, tech-radar, venn, version-control, wordcloud, arc, bar, clock, countdown, funnel, function, goal, heatmap, line, pie, polar-area, quadrant, radar, scatter and slope** take no tag group at all — skip this rule for them. Most report the lines; cycle, pyramid, ring, sankey, venn, version-control and wordcloud read them as content, and flowchart and tech-radar drop them without a word. 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 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>` in the header — after the tag group and before the first element, because a type such as c4 refuses it after content — then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). **Bracket, block, body, event-line and whiteboard** take the tag group but no `active-tag` line — declare the group and stop there; on event-line the line would be drawn as an element. **Class, flowchart, wireframe, raci, cycle, pyramid, ring, sankey, tech-radar, venn, version-control, wordcloud, arc, bar, clock, countdown, funnel, function, goal, heatmap, line, pie, polar-area, quadrant, radar, scatter and slope** take no tag group at all — skip this rule for them. Most report the lines; cycle, pyramid, ring, sankey, venn, version-control and wordcloud read them as content, and flowchart and tech-radar drop them without a word. 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.
@@ -125,6 +125,7 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 | `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                                                                                                                                            |
+| `swot`            | SWOT analysis: strengths, weaknesses, opportunities, threats in four fixed panels on helpful/harmful and internal/external axes                               |
 | `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)                                                                                    |
@@ -141,7 +142,6 @@ Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply
 | `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)                                                        |
 | `whiteboard`      | free-form infinite canvas: shapes, sticky notes, free arrows, text, images and freehand ink at pixel positions (canvas-drawn; AI writes all but ink)          |
 | `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                    |
@@ -215,7 +215,7 @@ tag GroupName as <alias>
 - Must appear before diagram content
 - Bare shorthand is not an alias (TD-18): `tag Priority p` declares a group _named_ "Priority p" — no alias registers, so `p:` assignments silently miss. The parser warns on this shape (spaced name, no alias, alias-shaped trailing word), suggesting `tag Priority as p` or a quoted name
 
-**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 whiteboard all accept `tag <Group> as <alias>` blocks (a whiteboard's names its colours — §24Ea). Check the per-type Options section for the exact directive set; if a type draws a tag legend, it takes tags. **Flowchart, wireframe, raci and class take no tags** — a `tag` block or `active-tag` on any of them is ignored with a warning, because what an element looks like is fixed by what it is (a flowchart's shape, a wireframe's state keywords, a class's trailing colour word) or by the roles (raci).
+**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, bracket, family, swot and whiteboard all accept `tag <Group> as <alias>` blocks (a whiteboard's names its colours — §24Ea). Check the per-type Options section for the exact directive set; if a type draws a tag legend, it takes tags. **Flowchart, wireframe, raci and class take no tags** — a `tag` block or `active-tag` on any of them is ignored with a warning, because what an element looks like is fixed by what it is (a flowchart's shape, a wireframe's state keywords, a class's trailing colour word) or by the roles (raci).
 
 ### 1.4 Same-Line Metadata
 
@@ -285,7 +285,7 @@ Two narrow exceptions accept same-line-metadata-only color: **cycle edges** (no
 - Indented content below belongs to the group
 - **A tag value on the group line colors the group's own frame**, and cascades
   to its children: `[Backend] s: Red`. Supported on boxes-and-lines, infra, c4,
-  state, pert, kanban, gantt, sequence, org, block and sketch. Two rules: a
+  state, pert, kanban, gantt, sequence, org and block. Two rules: a
   group never picks up the tag group's first-value default (an untagged group
   stays neutral grey), and a value the tag group does not recognize leaves it
   neutral rather than painting a fallback shade.
@@ -431,6 +431,25 @@ A block must have every key, hex only, text readable on its fills, and a name th
 
 **Who wins**, highest first: an explicit choice where the diagram is shown (a fence `palette=` attribute, `--palette` on the command line), then the file's palette, then the site's or app's own setting, then Slate. `theme` is retired — the mode word on the palette line does its job.
 
+### 1.11 Line Breaks in Description and Note Bodies
+
+A line break in the source is **not** a line break in the drawing. Consecutive body lines join into one paragraph and re-wrap to fit the card, so you can break prose wherever is comfortable in the editor. Two things keep a break:
+
+- **A blank line** starts a new paragraph, with a gap above it.
+- **A trailing `\`** breaks the line without starting a new paragraph (markdown's hard break).
+
+A `- ` line always starts its own bullet. A plain line straight after a bullet continues that bullet; a blank line returns to prose.
+
+```
+2026-09-28 67.10.0 deployed
+  *9:00 AM* \
+  Existing refresh code already deletes opted-out cards.
+```
+
+Without the `\`, the time and the sentence join into one line: `9:00 AM Existing refresh code…`.
+
+This applies to event-line descriptions, pyramid, ring and cycle descriptions, boxes-and-lines descriptions, and multi-line note bodies (sequence, flowchart, state, class, ER, journey-map, countdown).
+
 ---
 
 ## 2. Universal Name Handling
@@ -727,6 +746,8 @@ tag Security as sec
 
 Trailing `==` is optional.
 
+- **Fold a section** with a bare `collapsed` flag (or `collapsed: true`) after the divider: `== Checkout == collapsed`. The messages under it fold away until the next divider. `== collapsed ==` is a section named "collapsed".
+
 ### 2.5 Notes
 
 ```
@@ -753,6 +774,8 @@ Content formatting:
 - Inline markdown: `**bold**`, `*italic*`, `` `code` ``
 - Links: `[text](url)` and bare URLs (auto-truncated in display)
 - The note ends where the indentation does — there is **no `end` terminator** (a bare `end` line is rejected).
+- Body lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
+- **Fold a multi-line note** with a bare `collapsed` flag (or `collapsed: true`) at the end of its opening line: `note right of API collapsed`. It draws only the first body line, with the collapse bar. The flag counts only on a line followed by an indented body, so `note right of DB collapsed` with no body is a note that reads "collapsed".
 
 ### 2.6 Structural Blocks
 
@@ -772,6 +795,7 @@ parallel label
 ```
 
 - `parallel` requires a label
+- `else` is bare. A second condition is `else if <condition>`; `else <label>` means the same and draws as `else if <label>`
 - Blocks nest via indentation
 - **No `end`/terminator keyword** — a block closes by dedenting (like multi-line notes). `end` and `activate`/`deactivate` are not dgmo syntax (a bare `end` line is rejected); activation is controlled by the `activations` option (§2.7), not per-message keywords.
 - **Tags apply to participants, not messages** — there is no per-message tag/color. Color a participant by category with `<Participant> <tagAlias>: <Value>` after declaring a `tag <Name> as <alias>` group (§1.3). Message text is just the arrow label.
@@ -783,6 +807,27 @@ parallel label
 - `collapse-notes` / `no-collapse-notes`
 - `active-tag GroupName`
 
+Options go in the header. Put every option line — `active-tag` included — after the `tag` groups and before the first participant declaration, `[Group]`, divider or message. An option after any of those is an error (`Options like 'active-tag Zone' must appear before the first message or declaration`).
+
+```dgmo
+sequence Checkout
+tag Zone as z
+  Internal blue
+  External orange
+active-tag Zone
+
+Shop is a service z: Internal
+Bank is a service z: External
+
+Shop -charge-> Bank
+  if approved
+    Bank -receipt-> Shop
+  else if declined
+    Bank -decline code-> Shop
+  else
+    Bank -timeout-> Shop
+```
+
 ---
 
 ## 4. Infrastructure Diagrams
@@ -955,7 +1000,7 @@ API Gateway
 
 <!-- TIPS start -->
 
-**Styling tips:** write every connection as `Source -> Target` (or a single-line chain like `(Start) -> [Collect info] -> <Eligible?>`); write each connection on its own line. Every decision `<Question?>` MUST have at least two outgoing branches — usually `-yes->`/`-no->`, but use specific labels when the choices are not binary (e.g. `-retirement->`, `-disability->`, `-survivor->`); a decision with only one branch is invalid. Begin at exactly one start terminal `(Start)` and make every path terminate at a terminal node (`(Approved)`, `(Denied)`, `(End)`). Every node MUST connect to the rest of the graph: if a node cannot be traced from the start forward to a terminal, it is invalid — remove it, never leave it floating. Flowcharts have NO tag groups, node metadata, or manual node colors — do NOT write `tag … as …`, a `s: value` suffix, or a trailing color word; node colors are assigned automatically by shape (start terminal green, end terminals red, processes blue, decisions yellow). Just pick the right shape and let color follow. Label every decision edge so branches read unambiguously; keep each node to a short action phrase and phrase every decision as a question.
+**Styling tips:** write every connection as `Source -> Target` (or a single-line chain like `(Start) -> [Collect info] -> <Eligible?>`); write each connection on its own line. Every decision `<Question?>` MUST have at least two outgoing branches — usually `-yes->`/`-no->`, but use specific labels when the choices are not binary (e.g. `-retirement->`, `-disability->`, `-survivor->`); a decision with only one branch is invalid. Begin at exactly one start terminal `(Start)` and make every path terminate at a terminal node (`(Approved)`, `(Denied)`, `(End)`). Nothing points back at the start node: no arrow may end at `(Start)`, so a loop returns to a step after it (`-retry-> [Collect info]`), never to the start. Every node MUST connect to the rest of the graph: if a node cannot be traced from the start forward to a terminal, it is invalid — remove it, never leave it floating. Flowcharts have NO tag groups, node metadata, or manual node colors — do NOT write `tag … as …`, a `s: value` suffix, or a trailing color word; node colors are assigned automatically by shape (start terminal green, end terminals red, processes blue, decisions yellow). Just pick the right shape and let color follow. Label every decision edge so branches read unambiguously; keep each node to a short action phrase and phrase every decision as a question.
 
 <!-- TIPS end -->
 
@@ -1020,13 +1065,16 @@ Bracket syntax only.
 
 ### 4.7 Notes (Nodes)
 
-Attach an annotation to a node with `note <NodeId> text` (quote the id
-for multi-word labels). The note renders as a folded-corner box beside
-the node, expanded at rest.
+Attach an annotation to a node with `note NodeLabel text` (quote the
+label when it has more than one word). A note names the node by its
+label, without the shape's brackets: the decision `<Email exists?>` takes
+`note "Email exists?" …`, never `note <Email exists?> …`. The note renders
+as a folded-corner box beside the node, expanded at rest.
 
 ```
 note Validate checks the payload schema
 note "Read Map" the map is half-burned
+note "Email exists?" checks the users table
 ```
 
 Indent lines below the heading for a multi-line body (bullets + inline
@@ -1591,6 +1639,8 @@ All permutations supported: node→group, group→node, group→group. Brackets
   Pricing Auth: Public
 ```
 
+**Collapse:** a bare `collapsed` flag at the end of a page line or a `[Container]` line (`Products collapsed`, `[Shop] collapsed`; legacy `collapsed: true`) starts it folded. Every render path draws the fold with the collapse bar and a hidden-page count. Only a page with children or a container with pages folds.
+
 ### 11.5 Node Descriptions
 
 ```
@@ -1964,6 +2014,7 @@ Henry Turner + Carina Smyth m: 1751
 - **Unknown/private person:** a bare `?` renders a faint, solid-bordered, name-only placeholder card; each `?` is a distinct person.
 - **`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).
+- **`active-tag <Group>`** (option): picks which tag group colours the cards when there are two or more (the built-in Sex group counts); `active-tag none` turns colouring off.
 - **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.
 
@@ -2103,6 +2154,8 @@ Nested groups (max depth 2):
 
 Group metadata cascades to children (node metadata overrides). Nodes already declared above can be referenced inside groups to assign membership.
 
+A bare `collapsed` flag on the group line (`[AWS] collapsed`, or `[AWS] color: blue, collapsed`; legacy `collapsed: true`) starts the group folded: it draws as one pill with a member count and the collapse bar, and its edges end on the pill.
+
 ### 13.5 Group-Targeted Edges
 
 Node-to-group and group-to-group edges use bracket syntax `[Group Name]`:
@@ -2312,6 +2365,8 @@ marker
   1718-07 Woodes Rogers arrives
 ```
 
+A bare `collapsed` flag on the lane line (`[Royal Navy] collapsed`, `[Royal Navy] blue collapsed`; legacy `collapsed: true`) starts the lane folded to one summary row with the collapse bar. Lanes fold only in the grouped swimlane layout.
+
 ### 14.6 Options (Space-Separated, NO Colon)
 
 ```
@@ -2740,7 +2795,7 @@ tag Genre as g
 - **Date** — optional, ISO only (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `+HH:MM` / `+HH:MM:SS`, plus `YYYY BCE`/`BC`/`CE`/`AD`), formatted for reading as the card subtitle (`2008-09-02` → `Sep 2, 2008`). No `date:` key; no `M/D/YYYY`.
 - **`TBD` (future events)** — write the literal `TBD` (case-insensitive) in the date slot for a **not-yet-scheduled** event: `TBD Console Port  t: Engine`. Its caption reads `TBD` and it draws a **hollow dot + faded leader** (a faded shelf edge in `no-box`) so it reads as pending. To scale, its position is **inferred from its source-order dated neighbors**: a `TBD` followed by a dated event is interpolated into that gap; a **trailing** `TBD` (nothing dated after it) parks past the last real date and the spine **trails off dashed** — the open horizon. `TBD`s never trip the bad-date / out-of-order warnings.
 - **Tag** — trailing same-line metadata (`g: Pop`), like timeline; colors the dot, leader, and card.
-- **Description** — bare indented body lines (like `pyramid`/`ring`); `- ` makes a bullet; inline markdown (`**bold**`, `*italic*`, `` `code` ``) supported.
+- **Description** — bare indented body lines (like `pyramid`/`ring`); `- ` makes a bullet; inline markdown (`**bold**`, `*italic*`, `` `code` ``) supported. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 #### Eras
 
@@ -3327,7 +3382,7 @@ Act red
 
 ### Descriptions
 
-Indented lines under a node become the description. Inline markdown is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`), and `- item` renders as `• item`.
+Indented lines under a node become the description. Inline markdown is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`), and `- item` renders as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 ```
 Observe
@@ -3463,6 +3518,8 @@ persona Captain Mara
 
 Phases are `[Bracket]` headers at indent 0. Steps live indented under them. Phases are optional — omit them for a continuous flat flow.
 
+A bare `collapsed` flag on the phase line (`[Research] collapsed`; legacy `collapsed: true`) starts the phase folded to a narrow column with the collapse bar. Nothing else may follow a phase header.
+
 ```
 [Research]
   Compare specs score: 4
@@ -3610,7 +3667,7 @@ Physiological orange
 
 ### Descriptions
 
-Indented lines under a layer are description text. Markdown inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) is supported. Bullets written as `- item` render as `• item`.
+Indented lines under a layer are description text. Markdown inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) is supported. Bullets written as `- item` render as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11).
 
 ### Directives
 
@@ -3679,7 +3736,7 @@ The Open Sea cyan
 
 ### Descriptions
 
-Indented lines under a layer are description text. Markdown inline formatting is supported. Bullets written as `- item` render as `• item`. Descriptions appear in a stacked side list with colored accent bars.
+Indented lines under a layer are description text. Markdown inline formatting is supported. Bullets written as `- item` render as `• item`. Lines join into one paragraph — a blank line or a trailing `\` keeps a break (§1.11). Descriptions appear in a stacked side list with colored accent bars.
 
 ### Directives
 
@@ -3903,86 +3960,6 @@ In the desktop app a block diagram is interactive: click a container header to c
 
 ---
 
-## 24E. Sketch Diagrams
-
-<!-- TYPE:sketch -->
-
-**Beta — expect rough edges and syntax changes.**
-
-<!-- TIPS start -->
-
-**Styling tips:** Sketch is a GUI-authored format — the desktop and web canvas editors generate this markup, so hand-writing it is the exception. If you generate it anyway: keep it SMALL (sketches read best under ~15 shapes), and either omit `at:` everywhere (shapes flow into rows) or use integer half-slot coordinates with shapes **at least 3 half-slots apart** on one axis (a footprint spans 2 half-units and the mandatory gap adds 1 more, so each shape claims a 3×3 block; 2 apart overlaps). A `[Box]` may hold another `[Box]`, to **depth 2** — a third level is refused and its shapes join the box above it. Alias any shape an edge references (`as con`). Never write `size:`, `shape:`, colors, or fonts — every shape is the same plain card. In sketch, `~` dashed means secondary emphasis, NOT async. Categorize with a tag group — kind-of-thing is meaning, and meaning lives in tags. Reach for `sketch` when the drawing itself is the content; reach for `boxes-and-lines` when topology should auto-lay-out.
-
-<!-- TIPS end -->
-
-A **GUI-first constrained canvas**: uniformly-sized shapes placed freely on a snap grid, arrows between them, meaning through tags. The renderer owns all styling — authors own placement, connection, naming, and tags. Every shape has ONE universal footprint (no resizing); text always fits (shrink → smart-wrap → `…`). Pick `sketch` when the spatial arrangement is yours to decide; pick `boxes-and-lines` when topology should auto-lay-out.
-
-### Declaration
-
-```
-sketch [Title]
-```
-
-### Example
-
-```
-sketch Plunder Pipeline
-
-tag Crew
-  Deck
-  Hold
-
-Spyglass Feed at: 0 0, crew: Deck
-  -sightings-> con
-Captain's Console as con at: 2 0, crew: Deck
-  -orders-> bq
-Divvy Service as dvy at: 4 0, crew: Hold
-
-[Below Decks] at: 2 2, crew: Hold
-  Booty Queue as bq at: 0 0
-    ~haul~> dvy
-  Ship Ledger as ledger at: 2 0
-
-[Armory] as armory at: 0 2, collapsed
-  Powder Store at: 0 0
-```
-
-### Shapes
-
-One top-level line = one shape — a **bare name** plus same-line `key: value` metadata. Every shape is the same plain card — there are no shape kinds, and a `shape:` clause is an error (`E_SKETCH_SHAPE_UNSUPPORTED`); the shape still draws, without it. Duplicate labels are legal **when aliased** (`Cache as c1` / `Cache as c2`); unaliased duplicates merge (standard dgmo semantics).
-
-### Coordinates — `at: C R`
-
-Integer **half-slot steps** (a slot = one footprint + the mandatory gap), origin-normalized; box children are relative to the box origin. `at:` is **optional** — un-positioned shapes flow-place in rows below existing content. Hand-authored overlap auto-resolves with a warning; nothing renders broken.
-
-### Lines
-
-Indented under the source shape, targeting an alias (or an unambiguous bare label). Six forms: `-label->` one head · `<-label->` both heads · `-label-` no heads, plus `~` dashed twins. Unlabeled headless lines are `--` / `~~`. No left-pointing arrows — write `B -> A`, never `A <- B`. A tag on the edge tail (`crew: Hold`) colors the line. Both ends must attach.
-
-### Boxes
-
-`[Brackets]` = a **box** (labeled group frame) — the only bracket meaning in sketch. Label mandatory; one level only (no nested boxes); taggable (frame tints, cascades to children, individual overrides); bare `collapsed` folds it to a card with the collapse-bar and edges re-target the card. Interactive fold/unfold in the app; static export renders the authored state.
-
-### Node Metadata
-
-| Key         | Type           | Default                 | Description                                              |
-| ----------- | -------------- | ----------------------- | -------------------------------------------------------- |
-| `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. |
-
-### Interactivity vs export
-
-In the desktop and web app a sketch opens in the **canvas editor** (the code pane hides behind a toggle); boxes fold/unfold interactively. Static SVG / PNG export renders the authored state — the same interactive-vs-export split the map, treemap, and block charts use.
-
----
-
 ## 24Ea. Whiteboard Diagrams
 
 <!-- TYPE:whiteboard -->
@@ -3991,11 +3968,11 @@ In the desktop and web app a sketch opens in the **canvas editor** (the code pan
 
 <!-- TIPS start -->
 
-**Styling tips:** Whiteboard is a canvas-first format: people draw on it, and pen strokes (`ink` lines) only ever come from drawing — never write an `ink` line. Generate the readable parts only: `rectangle`, `ellipse`, `database`, `queue` with a label, `at: X Y` (top-left, integer pixels) and `size: W H`; `arrow` with `from: X Y, to: X Y` and an optional label, or `line` the same way for a connection with no head; add `style: dashed` to an arrow or line for a tentative or optional link; `heads: both` for a two-way arrow; `bend: 40` (px, sign picks the side) to curve a link around something in its way; `text` at a point; `note` with `at: X Y` for a sticky-note comment or open question (a 160 × 99 yellow card by default; `size:` and `color:` are optional). A shape label or a note wraps to its width on its own, so never break a sentence by hand to fit; for separate lines (a heading, a list), drop the inline label and indent each line two spaces under the element line. Leave ~40px between shapes and keep boards small (under ~15 elements). Colours are palette names (red, green, blue, teal, purple, orange, yellow, cyan, gray); leave colour off for the default ink. An arrow or line end placed inside a shape or note attaches to it and is drawn to its border, so point ends at shape centres. `no-notes` hides every note when the board is shown. Reach for `whiteboard` for a loose drawing someone will scribble over; reach for `sketch` for tagged shapes on a grid, and `boxes-and-lines` when topology should auto-lay-out.
+**Styling tips:** Whiteboard is a canvas-first format: people draw on it, and pen strokes (`ink` lines) only ever come from drawing — never write an `ink` line. Generate the readable parts only: `rectangle`, `ellipse`, `database`, `queue`, `file` (a page with a wavy bottom, for a document or file) with a label, `at: X Y` (top-left, integer pixels) and `size: W H`; `arrow` with `from: X Y, to: X Y` and an optional label, or `line` the same way for a connection with no head; add `style: dashed` to an arrow or line for a tentative or optional link; `heads: both` for a two-way arrow; `bend: 40` (px, sign picks the side) to curve a link around something in its way; `text` at a point; `note` with `at: X Y` for a sticky-note comment or open question (a 160 × 99 yellow card by default; `size:` and `color:` are optional). A shape label or a note wraps to its width on its own, so never break a sentence by hand to fit; for separate lines (a heading, a list), drop the inline label and indent each line two spaces under the element line. Leave ~40px between shapes and keep boards small (under ~15 elements). Colours are palette names (red, green, blue, teal, purple, orange, yellow, cyan, gray); leave colour off for the default ink. An arrow or line end placed inside a shape or note attaches to it and is drawn to its border, so point ends at shape centres. `no-notes` hides every note when the board is shown. Reach for `whiteboard` for a loose drawing someone will scribble over; reach for `boxes-and-lines` when topology should auto-lay-out.
 
 <!-- TIPS end -->
 
-A **free-form whiteboard** on an infinite canvas: rectangles, ellipses, databases, queues, sticky notes, free arrows and lines, text, pasted images and freehand ink, each at absolute pixel positions. Shapes are clean vector outlines; only ink looks hand-made. The export is cropped to the drawing plus a margin. Elements draw in kind bands, bottom to top: images; shapes, sticky notes, arrows and lines (`rectangle`, `ellipse`, `database`, `queue`, `note`, `arrow`, `line`); text; ink. A band always draws above the one before it. Inside a band, file order decides: a later line draws on top, so shapes, notes and arrows stack either way — except that an arrow or line always draws just above the latest shape or note it is attached to. No syntax sets the band.
+A **free-form whiteboard** on an infinite canvas: rectangles, ellipses, databases, queues, files, sticky notes, free arrows and lines, text, pasted images and freehand ink, each at absolute pixel positions. Shapes are clean vector outlines; only ink looks hand-made. The export is cropped to the drawing plus a margin. Elements draw in kind bands, bottom to top: images; shapes, sticky notes, arrows and lines (`rectangle`, `ellipse`, `database`, `queue`, `file`, `note`, `arrow`, `line`); text; ink. A band always draws above the one before it. Inside a band, file order decides: a later line draws on top, so shapes, notes and arrows stack either way — except that an arrow or line always draws just above the latest shape or note it is attached to. No syntax sets the band.
 
 ### Declaration
 
@@ -4474,6 +4451,8 @@ Phase headers accept a trailing-token color for per-phase styling:
 
 The phase bar tints to a soft mix of the color over the background. Phases without a color fall back to the neutral gray bar.
 
+A bare `collapsed` flag on the phase line (`[Departure] collapsed`, `[Departure] teal collapsed`; legacy `collapsed: true`) starts the phase folded: its task rows hide and the band keeps its summary chips and the collapse bar.
+
 ### Display vs source ordering
 
 Markers in cells are always **rendered in canonical alphabet order** (`R A C I`, `R A S C I`, `D A C I`) regardless of source order. Source casing and order are preserved in the file; mutations operate on source order to keep round-trips byte-stable except for the cell that changed.
@@ -4704,6 +4683,77 @@ The one directive is `url`. There are no elements, no indentation and no colons.
 
 ---
 
+## 25B. SWOT Analysis
+
+<!-- TYPE:swot -->
+
+<!-- TIPS start -->
+
+**Styling tips:** Keep items to a few words, and let the section colours stand: a tag group earns its place only when the items sort into kinds, such as priority or owner. Declare the sections in any order; they always draw S W / O T.
+
+<!-- TIPS end -->
+
+### 25B.1 Declaration
+
+```
+swot [Title]
+```
+
+A SWOT analysis names four fixed panels: **strengths** and **weaknesses** are internal, **opportunities** and **threats** are external; strengths and opportunities help, weaknesses and threats harm. The panels always draw as a 2×2 in the order S W / O T, whatever order the source uses. At phone width the chart stays 2×2 and scales as a whole.
+
+### 25B.2 Sections and items
+
+```
+swot Tortuga Rum Co.
+tag Priority as p
+  High red
+  Low gray
+active-tag Priority
+x-label Helpful, Harmful
+y-label Internal, External
+
+strengths
+  Oldest still on the island p: Low
+  Crew of 40 sworn tasters
+    Trained in three ports
+weaknesses Soft spots yellow
+  One barrel supplier p: High
+opportunities
+  Navy rum ration contract
+threats
+  Royal Navy blockade
+```
+
+- **Section line**, indent 0: `strengths|weaknesses|opportunities|threats [Label] [color]`. The keyword is case-insensitive. The label defaults to Strengths, Weaknesses, Opportunities, Threats; the colour defaults to green, yellow, blue, red. Sections are keywords, never `[brackets]`.
+- **Item line**: indented under a section. Text is literal, so colons and commas stay (`Cost: 20% below rivals, margins thin`) unless the key is a declared tag alias (`p: High`). A colour word ending an item stays in the text (`Margins are in the red`). A leading `- ` is removed.
+- **Detail line**: indented one level under an item; drawn smaller and muted. There is one detail level.
+- A missing or empty section still draws its panel, with a muted "None listed".
+- Long text wraps and the panel grows; nothing is truncated. A row takes its tallest panel's height, and the two columns stay equal.
+
+### 25B.3 Options
+
+| Option              | Effect                                                                                                                                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tag`, `active-tag` | A tag recolours an item's dot, tints its row faintly in the tag colour, and adds the legend. An untagged item keeps its section's colour and no tint, and the header bands always keep the section colour |
+| `x-label A, B`      | Column headers: a filled band over each column, in small caps. Default `Helpful, Harmful`                                                                                                                 |
+| `y-label A, B`      | Row headers: a filled rail beside each row, rotated, in small caps. Default `Internal, External`                                                                                                          |
+| `no-axes`           | Hide the axis labels. Wins over `x-label` and `y-label`                                                                                                                                                   |
+| `no-tint-items`     | Don't tint tagged rows; the dot alone carries the tag                                                                                                                                                     |
+| `no-legend`         | Hide the tag legend                                                                                                                                                                                       |
+| `palette`           | Draw in a built-in palette                                                                                                                                                                                |
+
+The TOWS strategy cross-matrix, scores or weights are not part of this chart.
+
+### 25B.4 Diagnostics
+
+| Code                       | Fires on                                                                                                   |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `E_SWOT_UNKNOWN_SECTION`   | an unknown word at indent 0, including `[Strengths]` and `strength`; the message names the nearest keyword |
+| `E_SWOT_DUPLICATE_SECTION` | the same section twice                                                                                     |
+| `E_SWOT_ORPHAN_ITEM`       | an item before any section                                                                                 |
+| `E_SWOT_TOO_DEEP`          | nesting below the detail level                                                                             |
+| `W_SWOT_EMPTY_SECTION`     | a missing or empty section; its panel still draws                                                          |
+
 ## 26. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
@@ -4805,16 +4855,16 @@ API description: Main gateway
 
 Some constructs _look_ universal but are scoped to specific chart types. Don't transplant them across charts.
 
-| 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"`                  |
+| Construct                                     | Scope                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bare `collapsed` trailing flag (§1.8)         | sequence (groups, sections, multi-line notes), infra, gantt, kanban, mindmap, pert, state, event-line (eras), block, wireframe, sitemap, boxes-and-lines, timeline (lanes), journey-map, raci. c4 parses it but draws nothing (c4 folds by drill level). 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
 

package/gallery/fixtures/swot-relabel.dgmo

@@ -0,0 +1,19 @@
+swot Coopérative du Rhum
+no-axes
+x-label Atouts, Risques
+y-label Interne, Externe
+
+// The source order is deliberately T O W S; the panels stay S W / O T.
+threats Menaces
+  Blocus de la marine royale, qui ferme le port principal pendant toute la saison des alizés
+opportunities Opportunités teal
+  Contrat de ration de rhum pour la marine
+  Ouverture d'une route commerciale vers les îles du sud
+  Demande croissante en Europe
+weaknesses Faiblesses
+  Un seul fournisseur de tonneaux
+strengths Forces
+  La plus ancienne distillerie de l'île
+  Quarante goûteurs assermentés, formés dans trois ports différents et capables de reconnaître un millésime à l'odeur
+    Formation reprise chaque hiver
+  Recette gardée depuis 1680

package/gallery/fixtures/swot-tags.dgmo

@@ -0,0 +1,16 @@
+swot Tortuga Rum Co.
+tag Priority as p
+  High red
+  Low gray
+active-tag Priority
+x-label Helpful, Harmful
+y-label Internal, External
+
+strengths
+  Oldest still on the island p: Low
+  Crew of 40 sworn tasters
+    Trained in three ports
+weaknesses Soft spots yellow
+  One barrel supplier p: High
+opportunities
+  Navy rum ration contract

package/gallery/fixtures/swot.dgmo

@@ -0,0 +1,13 @@
+swot Tortuga Rum Co.
+
+strengths
+  Oldest still on the island
+  Crew of 40 sworn tasters
+weaknesses
+  One barrel supplier
+  Cost: 20% above rivals, margins thin
+opportunities
+  Navy rum ration contract
+threats
+  Royal Navy blockade
+  Margins are in the red

package/gallery/fixtures/whiteboard.dgmo

@@ -9,6 +9,7 @@ rectangle Magic link at: 60 250, size: 180 70, color: green
 arrow emails a code from: 150 95, to: 150 285, color: green
 database Users at: 420 160, size: 140 100, color: purple, fill: solid
 queue Email jobs at: 300 380, size: 200 64, color: orange
+file Audit log at: 60 400, size: 140 80, color: gray
 arrow from: 150 285, to: 400 412, color: orange, bend: 50
 text keep it to ONE screen at: 62 184
 text 2FA here?? at: 560 -4, color: red

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.95.0",
+  "version": "0.97.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "author": "Diagrammo LLC",