@diagrammo/dgmo 0.30.0 → 0.32.0

package/docs/language-reference.md

@@ -51,9 +51,12 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 
 - **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 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`.
-- **No hex colors.** Named palette colors only: `red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white`. Trailing token (`Done green`) or parenthesized suffix (`North(red) 850`).
+<!-- COLORS start -->
+- **Colors are a closed set of EXACTLY these 11 — nothing else is a color.** Valid colors, the complete list: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `teal`, `cyan`, `gray`, `black`, `white`. That is the entire universe of DGMO colors — there are no others. Do NOT use hex (`#1f77b4`), `rgb(...)`, `hsl(...)`, or ANY CSS color name: `crimson`, `royalblue`, `navy`, `pink`, `lime`, `magenta`, `indigo`, `gold`, `salmon`, `turquoise`, `violet`, etc. are ALL invalid — they are rejected and the element falls back to an auto-assigned color. When you want a color outside the 11, map it to the nearest one: crimson/scarlet→`red`, royalblue/navy/cobalt→`blue`, pink/magenta/violet/indigo→`purple`, lime/olive→`green`, gold/amber→`yellow`, turquoise→`teal`. Apply a color as a trailing token (`Done green`) or after a category/group bracket (`[North America] red`). Named colors are mandatory because they re-resolve per active palette + light/dark theme; a hardcoded value never would.
+<!-- COLORS end -->
 - **Show-everything is the default.** Every label / value / percent renders by default. Emit `no-name` / `no-value` / `no-percent` / `no-*` ONLY when the user explicitly asks to hide something — never defensively.
 - **`//` comments only** (never `#`). **Indentation closes blocks** — never `end`.
 - **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.
@@ -498,6 +501,10 @@ rarely benefit. Aliases should aid comprehension, not obscure it.
 
 <!-- TYPE:sequence -->
 
+<!-- TIPS start -->
+**Styling tips:** stay terse — participants are created by the messages that name them, so a plain flow needs only the arrow lines (no participant declarations). Skip `is a TYPE`: the glyph is inferred from the name (`User`→actor, `*DB`→database, `Redis`→cache, `Kafka`→queue); add a declaration, a `[Group]`, or `position: N` only when it genuinely aids reading order or grouping, never as boilerplate. Give each participant a short role name; group related exchanges under `== Section ==` dividers rather than a wall of arrows; label a return arrow only when its value matters (unlabeled returns are auto-pruned). Drop a `note` where something subtle happens. When participants fall into trust or role categories, color the participants (not the messages) by category with a tag group using the named palette colors, so the boundary reads at a glance.
+<!-- TIPS end -->
+
 ### 2.1 Participants
 
 ```
@@ -548,6 +555,21 @@ Names that previously inferred to a removed type — `AuthService`, `WebApp`, `C
 ```
 
 - Metadata goes outside brackets: `[Backend] t: Eng`
+- **Color participants by category with a tag group** (§1.3). Declare the group with named palette colors, then assign each participant `<alias>: <Value>` — the tag is on the participant, not the group line or a message:
+
+```
+tag Security as sec
+  public blue
+  trusted yellow
+
+[Client Side]
+  User sec: public
+  Browser sec: public
+
+[Provider]
+  AuthServer sec: trusted
+  API sec: trusted
+```
 
 ### 2.3 Messages (Arrows)
 
@@ -597,6 +619,7 @@ Content formatting:
 - `- ` prefix on indented lines = bullet points
 - 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).
 
 ### 2.6 Structural Blocks
 
@@ -617,6 +640,8 @@ parallel label
 
 - `parallel` requires a label
 - Blocks nest via indentation
+- **No `end`/terminator keyword** — a block closes by dedenting (like multi-line notes). `end`, `activate`/`deactivate`, and `autonumber` 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.
 
 ### 2.7 Sequence Options
 
@@ -630,6 +655,10 @@ parallel label
 
 <!-- TYPE:infra -->
 
+<!-- TIPS start -->
+**Styling tips:** an infra diagram traces request traffic flowing inward from an `internet` or `edge` entry — that flow IS the diagram. **Every node MUST be reachable from an `internet`/`edge` entry by following the connections.** A node with no path back to an entry receives no traffic: it is dead, serves no purpose, and must be omitted entirely — not declared, not drawn, not even left as an island. There are no standalone nodes on an infra diagram. Before you add any node, ask "which request reaches this?" — if nothing routes to it, leave it out. Build strictly outward from the entry, one hop at a time along the request path, so the graph is connected by construction. Then: keep capabilities in properties (`latency-ms`, `max-rps`, `cache-hit`), not the node name; color by tier with a tag group so the layers read at a glance; reserve async edges (`~>`) for genuine fire-and-forget like queues or pub/sub.
+<!-- TIPS end -->
+
 ### 4.1 Declaration
 
 ```
