@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,2 @@
+eris
+Copyright 2026 Sibylline Labs

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# eris
 
-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.
+eris is a small, plugin-composed command-line tool written in TypeScript on
+[Bun](https://bun.sh). Core supplies the router, the verb registry, argument
+parsing, the output contract (`--output text|json`, slugged failure blocks)
+and shell completion; every verb group beyond that is a plugin composed in at
+build time.
+
+This build ships one plugin, `eris yak`, which AI coding agents (and people)
+use to file observations about their own tooling: a broken command, a
+misleading doc, a missing capability. A yak is redacted, given a dedup key and
+sent in one bounded request to a Yaks endpoint you configure. It never fails
+the task that filed it.
+
+## Install
+
+eris is published to npm as `@sibylline-labs/eris` and runs on Bun, which must be on
+PATH. npm is the only install path:
+
+```bash
+npx @sibylline-labs/eris@latest --help      # run the latest release, no install
+bunx @sibylline-labs/eris@latest --help     # the same, through bun
+bun add -g @sibylline-labs/eris@latest      # install `eris` globally
+```
+
+### From source
+
+You need Bun (the version in `.bun-version`) and git.
+
+```bash
+git clone https://github.com/sibylline-labs/eris && cd eris
+bun install --frozen-lockfile
+./eris --help
+```
+
+Put the checkout on your `PATH` to run it as `eris`. To build a standalone binary,
+run `bun scripts/build.ts`; it writes `dist/eris-<os>-<arch>`, which runs without Bun.
+
+### Version and updates
+
+```bash
+eris --version                      # eris v0.3.0 (sibylline-labs/eris)
+eris update                         # prints the npx / bunx / bun add -g commands for the latest release
+```
+
+`eris update` changes nothing: the package manager that installed eris updates it.
+[docs/UPDATE.md](docs/UPDATE.md) has the details.
+
+## Quickstart
+
+```bash
+eris --help                         # the commands this build composes
+source <(eris completion zsh)       # or bash; see docs/COMPLETION.md
+eris yak --help
+```
+
+### Filing a yak
+
+Sign in once with a device code. `eris login` shows a code to approve in the
+browser and writes the token to `~/.eris/yaks.json` (mode `0600`):
+
+```bash
+eris login
+```
+
+That signs in to `https://api.sibylline.group`. For another endpoint, pass
+`--url`, or configure it with environment variables:
+
+```bash
+export ERIS_YAKS_URL=https://yaks.example.com     # your Yaks endpoint
+export ERIS_YAKS_TOKEN=<bearer token>
+```
+
+Or, for a self-hosted endpoint without device login, mint a bearer into
+`~/.eris/yaks.json` from a checkout. The script prints the entry your endpoint's
+operator needs to register:
+
+```bash
+bun plugins/yak/yak-setup.ts --url https://yaks.example.com
+```
+
+Then file reports:
+
+```bash
+eris yak issue   --summary "completion fails on Alpine" --body "busybox sh lacks compgen"
+eris yak suggest --summary "a --dry-run for completion" --body-file notes.md
+eris yak fatal   --summary "eris exits before any verb runs" --body-file - < log.txt
+eris yak issue   --summary "…" --body "…" --repro "bun test tests/foo.test.ts" --repo acme/widgets
+eris --output json yak issue --summary "…" --body "…"    # one JSON record on stdout
+```
+
+A delivered yak prints `recorded: <id>`. A missing URL or token, an
+unreachable endpoint or a timeout prints a `WARN` line with its slug and still
+exits 0. Only misuse (a missing `--summary`, an over-long field, an unknown
+flag) exits 1. [docs/YAK.md](docs/YAK.md) has the full reference.
+
+### Agent skill
+
+[`skills/eris-yaks`](skills/eris-yaks/SKILL.md) is an agent skill that walks a coding agent
+through setting up Yaks for its user: running eris, the browser steps to connect Linear and
+create a token, a test yak, and the `AGENTS.md` block that teaches later sessions to file. Install
+it with the [skills](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+npx skills add sibylline-labs/eris --skill eris-yaks
+```
+
+## Writing a plugin
+
+A plugin is registry rows plus lazily loaded handlers, written against the SDK
+in `src/cli/plugin.ts`. Start with [docs/dev/PLUGINS.md](docs/dev/PLUGINS.md)
+and copy the worked example in [`examples/plugins/widgets/`](examples/plugins/widgets).
+A build's plugin list is `plugins/index.ts`.
+
+To ship your own binary with plugins of your own, write a distribution: depend
+on this repository, import `eris/sdk`, compose, and build with `build()`
+([docs/dev/PLUGINS.md#distributions](docs/dev/PLUGINS.md#distributions); the
+worked example is [`examples/distribution/`](examples/distribution)).
+
+## The Yaks wire contract
+
+[`packages/yak-contract`](packages/yak-contract) is `@sibylline-labs/yak-contract`:
+the Yaks submission contract v2 as Zod schemas, their inferred TypeScript
+types, and the JSON Schema they emit (`schema/yak-v2.schema.json`) for
+consumers in other languages. A repository that depends on this one (a git
+dependency pinned to a merge commit on `main`) imports the TypeScript contract
+as `eris/yak-contract`. The `eris yak` client in this build imports it and
+posts contract v2 submissions.
+
+The client's redaction pass, [`plugins/yak/yak-redact.ts`](plugins/yak/yak-redact.ts), is
+exported as `eris/yak-redact` (`redact`, `redactDeep`), so a server that redacts a submission
+before it commits runs the same rules. The module imports nothing.
+
+## Documentation
+
+[docs/README.md](docs/README.md) indexes the references: the architecture,
+the output contract every command follows, every error slug, and the
+developer guides.
+
+## Contributing and security
+
+We do not accept outside contributions; see [CONTRIBUTING.md](CONTRIBUTING.md).
+Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+
+## Licence
+
+Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/bin/eris.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env -S bun --no-env-file --config=/dev/null
+/**
+ * eris.ts — the `eris` command an install of this package links (package.json
+ * `bin`): `npm i -g`, `bun add -g`, `npx`, `bunx`.
+ *
+ * A checkout starts through the POSIX shim, `eris`. An installed package has no
+ * shell to run, so this file's shebang is the entrypoint, and it keeps the
+ * shim's invariants (the shim's header says why each exists):
+ *
+ *   - bun never reads the caller's cwd: `--no-env-file` stops it loading a
+ *     service dir's generated `.env`, and `--config=/dev/null` stops a cwd
+ *     `bunfig.toml` preload from running. A bare `#!/usr/bin/env bun` does
+ *     neither. `env -S` is what splits the flags out of one shebang line.
+ *   - BUN_CONFIG_VERBOSE_FETCH never reaches a fetch. The shim removes it
+ *     before bun starts; this file refuses to run under it
+ *     (`eris-verbose-fetch-set`) rather than print a bearer token.
+ *   - The install root is the package: src/runtime/home.ts resolves it from its
+ *     own location, so the symlink an install links this file under changes
+ *     nothing. Only the shim sets `_ERIS_SHIM_DIR`, so a stray value in the
+ *     caller's environment is removed before the program reads it.
+ *
+ * `src/main.ts` runs itself only when it is the entry, so this calls
+ * `runProgram`. The refusal comes first and `src/main` is imported after it:
+ * nothing of the program is evaluated under the variable.
+ *
+ * tests/bin.test.ts pins each of these.
+ */
+
+import { reportFailure } from "../ts/lib/eris-fail";
+
+if (process.env.BUN_CONFIG_VERBOSE_FETCH !== undefined) {
+  // Not `process.exit`: the exit code is set and the stream left to drain, as src/main.ts does.
+  process.exitCode = reportFailure({
+    slug: "eris-verbose-fetch-set",
+    what: "BUN_CONFIG_VERBOSE_FETCH is set — under it bun prints every fetch, Authorization bearer and body included, to stderr",
+    fix: "unset BUN_CONFIG_VERBOSE_FETCH, or run: env -u BUN_CONFIG_VERBOSE_FETCH eris <command>",
+  });
+} else {
+  delete process.env._ERIS_SHIM_DIR;
+  const { runProgram } = await import("../src/main");
+  runProgram();
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,188 @@
+# Eris architecture
+
+The current-state map: what eris is made of, what calls what, and the constraints any change has to
+survive. A claim here that no longer resolves against the tree is a bug in this file; fixing it
+belongs to the change that moved the code.
+
+---
+
+## 1. What eris is
+
+Eris is a TypeScript program run by bun, behind a POSIX `sh` shim: a small core (the router, the
+verb registry, the output contract, the plugin host and its SDK, shell completion and the top-level
+usage) plus the plugins a build composes in. This build's plugin is `eris yak`
+([YAK.md](YAK.md)).
+
+- **`eris`** finds bun and execs `src/main.ts`. Nothing else.
+- **`bin/eris.ts`** is the same entry for an installed package: the `eris` command that `npm i -g
+  @sibylline-labs/eris`, `bun add -g`, `npx` and `bunx` link (`bin` in `package.json`). It starts under bun
+  through its shebang and calls `runProgram`.
+- **`src/main.ts`** routes every command line.
+- **`plugins/index.ts`** lists the plugins this build compiles in.
+- **`src/sdk.ts`** is `eris/sdk`, the one module through which another repository reaches core
+  (the `exports` map names `eris/sdk/testing`, `eris/yak-contract` and `eris/yak-redact` beside it,
+  nothing deeper).
+  A **distribution** depends on this package, composes core with this build's plugins and its own,
+  and compiles its own binary with `build()` ([`dev/PLUGINS.md`](dev/PLUGINS.md#distributions)).
+- **`packages/yak-contract`** is the Yaks wire contract v2, a bun workspace package that builds
+  standalone. The `exports` map also names it, as `eris/yak-contract`, so a repository pinned to
+  this one imports the contract without core.
+
+eris installs from npm only (`npx`, `bunx`, `bun add -g @sibylline-labs/eris`); the package's
+`bin/eris.ts` is the command. A checkout needs `bun install --frozen-lockfile` and no build step:
+`bash <checkout>/eris` and `sh <checkout>/eris` run it as it stands.
+
+`bun scripts/build.ts` also compiles the same program into one executable,
+`dist/eris-<os>-<arch>`, through `build()` (`src/build.ts`), the same call a distribution makes
+with its own entry. It carries the docs the source names and writes them once per
+build to `${ERIS_CACHE_DIR:-${XDG_CACHE_HOME:-~/.cache}/eris}/<build id>/`, its install root
+(`src/runtime/home.ts`), so a failure block's `docs:` line names a file that exists.
+
+A binary also knows which build it is, from the same call: `build({ tag })` bakes the version,
+the release repository, an optional version line and the docs base of a failure block
+(`VERSION` and `identity()`, `src/runtime/home.ts`); a distribution run from source hands the
+same identity to `runProgram({ identity })`, and a binary keeps what its build baked. `eris --version`
+prints them. Core's `eris update` (`src/cli/commands/update.ts`) prints the npm commands for the
+latest release. A distribution that publishes binaries composes `RELEASE_UPDATE`
+(`src/cli/commands/update/`) in its place, which replaces the binary with the newest release of
+its own repository, after checking it ([`UPDATE.md`](UPDATE.md)). The release is cut by
+`.github/workflows/release.yml`, which builds and tests both binaries, publishes them with a
+`SHA256SUMS`, and publishes the package to npm
+([`dev/RELEASING.md`](dev/RELEASING.md)). The npm package is the source, run by bun: `exports` and
+`bin` name `.ts` files, and `files` in `package.json` is the allow-list of what the tarball holds
+(`tests/package.test.ts`).
+
+---
+
+## 2. The layers, as built
+
+```
+  eris                        POSIX sh shim: unset BUN_CONFIG_VERBOSE_FETCH; exec bun src/main.ts
+  bin/eris.ts                 the npm bin: refuse BUN_CONFIG_VERBOSE_FETCH; runProgram()
+   └─ src/main.ts             settings fill → route → handler (lazy import) | unknown
+       ├─ src/sdk.ts          eris/sdk: what a distribution imports · src/build.ts: build()
+       ├─ src/cli/            registry.ts (core's verbs) · compose.ts (core + plugins) · plugin.ts
+       │                      (the SDK) · router.ts · args.ts (argv + the global --output pre-pass)
+       │                      · output.ts (the json allow-list) · ts-verb.ts
+       ├─ src/cli/commands/   completion/ · usage.ts · version.ts · update.ts + update/
+       ├─ src/runtime/        logging · process · settings · env · home
+       ├─ ts/lib/eris-fail.ts the failure block
+       └─ plugins/            index.ts (the build's list) · yak/
+```
+
+### The shim
+
+`eris` is POSIX `sh` because consumers run it as `bash eris`, `sh eris` and `exec <repo>/eris`. It:
+
+- removes `BUN_CONFIG_VERBOSE_FETCH` before bun starts. Under it bun prints every fetch, bearer and
+  body included, to stderr, and bun reads it from its own environment at fetch time, so
+  `delete process.env.X` inside `src/main.ts` cannot turn it off;
+- refuses a missing bun with the `eris-bun-missing` failure block, rendered by the shim itself;
+- execs `bun --no-env-file --config=/dev/null src/main.ts`, so bun never loads a service
+  directory's generated `.env` or runs a cwd `bunfig.toml` preload;
+- exports nothing. It hands the router its logical directory through `_ERIS_SHIM_DIR`, which
+  `src/main.ts` removes before anything is spawned.
+
+`tests/cli-shim.test.ts` pins each of these.
+
+### The package's bin
+
+`bin/eris.ts` is what an install links as `eris`. It has no shell to run, so its shebang,
+`#!/usr/bin/env -S bun --no-env-file --config=/dev/null`, does what the shim's `exec` does: bun never
+reads the caller's cwd `.env` or `bunfig.toml` preload. A bare `#!/usr/bin/env bun` does neither, so
+`npx eris` run in a service directory would load that directory's `.env` and run its preload.
+`env -S` splits the flags out of the one shebang line (GNU coreutils 8.30 and newer, macOS).
+
+The bin does not remove `BUN_CONFIG_VERBOSE_FETCH`; it refuses to run under it, with the
+`eris-verbose-fetch-set` failure block, before it imports the program. With bun absent the operating
+system's own `env: bun: No such file or directory` is the diagnostic; there is no `eris-bun-missing`
+block, because nothing of eris has started to print one. The install root is the package directory,
+whatever symlink the install put the bin behind. `tests/bin.test.ts` pins each of these.
+
+### The router
+
+`src/cli/registry.ts` `REGISTRY` has a row per group, sub and nested sub: `impl` (`ts`; a sub
+inherits its group's), long flags with value arity, `json`, and a summary. From it
+are derived:
+
+- the router table (`src/cli/router.ts`, `deriveTable`): every group, empty argv, `-h`, `--help`,
+  and a `"group sub"` key where a sub's impl differs from its group's (the longer key wins);
+- the `--output json` allow-list (`src/cli/output.ts`);
+- the shell completion tree (`src/cli/commands/completion/emit.ts`);
+- every TS verb's argv parse (`src/cli/args.ts`): `readVerbArgs` accepts exactly the row's flags
+  and `pos` operands, refuses anything else uniformly, and types the handler's args from the row.
+
+The registry those planes read is core's rows composed with the build's plugins
+(`src/cli/compose.ts`, over the list in `plugins/index.ts`): a plugin is rows plus lazily loaded
+handlers, written against the SDK `src/cli/plugin.ts`, composed at build time, with collisions, a
+non-`ts` row and a json group with subs refused, and a group whose product the workspace has not
+bought locked per command line. [`dev/PLUGINS.md`](dev/PLUGINS.md).
+
+A `ts` route runs the composed handler for the verb (`HANDLERS` in `src/main.ts`, plus each
+plugin's), imported lazily, behind the global `--output` pre-pass. A command line whose verb is not in the table is refused by the router as an unknown
+command. Adding or flipping a verb is a registry edit; `tests/cli-registry.test.ts` and
+`tests/cli-router.test.ts` hold the rows against `HANDLERS`.
+
+`runTsVerb` (`src/cli/ts-verb.ts`) turns a package that cannot be resolved into the
+`eris-deps-not-installed` block, read from the error's `code` and `specifier`. Nothing on the path
+`src/main.ts` → `src/cli/ts-verb.ts` → `src/cli/output.ts` may import a third-party package, or that
+block cannot be reached.
+
+The top-level usage (`src/cli/commands/usage.ts`) is a `HANDLERS` row too: bare `eris`, `-h` and
+`--help` all print it. `--version` is the fourth argv shape (`ARGV_SHAPES`, `src/cli/registry.ts`):
+it is not a verb, but it renders JSON under `--output` and reads no file from the install root.
+
+---
+
+## 3. Dependency direction
+
+- **A plugin imports the SDK and nothing else of core.** `src/cli/plugin.ts` is the one core module
+  under `plugins/` may import (`plugin-imports-sdk-only`, in `rules/`).
+- **A distribution imports `eris/sdk` and nothing else of core.** The `exports` map refuses a
+  deeper path; `distribution-imports-sdk-only` holds the example distribution to it. Its suites
+  may also import `eris/sdk/testing` (`testing/`), which no source the binary bundles imports
+  (`runtime-imports-no-testing`). `eris/yak-contract` is not core: it is the workspace package
+  `packages/yak-contract`, which imports nothing of core (`tests/yak-contract-v2.test.ts`).
+  `eris/yak-redact` is `plugins/yak/yak-redact.ts`, the client's redaction pass, so a server that
+  redacts a submission runs the client's rules; it imports nothing (`tests/distribution.test.ts`).
+- **Completion imports the registry and nothing else.** `source <(eris completion bash)` runs on
+  every shell start, so a broken source file elsewhere must not break a login shell.
+  `tests/completion.test.ts` corrupts every other verb and every plugin's handler code in a copied
+  tree and asserts byte-identical emission. Plugin rows reach completion through their manifests,
+  which import nothing but the SDK (`plugin-manifest-lazy-handlers`); `tests/plugins.test.ts`
+  composes a plugin whose handler module throws on evaluation and completes past it.
+- **Only `src/runtime/process.ts` spawns.** Argv arrays only, an explicit
+  timeout, and the whole tree killed on expiry.
+
+---
+
+## 4. Constraints
+
+**C1 — `bash <checkout>/eris` runs from a git checkout with no build step**, with bun at
+`.bun-version` and `bun install --frozen-lockfile`.
+
+**C2 — the output contract and the error slugs are stable.** The failure block
+(`ts/lib/eris-fail.ts`, one `### <slug>` heading per slug in [`ERRORS.md`](ERRORS.md),
+harvested by `tests/errors-doc.test.ts`); exit `1` = failure and `2` = idempotent no-op; stdout
+carries the payload and nothing else. Stated in [`OUTPUT-CONTRACT.md`](OUTPUT-CONTRACT.md) and pinned
+by `tests/output-contract.test.ts`.
+
+**C3 — `eris completion` emits without loading any other verb**, and its output is
+byte-deterministic for a given composed registry. A row's completion domain is data on the row:
+its helper text is checked at composition (`src/cli/commands/completion/domain.ts`) so sourcing
+the script runs nothing and no helper can swallow core's text.
+
+**C4 — the shell only shrinks.** The shim is frozen as one total (`.sh` files,
+code lines, function definitions) by `tests/source-is-text.test.ts` against
+`tests/fixtures/ratchet-baseline.json` `FREEZE`. Growth fails; a shrink fails until the baseline is
+lowered in the same change, so freed room is never re-spent. The same file bans the quadratic
+`${v//pattern/repl}` blank test in that shell. New logic goes to TypeScript.
+
+---
+
+## See also
+
+- [`OUTPUT-CONTRACT.md`](OUTPUT-CONTRACT.md): what eris guarantees to a program.
+- [`dev/ADDING-A-COMMAND.md`](dev/ADDING-A-COMMAND.md): adding a verb behind the registry.
+- [`dev/PLUGINS.md`](dev/PLUGINS.md): adding a verb group as a build-time plugin.
+- [`ERRORS.md`](ERRORS.md): the error-slug catalogue.