[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DC6SFCE2V78R54EGHTWP9J":3,"skill-same:01M7DC6SFCE2V78R54EGHTWP9J":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M7DC6SFCE2V78R54EGHTWP9J","d2-diagram",null,"Draw a software architecture, system, data-model or call-flow diagram as D2 text laid out by TALA (D2's whiteboard-style engine, open source since D2 0.9), look at it in the terminal before anyone opens an image, and check that the picture says what it claims — `d2 --layout=tala x.d2 x.txt` renders the layout as Unicode box drawing, `--ascii-mode standard` as plain ASCII for a README, and `assets\u002Fd2-facts.mjs` reads the drawn boxes and arrows back out of the render and holds them to a fact sheet. Loop: write `.d2` → `d2 fmt --check` \u002F `validate` → facts → terminal render → PNG → fix the text. Use when asked for a D2 diagram, an architecture diagram kept as editable text in the repo, a TALA layout, a diagram that shows in a terminal or a code block, or when the repo already has `.d2` files. Not for animations or figures with a moving walk (`explanatory-animation`, `explain-with-anim`).","mizchi\u002Fexplainer","mizchi","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F73962?v=4","01M7CYQ4DMPTZ1DABWCBFNR2Z5","Kotaro Chikuba","01M7DC53GVPR6YPB4K41EXZXQ0",466,"MIT","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: d2-diagram\ndescription: >-\n  Draw a software architecture, system, data-model or call-flow diagram as D2 text laid out by TALA (D2's whiteboard-style engine, open source since D2 0.9), look at it in the terminal before anyone opens an image, and check that the picture says what it claims — `d2 --layout=tala x.d2 x.txt` renders the layout as Unicode box drawing, `--ascii-mode standard` as plain ASCII for a README, and `assets\u002Fd2-facts.mjs` reads the drawn boxes and arrows back out of the render and holds them to a fact sheet. Loop: write `.d2` → `d2 fmt --check` \u002F `validate` → facts → terminal render → PNG → fix the text. Use when asked for a D2 diagram, an architecture diagram kept as editable text in the repo, a TALA layout, a diagram that shows in a terminal or a code block, or when the repo already has `.d2` files. Not for animations or figures with a moving walk (`explanatory-animation`, `explain-with-anim`).\n---\n\n# d2-diagram\n\nPaths below: `\u003Cskill>` is this skill's directory and `\u003Cskills>` the directory the skills are\ninstalled in (`skills\u002F` in mizchi\u002Fexplainer, `.claude\u002Fskills\u002F` in a project that installed them).\n\nA D2 file is the diagram; the picture is a render of it. The writer's job is the\ntext — ids, labels, containers, connections — and TALA's job is where the boxes\ngo and how the lines bend. The terminal render exists so the writer reads the\npicture on every round without leaving the shell, and so the diagram can live in\na README code block, a PR comment, or a `--help` text.\n\n```d2\ndirection: right\nweb: Web frontend\napi: API server\ndb: PostgreSQL {shape: cylinder}\nweb -> api: HTTPS\napi -> db: SQL\n```\n\n```\n                                                          .-‾‾‾‾‾‾-.\n                                                         │╲-______-╱│\n                    HTTPS                        SQL     │          │\n┌─────────────┐──────────────▶┌───────────┐─────────────▶│          │\n│Web frontend │               │API server │              │PostgreSQL│\n│             │               │           │              │          │\n└─────────────┘               └───────────┘               ╲-______-╱\n```\n\n(`d2 --layout=tala x.d2 x.txt`, verbatim, D2 0.8.1-HEAD.)\n\nThis skill is for a diagram whose deliverable is **D2 text**: someone will edit\nit later, TALA lays it out, and it renders wherever D2 does. A step-by-step\nwalk (an algorithm, a request) is not animated: draw the structure once and\nnumber the steps in the prose. To ground the D2 in the code, list the modules\nand dependencies from the code first (imports, `package.json`), write them into\nthe fact sheet, and draw exactly those.\n\n## Invocation\n\n```bash\nd2 layout                                   # must list `tala (bundled)`. That, not the version\n                                            # string, is the gate: v0.8.1-HEAD already bundles it.\n\nd2 --layout=tala arch.d2 arch.txt && cat arch.txt        # the terminal render (Unicode box drawing)\nd2 --layout=tala --ascii-mode standard arch.d2 arch.txt  # plain ASCII (+ - | \u002F \u003C > v) for a README\nd2 --layout=tala arch.d2 --stdout-format ascii -         # to stdout, for a pipe or a PR comment\nd2 --layout=tala arch.d2 arch.svg                        # the figure for docs\nd2 --layout=tala arch.d2 arch.png                        # a raster to LOOK at (see the loop, step 5)\n\nd2 validate arch.d2                         # syntax only; exit 1 with file:line:col\nd2 fmt --check arch.d2                      # formatted? exit 1 and names the file, changes nothing\nd2 fmt arch.d2                              # ...and this rewrites it in place\n\nnode \u003Cskill>\u002Fassets\u002Fd2-facts.mjs arch.d2               # what the picture DRAWS\nnode \u003Cskill>\u002Fassets\u002Fd2-facts.mjs arch.d2 --expect f.json   # ...held to a sheet\nLC_ALL=C.UTF-8 wc -L arch.txt               # the width in columns — the locale matters, see below\n```\n\nInstall when `d2` is missing — never drive the diagram through an online\nplayground:\n\n```bash\ncurl -fsSL https:\u002F\u002Fd2lang.com\u002Finstall.sh | sh -s --      # the installer; it rejects the obsolete --tala flag\nbrew install d2                                          # macOS\ngo install github.com\u002Fd2lang\u002Fd2@latest                   # Go 1.27+; what to do when the install script gets a 403 through a proxy\n```\n\n`D2_LAYOUT=tala` in the environment is the same as the flag. `vars: { d2-config:\n{ layout-engine: tala } }` inside the file is honoured for `.svg` \u002F `.png` **and\nnot for `.txt`** on the build measured (0.8.1-HEAD: the text render fell back to\ndagre and came out 163 columns instead of 120), so pass the flag anyway; keep the\nconfig in the file so the next person's SVG gets the same engine. A\n`sequence_diagram` is the exception that proves the rule — it lays itself out, so\nits text render came out byte-identical with and without the flag.\n\n## Nothing in D2 tells you the picture is wrong\n\n`validate` reads syntax. The renderers draw whatever the file says. There is no\n`--expect`, no layout report, and **no error for a reference to an id that is not\nin scope — it creates a new shape.** So this is a silently wrong diagram:\n\n```d2\nedge:    { cdn; gateway }\ncluster: { orders; inventory }\ngateway -> orders        # ← two NEW empty boxes at the root; the real ones keep no arrow\n```\n\nA writer in this skill's own validation round shipped exactly that: `d2 validate`\n0, `d2 fmt` clean, 94 columns, and its log said \"can trace all connections\". The\nrender had **four duplicated boxes**, two orphans, and the system's entry call\ndrawn as a floating pair outside every region\n([report](https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fvlmkit\u002Fblob\u002Fmain\u002Fdocs\u002Freports\u002F2026-09-14-d2-diagram-v1.md)).\n\n**Write cross-container connections at the root, with full paths.** That is the\none form that always works and the one every writer in the round that got this\nright used:\n\n```d2\nedge.gateway -> cluster.orders          # at the root: full path on both ends\ncluster: {\n  billing -> _.outside.stripe           # from INSIDE: `_` is this container's parent\n}\n```\n\n`_` is **one level and only valid inside a container**. From inside `cluster`,\n`_` is the root, so a shape in a sibling container is `_.outside.stripe` — not\n`_.stripe`, which invents a root-level `stripe` (that was the round's fourth\nphantom). At the root `_` has no parent to mean: `d2` fails the compile with\n`invalid underscore`, which a later writer hit and read as the escape being\nbroken.\n\n`assets\u002Fd2-facts.mjs` is the check D2 does not have. It renders the file and\nreads the picture back out of the SVG — d2 writes every shape's and every\nconnection's fully-qualified id into it — so what it reports is what a reader\nsees, not what the source seems to say. No dependencies; copy it next to your\ndiagrams in another repo.\n\n```bash\nnode assets\u002Fd2-facts.mjs arch.d2               # boxes, containers and their members, labels, edges, columns\nnode assets\u002Fd2-facts.mjs arch.d2 --expect arch.facts.json\nnode assets\u002Fd2-facts.mjs arch.d2 --seeds 4,5,6 # the seed the final render will use, so the width it reports is real\nnode assets\u002Fd2-facts.mjs --from-svg arch.svg --from-txt arch.txt   # read renders that already exist, no d2 run\n```\n\nThe last form is how the checker is itself gated: `tests\u002Fd2\u002Fd2-facts.test.mjs` drives\nit over renders committed under `tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002F` with no `d2` installed,\nso the phantom-box, truncation, reversed-edge and width lines each have a test\nthat fails if they stop firing. It is also the way to check a render somebody\nelse produced, or a `.svg` in a PR you are reviewing.\n\nIt fails on its own, with no sheet, for three defects that are always defects:\n**a name drawn twice** (the scoping trap above), a box that overlaps a sibling or\nescapes its container, and **a truncated terminal render** — a `top` \u002F `left`\npin can push shapes off the ascii canvas, and `d2` exits 0 on a text file\nholding a fragment. One writer's five-table schema passed at \"71 columns\" with\nthree of the five tables missing from the render it had just measured, which is\nwhy the box-by-box comparison exists. It warns about a box nothing connects to.\nWith a sheet it also checks:\n\n```json\n{\n  \"boxes\": [\"gateway\", \"orders\", \"broker\"],\n  \"deps\": [\"gateway->orders\", \"orders->broker\"],\n  \"forbidden\": [\"orders->billing\"],\n  \"containers\": { \"cluster\": [\"orders\", \"inventory\"] },\n  \"order\": [\"browser->gateway\", \"gateway->orders\"],\n  \"exhaustive\": true,\n  \"maxColumns\": 100,\n  \"allowOrphans\": [\"legend\"]\n}\n```\n\n- `deps` are checked **with direction**: a reversed arrow reads `✗ edge\n  reversed: the sheet says broker->billing, the picture draws billing->broker`.\n- `exhaustive` makes an edge the sheet does not list an error, not a warning.\n- `order` reads a sequence diagram's messages back by their y position — the one\n  place D2 makes order visible.\n- Names match an id's last segment **or its label**, so a sheet says `gateway`\n  for a file that wrote `gw: API gateway`.\n- It cannot see inside a `sql_table`: a column-level edge\n  (`orders.customer_id -> customers.id`) is reported as `orders->customers`.\n  Constraint badges are not checked either; count them with\n  `grep -o '>FK\u003C\u002Ftext>' arch.svg | wc -l` (`grep -c` counts *lines*, and an SVG\n  is one line, so it prints 1 however many badges there are) and read the PNG\n  for which row each arrow actually leaves.\n\nWrite the sheet from the brief **before** the diagram, the way a test comes\nfirst. It is the only artifact that survives a TALA reflow.\n\n## How a sheet name finds its shape\n\nA name in a sheet is not matched on the id alone; the search widens until\nexactly one shape matches:\n\n1. the **last segment of an id** — `orders` finds `cluster.orders`\n2. an exact **label** — `gateway` finds `gw: API gateway`\n3. a **substring** of an id, or of a label, when exactly one shape matches\n\nStep 3 is generous on purpose and it will surprise you. A box called `pg`\nlabelled `Postgres orders (authoritative until cutover)` **is** a sheet's\n`orders`, so `forbidden: [\"checkout->orders\"]` fires on an edge into it. That is\nnot a bug in either the sheet or the figure — they disagree about a name — so\nevery line that turns on a loose match now says which match it used:\n\n```\n✗ forbidden edge drawn: checkout->orders (orders matched no id — it is a\n  substring of box pg's label \"Postgres orders (authoritative until cutover)\")\n```\n\nRead that clause before editing anything: with it, the choice is between\nscoping the sheet and fixing the figure. Without it, a writer relabelled a\ncorrect box to satisfy the checker\n(`tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002Fv2\u002Flabel-substring\u002F`).\n\n## Why TALA, and when not\n\nTALA (Terrastruct's AutoLayout Algorithm) is D2's own engine for software\narchitecture diagrams, open-sourced under MPL-2.0 and bundled with D2 (0.9.0 is\nthe release the announcement names; the 0.8.1-HEAD build measured here has it\ntoo — ask `d2 layout`, not the version). Where dagre and ELK lay a directed graph\nout in layers, TALA arranges boxes the way a whiteboard drawing does —\northogonal, symmetric where it can be, clustered by container — and it is the\nonly engine that honours every D2 feature: `direction` per container, `width` \u002F\n`height` on containers, `near: \u003Cother shape>`, and `top` \u002F `left` to pin a shape\nwhile the engine places the rest.\n\n| The diagram is… | Engine |\n|---|---|\n| Boxes in containers with connections in several directions (an architecture, a deployment, a data model) | **tala** |\n| One flow with a clear direction, many hops (a pipeline, a DAG) | tala with `direction: right`; if it still reads badly, `elk` — the announcement is explicit that TALA does less well on flowing graphs |\n| Thirty-plus shapes | Split by container into two files. TALA's runtime is nonlinear in size: 30 nodes took 0.94s here where ELK took 0.05s; layouts that size also read badly whatever the engine |\n\n**Randomness, made reproducible.** TALA tries three seeds (`--tala-seeds`,\ndefault `1,2,3`) and keeps the best complete result, so the same file renders the\nsame picture twice — measured identical. A label change can still cascade into a\ndifferent arrangement, so never describe the geometry in prose (\"the box on the\nleft\"); name ids. Two measured caveats before you reach for seeds:\n\n- **A different seed set often changes nothing.** One writer swept twelve seed\n  sets over a five-table schema and got the identical 109-column layout every\n  time; another moved 113 → 100 columns with `--tala-seeds 4,5,6`. Try it once,\n  keep the number you measured, and do not plan on it.\n- **Seeds cannot live in the file.** `d2 layout tala` says \"Diagram data under\n  tala-seeds takes precedence over the command-line flag\", but\n  `vars.d2-config.tala-seeds` is rejected at compile time. A committed diagram\n  whose layout depends on a seed only renders that way if every render passes the\n  flag — so write the flag into the script or the Makefile target, or do not rely\n  on it.\n\n## Route by task\n\n| Task shape | Write |\n|---|---|\n| \"Draw the architecture \u002F how the services fit\" | Containers per area (`cluster: our cluster { orders; inventory }`), connections between children at the **root** (`edge.gateway -> cluster.orders`) or with `_.` from inside. `direction: right` at the root; per-container `direction` on the fullest container is the width lever, see below |\n| \"Draw the data model \u002F tables\" | `shape: sql_table` with `id: int {constraint: primary_key}` and `customer_id: int {constraint: foreign_key}` rows; connect the columns (`orders.customer_id -> customers.id`) |\n| \"Draw the request \u002F call flow between components\" | `shape: sequence_diagram` at the root; actors in first-use order; one message per line with its label. D2 has no return or async arrow and the terminal render drops every style, so the distinction lives in the label — as a **bare marker of four characters or fewer, no punctuation**, at the start or the end (`ret 201 Created`, `order.placed async`), glossed in the prose above the figure. `reserved (ret)` does not survive: the render overwrites the parentheses with line characters and a label that fills the lane leaves the arrow with **no head at all**. A legend inside the diagram is not an option either — `shape: text` renders as an empty box |\n| \"Draw the classes\" | `shape: class` with `+method(): type` \u002F `-field: type` lines |\n| \"Draw the deployment \u002F network\" | Containers for hosts and zones; `shape: cylinder` for stores, `shape: cloud` for external services, `shape: queue` for brokers |\n| \"We already have a `.d2`\" | Edit it; `d2 fmt --check`; render before and after; do not switch its engine or theme without saying so |\n| \"Put it in the README \u002F a code block \u002F a PR comment\" | The `standard` ASCII render inside a fenced block; measure the width as below; keep the `.d2` next to it |\n| \"It has to be checked against the code\" | List the modules and deps from the code (imports, `package.json`) into the sheet first, draw exactly those, then `d2-facts --expect` |\n\n## The loop\n\n```\n1. write arch.facts.json                             the boxes, edges and width the brief asks for\n2. write arch.d2                                     ids ASCII; the label after the colon is what the reader sees\n3. d2 fmt --check arch.d2 && d2 validate arch.d2     syntax; exit 1 names file:line:col\n4. node assets\u002Fd2-facts.mjs arch.d2 --expect arch.facts.json\n                                                     duplicates, missing \u002F reversed \u002F invented edges,\n                                                     container members, overlaps, order, width\n5. d2 --layout=tala arch.d2 arch.png                 then READ arch.png with your file-reading tool — you can\n                                                     look at an image, and this is the only step that shows\n                                                     labels, shapes, key badges and which row an arrow leaves.\n                                                     Both writers who skipped it reported the same thing:\n                                                     \"a PNG read would have answered this\"\n6. d2 --layout=tala arch.d2 arch.txt && cat arch.txt the deliverable, if it is going in a terminal\n7. fix the text; go to 3\n```\n\nFive rounds at most. Each step answers a different question: 3 is \"does it\ncompile\", 4 is \"does it say what I meant\", 5 is \"does it read\", 6 is \"does it fit\nwhere it is going\". A compile error is one line —\n`arch.d2:2:9: invalid style keyword: \"colour\"`, `2:1: connection missing\ndestination` — fix the line it names.\n\n## Done condition\n\n- `d2 validate` exits 0 and `d2 fmt --check` exits 0.\n- `d2 layout` listed `tala (bundled)` and the render used it.\n- `d2-facts --expect` exits 0: no duplicate name, no truncated render, every\n  listed box and edge drawn with its direction, no forbidden edge, the width\n  inside budget — measured with the same `--seeds` the final render will use.\n- You read the PNG once, and it is one of the deliverables.\n- Every shape and connection in the prose is named by its id, and every id in\n  the prose is in the file.\n- The `.d2` is committed where the SVG is; the SVG is a build output or is\n  committed next to it — never only pasted.\n\n## Width: measure it the way a terminal sees it\n\n```bash\nLC_ALL=C.UTF-8 wc -L arch.txt      # 122 — correct, and CJK-aware\nwc -L arch.txt                     # 120 in the C locale: an undercount, and 87 vs 111 on a Japanese figure\nawk '{if(length($0)>m)m=length($0)}END{print m}' arch.txt   # 338 — BYTES. Never this.\n```\n\n`d2-facts.mjs` prints the same number as `columns`, which is the one to quote.\nTwo writers hit the undercount independently; one spent a round shrinking a\nrender that was already inside budget.\n\n**The levers are not monotone. Measure after every one.** Measured on two\ndifferent diagrams in the same round:\n\n| Lever | Diagram A | Diagram B |\n|---|---|---|\n| root `direction: right` → `down` | 144 → **145** (worse) | 148 → **109** (the win) |\n| shorter labels | 144 → **146** (worse) | 109 → **135** (worse) |\n| per-container `direction` on the fullest container | 146 → **113** (the win) | — |\n| `--tala-seeds 4,5,6` | 113 → **100** | no change across 12 seed sets |\n| `top` \u002F `left` pin on one shape | 113 → **74** | 102 → **75** |\n\nSo: set the root `direction`, then the **own `direction` of the container holding\nthe most boxes** — that is the first thing to try, not the last — and re-measure\nafter each. Shortening labels is as likely to make it wider, because TALA reflows\nthe whole picture. `--scale` does not change the text render at all. None of this\napplies to a `sequence_diagram`, which lays itself out: there the only lever is\nlabel length, and it moves the width by a column or two in either direction.\n\nTwo caveats on the escape hatches:\n\n- **Per-container `direction` is often ignored.** Setting it on two containers\n  produced byte-identical renders; on the fullest one it moved 33 columns. TALA\n  appears to honour it only where the container's internal flow is ambiguous.\n- **`top` \u002F `left` are SVG pixels, not columns**, and both must be set together\n  (TALA only). Roughly 11.5px per terminal column on a 100-column figure, but\n  every writer who used it found its numbers by trying three to five values.\n  Pin the one or two shapes whose place matters, comment why, and expect the pin\n  to need re-tuning after the next label change.\n- **A pin can truncate the terminal render, and that looks like a win.** One\n  writer pinned a table, watched the width fall 113 → 71, and the number was a\n  fragment: the pin had pushed shapes off the ascii canvas and three of five\n  tables were gone from the text while the SVG had grown. `d2` exits 0 on it.\n  `d2-facts` now reports it as an error; if you pin, re-read the render.\n- **The budget may be unreachable without a pin.** On five `sql_table`s no\n  documented lever got under 100 columns: `direction: down` reached 113, shorter\n  labels 127, a wrapping container 121, and only the unsafe pin went lower. When\n  that happens, split the diagram by container into two files, or keep the wider\n  figure and say in the prose that the terminal version is 113 columns — do not\n  buy the number with a pin you have not re-read.\n\n## Reading the terminal render\n\nMeasured on 0.8.1-HEAD. Read **structure** here; read **labels and shapes** on\nthe PNG.\n\n- **Edge labels are written onto the line** and their spaces become line\n  characters (`vlmkit check integrity─page─html`, `201─Created`). Keep\n  terminal-bound edge labels to one or two words.\n- **Every connection style is dropped.** `stroke-dash`, `stroke`, `bold` render\n  as a plain line: a writer diffed its styled render against a style-free copy\n  and they were **identical**. Dashed-means-async does not survive, so carry the\n  distinction in the label.\n- **Arrowheads are unreliable on long labels.** A label long enough to fill the\n  lane can leave the arrow with no head at all, and `\u003C\u003C` in a label is eaten\n  outright. Which character the line eats is not stable either: the same file\n  lost a label's parentheses on one round and its full stop on the next\n  (`order.placed` → `order─placed`). Probe the spelling you land on, and prefer\n  one short word with no punctuation.\n- **`shape: text` and `|md …|` blocks render as empty boxes.** A title, a legend\n  or a paragraph belongs in the prose around the render, or in a variant of the\n  file rendered only to SVG.\n- **`sql_table` rows render, their constraint badges do not.** PK \u002F FK markers\n  are visible only in the SVG \u002F PNG, and a column-level edge attaches to the\n  wrong row in the text view often enough that you cannot read it there.\n- **An edge label can land on a box or container border** (`┌────sync call────┐│`),\n  which reads as two boxes merged. Where it lands is **positional, not\n  length-driven**: a writer whose connection was already at the root both\n  shortened and lengthened the label and it stayed on the same border row at the\n  same width. The levers that do move it are the ones that reflow the picture —\n  the container's `direction`, a different seed — so treat it as a layout outcome\n  to check on the PNG, not a label to trim.\n- **CJK labels pad every glyph** (`ウ  ェ  ブ`) and misalign the box that holds\n  them. Ids stay ASCII always; for a figure that will be read in a terminal keep\n  the labels ASCII too and put the Japanese in the surrounding text. The SVG and\n  PNG render Japanese correctly.\n- **`standard` mode** keeps the same layout with `+ - | \u002F \u003C > v` only — the\n  version for a README read on GitHub, where box-drawing glyphs in a code block\n  depend on the viewer's font.\n- **Icons and images are dropped**; sequence diagrams, `sql_table` and `class`\n  shapes render, with their rows.\n\n## Rules the writer keeps\n\n- Ids are ASCII and stable (`api`, not `API server`); the label goes after the\n  colon. Abbreviating an id is fine — `d2-facts` matches on the label too — but\n  the next editor reads the id first.\n- **A cross-container connection is written at the root or with `_.`**, and `_`\n  is one level: from inside `cluster`, the root is `_`, so a shape in a sibling\n  container is `_.outside.stripe`. Never let an out-of-scope name stand: it\n  becomes a new box (see above).\n- One root `direction`; a container that must flow the other way sets its own\n  (TALA only, and only sometimes honoured).\n- Connections read as sentences: `a -> b: verb`. `--` is undirected, `\u003C->` both\n  ways. A style on a connection (`{style.stroke-dash: 3}`) is invisible in the\n  terminal — if the distinction matters there, put it in the label.\n- `vars: { d2-config: { layout-engine: tala } }` at the top of every file, so a\n  render without the flag still gets TALA for the SVG.\n- No coordinates unless a shape must be pinned; then `top` and `left` together,\n  on that shape only, and a comment saying why.\n\n## Deliver\n\n- In a chat: the terminal render in a fenced block (it *is* the picture in a\n  terminal), the ids named in the prose, the `.d2` and the PNG \u002F SVG as files\n  (`SendUserFile` when available).\n- In a PR or issue: the `standard` render in a fenced block, or the SVG committed\n  and linked. The `.d2` in the diff is the review target.\n- In docs: the `.d2` committed next to the page and the SVG generated by the\n  build (`d2 --layout=tala docs\u002Farch.d2 docs\u002Farch.svg` in a script), or the SVG\n  committed when the site has no build step.\n\n## Failure modes\n\n- `d2: command not found` → install (above); do not draw it in another tool.\n- `d2 layout` does not list `tala` → an old release; upgrade. The installer's\n  `--tala` flag no longer exists and is rejected.\n- **A box appears twice, or an arrow you wrote is nowhere** → an out-of-scope\n  reference created a phantom. `d2-facts` names it; the fix is a full path or\n  `_.`, not another arrow.\n- The text render came out dagre-shaped and wide though the file says\n  `layout-engine: tala` → the `.txt` path ignores the in-file config on some\n  builds; pass `--layout=tala`.\n- `\"tala-seeds\" needs a value` \u002F `is not a valid config` → seeds are a flag only.\n- `connection missing destination`, `maps must be terminated with }` → the line\n  and column are named; usually a trailing `->` or an unclosed brace.\n- `invalid style keyword` → D2 spells `color`, `stroke`, `stroke-dash`, `fill`,\n  `font-size`, `bold`, `opacity`, `shadow`, `3d`, `multiple`.\n- Every round moves the boxes though you changed one label → TALA reflowed. Pin\n  the few shapes whose place matters, or accept it and stop describing positions.\n- Two boxes look like they touch and you cannot tell → `d2-facts` reports\n  sibling overlaps in px²; D2 itself has no collision report.\n\n`assets\u002Fvlmkit-workspace.d2` is vlmkit's workspace (mizchi\u002Fvlmkit) as a D2 file, and\n`assets\u002Fvlmkit-workspace.txt` is its TALA terminal render — what a clean round\nlooks like. The validation round that produced the numbers above is\n`tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002F` and\n[`docs\u002Freports\u002F2026-09-14-d2-diagram-v1.md`](https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fvlmkit\u002Fblob\u002Fmain\u002Fdocs\u002Freports\u002F2026-09-14-d2-diagram-v1.md).\n","# d2-diagram\n\nPaths below: `\u003Cskill>` is this skill's directory and `\u003Cskills>` the directory the skills are\ninstalled in (`skills\u002F` in mizchi\u002Fexplainer, `.claude\u002Fskills\u002F` in a project that installed them).\n\nA D2 file is the diagram; the picture is a render of it. The writer's job is the\ntext — ids, labels, containers, connections — and TALA's job is where the boxes\ngo and how the lines bend. The terminal render exists so the writer reads the\npicture on every round without leaving the shell, and so the diagram can live in\na README code block, a PR comment, or a `--help` text.\n\n```d2\ndirection: right\nweb: Web frontend\napi: API server\ndb: PostgreSQL {shape: cylinder}\nweb -> api: HTTPS\napi -> db: SQL\n```\n\n```\n                                                          .-‾‾‾‾‾‾-.\n                                                         │╲-______-╱│\n                    HTTPS                        SQL     │          │\n┌─────────────┐──────────────▶┌───────────┐─────────────▶│          │\n│Web frontend │               │API server │              │PostgreSQL│\n│             │               │           │              │          │\n└─────────────┘               └───────────┘               ╲-______-╱\n```\n\n(`d2 --layout=tala x.d2 x.txt`, verbatim, D2 0.8.1-HEAD.)\n\nThis skill is for a diagram whose deliverable is **D2 text**: someone will edit\nit later, TALA lays it out, and it renders wherever D2 does. A step-by-step\nwalk (an algorithm, a request) is not animated: draw the structure once and\nnumber the steps in the prose. To ground the D2 in the code, list the modules\nand dependencies from the code first (imports, `package.json`), write them into\nthe fact sheet, and draw exactly those.\n\n## Invocation\n\n```bash\nd2 layout                                   # must list `tala (bundled)`. That, not the version\n                                            # string, is the gate: v0.8.1-HEAD already bundles it.\n\nd2 --layout=tala arch.d2 arch.txt && cat arch.txt        # the terminal render (Unicode box drawing)\nd2 --layout=tala --ascii-mode standard arch.d2 arch.txt  # plain ASCII (+ - | \u002F \u003C > v) for a README\nd2 --layout=tala arch.d2 --stdout-format ascii -         # to stdout, for a pipe or a PR comment\nd2 --layout=tala arch.d2 arch.svg                        # the figure for docs\nd2 --layout=tala arch.d2 arch.png                        # a raster to LOOK at (see the loop, step 5)\n\nd2 validate arch.d2                         # syntax only; exit 1 with file:line:col\nd2 fmt --check arch.d2                      # formatted? exit 1 and names the file, changes nothing\nd2 fmt arch.d2                              # ...and this rewrites it in place\n\nnode \u003Cskill>\u002Fassets\u002Fd2-facts.mjs arch.d2               # what the picture DRAWS\nnode \u003Cskill>\u002Fassets\u002Fd2-facts.mjs arch.d2 --expect f.json   # ...held to a sheet\nLC_ALL=C.UTF-8 wc -L arch.txt               # the width in columns — the locale matters, see below\n```\n\nInstall when `d2` is missing — never drive the diagram through an online\nplayground:\n\n```bash\ncurl -fsSL https:\u002F\u002Fd2lang.com\u002Finstall.sh | sh -s --      # the installer; it rejects the obsolete --tala flag\nbrew install d2                                          # macOS\ngo install github.com\u002Fd2lang\u002Fd2@latest                   # Go 1.27+; what to do when the install script gets a 403 through a proxy\n```\n\n`D2_LAYOUT=tala` in the environment is the same as the flag. `vars: { d2-config:\n{ layout-engine: tala } }` inside the file is honoured for `.svg` \u002F `.png` **and\nnot for `.txt`** on the build measured (0.8.1-HEAD: the text render fell back to\ndagre and came out 163 columns instead of 120), so pass the flag anyway; keep the\nconfig in the file so the next person's SVG gets the same engine. A\n`sequence_diagram` is the exception that proves the rule — it lays itself out, so\nits text render came out byte-identical with and without the flag.\n\n## Nothing in D2 tells you the picture is wrong\n\n`validate` reads syntax. The renderers draw whatever the file says. There is no\n`--expect`, no layout report, and **no error for a reference to an id that is not\nin scope — it creates a new shape.** So this is a silently wrong diagram:\n\n```d2\nedge:    { cdn; gateway }\ncluster: { orders; inventory }\ngateway -> orders        # ← two NEW empty boxes at the root; the real ones keep no arrow\n```\n\nA writer in this skill's own validation round shipped exactly that: `d2 validate`\n0, `d2 fmt` clean, 94 columns, and its log said \"can trace all connections\". The\nrender had **four duplicated boxes**, two orphans, and the system's entry call\ndrawn as a floating pair outside every region\n([report](https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fvlmkit\u002Fblob\u002Fmain\u002Fdocs\u002Freports\u002F2026-09-14-d2-diagram-v1.md)).\n\n**Write cross-container connections at the root, with full paths.** That is the\none form that always works and the one every writer in the round that got this\nright used:\n\n```d2\nedge.gateway -> cluster.orders          # at the root: full path on both ends\ncluster: {\n  billing -> _.outside.stripe           # from INSIDE: `_` is this container's parent\n}\n```\n\n`_` is **one level and only valid inside a container**. From inside `cluster`,\n`_` is the root, so a shape in a sibling container is `_.outside.stripe` — not\n`_.stripe`, which invents a root-level `stripe` (that was the round's fourth\nphantom). At the root `_` has no parent to mean: `d2` fails the compile with\n`invalid underscore`, which a later writer hit and read as the escape being\nbroken.\n\n`assets\u002Fd2-facts.mjs` is the check D2 does not have. It renders the file and\nreads the picture back out of the SVG — d2 writes every shape's and every\nconnection's fully-qualified id into it — so what it reports is what a reader\nsees, not what the source seems to say. No dependencies; copy it next to your\ndiagrams in another repo.\n\n```bash\nnode assets\u002Fd2-facts.mjs arch.d2               # boxes, containers and their members, labels, edges, columns\nnode assets\u002Fd2-facts.mjs arch.d2 --expect arch.facts.json\nnode assets\u002Fd2-facts.mjs arch.d2 --seeds 4,5,6 # the seed the final render will use, so the width it reports is real\nnode assets\u002Fd2-facts.mjs --from-svg arch.svg --from-txt arch.txt   # read renders that already exist, no d2 run\n```\n\nThe last form is how the checker is itself gated: `tests\u002Fd2\u002Fd2-facts.test.mjs` drives\nit over renders committed under `tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002F` with no `d2` installed,\nso the phantom-box, truncation, reversed-edge and width lines each have a test\nthat fails if they stop firing. It is also the way to check a render somebody\nelse produced, or a `.svg` in a PR you are reviewing.\n\nIt fails on its own, with no sheet, for three defects that are always defects:\n**a name drawn twice** (the scoping trap above), a box that overlaps a sibling or\nescapes its container, and **a truncated terminal render** — a `top` \u002F `left`\npin can push shapes off the ascii canvas, and `d2` exits 0 on a text file\nholding a fragment. One writer's five-table schema passed at \"71 columns\" with\nthree of the five tables missing from the render it had just measured, which is\nwhy the box-by-box comparison exists. It warns about a box nothing connects to.\nWith a sheet it also checks:\n\n```json\n{\n  \"boxes\": [\"gateway\", \"orders\", \"broker\"],\n  \"deps\": [\"gateway->orders\", \"orders->broker\"],\n  \"forbidden\": [\"orders->billing\"],\n  \"containers\": { \"cluster\": [\"orders\", \"inventory\"] },\n  \"order\": [\"browser->gateway\", \"gateway->orders\"],\n  \"exhaustive\": true,\n  \"maxColumns\": 100,\n  \"allowOrphans\": [\"legend\"]\n}\n```\n\n- `deps` are checked **with direction**: a reversed arrow reads `✗ edge\n  reversed: the sheet says broker->billing, the picture draws billing->broker`.\n- `exhaustive` makes an edge the sheet does not list an error, not a warning.\n- `order` reads a sequence diagram's messages back by their y position — the one\n  place D2 makes order visible.\n- Names match an id's last segment **or its label**, so a sheet says `gateway`\n  for a file that wrote `gw: API gateway`.\n- It cannot see inside a `sql_table`: a column-level edge\n  (`orders.customer_id -> customers.id`) is reported as `orders->customers`.\n  Constraint badges are not checked either; count them with\n  `grep -o '>FK\u003C\u002Ftext>' arch.svg | wc -l` (`grep -c` counts *lines*, and an SVG\n  is one line, so it prints 1 however many badges there are) and read the PNG\n  for which row each arrow actually leaves.\n\nWrite the sheet from the brief **before** the diagram, the way a test comes\nfirst. It is the only artifact that survives a TALA reflow.\n\n## How a sheet name finds its shape\n\nA name in a sheet is not matched on the id alone; the search widens until\nexactly one shape matches:\n\n1. the **last segment of an id** — `orders` finds `cluster.orders`\n2. an exact **label** — `gateway` finds `gw: API gateway`\n3. a **substring** of an id, or of a label, when exactly one shape matches\n\nStep 3 is generous on purpose and it will surprise you. A box called `pg`\nlabelled `Postgres orders (authoritative until cutover)` **is** a sheet's\n`orders`, so `forbidden: [\"checkout->orders\"]` fires on an edge into it. That is\nnot a bug in either the sheet or the figure — they disagree about a name — so\nevery line that turns on a loose match now says which match it used:\n\n```\n✗ forbidden edge drawn: checkout->orders (orders matched no id — it is a\n  substring of box pg's label \"Postgres orders (authoritative until cutover)\")\n```\n\nRead that clause before editing anything: with it, the choice is between\nscoping the sheet and fixing the figure. Without it, a writer relabelled a\ncorrect box to satisfy the checker\n(`tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002Fv2\u002Flabel-substring\u002F`).\n\n## Why TALA, and when not\n\nTALA (Terrastruct's AutoLayout Algorithm) is D2's own engine for software\narchitecture diagrams, open-sourced under MPL-2.0 and bundled with D2 (0.9.0 is\nthe release the announcement names; the 0.8.1-HEAD build measured here has it\ntoo — ask `d2 layout`, not the version). Where dagre and ELK lay a directed graph\nout in layers, TALA arranges boxes the way a whiteboard drawing does —\northogonal, symmetric where it can be, clustered by container — and it is the\nonly engine that honours every D2 feature: `direction` per container, `width` \u002F\n`height` on containers, `near: \u003Cother shape>`, and `top` \u002F `left` to pin a shape\nwhile the engine places the rest.\n\n| The diagram is… | Engine |\n|---|---|\n| Boxes in containers with connections in several directions (an architecture, a deployment, a data model) | **tala** |\n| One flow with a clear direction, many hops (a pipeline, a DAG) | tala with `direction: right`; if it still reads badly, `elk` — the announcement is explicit that TALA does less well on flowing graphs |\n| Thirty-plus shapes | Split by container into two files. TALA's runtime is nonlinear in size: 30 nodes took 0.94s here where ELK took 0.05s; layouts that size also read badly whatever the engine |\n\n**Randomness, made reproducible.** TALA tries three seeds (`--tala-seeds`,\ndefault `1,2,3`) and keeps the best complete result, so the same file renders the\nsame picture twice — measured identical. A label change can still cascade into a\ndifferent arrangement, so never describe the geometry in prose (\"the box on the\nleft\"); name ids. Two measured caveats before you reach for seeds:\n\n- **A different seed set often changes nothing.** One writer swept twelve seed\n  sets over a five-table schema and got the identical 109-column layout every\n  time; another moved 113 → 100 columns with `--tala-seeds 4,5,6`. Try it once,\n  keep the number you measured, and do not plan on it.\n- **Seeds cannot live in the file.** `d2 layout tala` says \"Diagram data under\n  tala-seeds takes precedence over the command-line flag\", but\n  `vars.d2-config.tala-seeds` is rejected at compile time. A committed diagram\n  whose layout depends on a seed only renders that way if every render passes the\n  flag — so write the flag into the script or the Makefile target, or do not rely\n  on it.\n\n## Route by task\n\n| Task shape | Write |\n|---|---|\n| \"Draw the architecture \u002F how the services fit\" | Containers per area (`cluster: our cluster { orders; inventory }`), connections between children at the **root** (`edge.gateway -> cluster.orders`) or with `_.` from inside. `direction: right` at the root; per-container `direction` on the fullest container is the width lever, see below |\n| \"Draw the data model \u002F tables\" | `shape: sql_table` with `id: int {constraint: primary_key}` and `customer_id: int {constraint: foreign_key}` rows; connect the columns (`orders.customer_id -> customers.id`) |\n| \"Draw the request \u002F call flow between components\" | `shape: sequence_diagram` at the root; actors in first-use order; one message per line with its label. D2 has no return or async arrow and the terminal render drops every style, so the distinction lives in the label — as a **bare marker of four characters or fewer, no punctuation**, at the start or the end (`ret 201 Created`, `order.placed async`), glossed in the prose above the figure. `reserved (ret)` does not survive: the render overwrites the parentheses with line characters and a label that fills the lane leaves the arrow with **no head at all**. A legend inside the diagram is not an option either — `shape: text` renders as an empty box |\n| \"Draw the classes\" | `shape: class` with `+method(): type` \u002F `-field: type` lines |\n| \"Draw the deployment \u002F network\" | Containers for hosts and zones; `shape: cylinder` for stores, `shape: cloud` for external services, `shape: queue` for brokers |\n| \"We already have a `.d2`\" | Edit it; `d2 fmt --check`; render before and after; do not switch its engine or theme without saying so |\n| \"Put it in the README \u002F a code block \u002F a PR comment\" | The `standard` ASCII render inside a fenced block; measure the width as below; keep the `.d2` next to it |\n| \"It has to be checked against the code\" | List the modules and deps from the code (imports, `package.json`) into the sheet first, draw exactly those, then `d2-facts --expect` |\n\n## The loop\n\n```\n1. write arch.facts.json                             the boxes, edges and width the brief asks for\n2. write arch.d2                                     ids ASCII; the label after the colon is what the reader sees\n3. d2 fmt --check arch.d2 && d2 validate arch.d2     syntax; exit 1 names file:line:col\n4. node assets\u002Fd2-facts.mjs arch.d2 --expect arch.facts.json\n                                                     duplicates, missing \u002F reversed \u002F invented edges,\n                                                     container members, overlaps, order, width\n5. d2 --layout=tala arch.d2 arch.png                 then READ arch.png with your file-reading tool — you can\n                                                     look at an image, and this is the only step that shows\n                                                     labels, shapes, key badges and which row an arrow leaves.\n                                                     Both writers who skipped it reported the same thing:\n                                                     \"a PNG read would have answered this\"\n6. d2 --layout=tala arch.d2 arch.txt && cat arch.txt the deliverable, if it is going in a terminal\n7. fix the text; go to 3\n```\n\nFive rounds at most. Each step answers a different question: 3 is \"does it\ncompile\", 4 is \"does it say what I meant\", 5 is \"does it read\", 6 is \"does it fit\nwhere it is going\". A compile error is one line —\n`arch.d2:2:9: invalid style keyword: \"colour\"`, `2:1: connection missing\ndestination` — fix the line it names.\n\n## Done condition\n\n- `d2 validate` exits 0 and `d2 fmt --check` exits 0.\n- `d2 layout` listed `tala (bundled)` and the render used it.\n- `d2-facts --expect` exits 0: no duplicate name, no truncated render, every\n  listed box and edge drawn with its direction, no forbidden edge, the width\n  inside budget — measured with the same `--seeds` the final render will use.\n- You read the PNG once, and it is one of the deliverables.\n- Every shape and connection in the prose is named by its id, and every id in\n  the prose is in the file.\n- The `.d2` is committed where the SVG is; the SVG is a build output or is\n  committed next to it — never only pasted.\n\n## Width: measure it the way a terminal sees it\n\n```bash\nLC_ALL=C.UTF-8 wc -L arch.txt      # 122 — correct, and CJK-aware\nwc -L arch.txt                     # 120 in the C locale: an undercount, and 87 vs 111 on a Japanese figure\nawk '{if(length($0)>m)m=length($0)}END{print m}' arch.txt   # 338 — BYTES. Never this.\n```\n\n`d2-facts.mjs` prints the same number as `columns`, which is the one to quote.\nTwo writers hit the undercount independently; one spent a round shrinking a\nrender that was already inside budget.\n\n**The levers are not monotone. Measure after every one.** Measured on two\ndifferent diagrams in the same round:\n\n| Lever | Diagram A | Diagram B |\n|---|---|---|\n| root `direction: right` → `down` | 144 → **145** (worse) | 148 → **109** (the win) |\n| shorter labels | 144 → **146** (worse) | 109 → **135** (worse) |\n| per-container `direction` on the fullest container | 146 → **113** (the win) | — |\n| `--tala-seeds 4,5,6` | 113 → **100** | no change across 12 seed sets |\n| `top` \u002F `left` pin on one shape | 113 → **74** | 102 → **75** |\n\nSo: set the root `direction`, then the **own `direction` of the container holding\nthe most boxes** — that is the first thing to try, not the last — and re-measure\nafter each. Shortening labels is as likely to make it wider, because TALA reflows\nthe whole picture. `--scale` does not change the text render at all. None of this\napplies to a `sequence_diagram`, which lays itself out: there the only lever is\nlabel length, and it moves the width by a column or two in either direction.\n\nTwo caveats on the escape hatches:\n\n- **Per-container `direction` is often ignored.** Setting it on two containers\n  produced byte-identical renders; on the fullest one it moved 33 columns. TALA\n  appears to honour it only where the container's internal flow is ambiguous.\n- **`top` \u002F `left` are SVG pixels, not columns**, and both must be set together\n  (TALA only). Roughly 11.5px per terminal column on a 100-column figure, but\n  every writer who used it found its numbers by trying three to five values.\n  Pin the one or two shapes whose place matters, comment why, and expect the pin\n  to need re-tuning after the next label change.\n- **A pin can truncate the terminal render, and that looks like a win.** One\n  writer pinned a table, watched the width fall 113 → 71, and the number was a\n  fragment: the pin had pushed shapes off the ascii canvas and three of five\n  tables were gone from the text while the SVG had grown. `d2` exits 0 on it.\n  `d2-facts` now reports it as an error; if you pin, re-read the render.\n- **The budget may be unreachable without a pin.** On five `sql_table`s no\n  documented lever got under 100 columns: `direction: down` reached 113, shorter\n  labels 127, a wrapping container 121, and only the unsafe pin went lower. When\n  that happens, split the diagram by container into two files, or keep the wider\n  figure and say in the prose that the terminal version is 113 columns — do not\n  buy the number with a pin you have not re-read.\n\n## Reading the terminal render\n\nMeasured on 0.8.1-HEAD. Read **structure** here; read **labels and shapes** on\nthe PNG.\n\n- **Edge labels are written onto the line** and their spaces become line\n  characters (`vlmkit check integrity─page─html`, `201─Created`). Keep\n  terminal-bound edge labels to one or two words.\n- **Every connection style is dropped.** `stroke-dash`, `stroke`, `bold` render\n  as a plain line: a writer diffed its styled render against a style-free copy\n  and they were **identical**. Dashed-means-async does not survive, so carry the\n  distinction in the label.\n- **Arrowheads are unreliable on long labels.** A label long enough to fill the\n  lane can leave the arrow with no head at all, and `\u003C\u003C` in a label is eaten\n  outright. Which character the line eats is not stable either: the same file\n  lost a label's parentheses on one round and its full stop on the next\n  (`order.placed` → `order─placed`). Probe the spelling you land on, and prefer\n  one short word with no punctuation.\n- **`shape: text` and `|md …|` blocks render as empty boxes.** A title, a legend\n  or a paragraph belongs in the prose around the render, or in a variant of the\n  file rendered only to SVG.\n- **`sql_table` rows render, their constraint badges do not.** PK \u002F FK markers\n  are visible only in the SVG \u002F PNG, and a column-level edge attaches to the\n  wrong row in the text view often enough that you cannot read it there.\n- **An edge label can land on a box or container border** (`┌────sync call────┐│`),\n  which reads as two boxes merged. Where it lands is **positional, not\n  length-driven**: a writer whose connection was already at the root both\n  shortened and lengthened the label and it stayed on the same border row at the\n  same width. The levers that do move it are the ones that reflow the picture —\n  the container's `direction`, a different seed — so treat it as a layout outcome\n  to check on the PNG, not a label to trim.\n- **CJK labels pad every glyph** (`ウ  ェ  ブ`) and misalign the box that holds\n  them. Ids stay ASCII always; for a figure that will be read in a terminal keep\n  the labels ASCII too and put the Japanese in the surrounding text. The SVG and\n  PNG render Japanese correctly.\n- **`standard` mode** keeps the same layout with `+ - | \u002F \u003C > v` only — the\n  version for a README read on GitHub, where box-drawing glyphs in a code block\n  depend on the viewer's font.\n- **Icons and images are dropped**; sequence diagrams, `sql_table` and `class`\n  shapes render, with their rows.\n\n## Rules the writer keeps\n\n- Ids are ASCII and stable (`api`, not `API server`); the label goes after the\n  colon. Abbreviating an id is fine — `d2-facts` matches on the label too — but\n  the next editor reads the id first.\n- **A cross-container connection is written at the root or with `_.`**, and `_`\n  is one level: from inside `cluster`, the root is `_`, so a shape in a sibling\n  container is `_.outside.stripe`. Never let an out-of-scope name stand: it\n  becomes a new box (see above).\n- One root `direction`; a container that must flow the other way sets its own\n  (TALA only, and only sometimes honoured).\n- Connections read as sentences: `a -> b: verb`. `--` is undirected, `\u003C->` both\n  ways. A style on a connection (`{style.stroke-dash: 3}`) is invisible in the\n  terminal — if the distinction matters there, put it in the label.\n- `vars: { d2-config: { layout-engine: tala } }` at the top of every file, so a\n  render without the flag still gets TALA for the SVG.\n- No coordinates unless a shape must be pinned; then `top` and `left` together,\n  on that shape only, and a comment saying why.\n\n## Deliver\n\n- In a chat: the terminal render in a fenced block (it *is* the picture in a\n  terminal), the ids named in the prose, the `.d2` and the PNG \u002F SVG as files\n  (`SendUserFile` when available).\n- In a PR or issue: the `standard` render in a fenced block, or the SVG committed\n  and linked. The `.d2` in the diff is the review target.\n- In docs: the `.d2` committed next to the page and the SVG generated by the\n  build (`d2 --layout=tala docs\u002Farch.d2 docs\u002Farch.svg` in a script), or the SVG\n  committed when the site has no build step.\n\n## Failure modes\n\n- `d2: command not found` → install (above); do not draw it in another tool.\n- `d2 layout` does not list `tala` → an old release; upgrade. The installer's\n  `--tala` flag no longer exists and is rejected.\n- **A box appears twice, or an arrow you wrote is nowhere** → an out-of-scope\n  reference created a phantom. `d2-facts` names it; the fix is a full path or\n  `_.`, not another arrow.\n- The text render came out dagre-shaped and wide though the file says\n  `layout-engine: tala` → the `.txt` path ignores the in-file config on some\n  builds; pass `--layout=tala`.\n- `\"tala-seeds\" needs a value` \u002F `is not a valid config` → seeds are a flag only.\n- `connection missing destination`, `maps must be terminated with }` → the line\n  and column are named; usually a trailing `->` or an unclosed brace.\n- `invalid style keyword` → D2 spells `color`, `stroke`, `stroke-dash`, `fill`,\n  `font-size`, `bold`, `opacity`, `shadow`, `3d`, `multiple`.\n- Every round moves the boxes though you changed one label → TALA reflowed. Pin\n  the few shapes whose place matters, or accept it and stop describing positions.\n- Two boxes look like they touch and you cannot tell → `d2-facts` reports\n  sibling overlaps in px²; D2 itself has no collision report.\n\n`assets\u002Fvlmkit-workspace.d2` is vlmkit's workspace (mizchi\u002Fvlmkit) as a D2 file, and\n`assets\u002Fvlmkit-workspace.txt` is its TALA terminal render — what a clean round\nlooks like. The validation round that produced the numbers above is\n`tests\u002Fd2\u002Ffixtures\u002Fd2-scenario\u002F` and\n[`docs\u002Freports\u002F2026-09-14-d2-diagram-v1.md`](https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fvlmkit\u002Fblob\u002Fmain\u002Fdocs\u002Freports\u002F2026-09-14-d2-diagram-v1.md).\n",{"name":5,"description":7},"main","ccdd7bacfb47451e38506d837af8a629504960b2","skills\u002Fd2-diagram",9,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer","https:\u002F\u002Fgithub.com\u002Fmizchi","https:\u002F\u002Fmizchi.dev","2026-10-11 00:43:28",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add mizchi\u002Fexplainer --skill d2-diagram",{"tool":38,"command":39},"bunx","bunx skills add mizchi\u002Fexplainer --skill d2-diagram",{"tool":41,"command":42},"pnpm","pnpm dlx skills add mizchi\u002Fexplainer --skill d2-diagram","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002FSKILL.md",true,[46,52,58,62,66],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"assets\u002Fd2-facts.mjs","SCRIPT","脚本",21052,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002Fassets\u002Fd2-facts.mjs",{"path":53,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":56,"sourceHtmlUrl":57},"assets\u002Fvlmkit-workspace.d2","ASSET","资产文件",953,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002Fassets\u002Fvlmkit-workspace.d2",{"path":59,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":60,"sourceHtmlUrl":61},"assets\u002Fvlmkit-workspace.facts.json",916,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002Fassets\u002Fvlmkit-workspace.facts.json",{"path":63,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":64,"sourceHtmlUrl":65},"assets\u002Fvlmkit-workspace.svg",19987,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002Fassets\u002Fvlmkit-workspace.svg",{"path":67,"resourceType":54,"resourceTypeDesc":55,"sizeBytes":68,"sourceHtmlUrl":69},"assets\u002Fvlmkit-workspace.txt",5352,"https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-diagram\u002Fassets\u002Fvlmkit-workspace.txt",[71,80,87,94],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":76,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7DCAA7PVXV0AJ67NCG49NC9","first-reader","Beta readers for any draft, run by simulating how a real reader experiences it, moment by moment. A skim gate, a no-lookahead timed read producing an attention transcript with quit points, a recall test of what a reader remembers the next day, and a trust ledger of the implied author. Use when the user asks for a beta read, beta readers, test readers, human review, reader review, to read something like a human, to be a first reader, whether a piece holds attention or will actually get read, for a quick read of whether a busy skimmer would even open a post, what readers will remember or take away tomorrow, where readers stop reading or bounce, or why a draft still feels off or hollow after anti-slop or humanizer edits. Final gate before publishing; reports where the reading broke; never rewrites.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Ffirst-reader\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Ffirst-reader\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7DC91J7122HP0984WZWM9TT","explainer","特定の読み手に向けて、概念・PR・設計を「冗長にならない水準」の速習資料として説明し、図と主張を道具で検証する。読み手のペルソナ（既に知っていること・知らないこと・読み方）を質問と公開情報から作り、その差分だけを書く。図は Mermaid \u002F D2 で描いて事実シートに照らし、本文に引用するコード・出力は再実行して照合し、HTML は vlmkit のゲートに通す。Use when the user says \"explain this to me \u002F to \u003Cperson>\", \"速習資料\", \"解説ドキュメント\", \"この PR を理解したい\", \"わかるように説明して\", \"I can't keep up with what the agent wrote\", \"この PR を \u003C人> が理解できるように説明して\", or when a reviewer asks what a change does. Use it even for a small diff or a chat-only answer whenever a named reader (a reviewer, an on-call engineer, a teammate, a PM) is given. Also when model or analysis results (diagnostics, metrics, charts) must be explained to someone who decides on them, e.g. \"このモデルを本番に出してよいか \u003C人> が判断できるように\". Also when the user wrote an explanation themselves and lost confidence in it.","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fexplainer\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M7DC88110G46GEJNJRHQ7Q9M","explainer-book","1 本の速習資料では収まらない、章立ての学習資料（\u003Ctopic>-book\u002F01-quickstart.md, 02-….md …）を、読み手のペルソナに合わせて設計・執筆・検証する。章ごとの学習目標と理解度チェックの対応、概念を導入より前に使わない順序、章の読了時間の予算、「未完成なら落ち、答えなら通る」演習、book.json から生成する章の依存図を、verify-book.mjs で検査し、各章の出力・図・HTML は explainer の verify-doc.mjs で検査する。Use when the user asks for a book, a tutorial series, a course, \"学習資料\", \"チュートリアル\", \"ハンズオン\", \"本にまとめて\", \"章立てで\", \"01-quickstart から\", or when an explainer crash course would exceed ~20 minutes or needs exercises.","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fexplainer-book\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M7DC7K3NAQ81ADAJZ0E6M3PR","d2-slides","Build a slide deck whose source is text and whose figures are laid out by TALA — one Markdown file with a ```d2 fence per figure, compiled to a self-contained HTML deck (keyboard nav, overview grid, print-to-PDF), each figure as its own SVG, and a copy manifest. The deck is a page, so vlmkit's own gates read it: `check integrity` for a slide that breaks or clips, `check copy --manifest` for text the frame cut off, `check a11y contrast` for a projector. Loop: write `deck.md` → build → gates → fix. Use when asked for slides, a deck, a talk, a presentation, a review walkthrough, or a figure-heavy explainer that has to be presented rather than read. Not for one diagram (`d2-diagram`) or a moving figure (`explanatory-animation`).","https:\u002F\u002Fgithub.com\u002Fmizchi\u002Fexplainer\u002Fblob\u002Fmain\u002Fskills\u002Fd2-slides\u002FSKILL.md",[],[]]