@@ -724,7 +753,16 @@ SearchAPI
 [Group Name] key: value
 ```
 
-- Bracket syntax only. Group coloring via tags.
+- Bracket syntax only. Group coloring via tags. Declare a `tag <Name> as <alias>` group (§1.3), then assign a node `<alias>: <Value>` same-line:
+
+```
+tag Team as t
+  Backend blue
+  Data green
+[API]
+  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):
@@ -754,6 +792,8 @@ internet
 
 Special top-level entry points. Either name works; `internet` only accepts `rps` and the `description` is silently ignored on entry-point nodes.
 
+**Reachability:** every node must have a directed path back to an `internet`/`edge` entry — that inbound traffic is the whole point of the diagram. The parser emits a `warning` for any node with no such path (`W_INFRA_UNREACHABLE`), or a single `warning` when the diagram has no entry node at all (`W_INFRA_NO_ENTRY`). These don't block rendering, but a flagged node carries no traffic and should be connected downstream of an entry or removed.
+
 ### 4.9 Node Descriptions
 
 ```
@@ -777,7 +817,7 @@ API Gateway
 <!-- TYPE:flowchart -->
 
 <!-- TIPS start -->
-**Styling tips:** label the edges out of a decision node (`-yes->`, `-no->`) so branches read unambiguously; color outcomes by category with a tag group (e.g. a `Status` group with `Approved green`, `Rejected red`) rather than coloring nodes individually; keep each node to a short action phrase.
+**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.
 <!-- TIPS end -->
 
 ### 4.1 Declaration
@@ -797,7 +837,15 @@ flowchart [Title]
 | Subroutine | `[[Label]]` | `[[Validate]]` |
 | Document   | `[Label~]`  | `[Report~]`    |
 
-- Node coloring: use tags (§1.3) — flowchart nodes have no color suffix
+- Node coloring: use tags (§1.3) — flowchart nodes have no color suffix. Declare a `tag <Name> as <alias>` group, then assign a node `<alias>: <Value>` (same-line after the node):
+
+```
+tag Status as s
+  Approved green
+  Rejected red
+[Review] -yes-> [Done] s: Approved
+[Review] -no-> [Reject] s: Rejected
+```
 
 ### 4.3 Arrows
 
@@ -861,6 +909,10 @@ collides with the indented-body grammar.
 
 <!-- TYPE:state -->
 
+<!-- TIPS start -->
+**Styling tips:** name states as nouns (`Idle`, `Loading`) and label transitions with the triggering event (`-submit->`); mark the initial and final states; color by state category with a tag group; keep transition labels to the event, not a sentence.
+<!-- TIPS end -->
+
 ### 5.1 Declaration
 
 ```
@@ -899,6 +951,17 @@ references, and the `no-notes` opt-out (see §4.7).
 
 - `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
+```
 - `solid-fill` (boolean; default off — render states with their full intent color instead of the canonical 25% tint; collapsed groups are also rendered at full saturation)
 - `no-notes` (boolean; default off — suppress all note boxes, see §4.7)
 
