@diagrammo/dgmo 0.32.0 → 0.33.0

package/docs/ai-integration.md

@@ -64,6 +64,7 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 - **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.
+- **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `<!-- … -->` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.)
 
 Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):
 
@@ -90,8 +91,12 @@ Billing t: Product
 
 Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:
 
-- **Title it.** Put a short title on the type-declaration line (`flowchart Checkout Flow`, `boxes-and-lines Service Map`) so the diagram is self-describing.
-- **Color by grouping, not at random.** When items fall into categories, declare a tag group and assign members so each category shares one color — far clearer than ad-hoc per-node colors. Use the tag-group syntax shown in the per-type section below (declare `tag Team as t`, indent the values — a trailing color is optional, bare values auto-pick a palette color — then assign `Node t: Team`). Only the 11 named palette colors exist.
+<!-- TITLE start -->
+- **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
+<!-- TITLE end -->
+<!-- CATEGORIZE start -->
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have *fewer* values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+<!-- 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.
 - **Pick a fitting direction.** Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction).

package/docs/language-reference.md

@@ -60,6 +60,7 @@ LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the
 - **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.
+- **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `<!-- … -->` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.)
 
 Two traps in the *other* direction (DGMO wants a colon / a space where you might not expect):
 
@@ -88,8 +89,12 @@ Billing t: Product
 
 Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:
 
-- **Title it.** Put a short title on the type-declaration line (`flowchart Checkout Flow`, `boxes-and-lines Service Map`) so the diagram is self-describing.
-- **Color by grouping, not at random.** When items fall into categories, declare a tag group and assign members so each category shares one color — far clearer than ad-hoc per-node colors. Use the tag-group syntax shown in the per-type section below (declare `tag Team as t`, indent the values — a trailing color is optional, bare values auto-pick a palette color — then assign `Node t: Team`). Only the 11 named palette colors exist.
+<!-- TITLE start -->
+- **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.
+<!-- TITLE end -->
+<!-- CATEGORIZE start -->
+- **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag <Axis> as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag <Axis>`, then assign each item `Node t: <Category>` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have *fewer* values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.
+<!-- 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.
 - **Pick a fitting direction.** Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction).
@@ -502,7 +507,7 @@ 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.
+**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. Reach for `== Section ==` dividers only when the flow splits into **two or more** distinct phases (e.g. `== Authentication ==` then `== Checkout ==`) — a single divider over one run of arrows just repeats the diagram's subject and adds a redundant band, so a one-phase flow should have no dividers at all. Label a return arrow only when its value matters (unlabeled returns are auto-pruned). Drop a `note` where something subtle happens. Categorize the participants and color them (not the messages) by that category with a tag group using the named palette colors — client vs service vs datastore, trust zones (internal / external), or owning team are almost always present, so default to coloring by one rather than leaving the lifelines monochrome, and the boundaries read at a glance.
 <!-- TIPS end -->
 
 ### 2.1 Participants
@@ -1279,7 +1284,7 @@ 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.
+**Styling tips:** Color EVERY column — write a lowercase color word right after the closing bracket (`[Done] green`). Don't match on column names; reason about what each column *means* for a card sitting in it, then pick the color whose everyday connotation fits, so the board reads at a glance. The guiding sense: green = good / finished / success, red = bad / stuck / needs attention, yellow = waiting / caution / in review, blue = active work in motion, gray = inert / not yet started / parked. Apply that to whatever columns exist — e.g. a terminal success column reads green even if it's called `Shipped`, `Hired`, or `Live`; a column meaning a card is stuck reads red whether it's `Blocked`, `On Hold`, or `Rejected`; an early holding column reads gray whether it's `Backlog`, `Ideas`, or `Inbox`. When several columns share a sense (two active-work stages), it's fine to keep a couple uncolored or reuse a color rather than force eleven distinct hues. Name columns for workflow stages, keep card titles to a short task phrase, and let column length convey WIP instead of annotating counts. Card color is separate from column color: color cards by owner or priority with a tag group, and if you use one, tag EVERY card — an untagged card currently inherits the first tag value (mislabeling it), so omit the tag group entirely for cards you want left uncolored.
 <!-- TIPS end -->
 
 ### 10.1 Declaration
@@ -1328,7 +1333,7 @@ tag Crew as c
 <!-- 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.
+**Styling tips:** Build a real navigation graph, not a flat column of boxes. Three things make a sitemap read well, and a good one uses all three. (1) **Cluster pages into `[Area]` group sections** when the site has distinct areas — e.g. `[Shop]`, `[Account]`, `[Admin]` — indenting each page under its bracket header, and leave only the true entry page (`Home` / `Landing`) at the top level. (2) **Show how a visitor moves** with an indented labeled arrow under the source page: `-submit-> Home`, `-checkout-> Payment`, `-back-> Dashboard`, where the label is the action or link text. Every arrow target must be declared as its own page; an arrow can point at a whole area with `-> [Admin]`. If pages share no links you've drawn a list, not a sitemap — connect them. (3) **Classify pages with a colored tag group**, so the legend organizes the map by meaning rather than by position. Declare a facet with colored values and assign it to every page in same-line metadata — access level works well: `tag Access` with `Public green`, `Member blue`, `Admin red`, then `Pricing Access: Public`; or a functional facet (`Browse`, `Purchase`, `Admin`). A second tag group for page kind (`Landing purple`, `Form orange`, `Content cyan`) adds a second color dimension. Reason about which facet actually distinguishes this site's pages rather than reaching for a fixed list. Keep the tree shallow and order siblings by prominence.
 <!-- TIPS end -->
 
 ### 11.1 Declaration
@@ -1541,7 +1546,7 @@ 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.
+**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.
@@ -1707,7 +1712,7 @@ 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.
+**Styling tips:** Show one clear direction of flow, label each edge with the relationship rather than a bare arrow, and keep every box a short noun phrase. **Color by category with a tag group:** declare a `tag <Facet> as <alias>` with a distinct color per value, then assign each box `<alias>: <Value>` so like things share a color and unlike things visibly differ — pick the facet that actually divides this system (tier: `Client`/`Edge`/`Compute`/`Data`, ownership, internal vs external, stateful vs stateless) rather than coloring at random. **Organize when it gets busy:** with more than ~4 boxes there is almost always a structure to surface — cluster the boxes that belong together into `[Group]` sections (a backend tier, a region, a subsystem) and draw edges to the group with `-> [Group]` where a whole cluster is the target. A flat row of many boxes is a missed opportunity; derive the grouping from how the parts relate. The `[Group]` brackets handle spatial clustering and the tag group handles color — use both, and they can cut across each other (e.g. group by subsystem, color by tier).
 <!-- TIPS end -->
 
 ### 13.1 Declaration
@@ -1843,6 +1848,30 @@ Flagship -> Sloop
   legend shows a gradient capsule; boxes without a `value:` get a neutral fill.
 - `show-values` additionally prints each box's number as text.
 
+### 13.9 Tag groups (categorical color)
+
+Color boxes by a category. Declare a `tag <Facet> as <alias>` group (§1.3) with one color per value — **values are indented under the `tag` header**, one per line, color as a trailing word — then assign each box `<alias>: <Value>` in its metadata. Do **not** write the values as `<alias> <Value>` lines; that is not the grammar.
+
+```
+boxes-and-lines Service Map
+tag Tier as t
+  Client blue
+  Edge teal
+  Compute green
+  Data purple
+
+[Client]
+  Web App t: Client
+[Edge]
+  API Gateway t: Edge
+[Compute]
+  Auth Service t: Compute
+[Data]
+  Postgres t: Data
+```
+
+The tag group (color) composes with `[Group]` clustering (spatial) and can cut across it — group by subsystem, color by tier. The group must be declared before any content line (§1.3).
+
 ---
 
 ## 15. Timeline Diagrams
@@ -2085,7 +2114,7 @@ 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.
+**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):
@@ -2110,7 +2139,7 @@ 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.
+**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 -->
 
 ```
