figdown 0.1.8 → 0.3.0

package/skill/figdown/reference/experimental/block.md

@@ -0,0 +1,60 @@
+# Genre `block` — markers and zones (EXPERIMENTAL)
+
+`threshold` and `band` are **outside the v0.1 conformance surface and outside
+the compatibility promise**. The engine accepts them and your document keeps
+working, but they may change or be withdrawn in a later `0.x`. The parser
+emits no warning, so a line that parses tells you nothing. Use them when the
+figure genuinely needs them; if the figure must be portable, do not, and if
+you use one anyway, say so beside the figure.
+
+**Both belong to `block` alone.** They are declared by this genre and by no
+other: writing either under `topology`, `flowchart` or `statechart` is a line
+error that says so and gives the ground. `block` earns them because it is the
+genre those figures are actually authored in; a state's box, a flowchart
+stage's box and a device's box have no extent that means anything, so a line
+drawn 60% down one asserts nothing a reader can read.
+
+Load `../scene.md` first — this file adds two words to `block`'s vocabulary
+and changes none of it.
+
+```figdown
+figdown 0.1 block
+group pool "Storage pool"
+node used "In use" in=pool
+threshold "High watermark = stop writes" in=pool offset=80%
+threshold "Low watermark = resume writes" in=pool offset=45%
+band "Reserved" 15% in=pool fill=#fee2e2
+band "Shared quota" 20..70% in=pool extend=down
+```
+
+- `threshold` needs a quoted label **and** `offset=<0..100>%`, both mandatory
+  — the `%` included. There is no `value=` and no `ref=`.
+- `band` needs a quoted label **first**, then either one percentage (a size)
+  or an explicit `<a>..<b>%` range. `..` is the language's ONE range
+  separator; the hyphen form is a line error. `extend=up|down|left|right`, and `up`
+  is the default.
+- Both attach to a node or a group via `in=`.
+- **Attach at the scope the fact belongs to.** A limit shared by everything in
+  a group is one group-level marker; a fact true of one element attaches to
+  that element. The renderer may draw the two the same way — the difference is
+  in the text, and the text is the knowledge.
+
+## The label is the knowledge, and `offset=` is not a value
+
+`offset=` is a fraction of the target's **rendered extent** — where to paint
+the line — **not a value of any quantity**. The target declares no scale, so
+there is no conversion and nothing to convert. Put the number in the label or
+it is not in the document.
+
+**This is the trap, and it is worth naming.** In the domain these figures
+usually come from, a threshold is a queue depth **with a numeric value**: an
+active-queue-management minimum and maximum threshold (RFC 2309, RFC 7567)
+is a number of packets or bytes. FigDown borrowed the word from exactly that
+domain and did **not** borrow the attribute the domain defines it by. So
+`threshold "Max cap" in=q offset=80%` invites a reader to take 80% as the
+threshold value. It is a paint position. Write
+`threshold "Max cap = 800 KB" in=q offset=80%` and the figure says what you
+mean.
+
+The same holds for `band`: a band is a range over that same scale-free
+extent. Its label is the whole of what it asserts.

package/skill/figdown/reference/experimental/chart.md

@@ -0,0 +1,32 @@
+# Charts from a table — `chart`, `type=` (EXPERIMENTAL)
+
+Outside the v0.1 conformance surface and outside the compatibility promise:
+the engine accepts it, but it may change or be withdrawn in a later `0.x`,
+and the parser emits no warning. If the figure must be portable, keep the
+table and drop the chart.
+
+**`chart` is composition, not subject vocabulary.** It says nothing about
+what the figure is *of*, so it is not one of the words a genre declares for
+its own domain — it is legal wherever a `table` region is legal, which is the
+`table` genre and every scene genre, and it means the same thing in all of
+them.
+
+```figdown
+figdown 0.1 table
+table t "Throughput"
+| Port | Gbps |
+|------|------|
+| 1    | 25   |
+| 2    | 40   |
+chart t type=bar3d
+```
+
+- `chart <table-id>` is the whole grammar. It draws from a `table` declared
+  in the same document and is defined by that reference, so the id must
+  already exist.
+- `type=` is the only option key and `bar3d` is its only value.
+- A scene document can carry both halves: open a `table` region inside it for
+  the numbers, then `chart` that id.
+
+For anything a chart library would do better, keep the raster and put the
+numbers in a table (`../transcribe.md`).