@@ -910,6 +973,10 @@ references, and the `no-notes` opt-out (see §4.7).
 
 <!-- TYPE:org -->
 
+<!-- TIPS start -->
+**Styling tips:** label each node with the name and role on separate lines, not a paragraph; let the layout build the hierarchy — don't hand-draw edges; color by department or team with a tag group; keep titles consistent (all roles, or all names).
+<!-- TIPS end -->
+
 ### 6.1 Declaration
 
 ```
@@ -929,6 +996,23 @@ CEO
 - Node coloring: per-node indented metadata `\n  color: blue` (deferred to a follow-up spec; tag groups inside org also work)
 - Same-line metadata: `Alice role: CEO, t: Exec`
 
+**Color by team / department** — declare a `tag <Name> as <alias>` group (§1.3) with palette colors, then assign each person the tag as metadata (`<alias>: <Value>`, indented under the node or same-line). There is **no `#team` or roster syntax** — a `#` line is not a grouping operator and renders as a stray node:
+
+```
+tag Team as t
+  Platform blue
+  Product green
+
+Dana Ruiz
+  title: VP Engineering
+  Sam Okafor
+    title: Dir. Platform
+    t: Platform
+  Priya Nair
+    title: Dir. Product Eng
+    t: Product
+```
+
 ### 6.3 Metadata (Indented, Colon REQUIRED)
 
 ```
@@ -959,6 +1043,10 @@ This is key-value metadata assignment, consistent with same-line metadata syntax
 
 <!-- TYPE:c4 -->
 
+<!-- TIPS start -->
+**Styling tips:** name each element by its responsibility, not its technology — put the tech in the `tech` field; color by system boundary with a tag group; keep one level of abstraction per diagram (context OR container, not both); keep relationship labels to the verb of the interaction. Write relationships INDENTED under their source element (`  -uses-> Other`), never as a top-level `A -uses-> B` line. Static renders (CLI, MCP) show the context level — containers/components appear only in the interactive drill-down, so author context-level diagrams for static output.
+<!-- TIPS end -->
+
 ### 7.1 Declaration
 
 ```
@@ -975,6 +1063,19 @@ Name is a container is a database     // shape override
 Types: `person`, `system`, `container`, `component`
 Shape overrides: `database`, `cache`, `queue`, `cloud`, `external`
 
+**Color by team / boundary** — declare a `tag <Name> as <alias>` group (§1.3), then assign each element `<alias>: <Value>` same-line (alongside `tech:`):
+
+```
+tag Team as t
+  Frontend blue
+  Backend green
+Customer is a person t: Frontend
+Shop is a system t: Backend
+  containers
+    WebApp is a container tech: React, t: Frontend
+    API is a container tech: Node, t: Backend
+```
+
 ### 7.3 Element Metadata (Indented, Colon REQUIRED)
 
 ```
@@ -1041,6 +1142,10 @@ Database is a container description: PostgreSQL with read replicas
 
 <!-- TYPE:er -->
 
+<!-- TIPS start -->
+**Styling tips:** name entities in the singular (`Customer`, not `Customers`); mark keys (`pk`, `fk`) and show only the columns that carry the relationship story; let the crow's-feet express cardinality instead of restating it in text; group related entities by color.
+<!-- TIPS end -->
+
 ### 8.1 Declaration
 
 ```
@@ -1091,6 +1196,10 @@ Cardinality symbols: `1` (one), `*` (many), `?` (optional)
 
 <!-- TYPE:class -->
 
