@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/docs/YAK.md

@@ -0,0 +1,395 @@
+# `eris yak` — land a durable observation with the Yaks endpoint
+
+Three verbs an agent (or a human) can invoke inline when the harness fights back —
+a broken tool, a confusing error, a config gap — or could serve them better, and never for the task's own
+outcome. `eris yak` redacts, resolves identity, derives a dedup key, makes one
+bounded HTTP call to a Yaks endpoint, and gets out
+of the way. Everything after the receipt — clustering, issue-tracker writes,
+incident routing — belongs to the endpoint, not to this CLI.
+
+```
+eris yak issue   --summary "…" --body "…"
+eris yak suggest --summary "…" --body-file -
+eris yak fatal   --summary "…" --body-file -
+```
+
+## Which verb
+
+| Verb | When |
+|---|---|
+| `issue` | A harness/tooling defect — a command that errors, a flag that does the wrong thing, a doc that lies. A suspected defect goes here too, with the hedge in the body |
+| `suggest` | An improvement to the harness — a missing verb or flag, a better default, a skill or rule that should exist, change or go. Nothing has to be broken |
+| `fatal` | The harness itself is broken — the thing you're standing on, not the thing you're building |
+
+None of the three is for the task's *own* outcome (a test failure in the code
+you're writing, a bug in the feature you're implementing). They exist for
+problems with the tools, not the work.
+
+## Flags
+
+```
+eris yak <issue|suggest|fatal>
+  --summary <text>                              required, ≤ 200 chars
+  --body <text> | --body-file <path|->          required, ≤ 4000 chars (`-` = stdin)
+  --evidence <text> | --evidence-file <path|->  optional, ≤ 20000 chars
+  --repro <command>                             optional, ≤ 2000 chars — see below
+  --repo <owner/name>                           optional, repeatable, ≤ 200 chars each,
+                                                ≤ 20 total — see below
+  --no-redact                                   skip the secret-scrub pass (loud warning)
+```
+
+`--body-file -` and `--evidence-file -` are mutually exclusive — there is only
+one stdin. `--body-file -` with no pipe fails immediately (`yak-stdin-is-a-tty`)
+rather than hanging: a command that blocks forever mid-task is exactly the
+yak-shave this feature exists to remove.
+
+Over-length fields fail locally with the actual/max lengths named, rather than
+letting the server truncate silently — a server-side truncation would desync
+the stored payload from the dedup key this CLI already derived from the full
+text (see [Idempotency](#idempotency-and-replay)).
+
+## Setup
+
+`eris yak` reads its endpoint URL and bearer token from **one file**,
+`~/.eris/yaks.json`, mode `0600`:
+
+```json
+{ "url": "https://yaks.example.com", "token": "…" }
+```
+
+The url is `ERIS_YAKS_URL`, then the file's `url`, then the default
+`https://api.sibylline.group`. Set either only to use another endpoint.
+
+### `eris login`: a device code
+
+Sign in from any terminal:
+
+```
+eris login
+```
+
+That signs in to `https://api.sibylline.group`. For another endpoint that
+offers device login, pass `--url https://yaks.example.com`.
+
+It prints a link and a short code (and opens the link in a browser when stderr
+is a terminal; `--no-browser` skips that). Approve the code there, and the
+token the endpoint mints is written to `~/.eris/yaks.json` with the url beside
+it, so later runs need no `--url`. The file is replaced only after a token
+arrives, via a temp file created `0600` and renamed into place: a denied or
+expired code writes nothing (`login-denied`, `login-expired`, exit 1). Neither
+the device code nor the token is printed; the short code is the one value
+shown, and it is useless without the approval. Without `--url` the url is
+`ERIS_YAKS_URL`, then the file's own `url`, then the default. The CLI follows RFC 8628: it
+polls `/v1/device/token` at the advertised interval and slows down when told to.
+
+`eris logout` removes the token from the file and keeps the url. No route lets
+a token revoke itself, so it stays valid until you revoke it from the
+endpoint's dashboard (Settings > API Tokens).
+
+### `yak-setup.ts`: a hand-registered bearer
+
+For a self-hosted endpoint, mint the file with
+`bun plugins/yak/yak-setup.ts --url <endpoint>` (or with `ERIS_YAKS_URL` set)
+from an eris checkout; it refuses without one, because the default endpoint
+signs machines in with `eris login`. It writes the file and prints the
+follow-up step: the endpoint's operator has to register the bearer against
+this machine's source slug, which the script does not automate. Until both
+halves are done, every yak from this machine warns and exits 0 rather than
+failing your task — see [Exit codes](#exit-codes).
+
+`ERIS_YAKS_TOKEN` / `ERIS_YAKS_URL` override the file's `token` / `url` fields
+independently. Nothing else is consulted: a per-source token *is* the ingest
+identity, so it never comes from a file in a repository.
+
+The directory `~/.eris` itself is `0755`; the **file's** mode is the guard. A
+group- or world-readable `yaks.json` is refused outright — never parsed, never
+logged — rather than silently trusting a permissive `~/.eris`.
+
+## Exit codes
+
+The table below describes **text mode** (the default). Under `--output json`
+the diagnostics move entirely onto stdout's record — see below.
+
+| Situation | Exit |
+|---|---|
+| Missing `--summary`/`--body`, an unreadable `--body-file`, `--body-file -` with no pipe, an over-length field, an unknown verb or flag, a bare positional word (the text belongs on `--summary`/`--body`) | **`1`** — the four-line `ERROR`/`slug:`/`fix:`/`docs:` block, same contract as every other eris failure |
+| Unresolved token/URL/device-id, an unreachable endpoint, a timeout, a non-2xx response | **`0`** — one `WARN` line + slug on stderr, empty stdout in text mode. A non-2xx status gets its own slug when the cause is on the caller's side (credentials, entitlement, size) and a retry changes nothing — see the rungs below |
+| An incomplete `node_modules` on this machine (`yak-deps-not-installed`) | **`0`** — the same four-line `ERROR`/`slug:`/`fix:`/`docs:` block as the exit-`1` row above, but exit `0`: a broken install on the operator's machine isn't something the calling agent could have done differently |
+| No `bun` on PATH | **`1`** — the shim's own `eris-bun-missing` block, printed before any verb is routed; it is not yak-specific |
+| Accepted (fresh or replay) | **`0`** |
+
+The line that decides which bucket a failure falls into: *could the agent have
+done anything differently?* A missing `--summary` is the agent's fault and is
+fixable on the spot. An unset token, an unreachable endpoint, or a machine with no
+network right now is not — failing the task over the operator's local
+environment would be worse than the problem this feature exists to report. So
+**environment, config, and transport problems never fail the task** — they warn
+on stderr and let the calling command continue.
+
+### Rungs for a non-2xx response
+
+Every non-2xx response is `WARN` + exit `0`. The endpoint's refusals that a
+retry does not fix get their own slug, so the `WARN` line (and `error.slug`
+under `--output json`) names the remedy instead of a generic transport failure:
+
+| Status | Slug | Meaning and fix |
+|---|---|---|
+| `401` | [`yak-unauthorized`](ERRORS.md#yak-unauthorized) | The endpoint rejected the bearer token. Check `~/.eris/yaks.json` / `ERIS_YAKS_TOKEN`, and that the token is registered. |
+| `402` | [`yak-not-entitled`](ERRORS.md#yak-not-entitled) | The workspace is not entitled to Yaks (plan or seat). |
+| `413` | [`yak-payload-too-large`](ERRORS.md#yak-payload-too-large) | The submission exceeded the endpoint's whole-body size cap. Trim `--evidence`. |
+| any other non-2xx | [`yak-transport-error`](ERRORS.md#yak-transport-error) | An outage, a missing route, a proxy page: no local remedy is known. |
+
+Each rung's `ERRORS.md` entry notes that a problem with eris itself is reported
+on the vendor route, the eris project's own tracker, rather than into the
+workspace.
+
+### `--output json`
+
+Under `--output json`, `eris yak <issue|suggest|fatal>` writes **exactly one
+JSON record to stdout and nothing at all to stderr**, on every outcome above —
+misuse, warn, and delivered alike, including the dispatcher-level check
+(`yak-deps-not-installed`, `plugins/yak/handlers.ts`) that never reaches the
+yak core. Exit codes are unchanged from the table above. The one exception is
+`eris-bun-missing`: the shim prints it before bun starts, so no record exists.
+
+The record: `{verb, delivered, id?, idempotency_key?, replay?,
+contract_version?, key_mismatch?, redactions: {count, classes, skipped},
+error?}`. **`delivered` is the field to branch on — never `id == null`**. Three fields exist specifically because their text-mode stderr
+equivalent is suppressed under json and would otherwise be silently lost:
+
+- **`redactions.skipped`** — `true` when `--no-redact` was set for this
+  submission. A skipped scrub and a scrub that ran and found nothing both
+  leave `count: 0, classes: []`; without this field the two are
+  indistinguishable on the wire. Text mode's `yak-no-redact` WARN carries the
+  same fact.
+- **`key_mismatch`** — present (`true`/`false`) only when `delivered: true`.
+  Mirrors text mode's `yak-key-mismatch` WARN — the record's own
+  `idempotency_key` is the *receipt's* key, never the locally-derived one the
+  mismatch is measured against, so this is the only way a machine caller can
+  detect canonicalization drift.
+- **`error.slug`/`error.reason`** — the content of the `WARN`/`ERROR` line
+  itself, on every non-delivered outcome.
+
+What is *not* reproduced in the record: the `fix:`/`docs:` lines from the
+text-mode failure block. Those are reconstructable from `error.slug` — every
+slug is a stable heading in [ERRORS.md](ERRORS.md) — the same way any other
+`--output json` failure's remediation is looked up.
+
+See [OUTPUT-CONTRACT.md §3](OUTPUT-CONTRACT.md#3-machine-surfaces).
+
+## Redaction
+
+`summary`, `body`, `evidence`, `repro`, every `--repo` hint, and the gathered provenance are scrubbed before
+anything else sees them — before the dedup key is derived, before the payload
+is validated, before the request leaves the machine. Each match is replaced
+with `«redacted:<class>»`. In text mode the count and class breakdown print
+to **stderr**, never stdout; under `--output json` the same information is
+`redactions.{count,classes}` on the record instead — stderr carries nothing
+either way (see [Exit codes](#--output-json) above).
+
+Classes covered: PEM private-key blocks, JWTs, `sib_` service tokens,
+`sibdc_` device codes (what `eris login` polls with),
+AWS access-key ids and `aws_secret_access_key` assignments,
+GitHub/Slack/Google/`sk-`-style API keys, `Authorization: Bearer|token …`
+headers, GCP service-account `"private_key"` values, connection strings with an
+inline password, and **key-name
+assignments** — `NAME=value` or `NAME: value` where `NAME` matches
+`(SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE_KEY|API_KEY|CREDENTIAL|ACCESS_KEY|CLIENT_SECRET|MNEMONIC|SEED|SESSION|COOKIE|AUTH)`.
+
+**Redaction is defence in depth, not a boundary.** It is a pattern scrub, and a
+pattern scrub can always miss a shape it wasn't written for. Do not paste
+material into `eris yak` on the assumption that anything sensitive will be
+caught — the honest framing is "this makes an accidental leak less likely," not
+"this makes a report safe by construction." `--no-redact` exists for the
+(rare, and loudly warned) case where the scrub itself is corrupting a report
+that needs to be read verbatim; it does not exist to work around a
+false-positive scrub eating a legitimate report — if that happens, file it as
+its own `eris yak issue` against the redaction pass.
+
+## The wire contract
+
+`eris yak` speaks the Yaks submission contract v2, the workspace package
+`@sibylline-labs/yak-contract` ([`packages/yak-contract`](../packages/yak-contract)),
+imported by name rather than vendored as a copy. One call per report:
+
+- `POST <url>/v1/yaks` with `Authorization: Bearer <token>`. The ingress
+  answers `202` with a receipt `{id, idempotency_key, replay, contract_version}`;
+  any `2xx` whose body is a receipt counts as delivered, whatever the
+  `contract_version` string says.
+- `route` is always `"workspace"`: the report files into the caller's own
+  tenant. It is not an input to the idempotency key.
+- There is no `reporter`. The ingress derives the tracker user from the bearer
+  token, so the CLI sends no identity of its own.
+- `schema_version` is the package's `YAKS_CONTRACT_VERSION`. The body is
+  validated against the package's `YakSubmission` before the request, so a field
+  the contract would refuse never leaves the machine.
+
+## Idempotency and replay
+
+Every submission derives a dedup key from `{device_id, execution_id, verb,
+summary, body, evidence}` **after** redaction — the endpoint re-derives the same
+key from the payload it actually received, so deriving from anything else
+would guarantee a mismatch on every report. Two calls with the same inputs in
+the same task dedupe to one observation: the second gets back the *same*
+receipt with `replay: true`, rendered as `already recorded: <id>` in text mode
+(a fresh delivery renders `recorded: <id>`) — an agent can tell "this landed"
+from "this already landed" without re-reporting.
+
+The contract exposes no server-side mismatch signal on the receipt itself
+(only a server console warning, invisible to the client). The one drift check
+`eris yak` can make is comparing its own locally-derived key against the
+receipt's `idempotency_key` — a mismatch prints a `yak-key-mismatch` warning
+alongside a still-successful delivery. It is a symptom of this CLI's contract
+package (`packages/yak-contract`) drifting from the endpoint's derivation, not
+something a caller needs to act on.
+
+## Repro
+
+`--repro <command>` attaches a command that reproduces the problem being
+reported — a failing test invocation, a `curl`/`eris` one-liner, a short
+repro script's entry point. It rides on the wire inside `provenance` (as
+`provenance.repro.command`) rather than as a new top-level field on
+`YakSubmission`: that contract is the workspace package
+`@sibylline-labs/yak-contract` ([The wire contract](#the-wire-contract)), and
+not something this CLI can extend on its own — `YakProvenance`'s `.catchall()` exists
+precisely so a CLI-side addition like this one doesn't have to wait on a
+contract bump. It is redacted the same as `evidence` (a repro command can
+itself embed a credential — `curl -H "Authorization: Bearer …"` is a
+realistic shape) and bounded to 2000 chars locally, the same courtesy bound
+`summary`/`body`/`evidence` get (see [`yak-repro-too-long`](ERRORS.md#yak-repro-too-long)).
+It does not participate in the idempotency-key derivation — attaching or
+editing a repro never changes an observation's dedup identity.
+
+**That stability has a sharp edge: a repro-only resubmission is a silent
+no-op.** The idempotency key is derived from `{device_id, execution_id, verb,
+summary, body, evidence}` (see [Idempotency and replay](#idempotency-and-replay))
+— `repro` deliberately isn't one of those fields, which is the right call
+(you don't want editing a repro to fork a fresh cluster off the same report).
+But it means resubmitting the *same* `summary`/`body`/`evidence` with a
+*different* (or newly-added) `--repro` derives the *same* key, so the endpoint's
+dedup treats it as a replay of the observation it already has: `delivered:
+true` comes back, but no new `YakObservation` is created and the new repro
+text is never stored or seen server-side. There is currently no supported way
+to attach or change a repro on an existing cluster after its first
+observation — only the repro that rode on whichever observation actually
+created (or first populated) the cluster survives.
+
+**Sandboxing — what this CLI guarantees, and what it doesn't.** `eris yak`
+never executes the repro command, on this machine or anywhere else; it is
+opaque text from the moment it's typed to the moment it's POSTed. Nothing in
+this codepath (`plugins/yak/handlers.ts`, `plugins/yak/yak.ts`, `plugins/yak/yak-submit.ts`,
+`plugins/yak/yak-context.ts`) shells out, and the submission carries no
+credential, project id, region, or `eris.yaml` env context — `yak-context.ts`
+explicitly excludes a config merge and any cloud-CLI/keychain read from its
+provenance gather (see that file's own header). So the one thing THIS repo
+could leak into a repro — live production access riding along with the
+command — structurally cannot happen here: there is no production
+credential in `eris yak`'s own process to leak.
+
+That is the client-side half of the requirement. **Actually rerunning the
+repro is the Yaks endpoint's job, not this CLI's** — "everything after the receipt —
+clustering, issue-tracker writes, incident routing — belongs to the endpoint"
+(see the top of this doc), and the same split applies to a rerun: only the
+endpoint (or whatever runner it dispatches to) has cluster state and knows when
+a fix lands. That side owns its own sandbox — an execution environment with
+no path to a production credential, project, or deploy target. This CLI
+captures and transmits `provenance.repro.command`, and that is all it does
+with it.
+
+## Target-repo hints
+
+`--repo <owner/name>` names a repo this report concerns — repeatable, for a
+report that spans more than one. It exists so triage doesn't have to run a
+code search across the whole org before it can even clone a worktree: a Yaks
+report with no target-repo hint anywhere forces a manual `search_code` sweep
+just to find out where the problem lives.
+
+```
+eris yak issue --summary "…" --body "…" --repo acme/widgets
+eris yak issue --summary "…" --body "…" \
+  --repo acme/widgets --repo acme/widgets-api
+```
+
+**Auto-populated, always overridable.** When no `--repo` is given at all,
+`eris yak` derives one hint from the invoking process's own git remote — the
+same `origin` URL `provenance.git.origin_url` already carries for every
+submission (see [Discoverability](#discoverability) below for what that
+provenance gather already promises: best-effort, never a gate). An agent
+filing a yak from inside a repo checkout gets a hint for free; one filed from
+outside any checkout, or from a repo with no `origin` remote, simply carries
+none. Passing `--repo` at all — even a single one — always wins over the
+derived value; the two are never merged.
+
+The derivation understands nested namespaces (a GitLab-style
+`group/subgroup/project` derives in full, never truncated to just
+`subgroup/project`) and refuses outright on a local checkout — a `file://`
+origin or a bare filesystem path has no "owner" at all, and guessing one from
+trailing path components would be a plausible-looking but wrong hint, worse
+than none. An auto-derived hint also clears the same length bound an
+explicit one does; one that wouldn't is dropped rather than sent unbounded.
+
+**Not validated against a live repo list.** Like `repro`, a target-repo hint
+is opaque text this CLI carries through, never confirms. A typo'd or
+nonexistent repo name is exactly as harmless (and exactly as un-caught) as a
+typo'd `--repro` command — triage reads it, decides whether it's right, and
+moves on.
+
+**On the wire.** Like `repro`, this rides inside `provenance` rather than as
+a new top-level field on `YakSubmission` — the same non-breaking,
+forward-compatible reason (`YakSubmission` is the contract package's, and this
+CLI doesn't extend it). Unlike `repro`, it lands in the
+`provenance.repo` category the CLI already had (`provenance.repo.service`,
+the nearest `eris.yaml`'s declared service — see `plugins/yak/yak-context.ts`), as
+`provenance.repo.target_repos`, always an array even for a single hint. The
+contract types that one key and bounds it (at most 20 hints of at most 200
+chars each), the same limits this CLI checks locally first. It
+does not participate in the idempotency-key derivation, for the same reason
+`repro` doesn't: attaching or changing a target-repo hint should never fork a
+fresh cluster off a report that's otherwise identical, and the same
+repro-only-resubmission caveat in [Idempotency and
+replay](#idempotency-and-replay) applies here too — resubmitting the same
+`summary`/`body`/`evidence` with a different `--repo` dedupes as a replay,
+and the new hint is never stored or seen server-side.
+
+**Surfacing it on the rendered issue is the endpoint's work, not this CLI's.**
+Exactly the same split as everything after the receipt (see the top of this
+doc): this CLI captures and transmits `provenance.repo.target_repos`;
+rendering it into the issue belongs to the endpoint's issue-tracker write path.
+
+## What a receipt does not promise
+
+**A receipt is not a promise that an issue was created.** The endpoint accepts,
+stores, and deduplicates every well-formed submission — but it may also
+enforce an issue-creation ceiling per rolling window, and an observation
+deferred by that ceiling is still accepted and stored: it just doesn't (yet)
+become an issue. Whether `fatal` also pages anyone depends on how the
+endpoint is configured; the submission succeeds either way.
+
+In short: a `0` exit and a `recorded: <id>` line mean *the observation is
+durably stored and deduplicated*. They do not mean *a human has been paged* or
+*a ticket now exists*. If you need to confirm the latter, that's a question
+for the Yaks endpoint's own surfaces, not for this CLI's receipt.
+
+## Discoverability
+
+`eris yak --help` and this doc only help someone who already went looking for
+the verb. Teaching an agent that `eris yak` exists is the agent harness's
+job (a skill, a rule, or the project's agent instructions), not this CLI's.
+
+## Not built here
+
+`eris yak list` / `get`, an offline queue for a machine with no network,
+automatic/hook-triggered reporting, and any agentic triage of what gets
+reported — all deliberately out of scope for v1. Reading cluster state,
+detecting a fix-mark, dispatching a sandboxed repro rerun, and recording
+pass/fail are server-side work — see [Repro](#repro) above. Rendering the
+`--repo` hint(s) onto the issue is likewise server-side — see [Target-repo
+hints](#target-repo-hints) above.
+
+## See also
+
+- [OUTPUT-CONTRACT.md](OUTPUT-CONTRACT.md) — the stdout/stderr split, exit
+  codes, and the `--output json` machine surface this command participates in
+- [ERRORS.md](ERRORS.md) — every `yak-*` slug's `ERROR`/`fix`/`docs` heading
+- `eris login --help` — sign this machine in with a device code
+- `plugins/yak/yak-setup.ts --help` — mint this machine's bearer

package/docs/dev/ADDING-A-COMMAND.md

@@ -0,0 +1,79 @@
+# Adding a command to Eris
+
+A new subcommand of an existing group, or a new group. Every new verb is
+TypeScript. Read [DEVELOPMENT.md](DEVELOPMENT.md) first. A group that belongs to
+a product rather than to core is a plugin instead: [PLUGINS.md](PLUGINS.md).
+
+## A subcommand of an existing core group
+
+`completion` is the reference: its dispatcher is `src/cli/commands/completion.ts`
+and each shell is one file under `src/cli/commands/completion/`. Say you are
+adding `eris completion fish`:
+
+1. **Handler.** Create `src/cli/commands/completion/fish.ts`, and route to it
+   from the dispatcher's `groupArgs("completion", args)` switch.
+
+2. **Register it.** A `"completion fish": { summary, flags, pos, usage }` row in
+   `src/cli/registry.ts`. The handler reads its argv with
+   `readVerbArgs("completion fish", args, ctx, { help: USAGE })`
+   (`src/cli/args.ts`): the result's `flags` and `pos` are typed from the row, so
+   a flag the row does not declare can be neither passed nor read. The router
+   table, the `--output json` allow-list and the completion tree derive from the
+   row with no further edit (`tests/cli-router.test.ts` pins the derived table).
+   A positional with a completable domain says so on the same row
+   (`complete`, [COMPLETION.md](../COMPLETION.md#how-it-works)).
+
+3. **Output.** Payload on stdout, every diagnostic on stderr
+   ([OUTPUT-CONTRACT.md](../OUTPUT-CONTRACT.md)). A machine rendering means
+   `json: true` on the registry row and a line in the refusal's fix text
+   (`UNSUPPORTED_FIX_SURFACES`, `src/cli/output.ts`); never a per-command
+   `--json`. A machine surface is pinned in `tests/output-contract.test.ts` and
+   listed in the contract's surface table.
+
+4. **Safety.**
+   - A failure is a slugged block (`renderFailureBlock`, `ts/lib/eris-fail.ts`),
+     and every slug gets a `docs/ERRORS.md` heading (`tests/errors-doc.test.ts`).
+   - A subprocess goes through the runner in `src/runtime/process.ts` with a
+     deadline. Nothing is backgrounded; fan-out is bounded.
+   - A command a CI job runs completes without an answer.
+
+5. **Tests.** A red-first `bun test` file under `tests/`: the handler with
+   injected deps for logic, and a black-box run through `tests/helpers/blackbox.ts`
+   for the CLI surface ([TESTING.md](TESTING.md)).
+
+6. **Verify and document.**
+
+   ```bash
+   bunx tsc --noEmit && bun test ./tests
+   ./eris completion fish   # run it and read its real output
+   ```
+
+   Update the group's doc under `docs/`.
+
+## A new core group
+
+1. **Dispatcher** `src/cli/commands/<group>.ts`: the group usage, the sub switch
+   over `groupArgs("<group>", args)` (`bare` and `help` print usage on stdout and
+   exit 0), and an `Unknown <group> command: <x>` failure. One file per sub at
+   `src/cli/commands/<group>/<sub>.ts`, each reading its argv with `readVerbArgs`.
+
+2. **Register it.**
+   - A `<group>: { impl: "ts", summary }` row and one row per sub in
+     `src/cli/registry.ts`.
+   - A lazily imported entry in `HANDLERS` (`src/main.ts`);
+     `tests/cli-registry.test.ts` fails for a `ts` group without one.
+   - A line in `COMMANDS` (`src/cli/commands/usage.ts`), the top-level help. Its
+     `--output` paragraph is derived from the json rows.
+
+3. **Tests and docs.** Steps 3–6 above apply per sub. Add `docs/<GROUP>.md` and an
+   entry in [docs/README.md](../README.md).
+
+## Checklist
+
+- [ ] Registry rows (group and every sub, flags exact) and a `HANDLERS` entry
+- [ ] Lazy imports: `--help` works anywhere, with nothing configured
+- [ ] stdout carries only the payload; every failure is a slugged block with an `ERRORS.md` heading and nothing on stdout
+- [ ] A non-prompting path if CI-facing
+- [ ] Nothing backgrounded; any fan-out bounded
+- [ ] Red-first `bun test` coverage at the CLI seam; no network
+- [ ] `bunx tsc --noEmit` and `bun test ./tests` green

package/docs/dev/DEVELOPMENT.md

@@ -0,0 +1,88 @@
+# Developing Eris
+
+How the codebase is put together: the entrypoint, the router, the layers under
+it, and the conventions every change follows.
+
+Companion guides: [TESTING.md](TESTING.md) (the `bun test` suite),
+[ADDING-A-COMMAND.md](ADDING-A-COMMAND.md) (a new subcommand or group, end to end)
+[PLUGINS.md](PLUGINS.md) (a verb group as a build-time plugin) and
+[RELEASING.md](RELEASING.md) (cutting a release: the tag, the workflow, npm).
+
+## Setup
+
+```bash
+git clone https://github.com/sibylline-labs/eris && cd eris
+bun install --frozen-lockfile
+./eris --help
+```
+
+`./eris` runs the working tree as it stands; put the checkout on your `PATH` to call it as
+`eris`. There is no build step for the checkout. The gates:
+
+```bash
+bunx tsc --noEmit
+bun test ./tests
+ast-grep scan                          # rules/ over eris's own source
+ast-grep test --skip-snapshot-tests    # the rules' own cases, rule-tests/
+shellcheck -s sh -S warning eris
+bun scripts/build.ts && ERIS_BIN=dist/eris-<os>-<arch> bun test ./tests
+```
+
+The last line is the binary oracle: it compiles the binary and runs the same
+suite against it ([TESTING.md](TESTING.md#the-binary-oracle)).
+
+## The entrypoint and the router
+
+- **`eris`** is a POSIX `sh` shim. It finds bun, removes
+  `BUN_CONFIG_VERBOSE_FETCH`, and execs `bun --no-env-file --config=/dev/null
+  src/main.ts`. Its header lists its invariants.
+- **`bin/eris.ts`** is the same entry for an installed package (`bin` in `package.json`): a
+  `#!/usr/bin/env -S bun --no-env-file --config=/dev/null` shebang that refuses to run under
+  `BUN_CONFIG_VERBOSE_FETCH` and then calls `runProgram`. Run it as `bun bin/eris.ts` or directly
+  (`./bin/eris.ts`) to see what an `npx`/`bunx` user sees.
+- **`src/cli/registry.ts`** names core's verbs: one `REGISTRY` row per group, sub
+  and nested sub, carrying `impl` (`ts`), long flags with value arity, `json`
+  (has a machine rendering) and a summary.
+  **`src/cli/compose.ts`** merges them with the build's plugins
+  (`plugins/index.ts`). The router table, the `--output json` allow-list, the
+  shell completion tree and the top-level usage are derived from the composed rows.
+- **`src/main.ts`** routes each command line. A `ts` verb runs in-process behind
+  the global `--output` pre-pass; its handler is a lazily imported entry in
+  `HANDLERS` (core's, or a plugin's). Anything else is refused as an unknown
+  command.
+
+## Where things live
+
+| Path | Holds |
+|---|---|
+| `bin/` | `eris.ts`, the package's `eris` command ([ARCHITECTURE.md](../ARCHITECTURE.md#the-packages-bin)) |
+| `src/cli/` | The registry, composition, the plugin SDK, the router, argv parsing, the output allow-list, the TS route |
+| `src/cli/commands/` | Core's verbs: `completion` and the top-level usage |
+| `src/runtime/` | Logging, the subprocess runner, settings, env reads, the install root |
+| `ts/lib/eris-fail.ts` | The failure block and the WARN lines |
+| `plugins/` | The plugins this build composes (`plugins/index.ts`): `plugins/yak/` is `eris yak` |
+| `packages/` | Bun workspace packages (root `package.json` `workspaces`): `packages/yak-contract/` is the Yaks wire contract v2, which the root `exports` map also names as `eris/yak-contract`. A package imports only itself and what its own manifest declares, and `tests/yak-contract-v2.test.ts` holds that |
+
+## Conventions
+
+**The output contract binds every command** ([OUTPUT-CONTRACT.md](../OUTPUT-CONTRACT.md)).
+stdout carries the payload and nothing else; stderr carries every diagnostic;
+`--output json` is global and a command with no JSON rendering refuses it
+(`output-json-unsupported`). Never add a per-command output-format flag.
+
+**Failures are slugged.** A failure writes the block from `renderFailureBlock`
+(`ts/lib/eris-fail.ts`) to stderr and nothing to stdout. Every slug has a heading
+in [ERRORS.md](../ERRORS.md); `tests/errors-doc.test.ts` harvests slugs from the
+source and fails on one without.
+
+**Argv is read from the row.** A handler reads its flags and operands through the
+registry-driven parser (`readVerbArgs` in core, `readArgs` from the SDK in a
+plugin), never from argv by hand; the `adhoc-argv-parse` rule holds it.
+
+**Nothing is backgrounded to render progress, and fan-out is bounded.** A leaked
+descendant holding a capture pipe makes the reader wait forever. Subprocesses go
+through the runner in `src/runtime/process.ts` with a deadline; concurrency is
+capped by `ERIS_BATCH_CONCURRENCY` (`ts/lib/pool.ts`).
+
+**Every bun eris launches carries `--no-env-file --config=/dev/null`**, so a
+directory's `.env` and `bunfig.toml` never load.

package/docs/dev/LAYOUT.md

@@ -0,0 +1,74 @@
+# Source Layout
+
+The annotated tree of the eris repo. Read the part for the area you are editing.
+
+## Project Structure
+
+```
+eris                    # POSIX sh shim: unsets BUN_CONFIG_VERBOSE_FETCH, execs bun src/main.ts
+bin/eris.ts             # the package's `eris` command (package.json `bin`, for an npm or bun install): an
+                        #   `env -S bun --no-env-file --config=/dev/null` shebang, refuses BUN_CONFIG_VERBOSE_FETCH
+                        #   (eris-verbose-fetch-set), then runs src/main.ts's runProgram; tests/bin.test.ts
+package.json            # @sibylline-labs/eris: `bin`, `exports`, and `files`, the allow-list of what the npm
+                        #   tarball holds (tests/package.test.ts reads `npm pack --dry-run`)
+src/                    # The TS program the shim and the bin run
+├── main.ts             #   the entry: composes core with the build's plugins (CLI), HANDLERS, main, runProgram
+├── sdk.ts              #   `eris/sdk`, the one module through which another repository reaches core (package.json exports):
+│                       #   the plugin SDK, composition, runProgram, the runtime, build()
+├── build.ts            #   build(): compiles a distribution's entry into one binary (eris:assets, stubs,
+│                       #   the build id and release repository); scripts/build.ts calls it for this repo
+├── cli/registry.ts     #   core's verbs (subs, flags, impl, json); the derivations
+│                       #   (router table, json allow-list) every plane reads
+├── cli/compose.ts      #   core rows + plugin rows → table, allow-list, handlers, json fix text;
+│                       #   collision and completion-slot refusals; the menu option; entitlement locks
+├── cli/plugin.ts       #   the plugin SDK: the one core module a plugin imports
+├── cli/router.ts       #   the per-verb route, from the derived table
+├── cli/args.ts         #   the registry-driven argv parser and the global --output pre-pass
+├── cli/output.ts       #   the --output json allow-list and its refusal block
+├── cli/ts-verb.ts      #   runTsVerb: pre-pass → allow-list → lock → handler; eris-deps-not-installed
+├── cli/commands/       #   completion.ts + completion/ (emit.ts generates the bash/zsh script from the
+│                       #   composed registry; it imports the registry only, because every shell start
+│                       #   runs it; domain.ts checks a row's completion domains), usage.ts (the
+│                       #   top-level usage: bare eris, -h, --help), version.ts (--version),
+│                       #   update.ts (eris update: prints the npm commands), update/ (RELEASE_UPDATE,
+│                       #   the in-place verb a distribution opts into: opt-in.ts the row and thunk,
+│                       #   release.ts the verb, github.ts the releases API and the download,
+│                       #   replace.ts the staged rename and its restore, semver.ts)
+└── runtime/            #   logging, process (the one spawn adapter), settings (~/.eris/settings.json),
+                        #   env (readEnv), home (the install root: the checkout, a distribution's own root
+                        #   when its entry names one, or a compiled binary's
+                        #   per-build asset home)
+ts/lib/eris-fail.ts     # the ERROR/slug/fix/docs failure block, and the WARN lines
+ts/lib/pool.ts          # the bounded-concurrency runner process.ts's runMany uses
+plugins/index.ts        # the plugins this build compiles in, composed by src/main.ts (docs/dev/PLUGINS.md)
+plugins/yak/            # `eris yak` as a plugin: index.ts (the manifest: rows + handler thunks), handlers.ts
+                        #   (the dispatcher), yak.ts (the core), yak-{identity,context,redact,submit}.ts
+                        #   (yak-redact.ts imports nothing; package.json exports it as `eris/yak-redact`),
+                        #   login.ts (`eris login`/`logout`, the device-code client), yak-setup.ts (mints the bearer; docs/YAK.md); the wire contract is packages/yak-contract, imported by name
+packages/yak-contract/  # the Yaks wire contract v2, a bun workspace package that builds standalone;
+                        #   `eris/yak-contract` (package.json exports) is its src/index.ts.
+                        #   src/v2.ts (Zod + inferred types), scripts/emit-json-schema.ts →
+                        #   schema/yak-v2.schema.json (committed; `bun run emit-schema` in the package re-emits)
+skills/eris-yaks/       # SKILL.md: the agent skill that sets up Yaks (`npx skills add sibylline-labs/eris
+                        #   --skill eris-yaks`); the skills CLI discovers skills/<name>/SKILL.md
+examples/plugins/widgets/  # the worked plugin example tests/plugins.test.ts composes
+examples/distribution/  # the worked distribution: an entry importing eris/sdk alone, a demo plugin with a
+                        #   completion domain, a menu, and build.ts; tests/distribution.test.ts builds and runs it
+testing/                # `eris/sdk/testing` (package.json exports): the test helpers a distribution's suites
+                        #   reuse. fake-runner.ts (createFakeRunner), build-child.ts (buildInChild: build() in a
+                        #   child bun, from a module exporting BUILD). Outside src/, so no binary carries it
+scripts/build.ts        # `bun scripts/build.ts` → dist/eris-<os>-<arch> (gitignored): this repo's binary,
+                        #   through src/build.ts; exports its options as BUILD
+.github/workflows/      # ci.yml (the PR gates, the npm tarball's install-and-run included) · release.yml (tag → build, oracle, publish, npm)
+sgconfig.yml            # the code-quality rules over eris's OWN source (ruleDirs: rules; cases in rule-tests/):
+rules/                  #   adhoc-argv-parse (one argv parser), env-read-own-property(-plugin) (env names
+rule-tests/             #   are read through readEnv), plugin-manifest-lazy-handlers + plugin-imports-sdk-only
+                        #   (the plugin contract), distribution-imports-sdk-only (eris/sdk alone),
+                        #   runtime-imports-no-testing (the program never imports testing/),
+                        #   regex-no-lookbehind (the pinned bun interprets a lookbehind pattern)
+tests/                  # `bun test ./tests` — the whole suite. helpers/blackbox.ts drives the real
+                        #   `./eris` in a physical per-test sandbox (PATH fakes, hideReal); helpers/plugins/
+                        #   holds a tripwire plugin; helpers/release-fixture.ts is GitHub's releases API
+                        #   on loopback, for eris update
+docs/                   # ARCHITECTURE.md, OUTPUT-CONTRACT.md, ERRORS.md, the verb docs, dev/
+```