package/skill/figdown/reference/experimental/flowchart.md

@@ -1,16 +1,39 @@
-# Genre `flowchart` — EXPERIMENTAL / EXPERIMENTAL
+# Genre `flowchart` — EXPERIMENTAL
 
 The genre itself is outside the v0.1 conformance surface: it may change or be
-withdrawn in a later `0.x`. A portable figure uses `block` instead.
+withdrawn in a later `0.x` without a migration entry. A portable figure uses
+`block` instead.
 
-Load `../scene.md` first — `flowchart` reuses the whole scene vocabulary
-(`node`, `group`, `external`, `edge`, `flow`, `rank`) with the same meanings,
-and adds the three role keywords below. `flow down` is the default here.
+Use `flowchart` when the figure is a **procedure**: stages performed in
+order, with branches. `flow down` is the default here.
 
-## Three role keywords
+**This file is `flowchart`'s whole vocabulary.** Load it and `../layout.md`
+and you can author in this genre; do not load another genre's file, because
+another genre's declaration of a word is not authority for this one. In
+particular this genre declares **no container**: there is no `group`, and
+`in=` and `gap=` are **not this genre's option keys** — `in=` named a `group`
+id and nothing else, so it went out with `group` rather than stay accepted with
+no value that could resolve. Writing either is a line error that names the
+withdrawal. Say what a container would have said with a `class`
+whose label states it — it earns a legend entry and applies to every member at
+once — or split the procedure into two figures joined by `external` endpoints.
+
+**Under `figdown 0.2` the connector is `flowline`, not `edge`** — the word the
+flowchart domain commonly uses for the symbol ISO 5807 §9.3.1 names *Line*.
+Same operators, same labels, same option keys, same model; only the word
+changed.
+
+**The spelling is gated by the version you declare.** Under
+`figdown 0.1 flowchart`, `edge` is still the word and `flowline` is a line
+error naming the version; under `figdown 0.2 flowchart` it is the other way
+round. Each version accepts exactly one spelling — two in one version would be
+an alias. A document that writes `flowline` must declare `figdown 0.2`, and
+`edge` under 0.1 stays legal until v1.0.
+
+## Three role keywords, and when to write `node` instead
 
 ```figdown
-figdown 0.1 flowchart
+figdown 0.2 flowchart
 flow down
 terminator start "Request received"
 process parse "Parse body"
@@ -19,13 +42,13 @@ process apply "Apply change"
 process reject "Reject"
 terminator done "Response sent"
 node log "Audit store" shape=cylinder
-edge start -> parse
-edge parse -> valid
-edge valid -[yes]-> apply
-edge valid -[no]-> reject
-edge apply -> done
-edge reject -> log
-edge log -> parse
+flowline start -> parse
+flowline parse -> valid
+flowline valid -[yes]-> apply
+flowline valid -[no]-> reject
+flowline apply -> done
+flowline reject -> log
+flowline log -> parse
 decision kind "Change kind?" shape=ellipse
 ```
 
@@ -44,13 +67,118 @@ wrong roughly one time in five.
 model still records the role. That is the escape hatch for matching a source
 drawing without lying about what the step is.
 