+<!-- TIPS start -->
+**Styling tips:** show only the members that serve the diagram's point, not every field; mark visibility (`+`/`-`); express connections with relationships (inheritance, composition) rather than restating them in notes; group related classes by color.
+<!-- TIPS end -->
+
 ### 9.1 Declaration
 
 ```
@@ -1169,6 +1278,10 @@ Optional label: `--|> Vessel : extends` (colon optional before label)
 
 <!-- TYPE:kanban -->
 
+<!-- TIPS start -->
+**Styling tips:** name columns for workflow stages (`Todo`, `Doing`, `Done`); keep card titles to a short task phrase; color cards by owner or priority with a tag group; let column length convey WIP instead of annotating counts. If you use a tag group, tag EVERY card — an untagged card currently inherits the first tag value (mislabeling it), so omit the tag group entirely for an uncolored board.
+<!-- TIPS end -->
+
 ### 10.1 Declaration
 
 ```
@@ -1179,6 +1292,17 @@ kanban [Title]
 
 Columns represent workflow stages and must flow left-to-right from least-done to most-done (e.g., Backlog → In Progress → Done). Every column should be a stage that cards pass through. Don't create columns for non-workflow concepts like gates, criteria, or definitions of done — use a tag instead (e.g., `type: Gate`).
 
+**Color cards by owner / priority** — declare a `tag <Name> as <alias>` group (§1.3), then assign each card `<alias>: <Value>` in its same-line metadata:
+
+```
+tag Crew as c
+  Alice blue
+  Bob green
+[Todo]
+  Task one c: Alice
+  Task two c: Bob
+```
+
 ```
 [Column Name]
 [Column Name] color wip: 3
@@ -1203,6 +1327,10 @@ Columns represent workflow stages and must flow left-to-right from least-done to
 
 <!-- TYPE:sitemap -->
 
+<!-- TIPS start -->
+**Styling tips:** Connect pages by indenting `-> Target` lines under a parent page (not a top-level `Home -> Products`, which becomes one box), and declare each target as its own page too — bare indentation alone draws no connectors. Default flow is left-to-right; use `direction-tb` for a vertical tree. Keep labels to short page names.
+<!-- TIPS end -->
+
 ### 11.1 Declaration
 
 ```
@@ -1279,6 +1407,10 @@ Blog
 
 <!-- TYPE:gantt -->
 
+<!-- TIPS start -->
+**Styling tips:** group tasks under labeled phases; mark milestones as zero-duration; color by workstream or status with a tag group; keep task names to a short verb phrase; draw dependencies only where they actually drive the schedule.
+<!-- TIPS end -->
+
 ### 12.1 Declaration
 
 ```
@@ -1296,6 +1428,17 @@ no-dependencies
 sort tag:Team
 ```
 
+**Color by workstream / status** — declare a `tag <Name> as <alias>` group (§1.3), then assign each task `<alias>: <Value>` in its same-line metadata:
+
+```
+tag Phase as p
+  Build blue
+  Test green
+[Tasks]
+  Design 5d p: Build
+  QA 3d p: Test
+```
+
 ### 12.3 Holidays
 
 ```
@@ -1397,6 +1540,10 @@ want; anything left un-chained starts together at the parent's start.
 
 <!-- TYPE:pert -->
 
+<!-- TIPS start -->
+**Styling tips:** Give each task a duration and wire dependencies with `-> next`. Provide a single (most-likely) estimate plus `default-confidence medium` to auto-expand to a 3-point estimate, or give optimistic/likely/pessimistic explicitly. The critical path and slack are computed for you.
+<!-- TIPS end -->
+
 PERT diagrams visualize project networks with three-point duration estimates, surfacing critical path, slack, and project μ/σ. Each activity renders as a node card (rectangle, or diamond for milestones); dependencies are arrows between them. Monte Carlo simulation runs automatically whenever any activity carries duration data.
 
 ```
@@ -1559,6 +1706,10 @@ See spec §13A for full date-anchoring semantics, S-curve axes, and diagnostic c
 
 <!-- TYPE:boxes-and-lines -->
 
