figdown 0.2.0 → 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,15 +1,27 @@
-# 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.
-
-Load `../scene.md` first — `flowchart` reuses the scene vocabulary
-(`node`, `group`, `external`, `flow`, `rank`) with the same meanings, and adds
-the three role keywords below. `flow down` is the default here.
-
-**Under `figdown 0.2` the connector is `flowline`, not `edge`** — ISO 5807's
-own word for a flowchart's connecting line. Same operators, same labels, same
-option keys, same model; only the word changed.
+withdrawn in a later `0.x` without a migration entry. A portable figure uses
+`block` instead.
+
+Use `flowchart` when the figure is a **procedure**: stages performed in
+order, with branches. `flow down` is the default here.
+
+**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
@@ -95,3 +107,78 @@ spelling, and only you know which one you did.
 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

@@ -1,4 +1,4 @@
-# Genre `statechart` — EXPERIMENTAL / EXPERIMENTAL
+# 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
@@ -9,12 +9,45 @@ The genre itself is outside the conformance surface: it may change or be
 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`.
 
-Load `../scene.md` first — `statechart` reuses the scene vocabulary
-(`group`, `external`, `class`, `flow`, `rank`) with the same meanings, and
-**renames the other two**: a node is a **`state`** and a connector is a
-**`transition`**, both taken from OMG UML 2.5.1 §14. Nothing else changes —
-same option keys, same id space, same operators, same model — and `node` or
-`edge` here is a **line error** naming the word to write instead.
+## 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.
@@ -38,6 +71,19 @@ transition locked -[push]-> locked      # self-transition: the event happens
 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
@@ -74,8 +120,8 @@ existence in what you are entitled to conclude from 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.** A `group` groups; it does not
-  make a superstate.
+- **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

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`).

package/skill/figdown/reference/reading.md

@@ -25,6 +25,18 @@ syntax detail in the other files beside it.
 - **Authored prose** in a `description=` is quotable and displayable, and
   **never parsable**. Quote it, attribute it to its field, and stop. It
   carries no structure, no relation and no condition.
+- **A `note=` is authored prose too, on the same terms** (`figdown 0.3`).
+  It is quotable and displayable and **never parsable**. It is an **aside**:
+  its content is not a fact about the figure's structure. You MAY attribute
+  it to the element that carries it — attachment is by syntactic position, so
+  there is never a question of which element is meant — and you MUST NOT
+  infer a participant, an edge or a category from it. A `note=` on `title`
+  (`doc.note`) belongs to the **figure**, not to any element.
+- **`description=` and `note=` are not the same channel and neither replaces
+  the other.** They divide by AUDIENCE: `description=` is written **for you**
+  and puts no ink on the page; `note=` is written for the **human** and always
+  draws. Both may appear in one document, and an element carrying both is
+  making two statements to two readers, not saying one thing twice.
 
 ## Genre-specific readings
 
@@ -71,7 +83,7 @@ Widths, colours and alignment never change it.
 **`timing`.** Cycle *t* is the *t*-th character of the lane. `.` continues
 the previous value, and cycles stay contiguous across a gap.
 
-**`statechart`** (EXPERIMENTAL, `figdown 0.2` only). Nodes are **states** — modes
+**`statechart`** (EXPERIMENTAL, `figdown 0.2` and later). Nodes are **states** — modes
 the machine is *in* — and edges are **transitions** on an event. This is the
 one reading you may not derive from the drawing: a cyclic figure with a
 self-loop is just as likely to be a polling `flowchart`, and the word "state

package/skill/figdown/reference/scene.md

@@ -1,27 +1,37 @@
-# Scene genres — `block`, and the vocabulary `topology` / `flowchart` / `statechart` share
+# Genre `block` — things and the connections between them
 
-Status: `block` is NORMATIVE and portable. The same seven keywords are
-the whole scene surface; `topology`, `flowchart` and `statechart` reuse them
-and add — or **rename** — their own, in their own files.
+Status: NORMATIVE and portable.
 
-Load this for any figure made of **things and the connections between them**.
+Load this for any figure made of **things and the connections between
+them** whose line 1 says `block`. Everything below is `block`'s own
+vocabulary; nothing below is authority for any other genre.
 
-**Two of the seven are spelled differently by genre.** Read
-this file for what they *mean*; write the word your genre uses:
+**Every scene genre declares its own words.** There are four, and each one's
+vocabulary is declared once, in its own file:
 