-**A bare `node` under `flowchart` states no role, and that is often correct.**
-Do not "upgrade" one to `process` unless it really is a step — a datastore, a
-wait, or an annotation is none of the three, and claiming a role would be a
-lie the reader cannot detect.
+**Prefer a role. `node` is the fallback, not the default.** Reach for
+`process`, `decision` or `terminator` first, and write `node` only when **the
+source does not state which** the stage is.
+
+That is what a bare `node` says here, and it is all it says: *the source does
+not state the role.* ISO 5807 is a standard for **drawing** flowcharts, so it
+has no "unclassified" — the person with the pen must draw some symbol, and
+every drawn stage therefore has a classification. FigDown separates role from
+geometry, so it can record the absence instead of inventing a role. A
+transcriber who genuinely cannot tell a Process from a Predefined process
+writes `node`, and that is the honest line.
+
+**`node` is NOT the spelling for "an ISO symbol FigDown has not implemented."**
+Nine ISO stage symbols have no word in this genre — Data (input/output),
+Stored data, Predefined process, Preparation, Manual operation, Manual input,
+Document, Parallel mode, Loop limit. That is a **gap in FigDown**, not a fact
+about your figure, and writing a bare `node` for one of them files the gap as
+if it were your judgement. When your source states a role this genre cannot
+spell:
+
+- write `node` — `process` would be a false claim, and nothing in the figure
+  could catch it;
+- **name the ISO symbol in a comment** on the same line, so the classification
+  survives as text a reader can quote (a comment is never parsed, and never a
+  second semantic channel);
+- report the gap, so it can be counted and closed.
+
+```figdown
+node cfg "Read config file"   # ISO 5807 Data (input/output) — no FigDown role
+```
+
+So do not "upgrade" a `node` to `process` to make it look decided — and do not
+write `node` because deciding was work. Those are different acts with the same
+spelling, and only you know which one you did.
 
 **Label every exit from a `decision`.** Use the on-line label form
-(`edge d -[yes]-> x`) or an endpoint label; an unlabelled branch is a figure
-the reader has to guess at.
+(`flowline d -[yes]-> x`) or an endpoint label; an unlabelled branch is a
+figure the reader has to guess at.
 
 **There is no loop keyword.** A plain back-edge *is* the loop.
+
+## `external` — the boundary, which is not the `terminator`
+
+```figdown
+figdown 0.2 flowchart
+flow down
+external ingress "Frame arrives on a port"
+terminator start "Begin lookup"
+process lookup "Look up destination"
+external egress "Frame leaves the switch"
+flowline ingress -> start
+flowline start -> lookup
+flowline lookup -> egress
+```
+
+`external` is an **out-of-figure endpoint**: the procedure connects to it and
+this figure does not describe it. It is **never drawn** — the flowline simply
+ends open — and it takes **no option key at all**. `terminator` is the
+opposite: a drawn stage of this procedure, its start or its end.
+
+So the question to ask is *whose* start it is. The first box of **this**
+procedure is a `terminator`. A step that belongs to some other procedure, or
+to the world outside the figure, is an `external`.
+
+ISO 5807 §9.4.2 names this concept — its **Terminator** symbol is "an exit
+to, or an entry from, the outside world" — and this genre already spells that
+word `terminator` for the drawn start/end symbol, so the ISO term is taken
+and `external` keeps FigDown's own spelling. Note what follows: ISO has no
+word at all for a boundary that is *never drawn*, which is what `external`
+is. The spelling is FigDown's, not ISO's, and this file is the only place
+that says so.
+
+## Presentation, layout intent and quoting
+
+`flow` takes `flow right|down|left|up` — one of the four, once per document,
+before the stages. `flow down` is this genre's default. `rank a,b,c` pulls
+peers onto one row or column: ONE comma-delimited token, no spaces.
+
+Values from a fixed list are written **bare**, never quoted: `shape=box`,
+`style=dashed`, `flow down`. So are ids. Labels always take quotes.
+
+`shape=` is pure geometry — `shape=box` (the default), `shape=rounded`,
+`shape=circle`, `shape=ellipse`, `shape=diamond`, `shape=cylinder`, and
+nothing else. `style=` takes `style=solid`, `style=dashed` or `style=dotted`.
+
+`class` declares what a colour **means**, and colour that means something
+must be a `class`:
+
+```figdown
+figdown 0.2 flowchart
+class yes "Yes path" stroke=#16a34a
+class no "No path" stroke=#dc2626
+decision check "Valid?"
+process accept "Accept"
+process reject "Reject"
+flowline check -> accept class=yes
+flowline check -> reject class=no
+```
+
+A class a flowline joins MUST declare `stroke=` or `style=`; a `fill=`-only
+class joined by one is an error naming `stroke=`. `fill=` and `stroke=` are
+legal on any drawn element, but a flowline has no interior, so `fill=` on one
+is an error.
+
+The connector's operators are `->`, `<-`, `--` and `<->`. In a procedure you
+almost always want `->`: a step follows another step in one direction, and an
+undirected or two-way flowline asserts an order the reader cannot recover.
+
+Endpoint labels nest (`flowline a [retry 1] -- b`); quote them when they hold
+a line break or an unbalanced bracket. A `#` inside a bracket label is
+ordinary text and needs no quotes, because `[ ]` is a verbatim region.
+
+Under `figdown 0.3` any of these lines may carry `note=`, a drawn aside in
+prose: `process parse "Parse body" note="…"`. It is never parsable and never
+where a structural fact lives.