+<!-- TIPS start -->
+**Styling tips:** Write each connection as `Source -> Target` on its own line; boxes are auto-created from the labels. Group related boxes with a `[Group]` bracket and indent its members. Keep every box label a short noun phrase.
+<!-- TIPS end -->
+
 ### 13.1 Declaration
 
 ```
@@ -1698,45 +1849,65 @@ Flagship -> Sloop
 
 <!-- TYPE:timeline -->
 
+<!-- TIPS start -->
+**Styling tips:** label each event with a date and a terse headline; keep entries in chronological order; color by era or category with a tag group; merge minor events rather than crowding the axis.
+<!-- TIPS end -->
+
 ### 14.1 Declaration
 
 ```
 timeline [Title]
 ```
 
+**Color by era / category** — declare a `tag <Name> as <alias>` group (§1.3), then assign each event `<alias>: <Value>` same-line:
+
+```
+tag Era as t
+  Ancient blue
+  Modern green
+1500 Founding t: Ancient
+2000 Boom t: Modern
+```
+
 ### 14.2 Events
 
-Events use **name-first syntax** with `start:`, `end:`, and `duration:` as reserved metadata keys.
+Events use **date-first syntax** — the date (or date range) leads, then the event name, with optional trailing same-line metadata (§1.4).
 
-**Point event** (`start:` only):
+**Point event** (single date):
 
 ```
-Blockades Charleston start: 1718-05, p: Blackbeard
+1718-05 Blockades Charleston p: Blackbeard
 ```
 
-**Range event** (`start:` + `end:`):
+**Range event** (`->` between dates, spaces optional):
 
 ```
-Sails under Hornigold start: 1716, end: 1717, p: Blackbeard
+1716 -> 1717 Sails under Hornigold p: Blackbeard
 ```
 
-**Duration event** (`start:` + `duration:`):
+**Duration event** (date + name + `duration:` metadata):
 
 ```
-Sprint 1 start: 2026-03-20, duration: 30d
+2026-03-20 Sprint 1 duration: 30d
 ```
 
-**Uncertain ending** (`?` suffix on `end:` or `duration:`):
+**Datetime** (date with `HH:MM` time component):
 
 ```
-Rackham builds crew start: 1718, end: 1719?
+2026-03-20 14:30 Standup Meeting
 ```
 
-Event type is determined by key presence:
+**Uncertain ending** (`?` suffix on end date or duration value):
+
+```
+1718 -> 1719? Rackham builds crew
+```
 
-- `start:` only → point event
-- `start:` + `end:` → range event
-- `start:` + `duration:` → duration event
+Event type is determined by positional structure:
+
+- single date → point event
+- `date -> date` → range event
+- single date + `duration:` → duration event
 
 Date formats: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`
 Duration units: `min`, `h`, `d`, `w`, `m`, `y`
@@ -1777,7 +1948,7 @@ marker
 
 ```
 [Royal Navy]
-  Woodes Rogers arrives start: 1718-07
+  1718-07 Woodes Rogers arrives
 ```
 
 ---
@@ -1786,6 +1957,10 @@ marker
 
 <!-- TYPE:bar -->
 
+<!-- TIPS start -->
+**Styling tips:** pick the form from the question — `bar` to compare categories, `line` for a trend over time, `pie`/`doughnut` only for parts of one whole (≤6 slices); sort bars by value unless the category order is inherent (time, size); give one highlighted series a distinct color and keep the rest neutral; always label units.
+<!-- TIPS end -->
+
 ### Conventions shared across all data charts
 
 Every section under §15 follows the same two rules.
@@ -1876,6 +2051,10 @@ era Day 1 -> Day 3 Rough Seas red
 
 <!-- TYPE:scatter -->
 
+<!-- TIPS start -->
+**Styling tips:** label both axes with units; group points into categories with `[Category] color` brackets (points indented under each) so clusters read at a glance — scatter colors by bracketed category, not by a tag group; reach for a second category only when the comparison is the point; keep marker labels off unless a few outliers need calling out.
+<!-- TIPS end -->
+
 **Data rows** — follows §15 Rule A (space-separated):
 
 ```
@@ -1905,6 +2084,10 @@ Point names render by default. Use `no-name` to hide them.
 
 <!-- TYPE:heatmap -->
 
+<!-- TIPS start -->
+**Styling tips:** Declare the column headers in a `columns` block, then one row per item with space-separated numeric values (`Dana 5 2 4 3 2`). The values drive the color scale, so keep them on a consistent range.
+<!-- TIPS end -->
+
 **Columns** — follows §15 Rule B (prefer the indented block for multiple columns):
 
 ```
