figdown 0.1.0-rc.1 → 0.1.0

package/{SHOWCASE.md → guide/showcase.md}

@@ -10,77 +10,82 @@ that would otherwise need OCR. The sixth — the complete TCP state machine —
 is the stress test: every state and every labelled transition of RFC 9293
 Figure 5 on one canvas.
 
-Each entry: the rendered SVG, the full `.fd`, one line on what the human sees,
-and questions an agent answers **from the text alone**. Every colour and
+Each entry: the rendered SVG, the `.fd` itself with its comment banners
+elided, one line on what the human sees, and questions an agent answers **from the text alone**. Every colour and
 dash is carried by a `class` whose label states its *meaning*; no meaning rides
-on geometry (`tools/r25-check.js --strict`) or presentation.
+on geometry (`tools/strip-check.js --strict`) or presentation.
 
 Two of these figures — the TCP handshake and ARP resolution — are deliberately
-**mixed documents**: a scene block *and* a `table` block in one `.fd`, composed
-in document order (spec §8). This is the project's ruled answer for content the
-scene genre cannot yet carry first-class (per-endpoint lifeline state; a local
-cache transition): a second typed block carries it machine-readably, rather than
-letting it ride on geometry or absence.
+**multi-section hybrids (`MULTI-FIGURE-DOCUMENTS`)**: a scene section *and* a later
+`figdown 0.1 table` section in one `.fd`, stacked into one SVG.
+Each section has one genre and its own id space (`GENRE-KEYWORD-ALLOWLIST` allowlist). This is the
+main-standard answer for content the scene genre cannot yet carry first-class
+(per-endpoint lifeline state; a local cache transition): a second section
+carries it machine-readably, rather than letting it ride on geometry or
+absence. Nested `table` under a single scene header is legacy, not the taught
+path.
 
 ---
 
 ## 1. TCP header — bit-exact machine-readable layout (`bitfield`)
 
-![TCP header](examples/showcase/tcp-header.svg)
+![TCP header](../examples/showcase/tcp-header.svg)
 
 ```figdown
 figdown 0.1 bitfield
-title TCP Header
+title "TCP Header"
 
-bitfield tcp "TCP Header (RFC 9293)" unit=32 numbering=msb0
+bitfield tcp "TCP Header (RFC 9293)" word=32 numbering=msb0
 
 field "Source Port" 16
 field "Destination Port" 16
 field "Sequence Number" 32
 field "Acknowledgment Number" 32
-field "Data Offset" 4 note="header length in 32-bit words; min 5 (=20 bytes), max 15 (=60 bytes)"
-field Reserved 4 note="must be zero"
-field CWR 1
-field ECE 1
-field URG 1
-field ACK 1
-field PSH 1
-field RST 1
-field SYN 1 color=#fee2e2
-field FIN 1 color=#fee2e2
-field Window 16 note="receive window size in bytes (subject to window scaling option)"
-field Checksum 16
+field "Data Offset" 4 description="header length in 32-bit words; min 5 (=20 bytes), max 15 (=60 bytes)"
+field "Reserved" 4 description="must be zero"
+field "CWR" 1
+field "ECE" 1
+field "URG" 1
+field "ACK" 1
+field "PSH" 1
+field "RST" 1
+field "SYN" 1 fill=#fee2e2
+field "FIN" 1 fill=#fee2e2
+field "Window" 16 description="receive window size in bytes (subject to window scaling option)"
+field "Checksum" 16
 field "Urgent Pointer" 16
-field Options 32 optional note="present iff Data Offset > 5; padded to a 32-bit boundary"
-field Data * note="variable-length payload; length from the IP datagram, not the TCP header"
+field "Options" 32 present="Data Offset > 5" description="padded to a 32-bit boundary"
+field "Data" * description="variable-length payload; length from the IP datagram, not the TCP header"
 ```
 
 **Human sees:** the RFC-style header — a 32-bit ruler, every field to width,
-the eight flags as individual bit cells, Options dashed (optional).
+the eight flags as individual bit cells, Options dashed with a caption stating
+its condition (`present=`).
 
 **An agent answers from the text alone:**
 
 - *Q: Which bits carry the window size?* A: bits 112–127 — the sum of preceding
   widths (96 for rows 1–3, then Data Offset 4 + Reserved 4 + eight 1-bit flags)
   places `Window` next. Derived from field order/width, not the drawing.