-| genre | the thing | the line |
-|---|---|---|
-| `block`, `topology` | `node` | `edge` |
-| `flowchart` | `node` | **`flowline`** |
-| `statechart` | **`state`** | **`transition`** |
+| genre on line 1 | where its vocabulary is declared |
+|---|---|
+| `block` | this file |
+| `topology` | `experimental/topology.md` |
+| `flowchart` | `experimental/flowchart.md` |
+| `statechart` | `experimental/statechart.md` |
 
-Each genre takes the term its own domain actually uses — ISO 5807 calls a
-flowchart's connector a *flowline*; UML calls a state machine's arc a
-*transition*. The wrong one is a **line error naming the right one**, never a
-silent acceptance, so you cannot get this wrong without being told. Everything
-else about them — operators, labels, option keys, the model — is identical.
+A word two of them spell the same is **two declarations that happen to agree
+today**, never one inherited — each genre may withdraw, rename or constrain
+its own without touching the others, and each carries its own reading advice
+because the same word can be safe in one domain and misleading in another.
+So do not carry a word from this file into another genre and do not go
+looking here for a word another genre's file did not give you: a word the
+genre on line 1 does not declare is a **line error that states the ground**,
+not a spellcheck.
 
-## The seven keywords
+Three words are spelled the same in all four and are not subject vocabulary
+at all — `class` says what a colour *means*, `flow` and `rank` state layout
+intent. None of them names a thing in the world, so no domain holds a rival
+meaning for one, and each genre's file repeats them rather than sending you
+here.
+
+## The vocabulary, in one figure
 
 ```figdown
 figdown 0.1 block
@@ -67,8 +77,8 @@ edge retry -> reject class=slow
 `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`, `plane=over`. So are ids. Labels are the
-opposite and always take quotes.
+`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`,
@@ -82,6 +92,26 @@ inside a bracket label is ordinary text and needs no quotes —
 `edge a -[hop #1]-> b` — because `[ ]` is a verbatim region, like a quoted
 string, a comment and a pipe row.
 
+## What `group` and `external` claim here, and what they do not
+
+`block` is the **general-purpose** genre: it has no single domain, and that
+is what general-purpose means. So its two container-and-boundary words carry
+no domain caveat, and you should not supply one.
+
+- **`group`** is a container and nothing more — a box drawn round its
+  members, one nesting level deep. It asserts no ownership, no lifecycle, no
+  address space and no failure domain. Whatever the grouping *means* goes in
+  the label.
+- **`external`** is an out-of-figure endpoint: something the figure talks to
+  but does not describe. It is **never drawn** — the edge simply ends open —
+  it takes **no option key at all**, and there is no source standard behind
+  the spelling. It is FigDown's own word for FigDown's own boundary.
+
+A genre with one domain cannot be this quiet. `topology`'s file has to warn
+its reader off a rival reading of both words before it can use either; this
+file has nothing to warn about, and that asymmetry is why the two
+declarations are separate.
+
 ## Field-tested pitfalls
 
 **Containment is not an edge.** An edge from a node to its own container
@@ -129,5 +159,28 @@ a `node` styled to look like one.
 ## Where to go next
 
 - The figure came out scrambled, or placement is the message → `layout.md`
-- Marker lines, zone bands, link bundles, overlay planes, charts →
-  `experimental/constructs.md` (EXPERIMENTAL)
+- Marker lines and zone bands over a `block` figure →
+  `experimental/block.md` (EXPERIMENTAL)
+- Bars drawn from a `table` region → `experimental/chart.md` (EXPERIMENTAL)
+
+## The drawn annotation — `note=` (`figdown 0.3`)
+
+`note=` is an **attribute on the annotated element's own line**, and the
+element it is about is the element it is written on: `node a "A" note="…"`,
+`group g "G" note="…"`, `edge a -> b note="…"`, `title "T" note="…"`.
+There is no id, no target key and no locator, so there is never a question
+of which of several identically-labelled elements is meant.
+
+**What you may conclude.** The text is authored prose — quotable,
+displayable, **never parsable**. It is an aside about the element, not a
+fact about the figure's structure. Attribute it to its carrier and stop;
+do not infer a participant, an edge or a category from it. A `note=` on
+`title` is about the **figure** and about no element.
+
+**What it is not.** It is not `description=`. The two divide by AUDIENCE:
+`description=` is machine-facing and draws nothing beyond an SVG `<title>`;
+`note=` is human-facing and always draws. And **where a typed slot exists,
+a note is never where the fact lives** — a category is a `class` meaning, a
+containment is `in=`, a direction is the operator. If a note's text looks
+like structure, it is still prose: read the structure off the construct that
+states it.