@@ -1926,6 +2109,10 @@ RowLabel 5 4 3
 
 <!-- TYPE:function -->
 
+<!-- TIPS start -->
+**Styling tips:** Set the domain once with `x <min> to <max>`. Give each curve a short plain-text name and put the math after the colon (`Sine blue: sin(x)`); the text before the colon is a label, so prefer a word like `Sine` over repeating the expression.
+<!-- TIPS end -->
+
 ```
 function Trajectories
 x-label Distance
@@ -1946,6 +2133,10 @@ The colon between name and expression is **required** — both sides can contain
 
 <!-- TYPE:sankey -->
 
+<!-- TIPS start -->
+**Styling tips:** Write each flow as `Source -> Target value` (space-separated value, no comma). The value sets the band width; flow reads left-to-right, so order sources upstream of targets.
+<!-- TIPS end -->
+
 **Tree structure (indented, space-separated):**
 
 ```
@@ -1967,6 +2158,10 @@ Source -- Target 2000
 
 <!-- TYPE:chord -->
 
+<!-- TIPS start -->
+**Styling tips:** Write each connection as `Source -> Target value` (or `--` for undirected). Every node becomes an arc on the circle and each value sets the ribbon thickness — good for dense many-to-many relationships.
+<!-- TIPS end -->
+
 ```
 Blackbeard -- Bonnet 150        // undirected
 Roberts -> Rackham 20           // directed
@@ -1978,6 +2173,10 @@ Values follow §15 Rule A.
 
 <!-- TYPE:funnel -->
 
+<!-- TIPS start -->
+**Styling tips:** order stages largest→smallest, top to bottom; keep each stage name to a noun phrase; let the stages auto-color (each gets a distinct hue — no tag group needed); cap it at ~6 stages and merge minor drop-offs rather than crowding.
+<!-- TIPS end -->
+
 **Data rows** — follows §15 Rule A (space-separated):
 
 ```
@@ -1994,6 +2193,10 @@ Purchases 200
 
 <!-- TYPE:slope -->
 
+<!-- TIPS start -->
+**Styling tips:** Declare exactly two periods with `period <A> <B>`, then one line per item as `Label <from> <to>`. Slope charts compare two points in time only — use a line/bar chart for more periods.
+<!-- TIPS end -->
+
 ```
 slope Fleet Strength
 
@@ -2018,6 +2221,10 @@ Roberts 12 52
 
 <!-- TYPE:wordcloud -->
 
+<!-- TIPS start -->
+**Styling tips:** One `term weight` per line (`TypeScript 95`); the weight drives font size, so spread weights across a wide range for visual contrast. Keep terms to single words or short phrases.
+<!-- TIPS end -->
+
 ```
 wordcloud Pirate Skills
 rotate none
@@ -2035,6 +2242,10 @@ navigation 88
 
 <!-- TYPE:arc -->
 
+<!-- TIPS start -->
+**Styling tips:** Write each link as `Source -> Target value`; nodes sit on a single axis and arcs are sized by value. Order nodes so the busiest connections form short arcs where possible.
+<!-- TIPS end -->
+
 ```
 arc Pirate Alliances
 
@@ -2052,6 +2263,10 @@ order group
 
 <!-- TYPE:venn -->
 
+<!-- TIPS start -->
+**Styling tips:** Declare each set as `Name as <alias> <color>`, then intersections as `<alias> + <alias> <count>` (and a triple `a + b + c <count>`). Note: all circles render the same size — overlap labels, not circle area, convey the numbers.
+<!-- TIPS end -->
+
 ```
 venn Skill Overlap
 
