spiega 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 Pierangelo Cecchetto - TulipLogic
+
+The spiega icon (docs/logo/spiega-mark.svg and spiega-mark-on-dark.svg) is
+original work under the copyright above, and not part of the visual language
+credited below.
+
+The visual language (palette, hand-drawn ink and grain treatment, flat
+three-band bodies, cobalt cast shadow) follows Colorfigures and ISO-GLOW:
+Copyright (c) 2026 April Zhu — MIT
+and iso-figure, on which ISO-GLOW is based:
+Copyright (c) 2026 Tolga Cohce — MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,409 @@
-# Temporary Holding Version
+<img src="https://raw.githubusercontent.com/pierangeloc/spiega/main/docs/logo/spiega-mark.svg" alt="" width="72" align="left" hspace="12">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# spiega
+
+A hand-drawn board an AI agent draws on **while it explains**.
+
+*spiega* is Italian for *explain* — and for *unfold*, which is what this does
+to a long document: spreads it out until you can see the whole shape at once.
+
+Say it **SPYEH-ga** (/ˈspjɛɡa/): two syllables, stress on the first, and the
+`i` is a glide rather than a vowel — *spyeh*, not *spee-eh*. It is the sound
+English keeps missing in *piano*, which Italian says the same way.
+
+You ask how something works. The agent answers in the terminal, as usual — and
+beside it, a board fills in: boxes for the services, labelled arrows for the
+calls, a dashed enclosure round the VPC, a note where the gotcha is. Then it
+walks the request through, one numbered hop at a time.
+
+It is meant for the thing a terminal is bad at: holding six nouns and the
+arrows between them in your head while you read a paragraph about them.
+
+![a finished board, saved as a snapshot, with step 3 lit](https://raw.githubusercontent.com/pierangeloc/spiega/main/docs/board.png)
+
+## Why not Miro, or Mermaid
+
+Miro is a place you go. This is a pane beside the conversation that the agent
+is already having, and the board is gone when you are done unless you keep it.
+
+Mermaid renders a finished diagram. This is drawn incrementally, in the order
+the explanation goes, which is most of what makes it followable — and it looks
+drawn, not generated, so it reads as somebody thinking rather than a document.
+
+## Install
+
+Node 20 or newer. No dependencies and no build step, so there is nothing to
+compile and nothing to wait for.
+
+Developed and used on **macOS**, and tested on macOS and Linux across Node 20,
+22 and 24. Windows paths are in the code and nobody has run them in anger — if
+you are on Windows, expect to file the first issue, and say so and it will get
+fixed.
+
+### 1. Get it on your PATH
+
+```bash
+npm install -g spiega
+```
+
+Or from a clone, if you want to change it:
+
+```bash
+git clone https://github.com/pierangeloc/spiega.git
+cd spiega
+npm link                  # `spiega` now points at this checkout
+```
+
+`npm link` rather than a copy on purpose: the CLI, the MCP server and the agent
+skill all resolve to that directory, so `git pull` updates every one of them at
+once.
+
+Check it:
+
+```bash
+spiega help
+```
+
+### 2. Wire it into your agents
+
+```bash
+spiega install --detect     # what it would do, touching nothing
+spiega install              # do it
+```
+
+`install` with no arguments does only what it finds on this machine, because
+writing a config for a harness you do not use is how you end up with a file you
+never asked for. `--list` shows every target and what it writes.
+
+It also links the command into a directory an agent's shell can see. That link
+is the one write it makes outside a config file of its own, and when
+`~/.local/bin` is not already on a non-interactive `PATH` it **asks** before
+adding a line to your `~/.zshenv`:
+
+```
+  spiega needs to be where an agent can find it.
+  ~/.local/bin is not on the PATH a non-interactive shell gets.
+
+  This would add one line to ~/.zshenv, after backing it up:
+      export PATH="$HOME/.local/bin:$PATH"
+
+  Add it? [y/N]
+```
+
+Anything but yes is no. Where there is nobody to ask — a script, CI, an agent's
+own tool call — the answer is no and the line is printed instead, so an install
+never hangs on a prompt and never edits a shell file unattended. `--path` and
+`--no-path` answer in advance.
+
+**Saying no withholds nothing else.** The skills and the MCP entries still
+install, and MCP runs spiega by its full path, so it works. What you lose is
+the fallback: an agent whose MCP server has died cannot find the command, and
+writes prose instead of drawing with nothing on screen to say it meant to.
+Install says so when you decline, and `spiega doctor` keeps saying so.
+
+| target | what it gets |
+|---|---|
+| `claude` | the skill, linked into `~/.claude/skills/` |
+| `codex` | the skill, an `AGENTS.md` block, an `mcp_servers` table |
+| `gemini` | the skill, a `GEMINI.md` block, an `mcpServers` entry |
+| `opencode` | `mcp.spiega` in `opencode.json`, and an `AGENTS.md` block |
+| `copilot` `cursor` `windsurf` `zed` `vscode` `claude_desktop` | the MCP server, in each one's own config shape |
+| `herdr` | a plugin: reach this task's board from its pane |
+| `project` | an `AGENTS.md` block in the repo you are in — ask for it by name |
+
+Everything is idempotent and backs up what it rewrites. Skills are
+**symlinked**, so they track the checkout instead of going stale. Instruction
+files get a delimited `SPIEGA_START`/`SPIEGA_END` block that leaves your own
+text alone. For a harness nothing here knows about, `spiega mcp-config`
+prints the entry to paste.
+
+### 3. See that it works
+
+```bash
+spiega draw '[{"op":"title","text":"Hello"},
+                {"op":"node","id":"gw","kind":"gateway","label":"API Gateway"},
+                {"op":"node","id":"db","kind":"datastore","label":"Postgres"},
+                {"op":"edge","from":"gw","to":"db","label":"SQL"}]'
+spiega open             # a window of its own
+```
+
+Two boxes and a line, drawn on. If you see them, every layer is working: the
+board, the renderer and the CLI.
+
+### 4. Restart your agent
+
+A running agent session holds the MCP process it started, and that process has
+the code it was launched with. **Start a fresh session after installing**, or
+the agent will be reading an older spiega than the one on disk. The symlink
+keeps files current; it cannot do anything about processes already running.
+
+Then ask for something architectural — "walk me through how X talks to Y, on
+the board" — and watch the pane.
+
+### Updating, and checking that it took
+
+```bash
+cd spiega && git pull && npm test
+spiega install          # only the copies need this: AGENTS.md blocks, the Cursor rule
+spiega doctor           # is what is running the thing that is on disk?
+```
+
+spiega reaches an agent through four kinds of thing, and they go stale
+differently:
+
+| | goes stale when |
+|---|---|
+| the CLI, via `npm link` | never — it is this checkout |
+| a skill, symlinked | never — but the agent loaded it when its session started |
+| an `AGENTS.md` block, a Cursor rule | the wording changes — re-run `spiega install` |
+| **a running process** | **immediately — it holds the code it was launched with** |
+
+The last one is the trap, and it is the one that looks like a feature that was
+never built. `spiega doctor` finds it:
+
+```
+ spiega doctor ──────────────────────────────────────────
+
+  ✓ spiega on PATH     ~/.nvm/…/spiega → this checkout
+  ✓ claude skill         linked — tracks the checkout
+  ✓ opencode AGENTS.md   block is current
+  ✗ agent MCP server     16 running, 16 started before the current commit
+
+  To fix
+    → start a fresh agent session — a running one keeps the server it launched
+```
+
+It exits non-zero when something is wrong, so it can go in a shell prompt or a
+pre-flight check. It makes no network calls and changes nothing.
+
+### If you use herdr
+
+```bash
+spiega install herdr
+```
+
+Then bind a key, in `~/.config/herdr/config.toml`:
+
+```toml
+[[keys.command]]
+key = "prefix+alt+h"
+type = "plugin_action"
+command = "spiega.board.focus"
+```
+
+`herdr server reload-config`, and that key brings the board for whatever pane
+you are in to the front — starting one if there is none.
+
+## Use it yourself
+
+```bash
+spiega draw '{"op":"title","text":"Placing an order"}'   # starts a board, prints its URL
+spiega draw '{"op":"node","id":"gw","kind":"gateway","label":"API Gateway","sub":"authn"}'
+spiega draw '{"op":"node","id":"orders","kind":"service","label":"Orders"}'
+spiega draw '{"op":"edge","from":"gw","to":"orders","label":"gRPC"}'
+spiega say  "The gateway does **authn** and rate limiting, then hands off."
+```
+
+Give the board a window of its own — chromeless, no tabs, its own Dock entry,
+so it sits beside your terminal like a native panel:
+
+```bash
+spiega open --size 1200x900 --pos 60,60
+```
+
+Render a whole spec with no server, or keep what is on the board:
+
+```bash
+spiega render examples/order-flow.json -o order-flow.html
+spiega snapshot -o docs/board.html
+```
+
+`spiega help` lists the rest.
+
+**Replay.** A board holds the order it was drawn in, not just its final state,
+so press **replay** (or `r`) and the session plays back as it happened: the
+line that was said, then the thing it was about being drawn, with the camera
+moving to wherever the work is and the words captioned over the picture. On
+anything complex the finished board is a wall; the replay is the explanation.
+It ends on a wide shot of the whole thing.
+
+The log lives on the board, so a replay can also be asked for from outside —
+`spiega replay`, or `board_replay` over MCP. An agent that has just finished
+an explanation can offer to play it back without thinking the drawing out a
+second time, and nothing is re-sent: it is the same session, run again.
+
+**Clicking the script.** A line tagged with a step is a way into that step:
+click it and the board walks there, so you can read a sentence and go straight
+to the hop it describes rather than hunting for the number. Clicking the step
+already lit clears it, so one gesture goes both ways. Lines tied to no step are
+not clickable and do not pretend to be.
+
+**Keys on the board:** `←` `→` walk the flow, `space` plays it, `r` replays the
+session, `+` `-` zoom a step at a time, `0` or `f` fits, `esc` stops.
+
+**Where to put the board.** `spiega open` gives it a real window and is the
+right answer for anything interactive. A terminal pane (`terminal-browser
+open "$(spiega url)"`) is good for *glancing* while you work and for stepping
+a flow with the arrow keys — those repaint once per keypress. It is poor at
+continuous zoom and dragging, because every frame has to be encoded and pushed
+through the TTY however fast the page itself is. Both can watch the same board
+at once.
+
+## One board per conversation
+
+A board belongs to an explanation, and people hold more than one at a time. Two
+agents drawing on the same board interleave two explanations into one picture,
+which is worse than either having none — so boards have names.
+
+```bash
+spiega boards                      # every board, and which one this shell uses
+spiega focus                       # bring this session's board window forward
+spiega --board api draw '...'      # or SPIEGA_BOARD=api
+spiega stop                        # drop this board; the others keep drawing
+spiega stop --all                  # all of them, and the server with them
+```
+
+A board names itself after the task: the working directory's own name, which
+for a worktree is the thing you called it — `domain-modeling-for-rights`, not a
+uuid. A session keeps the board it already has, matched on whichever identity
+its harness exposes (the conversation id, else the terminal pane, else the
+directory). Two conversations about one repo get `name` and `name-2`, and
+`spiega boards` prints each board's directory so they can be told apart.
+
+Not per harness, per task: four opencode sessions and four Claude Code sessions
+at once is the normal case, and a board per harness would put four
+explanations on one drawing. Note that an MCP server started by a long-lived
+daemon inherits that daemon's environment, so the CLI — which runs in the pane
+— resolves the session correctly where MCP may not.
+
+A board is registered by the process serving it and pruned when that process is
+gone, so a name never resolves to a socket nobody is listening on.
+
+## One server, all the boards
+
+They all live in one process, on port 4777, each under `/b/<name>`. It used to
+be a process and a port per board, and the arithmetic was indefensible: the
+Node runtime is 55-70 MB and a board with nine boxes is a few KB of state, so
+eight parallel tasks spent ~600 MB holding a few hundred KB of drawing.
+
+The second reason is staleness, and it is the one that actually bit. A server
+per board meant a board started before an update kept serving the old page for
+as long as it lived — one of them 404'd on a route the code on disk had — while
+the isolation that a process per board bought had never once been needed.
+
+So: one port, no scanning upward, one copy of the renderer served to every
+board, and every board running the code that is on disk. Starting a board is a
+map entry on a process that is almost certainly already up; the port itself is
+the lock, so two agents drawing at the same moment do not end up with two
+servers. `spiega stop` drops one board and leaves the rest drawing;
+`spiega stop --server` ends the process and everything on it.
+
+`spiega serve --solo` gives a board its own process and its own port if an
+isolation case ever turns up. Clients cannot tell the difference: the url shape
+is the same either way, and `spiega boards` says which boards are on their own.
+
+If you run your sessions in [herdr](https://herdr.dev), `spiega install herdr`
+links a plugin that goes from the pane you are working in to that task's board —
+bind a key to **spiega: show this task's board**. It reads the pane's working
+directory rather than the conversation, so it needs nothing from the agent.
+See [`integrations/herdr/`](integrations/herdr/).
+
+## Compare how models use it
+
+```bash
+spiega bench --list                     # models you can reach right now
+spiega bench "how a write-through cache works" \
+  --models github-copilot/claude-opus-5.5,github-copilot/gpt-6-sol
+```
+
+Runs the same brief through each model via `opencode run`, parses the ops out of
+whatever it replied with, renders each board, and writes `bench/index.html`
+comparing them side by side — boxes, lines, steps, how many edges it bothered to
+label, how many kinds it reached for. Each model's raw reply is kept next to its
+board. Runs are isolated and never touch a live board.
+
+
+
+A Claude skill, a Cursor rule and an MCP server, all driving the same board —
+see [`integrations/`](integrations/). The agent needs no new vocabulary: it
+emits small JSON ops as it talks.
+
+Every op, every node kind and every layout hint is in
+[`docs/vocabulary.md`](docs/vocabulary.md), along with what the board does
+*not* model — worth reading before asking for a sequence diagram. The
+instructions the agent itself reads are in [`docs/skill.md`](docs/skill.md).
+
+```jsonc
+{"op":"node","id":"db","kind":"datastore","label":"Postgres","sub":"orders"}
+{"op":"edge","from":"orders","to":"bus","label":"publish","async":true}
+{"op":"note","label":"idempotency key\nlives 24h"}
+{"op":"boundary","label":"our VPC","members":["gw","orders","db"]}
+{"op":"step","edge":"gw>orders","step":"Gateway authenticates and forwards"}
+{"op":"say","text":"The gateway checks the token first.","step":2}
+```
+
+A board has two halves, and a `say` can name the step it explains. Walking the
+flow then lights the matching lines of the script while the others recede, so
+the words and the picture move together. Lines about the board as a whole carry
+no step and never dim; a line said while a step was lit is attributed for free.
+Nothing is inferred beyond that — an untagged script does not highlight rather
+than highlighting the wrong thing.
+
+Which lines went with which step is often clear only afterwards, so tags can be
+set on lines already said. The board keeps them; nothing is drawn again.
+
+```bash
+spiega script                              # the lines, numbered, and what each is tied to
+spiega tag --match "Flyway V25" --step 6
+spiega tag 1 --step off                    # an opening remark belongs to no step
+```
+
+The rail shows what was said, in the order it was said. So a script narrated
+topic by topic, with each line tagged by whichever step it touches, comes out
+`2, 1, 3, 3, 4, 3, 6` — which looks like a sort gone wrong, though nothing
+sorted anything. `spiega script` says so when it happens, because from the
+board you cannot tell the difference between that and a bug.
+
+Nothing is ever placed by hand. Columns are derived from the edges — a node
+sits one column right of whatever points at it — so the agent draws a box, then
+the arrow into it, and the layout follows.
+
+## How it is put together
+
+| | |
+|---|---|
+| `src/render/ink.js` | seeded wobble: the geometry that makes a line look drawn |
+| `src/render/glyphs.js` | one drawing per kind — service, cylinder, queue, cloud, note |
+| `src/render/edges.js` | gutter routing, fan-out anchors, numbered tags |
+| `src/render/layout.js` | columns from the flow, order-stable so nothing jumps |
+| `src/board/state.js` | the board as an op log |
+| `src/board/server.js` | one process, every board; HTTP + SSE, and the renderer as plain ES modules |
+| `src/board/board.html` | the pane: transcript rail, step strip, pan and zoom |
+| `src/board/draw-on.js` | the hand: variable pen speed, uneven pauses, ink then colour |
+| `src/mcp/server.js` | the same board as MCP tools |
+
+Two separate things make it look hand-drawn, and both are needed. The geometry
+is off true — `waver()` in `ink.js` pushes every point around a seeded wobble,
+so a line bows rather than buzzing. And the *motion* is off true: a stroke is
+drawn with keyframes whose progress runs ahead of and behind the clock, so the
+pen hurries down a straight and slows coming round a corner, strokes start
+before the one before has finished, and the colour only goes on once the
+outline is closed. A constant-speed dashoffset tween reads as a machine tracing
+a path, which is exactly what it is.
+
+The wobble lives in the path data rather than in an SVG filter, so the board can
+animate without recomputing a filter every frame. Snapshots, which are rendered
+once and never animate, do get the full ink-and-paper filter on top.
+
+## Credits
+
+The look — warm paper, flat three-band bodies, the cobalt cast shadow, the
+ink-and-grain filter — follows [Colorfigures](https://april-zhu.com/colorfigures)
+by April Zhu (MIT), which is built on ISO-GLOW by April Zhu and
+[iso-figure](https://github.com/MrBongoC/ai-iso-skill) by Tolga Cohce, both MIT.
+Colorfigures draws machines in isometric 3D; spiega borrows its palette and
+its hand, and points them at software architecture in 2D.
+
+## License
+
+MIT.

package/bin/spiega

@@ -0,0 +1,155 @@
+#!/bin/sh
+# spiega — a launcher, not a node script.
+#
+# `#!/usr/bin/env node` is a lottery on a machine with nvm: the shebang resolves
+# `node` from the caller's PATH, and an agent's non-interactive shell may find a
+# brew node missing its dylibs or a node from 2016. So this resolves a node that
+# is new enough for the engines floor, preferring the one `spiega install` ran
+# under, and execs the real CLI with it. It is /bin/sh so it runs before any
+# node does.
+#
+# The guesses below are nvm-shaped, which is no use to a node from brew, asdf,
+# volta or mise. The record is what makes the first run after install work
+# there: install only gets that far on a node the engines guard has accepted.
+#
+# The one thing it must never do is guess silently: if no usable node is found,
+# it says so in one sentence and exits non-zero.
+
+set -u
+
+# Resolve this script through any symlinks. npm and `spiega install` both link
+# to it, so $0 is usually the link and not the file next to src/.
+target=$0
+while [ -h "$target" ]; do
+  dir=$(CDPATH= cd -- "$(dirname -- "$target")" && pwd -P)
+  link=$(readlink "$target")
+  case $link in
+    /*) target=$link ;;
+    *) target=$dir/$link ;;
+  esac
+done
+root=$(CDPATH= cd -- "$(dirname -- "$target")/.." && pwd -P)
+cli=$root/src/cli.js
+
+# The floor lives in package.json; this only repeats it if the read fails.
+floor=$(sed -n 's/.*"node"[[:space:]]*:[[:space:]]*">=[[:space:]]*\([0-9][0-9]*\).*/\1/p' \
+  "$root/package.json" 2>/dev/null | head -n 1)
+[ -n "${floor:-}" ] || floor=20
+
+# A node is usable only if it actually runs and clears the floor. A binary that
+# exists but cannot load its libraries fails here rather than inside the CLI.
+usable() {
+  [ -n "${1:-}" ] && [ -x "$1" ] || return 1
+  v=$("$1" -p 'process.versions.node' 2>/dev/null) || return 1
+  [ -n "$v" ] || return 1
+  major=${v%%.*}
+  case $major in ''|*[!0-9]*) return 1 ;; esac
+  [ "$major" -ge "$floor" ]
+}
+
+nvm=${NVM_DIR:-$HOME/.nvm}
+
+# The node `spiega install` was running under when it wrote this install. It
+# lives in the state directory rather than in this file, because this is a
+# tracked file: an install that wrote into it would dirty the checkout, and a
+# `git pull` would either revert it or refuse. It is per HOME, so a checkout
+# shared between machines keeps one answer each.
+#
+# A recorded path can be gone — a deleted nvm version, an upgraded brew. It is
+# a candidate like any other and goes through usable() below, so staleness
+# costs a shell call, not the run.
+record_file=$HOME/.spiega/node
+recorded=''
+if [ -f "$record_file" ]; then
+  IFS= read -r recorded < "$record_file" 2>/dev/null || true
+fi
+
+# nvm's default alias, followed through links like lts/* and node. The alias
+# file may name a version (`26.10.0`, `v26.10.0`) or another alias.
+from_alias() {
+  a=$1
+  i=0
+  while [ "$i" -lt 5 ] && [ -f "$nvm/alias/$a" ]; do
+    a=$(cat "$nvm/alias/$a" 2>/dev/null) || return 1
+    i=$((i + 1))
+  done
+  case $a in
+    v[0-9]*) printf '%s\n' "$nvm/versions/node/$a/bin/node" ;;
+    [0-9]*) printf '%s\n' "$nvm/versions/node/v$a/bin/node" ;;
+  esac
+}
+
+node=''
+# Which rung answered, so `spiega doctor` can say why rather than only which.
+via=''
+
+# 1. An explicit choice, for a machine whose right node is not nvm's default.
+if [ -n "${SPIEGA_NODE:-}" ] && usable "$SPIEGA_NODE"; then
+  node=$SPIEGA_NODE
+  via=override
+fi
+
+# 2. The node that installed this, remembered because install ran under a node
+#    it had already checked against the floor. This is the rung that works
+#    when the node came from somewhere the guesses below have never heard of.
+if [ -z "$node" ] && [ -n "$recorded" ] && usable "$recorded"; then
+  node=$recorded
+  via=recorded
+fi
+
+# 3. What nvm calls the default — the node someone actually uses in a terminal.
+if [ -z "$node" ]; then
+  alias_node=$(from_alias default 2>/dev/null) || alias_node=''
+  if [ -n "$alias_node" ] && usable "$alias_node"; then
+    node=$alias_node
+    via=nvm-default
+  fi
+fi
+
+# 4. Any installed nvm version that clears the floor, newest first.
+if [ -z "$node" ] && [ -d "$nvm/versions/node" ]; then
+  while IFS= read -r candidate; do
+    if usable "$candidate"; then node=$candidate; via=nvm-any; break; fi
+  done <<EOF
+$(ls -1d "$nvm"/versions/node/*/bin/node 2>/dev/null | sort -r)
+EOF
+fi
+
+# 5. Whatever the PATH has, if it is usable.
+if [ -z "$node" ]; then
+  candidate=$(command -v node 2>/dev/null) || candidate=''
+  if [ -n "$candidate" ] && usable "$candidate"; then node=$candidate; via=path; fi
+fi
+
+# 6. The usual places, for a shell whose PATH is as bare as an agent's.
+if [ -z "$node" ]; then
+  for candidate in /opt/homebrew/bin/node /usr/local/bin/node /usr/bin/node; do
+    if usable "$candidate"; then node=$candidate; via=known; break; fi
+  done
+fi
+
+if [ -z "$node" ]; then
+  echo "spiega needs Node $floor or newer and found no node on this machine that can run it; install one with nvm (nvm install --lts) or point SPIEGA_NODE at it." >&2
+  exit 1
+fi
+
+# `spiega doctor` asks the launcher which node an agent would really get,
+# because the node on PATH and the node nvm calls default are not the same
+# thing, and only the second one runs this.
+if [ "${SPIEGA_NODE_VERSION:-}" = "1" ]; then
+  printf '%s %s %s\n' "$node" "$("$node" -p 'process.versions.node')" "$via"
+  # The record is a second answer to a second question: which node was
+  # installed against, and is it still there? It can be stale while the
+  # launcher is fine, so doctor cannot infer it from the node above. No line
+  # at all means there is no record; that is not the same as a broken one.
+  if [ -n "$recorded" ]; then
+    if usable "$recorded"; then
+      printf 'recorded %s ok\n' "$recorded"
+    else
+      printf 'recorded %s stale\n' "$recorded"
+    fi
+  fi
+  exit 0
+fi
+
+exec "$node" "$cli" "$@"

package/docs/README.md

@@ -0,0 +1,9 @@
+# docs
+
+| page | what is in it |
+|---|---|
+| [skill.md](skill.md) | the instructions an agent reads, and the three routes they travel |
+| [vocabulary.md](vocabulary.md) | every op, kind and layout hint — and what the board does not model |
+| [shapes.md](shapes.md) | what each of them is drawn as, rendered from the renderer itself |
+
+The README covers installing and using spiega. These cover steering it.

package/docs/logo/spiega-mark-on-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="31 31 138 138" role="img" aria-label="Spiega"><rect x="31" y="31" width="138" height="138" rx="28" fill="#1E1C17"/><path d="M139.9 52.5 A62 62 0 1 1 49.2 135.6" fill="none" stroke="#C4823A" stroke-width="14" stroke-linecap="round"/><path d="M41.0 119.2 A62 62 0 0 1 110.8 38.9" fill="none" stroke="#76AE62" stroke-width="14" stroke-linecap="round"/><path d="M142.2 80.4 L142.0 79.9 L141.9 79.4 L141.8 78.9 L141.7 78.3 L141.6 77.8 L141.5 77.2 L141.4 76.6 L141.3 76.1 L141.3 75.5 L141.2 74.9 L141.1 74.3 L141.0 73.7 L140.9 73.1 L140.9 72.5 L140.8 71.9 L140.7 71.3 L140.6 70.7 L140.5 70.0 L140.4 69.4 L140.3 68.8 L140.2 68.1 L140.1 67.5 L140.0 66.8 L139.9 66.2 L139.8 65.5 L139.6 64.9 L139.5 64.2 L139.4 63.5 L139.2 62.8 L139.1 62.2 L138.9 61.5 L138.8 60.8 L138.6 60.1 L138.4 59.4 L138.2 58.7 L138.0 58.0 L137.9 57.3 L137.6 56.6 L137.4 55.8 L137.2 55.1 L137.0 54.4 L136.8 53.7 L136.5 52.9 L136.3 52.2 L136.0 51.4 L135.7 50.7 L135.4 50.0 L135.1 49.2 L134.8 48.5 L134.5 47.7 L134.2 46.9 L133.9 46.2 L133.5 45.4 L133.2 44.6 L132.8 43.9 L132.5 43.1 L132.1 42.3 L131.7 41.6 L131.3 40.8 L130.9 40.0 L121.5 47.6 L122.1 48.1 L122.7 48.5 L123.3 49.0 L123.9 49.5 L124.4 50.0 L124.9 50.5 L125.5 51.0 L126.0 51.5 L126.5 52.0 L127.0 52.5 L127.5 53.0 L128.0 53.6 L128.5 54.1 L128.9 54.6 L129.4 55.2 L129.9 55.7 L130.3 56.2 L130.7 56.8 L131.2 57.3 L131.6 57.9 L132.0 58.5 L132.4 59.0 L132.7 59.6 L133.1 60.2 L133.5 60.7 L133.8 61.3 L134.2 61.9 L134.5 62.4 L134.9 63.0 L135.2 63.6 L135.5 64.2 L135.8 64.8 L136.1 65.3 L136.4 65.9 L136.6 66.5 L136.9 67.1 L137.2 67.7 L137.4 68.3 L137.6 68.8 L137.9 69.4 L138.1 70.0 L138.3 70.6 L138.5 71.2 L138.7 71.7 L138.9 72.3 L139.1 72.9 L139.3 73.5 L139.4 74.0 L139.6 74.6 L139.8 75.2 L139.9 75.7 L140.1 76.3 L140.2 76.9 L140.4 77.4 L140.5 78.0 L140.6 78.5 L140.8 79.1 L140.9 79.6 L141.0 80.2 L141.2 80.7 Z" fill="#B52D6A"/><circle cx="126.2" cy="43.8" r="10" fill="#B52D6A"/></svg>

package/docs/logo/spiega-mark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="31 31 138 138" role="img" aria-label="Spiega"><path d="M139.9 52.5 A62 62 0 1 1 49.2 135.6" fill="none" stroke="#C4823A" stroke-width="14" stroke-linecap="round"/><path d="M41.0 119.2 A62 62 0 0 1 110.8 38.9" fill="none" stroke="#76AE62" stroke-width="14" stroke-linecap="round"/><path d="M142.2 80.4 L142.0 79.9 L141.9 79.4 L141.8 78.9 L141.7 78.3 L141.6 77.8 L141.5 77.2 L141.4 76.6 L141.3 76.1 L141.3 75.5 L141.2 74.9 L141.1 74.3 L141.0 73.7 L140.9 73.1 L140.9 72.5 L140.8 71.9 L140.7 71.3 L140.6 70.7 L140.5 70.0 L140.4 69.4 L140.3 68.8 L140.2 68.1 L140.1 67.5 L140.0 66.8 L139.9 66.2 L139.8 65.5 L139.6 64.9 L139.5 64.2 L139.4 63.5 L139.2 62.8 L139.1 62.2 L138.9 61.5 L138.8 60.8 L138.6 60.1 L138.4 59.4 L138.2 58.7 L138.0 58.0 L137.9 57.3 L137.6 56.6 L137.4 55.8 L137.2 55.1 L137.0 54.4 L136.8 53.7 L136.5 52.9 L136.3 52.2 L136.0 51.4 L135.7 50.7 L135.4 50.0 L135.1 49.2 L134.8 48.5 L134.5 47.7 L134.2 46.9 L133.9 46.2 L133.5 45.4 L133.2 44.6 L132.8 43.9 L132.5 43.1 L132.1 42.3 L131.7 41.6 L131.3 40.8 L130.9 40.0 L121.5 47.6 L122.1 48.1 L122.7 48.5 L123.3 49.0 L123.9 49.5 L124.4 50.0 L124.9 50.5 L125.5 51.0 L126.0 51.5 L126.5 52.0 L127.0 52.5 L127.5 53.0 L128.0 53.6 L128.5 54.1 L128.9 54.6 L129.4 55.2 L129.9 55.7 L130.3 56.2 L130.7 56.8 L131.2 57.3 L131.6 57.9 L132.0 58.5 L132.4 59.0 L132.7 59.6 L133.1 60.2 L133.5 60.7 L133.8 61.3 L134.2 61.9 L134.5 62.4 L134.9 63.0 L135.2 63.6 L135.5 64.2 L135.8 64.8 L136.1 65.3 L136.4 65.9 L136.6 66.5 L136.9 67.1 L137.2 67.7 L137.4 68.3 L137.6 68.8 L137.9 69.4 L138.1 70.0 L138.3 70.6 L138.5 71.2 L138.7 71.7 L138.9 72.3 L139.1 72.9 L139.3 73.5 L139.4 74.0 L139.6 74.6 L139.8 75.2 L139.9 75.7 L140.1 76.3 L140.2 76.9 L140.4 77.4 L140.5 78.0 L140.6 78.5 L140.8 79.1 L140.9 79.6 L141.0 80.2 L141.2 80.7 Z" fill="#B52D6A"/><circle cx="126.2" cy="43.8" r="10" fill="#B52D6A"/></svg>