-- *Q: Is SYN one bit or a byte?* A: one bit (`field SYN 1`); each of the eight
+- *Q: Is SYN one bit or a byte?* A: one bit (`field "SYN" 1`); each of the eight
   flags is a distinct, individually addressable 1-bit field.
 - *Q: When are Options present; what is the minimum header length?* A: present
-  iff Data Offset > 5 (`optional` + note); minimum header = 5 × 32-bit words =
-  20 bytes (Data Offset note).
+  iff Data Offset > 5 (`present="Data Offset > 5"`, which also draws as a
+  caption under the block); minimum header = 5 × 32-bit words = 20 bytes
+  (Data Offset field's `description=`).
 
 ---
 
 ## 2. TCP three-way handshake — labelled directed exchange (`topology`)
 
-![TCP handshake](examples/showcase/tcp-handshake.svg)
+![TCP handshake](../examples/showcase/tcp-handshake.svg)
 
 ```figdown
 figdown 0.1 topology
-title TCP Three-Way Handshake
+title "TCP Three-Way Handshake"
 
-class setup "Connection-setup segment — carries SYN and/or ACK control flags" color=#2563eb
-class data  "Segment that also carries application data (piggybacked on the ACK)" color=#16a34a
+class setup "Connection-setup segment — carries SYN and/or ACK control flags" stroke=#2563eb
+class data  "Segment that also carries application data (piggybacked on the ACK)" stroke=#16a34a
 
 node client "Client (active open)"
 node server "Server (passive open, LISTEN)"
@@ -91,6 +96,8 @@ edge client -[1: SYN  seq=x]-> server class=setup
 edge server -[2: SYN,ACK  seq=y ack=x+1]-> client class=setup
 edge client -[3: ACK  ack=y+1  (+ data)]-> server class=data
 
+# --- panel: separate genre section (multi-section `MULTI-FIGURE-DOCUMENTS`) ---
+figdown 0.1 table
 table state "Endpoint state after each segment (RFC 9293 §3.3.2 state names)"
 | Segment            | Client state          | Server state              |
 |--------------------|-----------------------|---------------------------|
@@ -100,11 +107,12 @@ table state "Endpoint state after each segment (RFC 9293 §3.3.2 state names)"
 | 3: ACK →           | ESTABLISHED           | ESTABLISHED on receipt    |
 ```
 
-This is a **mixed document**: a `topology` scene *and* a `table` in one `.fd`,
-composed in document order (spec §8). The canonical RFC 9293 figure carries the
-per-endpoint state on the lifelines; the topology genre has no lifeline-state
-construct, so the companion table carries those states machine-readably —
-composition is the ruled interim until the sequence genre lands.
+This is a **multi-section hybrid**: a `topology` scene section *and* a
+`table` section in one `.fd`, stacked into one SVG (`MULTI-FIGURE-DOCUMENTS`). The canonical RFC
+9293 figure carries the per-endpoint state on the lifelines; the topology
+genre has no lifeline-state construct, so the companion table section carries
+those states machine-readably — multi-section composition is the main-standard
+interim until the sequence genre lands.
 
 **Human sees:** two endpoints and three numbered segments — SYN out, SYN-ACK
 back, ACK (with piggybacked data) out — with a state table below tracking each
@@ -122,25 +130,25 @@ endpoint's TCP state segment by segment.
   the companion table carries the RFC 9293 lifeline states.
 
 > **Honest limit (stated in the source):** message *order* rides on the 1/2/3
-> label ordinals, not a first-class construct — R37 does not treat numbering as
-> semantics. The v0.2 sequence genre (OQ-S18) closes this; see
-> [EXPRESSING.md](EXPRESSING.md), "strict message ordering".
+> label ordinals, not a first-class construct — `MEANING-RECOVERY-SOURCE` does not treat numbering as
+> semantics. The v0.2 sequence genre (`FLOWCHART-GENRE-DESIGN`) closes this; see
+> [expressing.md](expressing.md), "strict message ordering".
 
 ---
 
 ## 3. L2 switch forwarding decision — protocol logic, readable (`flowchart`)
 
-![L2 forwarding logic](examples/showcase/l2-forwarding-logic.svg)
+![L2 forwarding logic](../examples/showcase/l2-forwarding-logic.svg)
 
 ```figdown
 figdown 0.1 flowchart
-title L2 Switch Forwarding Decision
+title "L2 Switch Forwarding Decision"
 
-class forward "Forward — send the frame out the single learned egress port" color=#16a34a
-class flood   "Flood — send out every port in the VLAN except the ingress port" color=#2563eb
-class filter  "Filter — discard; destination is out the same port it arrived on" color=#dc2626
+class forward "Forward — send the frame out the single learned egress port" fill=#16a34a
+class flood   "Flood — send out every port in the VLAN except the ingress port" fill=#2563eb
+class filter  "Filter — discard; destination is out the same port it arrived on" fill=#dc2626
 
-boundary wire "from ingress port"
+external wire "from ingress port"
 
 node learn  "Learn source MAC:\nupdate MAC table\n(SA -> ingress port)"
 node lookup "Look up destination MAC\nin MAC table"
@@ -180,13 +188,13 @@ is no unstated fourth path.
 
 ## 4. Ethernet II frame — byte order carried by syntax (`table`)
 
-![Ethernet frame](examples/showcase/ethernet-frame.svg)
+![Ethernet frame](../examples/showcase/ethernet-frame.svg)
 
 ```figdown
 figdown 0.1 table
-title Ethernet II Frame — Untagged vs 802.1Q Tagged
+title "Ethernet II Frame — Untagged vs 802.1Q Tagged"
 
-class tag "802.1Q VLAN tag (4 bytes), inserted after Source MAC; absent in an untagged frame" color=#dbeafe
+class tag "802.1Q VLAN tag (4 bytes), inserted after Source MAC; absent in an untagged frame" fill=#dbeafe
 
 table eth "Ethernet II frame — column order = wire order (byte counts in the second header tier)"
 | Variant  | Destination MAC | Source MAC | 802.1Q Tag  | EtherType | Payload         | FCS       |
@@ -194,9 +202,9 @@ table eth "Ethernet II frame — column order = wire order (byte counts in the s
 |----------|-----------------|------------|-------------|-----------|-----------------|-----------|
 | Untagged | DA              | SA         | (none)      | Type      | Data            | CRC-32    |
 | Tagged   | DA              | SA         | TPID 0x8100 + PCP/DEI/VID | Type | Data       | CRC-32    |
-colw 90 auto auto auto auto auto auto
-cell 1,4 class=tag
-cell 2,4 class=tag
+width 90,auto,auto,auto,auto,auto,auto
+cell (1,4) class=tag
+cell (2,4) class=tag
 ```
 
 **Human sees:** the frame in wire order left-to-right, two variants (untagged /
@@ -211,32 +219,32 @@ cell 2,4 class=tag
 - *Q: Untagged vs tagged?* A: the tag column is `(none)` vs
   `TPID 0x8100 + PCP/DEI/VID` — absent, not zeroed (class label).
 
-The OQ-S24 sanctioned pattern: a byte-unit packet is a single-row `table`, so
+The `BYTE-UNIT-PACKET-BLOCKS` sanctioned pattern: a byte-unit packet is a single-row `table`, so
 byte order lives in cell order (strip test survives), not a bit ruler.
 
 **One fact this figure cannot draw:** the FCS (CRC-32) is computed over
 Destination MAC through Payload inclusive — a coverage span across a
 *contiguous run of columns*. FigDown has no construct to annotate such a span
-(curly-brace grouping over a contiguous cell range is **OQ-S16**, v0.2), so the
+(curly-brace grouping over a contiguous cell range is **`CONTIGUOUS-RANGE-GROUPING`**, v0.2), so the
 fact is stated in the `.fd` source comment and here in prose, never on geometry.
 
 ---
 
-## 5. ARP resolution — boundary + class discipline (`topology`)
+## 5. ARP resolution — external + class discipline (`topology`)
 
-![ARP resolution](examples/showcase/arp-resolution.svg)
+![ARP resolution](../examples/showcase/arp-resolution.svg)
 
 ```figdown
 figdown 0.1 topology
-title ARP Resolution
+title "ARP Resolution"
 
-class bcast "Broadcast — delivered to every host on the LAN (dst MAC ff:ff:ff:ff:ff:ff)" color=#dc2626 style=dashed
-class ucast "Unicast — delivered only to the requester (dst MAC = A's MAC)" color=#16a34a
+class bcast "Broadcast — delivered to every host on the LAN (dst MAC ff:ff:ff:ff:ff:ff)" stroke=#dc2626 style=dashed
+class ucast "Unicast — delivered only to the requester (dst MAC = A's MAC)" stroke=#16a34a
 
 node a "Host A\nwants MAC for B's IP"
 node b "Host B\nowns the target IP"
 
-boundary lan "rest of the LAN\n(hosts C, D, ...)"
+external lan "rest of the LAN\n(hosts C, D, ...)"
 
 flow right
 
@@ -244,6 +252,8 @@ edge a -[1: who-has B?  (broadcast)]-> b class=bcast
 edge a -[1: heard, ignored]-> lan class=bcast
 edge b -[2: B is at aa:bb:cc:...  A caches it]-> a class=ucast
 
+# --- panel: separate genre section (multi-section `MULTI-FIGURE-DOCUMENTS`) ---
+figdown 0.1 table
 table cache "Host A's ARP cache — before and after the exchange"
 | Moment             | Entry                                   |
 |--------------------|-----------------------------------------|
@@ -251,14 +261,14 @@ table cache "Host A's ARP cache — before and after the exchange"
 | after segment 2    | B's IP → aa:bb:cc:... , learned from the reply |
 ```
 
-This too is a **mixed document** (scene + table in one `.fd`, document order):
-the cache *transition* is the figure's actual outcome, but it is a local state
-change on A rather than a message, so the companion table carries the
-before/after cache state machine-readably.
+This too is a **multi-section hybrid** (scene section + `table` section in one
+`.fd`, stacked SVG): the cache *transition* is the figure's actual outcome, but
+it is a local state change on A rather than a message, so the companion table
+section carries the before/after cache state machine-readably.
 
 **Human sees:** A broadcasts who-has (reaching B; the rest of the LAN hears it
 and ignores it), B replies by unicast and A caches the binding — broadcast
-dashed-red, unicast green, "rest of the LAN" an open boundary — with a cache
+dashed-red, unicast green, "rest of the LAN" an open `external` endpoint — with a cache
 table below showing the before/after state. The cache update is a local action
 on A, not a message, so it rides on the reply label, the cache table, and this
 prose rather than on an edge of its own.
@@ -271,30 +281,30 @@ prose rather than on an edge of its own.
 - *Q: Who receives the reply, and what does A do with it?* A: only Host A —
   reply edge `class=ucast`, directed `b -> a`; the label states A caches the
   IP → MAC binding on receipt.
-- *Q: Is "rest of the LAN" a participating host?* A: no — a `boundary`, stating
+- *Q: Is "rest of the LAN" a participating host?* A: no — an `external`, stating
   only that the broadcast crosses the figure's edge.
 - *Q: What does A's cache hold before the exchange?* A: nothing — row 1 of the
   cache table (`before the exchange` → `(no entry for B's IP)`). Answerable only
   because the companion table carries the before-state explicitly.
 
 > **Honest limit:** step order (1/2) rides on label ordinals, pending the v0.2
-> sequence genre (OQ-S18).
+> sequence genre (`FLOWCHART-GENRE-DESIGN`).
 
 ---
 
 ## 6. TCP connection state machine — every state, every transition (`flowchart`)
 
-![TCP state machine](examples/showcase/tcp-state-machine.svg)
+![TCP state machine](../examples/showcase/tcp-state-machine.svg)
 
 ```figdown
 figdown 0.1 flowchart
-title TCP Connection State Machine (RFC 9293, Figure 5)
+title "TCP Connection State Machine (RFC 9293, Figure 5)"
 
-class states  "A node IS a TCP state (RFC 9293 §3.3.2); the two CLOSED nodes are one state — no node-identity construct yet (OQ-S26)" color=#eef2ff
-class setup   "Connection-setup transition — opening the connection (OPEN, SYN exchange, first ACK)" color=#2563eb
-class client  "Active-close path (typically the client) — calls CLOSE first: FIN-WAIT-1 → FIN-WAIT-2 / CLOSING → TIME-WAIT → CLOSED" color=#dc2626
-class server  "Passive-close path (typically the server) — receives the peer's FIN first: CLOSE-WAIT → LAST-ACK → CLOSED" color=#16a34a
-class rare    "Rare / simultaneous transition — simultaneous open or close, or a reset/abort (RST, close from a half-open state)" color=#9333ea style=dashed
+class states  "A node IS a TCP state (RFC 9293 §3.3.2); the two CLOSED nodes are one state drawn twice — only this label says so" fill=#eef2ff
+class setup   "Connection-setup transition — opening the connection (OPEN, SYN exchange, first ACK)" stroke=#2563eb
+class client  "Active-close path (typically the client) — calls CLOSE first: FIN-WAIT-1 → FIN-WAIT-2 / CLOSING → TIME-WAIT → CLOSED" stroke=#dc2626
+class server  "Passive-close path (typically the server) — receives the peer's FIN first: CLOSE-WAIT → LAST-ACK → CLOSED" stroke=#16a34a
+class rare    "Rare / simultaneous transition — simultaneous open or close, or a reset/abort (RST, close from a half-open state)" stroke=#9333ea style=dashed
 
 node closed "CLOSED"        shape=rounded class=states
 node listen "LISTEN"        shape=rounded class=states
@@ -336,30 +346,40 @@ edge estab -[rcv FIN / snd ACK]-> closewait class=server
 edge closewait -[CLOSE / snd FIN]-> lastack class=server
 edge lastack -[rcv ACK of FIN / x]-> closed2 class=server
 
-render
-pin closed    at=394,20
-pin listen    at=394,150
-pin synrcvd   at=152,280
-pin synsent   at=607,280
-pin estab     at=376,410
-pin fw1       at=159,540
-pin closewait at=600,540
-pin fw2       at=159,670
-pin closing   at=311,670
-pin lastack   at=607,670
-pin timewait  at=304,800
-pin closed2   at=614,800
-route closed -> synsent via=790,38;790,298
-route listen -> closed via=300,105
-route synsent -> closed via=640,120
+layout
+pin closed    at=(394,20)
+pin listen    at=(394,170)
+pin synrcvd   at=(120,290)
+pin synsent   at=(700,290)
+pin estab     at=(376,410)
+pin fw1       at=(159,540)
+pin closewait at=(690,540)
+pin fw2       at=(159,670)
+pin closing   at=(311,670)
+pin lastack   at=(690,670)
+pin timewait  at=(304,800)
+pin closed2   at=(697,800)
 ```
 
-The `pin`/`route` block reproduces the canonical Figure 5 arrangement so a
+The `pin` block reproduces the canonical Figure 5 arrangement so a
 reader who knows the RFC diagram recognises it — but it is **presentation
-only** (`r25-check --strict` passes): strip every line after `render` and all
+only** (`strip-check --strict` passes): strip every line after `layout` and all
 11 states, all 21 transitions and their `event / action` labels survive on the
 `node`/`edge`/`class` lines. All meaning is in the edges; the pins are layout.
 
+Three `path … points=` lines used to sit under those pins, bowing the active  <!-- fence-check: skip -->
+OPEN and the two aborts out to the margins. `EDGE-GEOMETRY-CONSTRUCTS` **withdrew the construct from
+the language**, so those transitions now draw straight — which
+put each of them beside its anti-parallel partner and stacked two pairs of
+labels. The fix was content-zone geometry, not a substitute waypoint: rows 1
+and 2 gained 20 px and 10 px and the right-hand column moved ~90 px out, which
+separates the label midpoints. Worth noting what caught it — the linter scored
+the figure **2 either way** and reported 0 crossings both times; only looking
+at the render did (§7 of [layout.md](layout.md) makes the same
+point). The part of the old arrangement that has no replacement — pulling a
+specific edge into a channel of your choosing — is recorded as core §9
+**`EDGE-IDENTITY-AND-GEOMETRY`**.
+
 **Human sees:** the whole RFC 9293 state diagram — CLOSED at top, the SYN pair
 flanking, ESTABLISHED centred, the active-close column falling left and the
 passive-close column right — four colour-coded transition families (blue setup,
@@ -372,10 +392,11 @@ arrow carrying its `event / action`.
   send?* A: `rcv FIN / snd ACK` — one edge label
   (`edge estab -[rcv FIN / snd ACK]-> closewait`).
 - *Q: From FIN-WAIT-1, how many ways lead to TIME-WAIT and under what
-  conditions?* A: two. Directly, `rcv FIN,ACK / snd ACK` (the RFC Note-2
-  transition, `fw1 -> timewait`); and via FIN-WAIT-2, `rcv ACK of FIN / x` then
-  `rcv FIN / snd ACK` (`fw1 -> fw2 -> timewait`). A third path runs via CLOSING
-  (`rcv FIN / snd ACK` then `rcv ACK of FIN / x`). All read off the edges.
+  conditions?* A: three. (1) Directly: `rcv FIN,ACK / snd ACK` (the RFC Note-2
+  transition, `fw1 -> timewait`). (2) Via FIN-WAIT-2: `rcv ACK of FIN / x` then
+  `rcv FIN / snd ACK` (`fw1 -> fw2 -> timewait`). (3) Via CLOSING:
+  `rcv FIN / snd ACK` then `rcv ACK of FIN / x` (`fw1 -> closing -> timewait`).
+  All read off the edges.
 - *Q: How long does TIME-WAIT last and what happens after?* A: `Timeout=2MSL`,
   then `delete TCB` → CLOSED (`timewait -[Timeout=2MSL / delete TCB]-> closed2`).
 - *Q: Which transitions belong to the typical server (passive-close) path?*
@@ -384,10 +405,10 @@ arrow carrying its `event / action`.
   class, whose label spells the path out.
 
 > **Honest limit (stated in the source):** a node *is* a state is not yet a
-> machine-declarable fact — FigDown has no state genre (the R49 §6 candidate),
+> machine-declarable fact — FigDown has no state genre (the `GENRE-EARNING-THRESHOLD` §6 candidate),
 > so "this node is a protocol state" rides on the `states` class label, interim.
 > And CLOSED is drawn **twice** (top origin, bottom terminus) because FigDown
-> has no node-identity/alias construct (**OQ-S26**): the two `closed`/`closed2`
+> has no node-identity/alias construct (**`IDENTITY-ASSERTION`**): the two `closed`/`closed2`
 > nodes are declared one state only by the shared class label, not machine-
 > readably. Everything else — all 11 states, all 21 labelled transitions
 > including the one the canonical figure omits in its own Note 2 — the edges
@@ -399,23 +420,24 @@ arrow carrying its `event / action`.
 
 Two figures depend on a convention the language does not yet make first-class:
 **message/step ordering** in the handshake and ARP is carried by numbering edge
-labels `1:`/`2:`/`3:`, which R37 treats as naming, not semantics — the v0.2
-sequence genre (OQ-S18) will fix it, and the sources say so. Relatedly, the RFC
+labels `1:`/`2:`/`3:`, which `MEANING-RECOVERY-SOURCE` treats as naming, not semantics — the v0.2
+sequence genre (`FLOWCHART-GENRE-DESIGN`) will fix it, and the sources say so. Relatedly, the RFC
 9293 handshake carries **per-endpoint lifeline state** (LISTEN, SYN-SENT, …)
-that the topology genre has no construct for; the companion state table carries
-it as composition (a ruled interim, again pending the sequence genre, OQ-S18).
-The Ethernet frame uses the **OQ-S24** byte-unit workaround (single-row `table`,
+that the topology genre has no construct for; the companion state table section
+carries it as multi-section composition (`MULTI-FIGURE-DOCUMENTS` main-standard interim, again
+pending the sequence genre, `FLOWCHART-GENRE-DESIGN`).
+The Ethernet frame uses the **`BYTE-UNIT-PACKET-BLOCKS`** byte-unit workaround (single-row `table`,
 not `bitfield`) so byte order rides on cell order, and one of its facts — the
 FCS **coverage span** over a contiguous run of columns (DA through Payload) —
-has no annotation construct yet (**OQ-S16**), so it rides on a source comment
+has no annotation construct yet (**`CONTIGUOUS-RANGE-GROUPING`**), so it rides on a source comment
 and prose. The TCP state machine meets two more: **state-ness is not first-class**
 — a node *is* a state carries as the `states` class label until the state genre
-lands (the R49 §6 candidate) — and CLOSED is drawn **twice** because FigDown has
-no **node-identity/alias** construct (**OQ-S26**) to declare two nodes the same
+lands (the `GENRE-EARNING-THRESHOLD` §6 candidate) — and CLOSED is drawn **twice** because FigDown has
+no **node-identity/alias** construct (**`IDENTITY-ASSERTION`**) to declare two nodes the same
 entity; the shared class label asserts it instead. Every state and every labelled
 transition still rides on an edge, so those two are the *only* facts the figure
 cannot carry that the canonical drawing implies. All are documented in
-[EXPRESSING.md](EXPRESSING.md)'s "Known limits".
+[expressing.md](expressing.md)'s "Known limits".
 That a figure format states its own limits — and that a reading agent recovers
 exactly what the text declares and nothing the geometry merely implies — is the
 claim these figures make.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figdown",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0",
   "description": "Figures as text — one source, two readers: a closed, deterministic figure language for Markdown, readable by AI agents and humans alike",
   "license": "MIT",
   "author": "FigDown <hello@figdown.org>",
@@ -23,6 +23,30 @@
     "deterministic"
   ],
   "type": "commonjs",
+  "scripts": {
+    "gate:conformance": "node conformance/run.js",
+    "gate:conformance-experimental": "node conformance/run.js --experimental",
+    "gate:comment": "node tools/comment-check.js --strict",
+    "gate:editor": "node tools/editor-check.js --strict",
+    "gate:fence": "node tools/fence-check.js --strict",
+    "gate:page": "node tools/page-check.js",
+    "gate:shape": "node tools/shape-check.js --strict",
+    "gate:strip": "node tools/strip-check.js --strict",
+    "gate:layout": "node tools/layout-lint.js",
+    "gate:artifact": "node tools/artifact-check.js --strict",
+    "gate:dist": "node tools/dist-check.js --strict",
+    "gate:isolation": "node tools/isolation-check.js --strict",
+    "gate:boundary": "node tools/boundary-check.js --strict",
+    "gate:stability": "node tools/stability-check.js",
+    "gate:migrate": "node tools/migrate-check.js",
+    "gate:skill-coverage": "node tools/skill-coverage.js --strict",
+    "gate:legend": "node tools/legend-check.js --strict",
+    "gate:registry": "node tools/registry-check.js --strict",
+    "gate:capability": "node tools/capability-coverage.js --strict",
+    "gates:list": "node -e \"const s=require(process.cwd()+'/package.json').scripts||{};const g=Object.keys(s).filter(k=>k.startsWith('gate:'));if(!g.length){console.error('gates:list — no gate:* scripts found');process.exit(2);}if(process.env.GATES_JSON)console.log(JSON.stringify(g));else g.forEach(k=>console.log(k+'  ->  '+s[k]));\"",
+    "test": "node -e \"const s=require(process.cwd()+'/package.json').scripts||{};const sp=require('child_process').spawnSync;const g=Object.keys(s).filter(k=>k.startsWith('gate:'));if(!g.length){console.error('npm test — no gate:* scripts found; refusing to report success');process.exit(2);}const bad=[];g.forEach(k=>{const a=s[k].split(' ');const bin=a[0]==='node'?process.execPath:a[0];console.log('');console.log('=== GATE '+k+'  ['+s[k]+'] ===');const r=sp(bin,a.slice(1),{stdio:'inherit'});if(r.error)console.error('    spawn error: '+r.error.message);const c=(r.status===null||r.status===undefined)?1:r.status;console.log('--- '+k+': '+(c===0?'PASS':'FAIL (exit '+c+')')+' ---');if(c!==0)bad.push(k+'  ['+s[k]+']  exit '+c);});console.log('');console.log('=== GATE SUMMARY: '+(g.length-bad.length)+'/'+g.length+' passed ===');if(bad.length){console.log('FAILED GATES:');bad.forEach(b=>console.log('  '+b));process.exit(1);}console.log('ALL GATES GREEN');\"",
+    "gate:reference": "node tools/reference-gate.js"
+  },
   "main": "dist/figdown.js",
   "module": "dist/figdown.mjs",
   "exports": {
@@ -37,11 +61,13 @@
   "files": [
     "dist/figdown.js",
     "dist/figdown.mjs",
+    "skill/figdown/SKILL.md",
+    "skill/figdown/reference/",
     "skill/figdown/figdown.html",
     "skill/figdown/build-svg.js",
-    "SHOWCASE.md",
-    "EXPRESSING.md",
-    "LAYOUT-GUIDE.md",
+    "guide/showcase.md",
+    "guide/expressing.md",
+    "guide/layout.md",
     "examples/evpn-fabric.svg",
     "examples/showcase/*.svg"
   ],