@diagrammo/dgmo 0.31.0 → 0.32.1

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:** Mirror the real navigation: group child pages under their section and keep the tree shallow (2–3 levels), ordering siblings by prominence. Connect pages with indented `-> Target` lines under each parent (a top-level `Home -> Products` renders as one box) and declare every target as its own page.
+<!-- 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:** Name each task as a short action and wire the real finish-to-start dependencies — branch and merge them so the critical path and per-task slack become meaningful. Give one most-likely estimate per task (the engine derives optimistic/pessimistic), or explicit O/M/P when you know them.
+<!-- 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:** Show one clear direction of flow; group related boxes with a `[Group]` bracket and label each edge with the relationship rather than a bare arrow. Keep every box 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:** Sort rows and columns by their totals (not alphabetically) so the strongest cells gather in one corner and the high-to-low pattern reads at a glance; keep every cell on the same numeric scale so the colors stay comparable.
+<!-- 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:** Pick a domain (`x <min> to <max>`) that frames the interesting behavior and keep to a few curves for legibility. Give each curve a short readable name before the colon (`Sine: sin(x)`), not the expression repeated.
+<!-- 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:** Feed flows in process order (left to right) and let each connection’s value set its band width — the layout already orders nodes to reduce crossings. Fold flows into one "Other" band only when many are individually negligible; never rename a single meaningful node.
+<!-- TIPS end -->
+
 **Tree structure (indented, space-separated):**
 
 ```
@@ -1967,6 +2158,10 @@ Source -- Target 2000
 
 <!-- TYPE:chord -->
 
+<!-- TIPS start -->
+**Styling tips:** Chord shines for genuinely reciprocal, many-to-many relationships; if your flows are mostly one-directional or hub-and-spoke, a sankey reads clearer. List heavily-connected nodes consecutively — arcs follow first-appearance order, so this keeps the thickest ribbons short.
+<!-- 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:** Slope auto-labels both endpoints and colors each line — recolor only when one line is the story, then color just that mover and leave the rest to the default palette. It compares exactly two periods; use a line chart for more.
+<!-- TIPS end -->
+
 ```
 slope Fleet Strength
 
@@ -2018,6 +2221,10 @@ Roberts 12 52
 
 <!-- TYPE:wordcloud -->
 
+<!-- TIPS start -->
+**Styling tips:** Make the largest and smallest terms differ enough in size to read at a glance — set an explicit `size <min> <max>` when raw weights are bunched together. Keep to the signal terms: cap the list (~30–40) and drop filler words.
+<!-- TIPS end -->
+
 ```
 wordcloud Pirate Skills
 rotate none
@@ -2035,6 +2242,10 @@ navigation 88
 
 <!-- TYPE:arc -->
 
+<!-- TIPS start -->
+**Styling tips:** Set `order appearance` and list links so the busiest pairs sit next to each other — heavy connections then read as short arcs hugging the axis instead of long sweeps (otherwise placement is automatic and row order is ignored).
+<!-- TIPS end -->
+
 ```
 arc Pirate Alliances
 
@@ -2052,6 +2263,10 @@ order group
 
 <!-- TYPE:venn -->
 
+<!-- TIPS start -->
+**Styling tips:** Use 2–3 sets and write the count of each meaningful overlap directly on its intersection; circle area is NOT proportional, so the numbers — not the sizes — carry the comparison.
+<!-- TIPS end -->
+
 ```
 venn Skill Overlap
 
@@ -2071,6 +2286,10 @@ sw + nav + lead Legendary Pirates
 
 <!-- TYPE:quadrant -->
 
+<!-- TIPS start -->
+**Styling tips:** Name the four quadrants as meaningful categories (not just positions) and call out the outliers; normalize values to 0–1 so the points spread across the whole space.
+<!-- 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:** Keep it low-fidelity — boxes, labels, and one primary action `(Sign in) primary` per screen, grouped by region. Links are bare text (`Forgot password?`); `[brackets]` is an input 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:** Group blips into the four domain quadrants and let the rings carry adoption stage (Adopt→Hold); annotate movement with a `trend`. When the source is a numeric score, bucket it into a ring and keep the number in the 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:** Aim for 3–6 stages so the loop stays legible; name each as a short step and let the closed ring imply repetition (no wrap-around edge needed). An indented line adds a 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:** Label a single-word `emotion:` on each step so the highs and lows are named, not just shaped; give one concrete action per stage and name the persona. Mark the trough with `pain:` and the peak with `opportunity:` so the arc’s meaning lands.
+<!-- 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:** Keep to a few tiers (3–5), widest at the base, and label each tier with its value — bands are uniform height, so the number carries the magnitude. For a funnel-shaped dataset, list the smallest stage first.
+<!-- 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:** Order rings core→outward by hierarchy, not by size — band thickness is uniform and carries no proportional meaning (use pie/funnel for part-of-whole). Keep any value you want read at a glance in the ring’s own label.
+<!-- 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 with its `Role: A/R/C/I` cells indented one level under it — never nest tasks inside the `roles` block (it swallows them). Give every task exactly one Accountable (ideally one Responsible) and keep roles small (≤~6) so the matrix stays scannable.
+<!-- 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.