@@ -2071,6 +2286,10 @@ sw + nav + lead Legendary Pirates
 
 <!-- TYPE:quadrant -->
 
+<!-- TIPS start -->
+**Styling tips:** Plot points as `Label x y` (space-separated, no comma between x and y). Normalize raw metrics to a 0–1 range yourself — axes are not auto-scaled. Name the four regions with `top-left`/`top-right`/`bottom-left`/`bottom-right` + a color so each quadrant reads as a category.
+<!-- TIPS end -->
+
 ```
 quadrant Crew Assessment
 x-label Low Skill, High Skill
@@ -2095,6 +2314,10 @@ Navigator 0.85 0.8
 
 <!-- TYPE:mindmap -->
 
+<!-- TIPS start -->
+**Styling tips:** keep each node to 1–3 words; let depth carry the structure — don't echo a parent's word in its child; color the top-level branches distinctly with a tag group; favor breadth over long single chains.
+<!-- TIPS end -->
+
 A radial hierarchy of ideas branching out from a central root. Hierarchy is established by indentation, nodes accept descriptions and tag-driven coloring, and any subtree can be collapsed by default.
 
 ```
@@ -2223,6 +2446,10 @@ Universal options (`palette`, `theme`) apply as elsewhere.
 
 <!-- TYPE:wireframe -->
 
+<!-- TIPS start -->
+**Styling tips:** There is no link element — render hyperlinks as bare text (`Forgot password?`), NOT `[brackets]` (which is a text INPUT). Use `#`/`##` for headings, `(Label) primary` for the main button, and the `password` flag to mask a field.
+<!-- TIPS end -->
+
 Wireframe diagrams use **visual-mnemonic syntax** where bracket characters communicate element type.
 
 ### Declaration
@@ -2357,6 +2584,10 @@ wireframe Login Page
 
 <!-- TYPE:tech-radar -->
 
+<!-- TIPS start -->
+**Styling tips:** Use exactly four quadrants and place each item in one with `quadrant: <name>`; every blip needs a `ring:`. When the source is a numeric score rather than adopt/trial/assess/hold, bucket the scores into rings yourself and note the raw value in the blip description.
+<!-- TIPS end -->
+
 ```
 tech-radar Title
 
@@ -2425,6 +2656,10 @@ Blips receive sequential global numbers. Order: quadrants clockwise (top-left
 
 <!-- TYPE:cycle -->
 
+<!-- TIPS start -->
+**Styling tips:** List the stages in order — the renderer closes the loop back to the first automatically, so do not add a wrap-around edge. An indented line under a stage becomes its description.
+<!-- TIPS end -->
+
 Circular process flows where nodes sit on a ring and directed edges connect each to the next, wrapping from last back to first. Common use: OODA loops, PDCA, product lifecycles, continuous improvement.
 
 ### Declaration
@@ -2558,6 +2793,10 @@ Act red
 
 <!-- TYPE:journey-map -->
 
+<!-- TIPS start -->
+**Styling tips:** Write each stage as `Stage score: <1-5>` with an indented `description:` for the action; add `persona <name>` once at the top. The scores draw the emotion curve, so vary them to show highs and lows.
+<!-- TIPS end -->
+
 Persona-centric mood landscapes. Steps carry a 1–5 score and optional emotion label; the renderer draws an emotion curve over phase-grouped step cards. **Declaration is required** — the `journey-map` keyword must appear on the first line (no inference, to avoid colliding with kanban's `[Column]` + indented items shape).
 
 ### Declaration
@@ -2683,6 +2922,10 @@ Got resolution score: 5, emotion: Relieved
 
 <!-- TYPE:pyramid -->
 
+<!-- TIPS start -->
+**Styling tips:** Source order is apex-first (first line = top). For a funnel-shaped dataset, list the smallest stage first so the widest tier lands at the base. Bands are uniform height (not value-proportional) — put counts in an indented description.
+<!-- TIPS end -->
+
 Hierarchical pyramid visualization with stacked layers, descriptions, and optional per-layer color. Source order reads apex-first (top of file = top of pyramid).
 
 ### Declaration
@@ -2746,6 +2989,10 @@ When descriptions don't fit a layer's band the renderer wraps at the column edge
 
 <!-- TYPE:ring -->
 
+<!-- TIPS start -->
+**Styling tips:** Source order is innermost→outermost (first line = center disc). Bands are uniform thickness, not value-proportional; put the value in an indented description line. For a true part-of-whole proportion use pie or funnel instead.
+<!-- TIPS end -->
+
 Concentric-ring visualization for nested or hierarchical categories. Source order reads core-out: top of file = innermost element (rendered as a filled disc), last line = outermost ring. Min 2 layers, max 15.
 
 ### Declaration
@@ -2815,6 +3062,10 @@ When ring band thickness would force the in-band label below the readable floor
 
 <!-- TYPE:raci -->
 
+<!-- TIPS start -->
+**Styling tips:** Put each task at indent-0 and its role cells one level in (`Role: A`/`R`/`C`/`I`); declare the roles with a top-level `roles <A>, <B>, ...` line. Give every task exactly one A and one R to avoid lint warnings. A `[Phase]` header is optional — only use the indented `roles` block form when a `[Phase]` header follows.
+<!-- TIPS end -->
+
 A tasks × roles responsibility matrix with author-time linting. **One chart type — `raci` — covers all three variants.** Variant is inferred from the markers used; an optional `variant-*` directive locks it explicitly.
 
 | Variant | Marker alphabet | Constraint                                   |
@@ -2869,13 +3120,15 @@ roles
 raci Choose the next port
 roles Cap, Nav, QM, Bos
 
-  Pick destination
-    Cap: D
-    Nav: A
-    QM: C
-    Bos: I
+Pick destination
+  Cap: D
+  Nav: A
+  QM: C
+  Bos: I
 ```
 