@@ -2134,7 +2163,7 @@ 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.
+**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):**
@@ -2159,7 +2188,7 @@ 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.
+**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 -->
 
 ```
@@ -2194,7 +2223,7 @@ 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.
+**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 -->
 
 ```
@@ -2222,7 +2251,7 @@ 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.
+**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 -->
 
 ```
@@ -2243,7 +2272,7 @@ 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.
+**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 -->
 
 ```
@@ -2264,7 +2293,7 @@ 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.
+**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 -->
 
 ```
@@ -2287,7 +2316,7 @@ 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.
+**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 -->
 
 ```
@@ -2447,7 +2476,7 @@ 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.
+**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.
@@ -2585,7 +2614,7 @@ 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.
+**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 -->
 
 ```
@@ -2657,7 +2686,7 @@ 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.
+**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.
@@ -2794,7 +2823,7 @@ 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.
+**Styling tips:** A journey map is a story about one specific person, so author it richly even when the prompt is thin — fill the gaps with plausible, concrete detail rather than leaving it skeletal. **Persona:** give them a real first name, a color, and a short background — `persona Gina green`, then a sentence or 2–3 indented bullet (`- …`) lines covering who they are, their goal, and their constraints. Always color the persona (trailing color word after the name, or `persona Name color: green`) so the protagonist's card stands out. When the prompt implies a customer archetype, let the name's first letter echo it (a fanatic → Fred, a casual user → Carl, a beginner → Betty) — a light touch, never forced. **Structure:** organize the journey into 2–4 `[Phase]` sections, each holding 1–3 steps — and never one step per phase across the board. If every phase has exactly one step you've just bracketed a flat list; that 1:1 mapping is wrong — either give phases multiple steps or drop the brackets and let the steps run flat. Give every step a 1–5 `score:` (and a single-word `emotion:` at the highs and lows) so the mood curve has shape. **Depth per step:** every step gets a `description:` (what actually happens there) plus 2–5 annotations drawn from `pain:` (friction, red), `opportunity:` (a fix, green), and `thought:` (what they're thinking, italic) — choose the ones that genuinely fit that moment; a smooth early step might be all `thought:`/`opportunity:`, a trough heavy on `pain:`. Don't pad every step identically — let the friction cluster where the score dips so the arc reads true.
 <!-- 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).
@@ -2923,7 +2952,7 @@ 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.
+**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).
@@ -2990,7 +3019,7 @@ 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.
+**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.
@@ -3063,7 +3092,7 @@ 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.
+**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.
@@ -3159,7 +3188,7 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 <!-- TYPE:map -->
 
 <!-- TIPS start -->
-**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For 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.
+**Styling tips:** the zero-config map already looks good — name places and stop. When POIs fall into categories, tag them so each category gets its own color; keep place labels to the place name; leave region colorize and coastlines on unless the user asks to hide them. **For flights and airport routes, use IATA codes, not city names** — `LHR ~> JFK`, `LHR ~> DXB`, `LHR ~> SIN`, `LHR ~> HND` — the bundled airport set (large international hubs + all US commercial airports) resolves them to the right coordinates and labels them with the code. **For cities, use the exact canonical name**: "New York City" (NOT "New York"), "Washington, D.C.", etc. — a name the gazetteer doesn't have **silently drops that point** and the map just reframes around the rest, so it looks fine but is wrong. When unsure of the exact token, look it up: `dgmo map search "<place>"` (or the `lookup_map_location` MCP tool) returns the city name or airport code to paste; fall back to coordinates (`poi Name as 40.71,-74.0`) for anything not found. **For routes/flows from a hub** (an airport's daily flights, a distribution center's shipments), write ONE edge per line and repeat the origin — never indented edges (those error). Use **arcs** (`~>`) for flights and long-haul links so the spokes separate; the connector label carries the relationship (`~daily~>`, `~2x daily~>`). Endpoints auto-create POIs, so don't add separate `poi` lines for places already in an edge. Reach for a `route` block only when the trip is an **ordered voyage** that continues stop→stop (a cruise itinerary), not a set of independent routes from one origin.
 <!-- TIPS end -->
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
@@ -3302,6 +3331,8 @@ cove -> hav l: March    # the LINE turns green
   - **Name + scope** (readable): `Georgia US value: 5` → the state, `Georgia GE value: 5` → the country.
   - The redundant `Georgia US-GA` still works but isn't needed (a mismatched code like `Georgia US-CA` is rejected). A bare ambiguous `Georgia` follows the inferred US-scope signal and warns with both fixes named.
 - **IATA airport codes** resolve to airport coordinates — `poi JFK`, `route JFK -> LAX` — with no new syntax (large international hubs + all US scheduled-commercial airports). Case-insensitive (`jfk`/`JFK`). Airports are the **lowest-precedence** identifier: a token that is both a city and a code resolves to the **city** (`Ufa` → the city, not UFA airport), with a hint naming the airport. Resolution is by **code only** (never by airport name); the POI label is the typed code. An unknown three-letter code errors with an `as <CODE>` coordinates hint.
+- **A city name must match the gazetteer's canonical form** — `New York City`, not `New York`; `Washington, D.C.`, not `Washington`. An unrecognized name is dropped (with a did-you-mean note) and the map reframes around the places that *did* resolve, so the result can look complete but be missing a point. Use the exact name or coordinates.
+- **Discover the exact token** with the lookup surface rather than guessing — `dgmo map search "<place>"` (CLI; `--json` for machine output) or the `lookup_map_location` MCP tool. It substring-searches cities **and** the bundled airports and returns the precise token to paste (e.g. `york` → `New York City`; `heathrow` → `LHR`). There is intentionally **no exhaustive printed list** — the gazetteer holds thousands of cities plus ~1,500 airports; search is the interface.
 - Positional coordinates are the escape hatch for anything missing/ambiguous (including forcing an airport over a colliding city: `poi 54.56 55.87 as UFA`).
 
 ### Directives & reserved keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {
@@ -134,7 +134,7 @@
     "check:deadcode": "knip",
     "check:spelling": "cspell \"src/**/*.ts\" \"tests/**/*.ts\"",
     "check:all": "pnpm check:deadcode && pnpm check:spelling && pnpm check:duplication && pnpm check:circular && pnpm check:deps && pnpm check:security && pnpm build && bash scripts/check-api.sh check && pnpm check:publish && pnpm check:types",
-    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>5){console.error('New circular deps found ('+n+' > 5 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
+    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>6){console.error('New circular deps found ('+n+' > 6 known type-only/dynamic cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
     "check:deps": "depcheck --ignores='@diagrammo/dgmo,@codemirror/language,@lezer/*,husky,lint-staged,tsup,axe-core,type-coverage'",
     "check:security": "pnpm audit --prod",
     "check:publish": "publint",

package/src/advanced.ts

@@ -569,11 +569,16 @@ export type {
   ProjectionFamily,
   GeoExtent,
 } from './map/resolved-types';
-export { completeMapPlaces, completeMapRegions } from './map/completion';
+export {
+  completeMapPlaces,
+  completeMapRegions,
+  searchMapLocations,
+} from './map/completion';
 export type {
   MapPlaceCompletion,
   MapRegionCompletion,
   MapCompletionOptions,
+  MapLocationMatch,
 } from './map/completion';
 export type {
   Gazetteer,