package/skill/figdown/reference/experimental/statechart.md

@@ -0,0 +1,138 @@
+# Genre `statechart` — EXPERIMENTAL
+
+The genre itself is outside the conformance surface: it may change or be
+**withdrawn** in a later `0.x` without a migration. A portable figure uses
+`block` instead — that is what these figures were spelled as before `figdown
+0.2`, and the rewrite back is one line.
+
+**It needs `figdown 0.2` on line 1.** `figdown 0.1 statechart` is a line
+error, and a deliberately named one: `genre "statechart" requires figdown 0.2`.
+An engine may not read a `0.1` document as though it were `0.2`.
+
+## The vocabulary, which is two words
+
+**This file is `statechart`'s whole vocabulary.** Load it and `../layout.md`
+and you can author in this genre; do not load another genre's file, because
+another genre's declaration of a word is not authority for this one.
+
+This genre declares **two** words of its own — a node is a **`state`** and a
+connector is a **`transition`**, both taken from OMG UML 2.5.1 §14 — and
+**that is the entire list**. It names no container, no boundary, no marker,
+no band and no bundle. Writing one of those here is a line error that states
+the ground rather than guessing at a spelling, and `node` or `edge` here is a
+line error naming the word to write instead.
+
+Three more words are legal because they are not about states at all:
+`class` (what a colour means), `flow` and `rank` (layout intent). Nothing in
+UML competes for them.
+
+Two consequences worth stating, because an author arriving from another genre
+will reach for both:
+
+- **There is no grouping construct.** `in=` and `gap=` are **not this genre's
+  option keys** — writing either is a line error that names the withdrawal.
+  A composite state, a region and a history are things this genre cannot
+  express; a `class` can say two states share a mode, and that is a different
+  and weaker claim. Do not fake a superstate. **`in=`'s spelling is RESERVED
+  here**: if composite states are ever earned, they arrive as nesting on
+  `state` through this exact key, with a `state` id as its value (UML 2.5.1
+  §14.2.3.4) — which is why the key was withdrawn rather than left pointing at
+  a container.
+- **There is no out-of-figure endpoint.** A transition to something the
+  figure does not describe has no spelling. Draw the state, or leave the
+  transition out and say so in the prose beside the figure.
+
+**`external` in particular is not available, and it is reserved.** UML 2.5.1
+§14 already defines `TransitionKind` as `external | internal | local`, where
+an *external* transition is one that exits and re-enters its source state,
+firing its exit and entry behaviours. That is a defined term of art in this
+genre's own source standard. If `external` ever appears in `statechart` it
+will mean what UML means by it, never "an endpoint outside the figure".
+
+`flow right` is the default, as in `block`; `flowchart`'s `down` default does
+**not** apply here.
+
+**Why this genre loses `node` and `flowchart` keeps it:** a statechart has
+exactly one kind of node, so there is nothing to leave unstated and `state`
+gives up nothing. A flowchart stage can have a role **the source does not
+state**, and there `node` is the only way to say so without asserting a role
+the source never gave.
+
+```figdown
+figdown 0.2 statechart
+title "Turnstile"
+class mode "A mode of the mechanism" fill=#e0e7ff
+state locked "LOCKED" class=mode
+state unlocked "UNLOCKED" class=mode
+transition locked -[coin]-> unlocked
+transition unlocked -[push]-> locked
+transition locked -[push]-> locked      # self-transition: the event happens
+                                        # and the machine stays
+flow right
+```
+
+`flow` takes `flow right|down|left|up` — one of the four, once per document.
+`rank a,b` pulls peers onto one row or column: ONE comma-delimited token, no
+spaces. Values from a fixed list are bare (`shape=box`, `style=dashed`,
+`flow right`); labels always take quotes.
+
+`shape=` is pure geometry and changes only the drawing — `shape=box` (the
+default), `shape=rounded`, `shape=circle`, `shape=ellipse`, `shape=diamond`,
+`shape=cylinder`. `style=` takes `style=solid`, `style=dashed` or
+`style=dotted`. A class a transition joins MUST declare `stroke=` or
+`style=`; `fill=` on a transition is an error, because a line has no
+interior. Under `figdown 0.3` a line may carry `note=`, a drawn aside in
+prose — never parsable, never where a structural fact lives.
+
+## What the genre adds, which is a reading and not a syntax
+
+Everything above parses identically under `block`. The genre earns its
+existence in what you are entitled to conclude from it.
+
+**Under `statechart`, and not under `flowchart` or `block`:**
+
+- **Every top-level `state` is a state** — a *mode the machine is in*, not a
+  step it performs. It has duration; the machine sits in it until something
+  happens.
+- **Every `transition` is a transition**, and its direction is the direction of the
+  change. An undirected `--` between two states asserts a relationship the
+  genre has no reading for; do not read it as a transition in both directions.
+- **A mid label is a transition inscription** — the trigger, and optionally a
+  guard and an effect — as free text. There is no structure in it. Quote it,
+  attribute it to its edge, and stop; you may not parse `event / action` into
+  fields, because nothing in the language promises that shape.
+- **A self-loop is "the event occurs and the machine stays"**, which is a
+  fact about the machine. Under `flowchart` the same drawing is a *poll* —
+  "check again" — and that is a different claim entirely.
+- **The set of states is closed.** The nodes are all the modes the figure
+  asserts; a state not drawn is not asserted to exist.
+
+**Still not conclusible, and the list is the same as everywhere else:**
+
+- **No current state.** Nothing in a figure says which state the machine is
+  in now. A fill colour does not, a `class` does not, position does not.
+- **No initial and no final state.** The language has no vocabulary for
+  either at `figdown 0.2` — deliberately, pending evidence, and **no `start`
+  keyword was added**: ISO's terminator symbol is *both* ends distinguished by
+  its label, so there is no word to borrow, and a reader who lacks one answers
+  "unstated" rather than answering wrongly. A state with no incoming
+  transition is *drawn* that way; it is not *declared* initial, and reading it
+  as initial is inventing a fact.
+- **No ordering among transitions.** Peer edges have no sequence, and an
+  ordinal in a label is naming, not order.
+- **No hierarchy, no regions, no history.** There is no grouping construct to
+  misuse for one.
+- **Nothing from the layout zone.** `pin` is arrangement for humans; skip it.
+
+**Reclassifying costs more than one line now.** Changing `flowchart` to
+`statechart` on line 1 no longer suffices: every `flowline` becomes a
+`transition` and every `node` a `state`. Run `tools/migrate-figdown.js` — it
+rewrites both, scoped by the header genre.
+
+**Do not upgrade a `flowchart` to a `statechart` on structure.** It was
+measured: cycles do not separate the two (of the state machines and the
+flowcharts in this project's own corpus, both are usually cyclic), and
+self-loops appear in almost none. A retry loop drawn as a flowchart is exactly
+the figure that reads wrong as a statechart. **Only the declared genre says
+which it is** — and a title that contains the words "state machine" does not,
+because a polling flowchart is routinely titled that way.

package/skill/figdown/reference/experimental/timing.md

@@ -1,4 +1,4 @@
-# Genre `timing` — EXPERIMENTAL / EXPERIMENTAL
+# Genre `timing` — EXPERIMENTAL
 
 The genre itself is outside the v0.1 conformance surface: it may change or be
 withdrawn in a later `0.x`. There is no portable alternative — a waveform

package/skill/figdown/reference/experimental/topology.md

@@ -1,38 +1,164 @@
-# Genre `topology` — EXPERIMENTAL / EXPERIMENTAL
+# Genre `topology` — EXPERIMENTAL
 
 The genre itself is outside the v0.1 conformance surface: it may change or be
-withdrawn in a later `0.x`. A portable figure uses `block` instead — the
-vocabulary is identical, the defaults are identical, and `block` is inside
-the compatibility promise.
+withdrawn in a later `0.x` without a migration entry. A portable figure uses
+`block` instead, which is inside the compatibility promise.
 
-Load `../scene.md` first. `topology` adds **no keyword of its own and changes
-no default**: it is the scene vocabulary under a name that says the figure is
-a network of peers rather than a pipeline of stages. What it carries is the
-intent — which matters to a reader and to nothing else.
+Use `topology` when the figure is a **network of devices and the links
+between them** — fabrics, overlays, access layers, peering diagrams. The
+nodes are devices or endpoints and the edges are physical or logical links,
+not dataflow steps. That intent is what the genre carries; it matters to a
+reader and to nothing else.
+
+**This file is `topology`'s whole vocabulary.** Load it and `../layout.md`
+and you can author in this genre; do not load another genre's file, because
+another genre's declaration of a word is not authority for this one. Words
+`topology` does **not** declare — and there are several a `block` author
+would reach for — are line errors that say so and give the ground.
+
+## The vocabulary, in one figure
 
 ```figdown
 figdown 0.1 topology
 title "Leaf-spine fabric"
-flow right
+
+flow right                       # reading direction; ONE per document,
+                                 # before the nodes
+
 node s1 "Spine 1"
 node s2 "Spine 2"
-group pod "Pod A"
-node l1 "Leaf 1" in=pod
-node l2 "Leaf 2" in=pod
-external wan "To WAN"
-edge l1 -- s1
+
+group pod "Pod A" gap=0          # a container; gap=0 packs its members
+node l1 "Leaf 1" in=pod          # flush against each other. The id is
+node l2 "Leaf 2" in=pod          # required and exists only so other lines
+                                 # can name it
+
+node fw "Firewall" shape=rounded
+node store "Config store" shape=cylinder style=solid
+
+external wan "To WAN"            # outside the figure. NEVER drawn as a
+                                 # shape — the link simply ends open there
+
+edge l1 -- s1                    # ops: ->  <-  --  <->
 edge l1 -- s2
 edge l2 -- s1
 edge l2 -- s2
-edge s1 -- wan
-class uplink "40G uplink" stroke=#0284c7
+edge s1 -> wan                   # arrow points at `wan`
+edge wan <- s2
+edge fw <-> store
+edge l1 -[lacp]-> fw             # on-line label splits the operator
+edge l2 [ge-0/0/1] -- [xe-0/0/0] fw   # endpoint labels: ports, roles
+edge s1 -- s2 style=dotted       # spines not cabled to each other
+
+rank l1,l2                       # pull peers onto one row/column. ONE
+                                 # comma-delimited token, no spaces
+
+class uplink "Uplink, 40G" stroke=#0284c7
 edge l2 -- s2 class=uplink
+
+bundle lag1 "LAG to the leaf pair" l1--s1,l2--s1
+```
+
+`flow` takes `flow right|down|left|up` — one of the four, once per document.
+
+Values from a fixed list are written **bare**, never quoted: `shape=box`,
+`style=dashed`, `flow down`, `gap=0`. So are ids. Labels are the opposite
+and always take quotes.
+
+`shape=` is **pure geometry, no domain nouns** — `shape=box` (the default),
+`shape=rounded`, `shape=circle`, `shape=ellipse`, `shape=diamond`,
+`shape=cylinder`, and nothing else. There is no router symbol, no switch
+symbol and no cloud: a cloud in a source drawing is an ellipse or a group,
+with what it *is* — "the internet", "the transit provider" — written in the
+label. `style=` takes `style=solid`, `style=dashed` or `style=dotted`.
+
+`class` declares what a colour **means** and is the only way to make colour
+carry meaning; a class an edge joins MUST declare `stroke=` or `style=`, and
+a `fill=`-only class joined by an edge is an error naming `stroke=`. `fill=`
+and `stroke=` are legal on any element, but an `edge` has no interior, so
+`fill=` on one is an error.
+
+Endpoint labels nest (`edge a [xe-0/0/0:1] -- b`); quote them when they hold
+a line break or an unbalanced bracket (`edge a ["slot\n1/1"] -- b`). A `#`
+inside a bracket label is ordinary text and needs no quotes —
+`edge a -[hop #1]-> b` — because `[ ]` is a verbatim region.
+
+Under `figdown 0.3` any of these lines may carry `note=`, a drawn aside in
+prose: `node s1 "Spine 1" note="…"`, `edge l1 -- s1 note="…"`,
+`title "Fabric" note="…"`. It is never parsable and never where a structural
+fact lives.
+
+## `group` is not a multicast group
+
+`group` here is a **container**: a box drawn round its members, one nesting
+level deep — a pod, a rack, a site, a tenant. It is not IGMP or MLD
+membership, and `group g "224.0.0.5"` does not say what a reader of that
+address expects.
+
+The spelling stays anyway, because in this domain every synonym is more
+taken than the word is: `zone` belongs to DNS and to firewalls, `cluster` to
+route reflection (RFC 4456), `domain` to inter-domain traffic engineering
+(RFC 7926), `area` to OSPF, `site` to EVPN. Trading a soft collision for a
+hard one is a bad trade — and this collision **is** soft, because the drawing
+contradicts the wrong reading: a multicast group is never drawn as a box
+round its members.
+
+## `external` is not an external route
+
+`external` is an **out-of-figure endpoint**: something this figure talks to
+but does not describe. It is never drawn, it takes **no option key at all**,
+and the link to it simply ends open.
+
+It is not an external route — not an OSPF Type 5 or Type 7 LSA, not an eBGP
+peer, not "the external interface". Same soft collision, same reason for
+keeping the spelling: an `external` is never drawn at all, so a reader who
+starts with the routing sense finds nothing on the page to sustain it. Where
+the figure means *the router that faces outside*, that router is a `node`
+with a label saying so; `external` is for what the figure leaves out.
+
+## `bundle` — a LAG, an ECMP set, an Ethernet Segment
+
+```figdown
+figdown 0.1 topology
+node leaf "Leaf"
+node s1 "Spine 1"
+node s2 "Spine 2"
+edge leaf -- s1
+edge leaf -- s2
+bundle ecmp "ECMP uplink set, 2 × 100G" leaf--s1,leaf--s2
 ```
 
-The constructs most topology figures reach for next — link bundles for LAGs
-and ECMP sets, overlay planes for tunnels, markers and zone bands — are in
-`constructs.md`, and every one of them is EXPERIMENTAL too.
+A **link bundle**: a set of parallel links between the same pair of devices
+operated as one logical link. Its referents are the ones this domain already
+names — a link aggregation group (IEEE 802.1AX), an equal-cost multipath
+set, an EVPN Ethernet Segment — and the ring drawn round the member links is
+the same thing the domain means. The domain reading and the drawn reading
+are one reading; this is the cell where the word and the referent agree, and
+it is why `topology` declares `bundle` and the general-purpose genre has no
+use for it.
+
+`bundle` is EXPERIMENTAL even inside this experimental genre. It is spelled
+`bundle` and not after the standard's own noun deliberately: *aggregation*
+is right for a link aggregation group and false for an equal-cost multipath
+set and for an Ethernet Segment, so the standard's word cannot be taken
+whole and an umbrella spelling is the honest one.
+
+- The member list is ONE comma-delimited token, no spaces.
+- Each member must name an edge that **already exists** and is unambiguous.
+  There is no way to address one of two parallel edges between the same
+  pair, so a bundle over parallel links cannot be spelled — declare the
+  members as distinct edges to distinct peers, as above.
+- `bundle` takes `fill=`, `stroke=` and `style=`; the dashed ring is drawn
+  for you.
+
+## Two mistakes this genre invites
+
+**A shared medium is not a star.** Flattening a bus, a broadcast segment, a
+shared VLAN or a fabric's underlay into point-to-point links changes what the
+figure asserts: the shared thing reaches every participant at once. Model it
+as one intermediate `node` that fans out.
 
-The two mistakes this genre invites are both covered where they are owned:
-a shared medium modelled as a mesh (`../scene.md`, "A shared bus is not a
-star") and geography carried by the layout zone alone (`../layout.md`).
+**Geography is not carried by the layout zone.** If where a device sits is
+part of the claim — a site, a rack, a country — say it with a `group` and a
+label. Delete every `pin` and the figure must still be the same figure
+(`../layout.md`).