+> Without a `[Phase]` header, put each task at **indent-0** and its role cells one level in (as above). Only nest tasks under a phase when a `[Phase]` header is present — otherwise the indented `roles` block greedily swallows the following lines.
+
 ### Directives
 
 | Directive                                         | Effect                                                                                                                                                                                                                      |
@@ -2906,7 +3159,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.
+**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 routes/flows from a hub** (e.g. an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — `JFK ~daily~> LAX`, `JFK ~daily~> LHR`, … — 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 that already appear 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.
@@ -3005,11 +3258,13 @@ A -> B                  # one-off, directed
 A -ferry- B value: 12   # undirected line; value = line thickness
 A ~cable~ B             # undirected arc with a label
 A -> B -> C             # inline chain
-dcw                     # hub/star — indented edges share the source
-  -> office-east
-  -- office-west        # hub legs accept any connector token
+JFK ~daily~> LAX        # hub/star: ONE edge per line, repeat the origin
+JFK ~daily~> LHR        # (NOT indented — indented legs are only valid
+JFK ~2x daily~> SFO     #  inside a `route` block, which is an ordered voyage)
 ```
 
+Each native edge is ONE full line — `<origin> <connector> <destination>`. There is no indented-edge / shared-source hub form for native edges (it errors as "Malformed edge"); to fan out from a hub, repeat the origin on each line as above. Endpoints auto-create their POIs, so a connected map needs no separate `poi` lines.
+
 There is no geographic path-finding and no `surface:` — legs are plain straight or arced geometry (`style: arc` to bow one) and may cross land.
 
 **Tagging the line.** A tag value on any connector or route leg colours the **line itself** (the universal tag model applied to edges) — the "trip-leg type" idiom. Edge-only tag groups show in the legend as a line-colour key; hovering a legend entry dims the lines that don't match. To categorise a **stop** instead, tag its own `poi` line. An edge-only tag group never tints regions or suppresses the colorize dress.