@north-light/cli 0.0.0-stage → 0.3.413

package/dist/builtin-memory/internal/plugins.md

@@ -0,0 +1,457 @@
+---
+kind: knowledge
+when-and-why-to-read: When creating a crtr plugin, packaging documents for distribution, adding top-level CLI commands via a command manifest, or debugging install/resolution, this knowledge should be read so installs resolve predictably across scopes and command surfaces do not fail from manifest drift or protocol mistakes.
+short-form: How to author a crtr plugin — plugin.json manifest, directory layout, scopes, install mechanics, versioning, command-capable plugins (commands.json plus an exec or HTTP transport), bare binaries (`bin`) a plugin or scope puts on every node's PATH, scope-configured human completion actions (`humanActions`), and advisory external executable requirements (`requires`). Use when creating a plugin, packaging documents, contributing commands or executables, or debugging install/resolution.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# Authoring crtr plugins
+
+A **plugin** is a directory shipping documents (knowledge and preferences) in its `memory/` folder, plus other content like `rules/` and `agents/`, and optionally commands. Plugins are how you package that content for sharing across machines, projects, and people. An installed plugin is an **app** on the canvas (`app:<plugin>`) and owns the documents it ships (the object model is in [[internal]]). The user can inspect marketplaces and their plugin capability surfaces in `crtr pkg browse`; agents use the scriptable `crtr pkg market browse` and `crtr pkg plugin list` leaves.
+
+Audience: LLM agents creating or maintaining a crtr plugin.
+
+## When you need a plugin (vs documents a person or repo owns)
+
+A document you write at runtime is an object created with `crtr doc write`, owned by a node, the person, a profile, an app or a repo (`--owner`), and kept in the canvas database. A plugin's documents are different: they ship as markdown **files** in its `memory/` folder and belong to the plugin's app. They are public, read-only to everyone, and change only when the plugin is updated.
+
+Each file under `memory/` becomes one such document. Its path below `memory/`, without `.md` and without any `NN-` ordering prefix, is the document's name, read as `crtr canvas read <plugin>/<name>`. When the daemon starts, and after a plugin install or update, it reconciles the files into document objects: the body comes from the file, and a changed file becomes a new revision that its watchers see as an edit.
+
+### The package-file format
+
+The frontmatter of a `memory/` file is the **package-file format**, not the `crtr doc write` flag set. It is validated at install and update (`src/core/graph/package-files.ts`) and then **converted** into document fields and rules on import (`src/core/graph/package-docs.ts`, `rulesFromFrontmatter`). Do not author `preview:` or `delivery:` keys; they are not part of this format.
+
+| Frontmatter key | Becomes |
+|---|---|
+| `kind` (required) | the document kind, `knowledge` or `preference` |
+| `when-and-why-to-read` (required) | the document's preview — "When <situation>, this <kind> should be read because <what the reader gains>" |
+| `short-form` | the summary shown in `crtr canvas list` |
+| `rationale` | why-it-exists (visible with `crtr canvas read --fields`) |
+| `surfaces` — a list of `{on, at, match?, match-frontmatter?, gate?}` | one rule per entry. `on`: `boot`, `workspace-open`, `read` (→ `file-read`), `memory-read` (→ `document-read`), `command`, `pre-command`; `at`: `name`, `preview`, `content` (→ `deliver`); `gate` → the rule's `if` |
+| `gate` | a node-eligibility predicate ANDed into every rule's `if` |
+| `slash: true` | a `slash-command` rule delivering the content |
+| `unlisted`, `privacy`, `lint-ignore`, `extensions` | the document fields of the same names (a package document is always public and shipped) |
+| `name` | an explicit local name, instead of one derived from the path |
+
+Delivery semantics (events, levels, `if`) are the rule model in [[internal/memory-loading]]; `crtr doc write --rule -h` documents the rule JSON the converted rules take. The loader's `lint-ignore` accepts `length`, `broad-memory-read` and `orphan` and records it on the document, but `crtr doc lint` never checks package documents (see the end of this page), so it suppresses nothing there. A file whose frontmatter fails validation blocks install and update.
+
+File naming decides the document name: a directory's `INDEX.md` is the document named for the directory (reading it lists the names under it), a package-root `INDEX.md` is `index`, and a leading `NN-` ordering prefix is stripped from every segment (`04-orchestration-kernel.md` is `orchestration-kernel`). Renaming or moving a file changes the document's name, and `[[links]]` to the old name stop resolving.
+
+Reach for a **plugin** when:
+- You want to share documents across multiple projects or with other people.
+- You want versioning + update mechanics (`crtr pkg plugin update --name <name>`).
+- You want a marketplace to index the work — see [[internal/marketplaces]].
+
+If it's a one-off note for yourself, a document you own (`crtr doc write --owner user|repo`) is simpler. Promote to a plugin later.
+
+## Directory layout
+
+```
+<plugin-name>/
+├── .crouter-plugin/
+│   └── plugin.json                  # manifest — required
+└── memory/
+    ├── <name>.md                    # a package-format document (kind: knowledge or preference)
+    └── <area>/
+        ├── INDEX.md                 # optional; becomes the document named for the directory, and reading it lists the names under it
+        └── <name>.md
+```
+
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `hooks/`) hold the other kinds of plugin content. A plugin that contributes CLI commands adds a `commands.json` manifest plus a `transport` declaration — see [Plugin commands](#plugin-commands).
+
+## The manifest
+
+`.crouter-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "One sentence — shown in `crtr pkg plugin list`.",
+  "source": "https://github.com/<owner>/<repo>",
+  "owner": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  }
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Must match the directory name. Lowercase kebab. |
+| `version` | yes for authored plugins | Semver. Marketplace CI may bump automatically; archive installs synthesize a 12-character content identifier. |
+| `description` | yes | One sentence. |
+| `source` | recommended | Human-facing URL where the plugin lives. Source-installed plugin updates derive provenance from their checkout or marketplace registration, not this descriptive field. |
+| `owner` | optional | Author info. |
+| `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. It must appear with `transport`; together they make the plugin contribute `crtr` commands — see [Plugin commands](#plugin-commands). |
+| `transport` | optional | Required exactly when `commands` is present. `{ "kind": "exec", "executable": "bin/cmd.js" }` runs executable leaves; a passthrough-only exec manifest may omit `executable`. `{ "kind": "http", "endpoint": "https://…", "authEnv": "TOKEN_NAME" }` calls a remote HTTP command surface. Archive-installed plugins also carry crouter-synthesized `bundle` provenance; authors do not add it. |
+| `page_components` | optional | Page-component contributions: an array of the same registrations a scope `config.json` `page_components` block carries. See [Plugin page components](#plugin-page-components). |
+| `bin` | optional | Bare-callable executables the plugin ships, as `{"<bare-name>": "<plugin-relative path>"}`. Each becomes callable by bare name from any node's bash — no `crtr` command, no protocol. See [Bare binaries on the node PATH](#bare-binaries-on-the-node-path). |
+| `requires` | optional | Advisory external executables the plugin needs, as `{"<bare-name>": "one-line install hint"}`. crouter never installs them or disables the plugin when absent: install warns and Doctor reports the hint. See [External executable requirements](#external-executable-requirements). |
+| `env` | optional | App-scoped env names the plugin needs. Each name maps to a required `description`, optional `required` and `secret` (both default `true`), and optional `url` for obtaining the value. `CRTR_*` and `HOME` are reserved. Malformed declarations fail install; missing values warn but never block install. |
+| `kinds` | optional | Kind-registry contributions, keyed by full kind string — the same rule a scope `config.json` `kinds` block follows: each entry is any subset of `KindConfig` fields (`whenToUse`, `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`). It field-merges over a kind a lower layer already defines — `whenToUse` included, so overriding just the spawn guidance never strips the kind's model tier — and defines a new kind when none does (then `whenToUse` is required). See [Plugin kinds](#plugin-kinds). |
+| `memory_extensions` | optional | Typed plugin-owned metadata declarations for document `extensions` fields. The manifest name owns the namespace; see [Plugin-owned document metadata](#plugin-owned-document-metadata). |
+
+## Plugin credentials
+
+A local plugin runs as its caller's app, with no plugin identity or home of its own. Its credentials belong in that app's daemon-managed env store (`/runtime/secrets/env/<app>/_app`), not a file under `HOME`; the app home is for dotfiles and tool configuration. Model vendor credentials belong only to the daemon's `/runtime/secrets/auth.json`, and a crouter cloud provider's vendor keys belong to its deployment config. A profile's env store overlays the app layer when that profile belongs to the launched app. Crtr-constructed launch values win last.
+
+```json
+"env": {
+  "EXA_API_KEY": {
+    "description": "Exa API key used for every exa-search call.",
+    "required": true,
+    "secret": true,
+    "url": "https://dashboard.exa.ai/api-keys"
+  }
+}
+```
+
+On a TTY, `crtr pkg plugin install` and update prompt for required declared names missing from the app store (hidden input for secrets); without a TTY they warn with `crtr sys env set --name NAME`. Doctor reports an `env:<NAME>` check for each enabled plugin's required name. `crtr sys env set --name NAME` reads from stdin; `list` returns only names. A running node picks up changes on its next revive. Use `crtr profile env` for a profile-specific override. Never derive the person's key location from the calling process's `homedir()` — an agent's HOME is its app home.
+
+## Plugin-owned document metadata
+
+A plugin can declare typed metadata that crouter validates and carries without teaching the core document schema what the metadata means. The manifest key keeps its name, `memory_extensions`, and each value is a document's `extensions` field. This keeps routing, loading, listings, and agent delivery governed only by core frontmatter while a plugin's own product surfaces interpret its fields.
+
+Declare fields in the optional `memory_extensions` manifest addendum. The manifest's exact `name`, not a configurable declaration value or installation path, is always the namespace:
+
+```json
+{
+  "name": "acme",
+  "memory_extensions": {
+    "visibility": {
+      "type": "boolean",
+      "default": true,
+      "write_help": "Control whether this document appears in the acme app's human document surfaces.",
+      "edit_help": "Change whether this document appears in the acme app's human document surfaces."
+    }
+  }
+}
+```
+
+Each addendum is a nonempty object keyed by lowercase kebab-case local field names. A declaration has no keys beyond these:
+
+| Key | Required | Contract |
+|---|---|---|
+| `type` | yes | `boolean`, `string`, `number`, or `enum`. |
+| `values` | enum only | A nonempty, unique list of nonempty strings. It is invalid for every other type. |
+| `default` | no | A value matching `type`; an enum default must be one of `values`. |
+| `write_help` | yes | Nonblank single-line text generated into the field catalog on `crtr doc write -h`. |
+| `edit_help` | yes | Nonblank single-line text generated into the field catalog on `crtr doc edit -h`. |
+
+The generated catalogs show each installed field's full path, type (or enum alternatives), and default when declared. They are the maintained authoring surface; the addendum is their sole help source. Read those leaves for the set, change, and unset mechanics.
+
+Document values live under `extensions.<plugin-name>.<field>` — in a package file's frontmatter, or the `--extension <plugin>.<field>=<json>` flag of `crtr doc write` — never beneath a `properties` layer. In frontmatter:
+
+```yaml
+extensions:
+  acme:
+    visibility: false
+```
+
+`extensions` and each namespace must be mappings. Values may only be strings, booleans, or finite numbers; a declared field then must satisfy its own type, and an enum must be one of its declared strings. A plugin can declare only fields in its own manifest-name namespace. Two plugins can use the same local field name because their namespaces remain distinct.
+
+A default is interpretation, not persistence: an absent declared field resolves to its default only in the effective metadata projection and is never written back into frontmatter. `crtr canvas read --fields` exposes exactly the explicit raw mapping. Structured `crtr --json canvas read` and `crtr --json canvas list --type document` expose only effective, valid metadata in `extensions`, overlaying explicit values on enabled declarations' defaults. Ordinary read and list rendering deliberately omit the metadata, and crouter never injects it into a document body or agent-facing document render.
+
+Crouter maintains separate declaration views for validation and interpretation. Validation and generated authoring help use the closest installed declaration even when its plugin is disabled, so an existing value remains type-checked and can be changed or removed. Effective structured metadata uses only the winning enabled declaration. Therefore disabling a plugin leaves its raw frontmatter in place but omits that namespace and its defaults from effective output; it has no crouter behavior of its own. If the owner is removed or cannot resolve, the namespace is raw-only and inert, lint reports it as unresolved, and unrelated core-frontmatter edits preserve it. Re-enabling or reinstalling the owner restores explicit values and defaults to effective interpretation without rewriting the document.
+
+Archive plugins declare the identical addendum in `bundle.json` beside `bundleVersion`:
+
+```json
+{
+  "bundleVersion": 1,
+  "memory_extensions": {
+    "visibility": {
+      "type": "boolean",
+      "default": true,
+      "write_help": "Control whether this document appears in a human-facing view.",
+      "edit_help": "Change whether this document appears in a human-facing view."
+    }
+  }
+}
+```
+
+The archive validator applies the same closed declaration contract and copies the accepted block into the synthesized installed `plugin.json`; archive and source plugins therefore present one installed declaration model.
+
+`crtr doc lint` validates extension mappings and reports malformed mappings, unresolved namespaces, undeclared fields, non-scalar values, wrong types, and invalid enum values at their field paths. Installation and every update validate the candidate declaration plus every candidate `memory/**/*.md` document against the shared core-frontmatter and extension contracts before activation. The candidate's own declaration governs its package while it is checked, including when it changes or removes a declaration present in the installed version. Candidates are staged outside active plugin paths and replace the active package only after validation; a failed source, archive, or marketplace candidate never becomes reachable through an active plugin path, and the previous package and recorded version remain active.
+
+## Plugin kinds
+
+A plugin can ship a complete persona kind: declare the registry entry in the manifest's `kinds` block, and author the persona prose as ordinary plugin documents with the rule `{on: boot, if: {kind: <name>, mode: base}, deliver: content}` (and one with `if: {kind: <name>, mode: orchestrator}`) — the same shape a builtin kind uses at `kinds/<kind>/00-base.md`. Nothing else is needed: `if` conditions evaluate uniformly over plugin documents, so the persona splices into any node launched with that kind.
+
+`readMergedLaunchConfig` layers an enabled plugin's `kinds` entries directly above the builtin registry and below its host scope's own `config.json` — full precedence: builtin → user-scope plugins → user config → profile → per project root (that root's plugins → that root's config). So a plugin kind appears in `crtr node new -h` and is launchable like any other, and a user or project `config.json` can still patch or shadow it. Plugins within one scope layer name-sorted; the scope's own config always wins.
+
+For archive plugins the declaration lives in the archive's `bundle.json` — `{"bundleVersion": 1, "kinds": {…}}` — and the installer copies the block into the synthesized manifest. Install validates the block strictly (an invalid entry fails the install with per-entry reasons); the read side drops invalid entries silently, so the loud gate is install time.
+
+## Plugin page components
+
+A plugin can make product page components authorable: declare them in the manifest's `page_components` array, each entry a kind string or `{kind, description?, useWhen?, doc?, display?}` — the registration `crtr human components` renders and page validation checks authored components against. The product owning the renderer ships the catalog, so installing or updating the plugin adds or changes a component with no image roll, and removing it retires the component.
+
+`resolvePageComponents` concatenates the user scope's own `config.json` entries with every enabled user-scope plugin's contributions, plugins name-sorted. Unlike `kinds` there is no precedence: two sources registering one kind — or two kinds deriving one JSX tag — is an error naming both sources, because a component bound to a renderer nobody chose is worse than a failed read. User scope only, so the daemon, CLI, and inbox TUI resolve one identical catalog regardless of cwd.
+
+For archive plugins the declaration lives in the archive's `bundle.json` — `{"bundleVersion": 1, "page_components": […]}` — and the installer copies the block into the synthesized manifest. Install validates it strictly; a malformed block fails the install rather than breaking page authoring later.
+
+## Scopes
+
+A plugin can live in either scope:
+
+| Scope | Path | Use case |
+|---|---|---|
+| user | `~/.crouter/plugins/<name>/` | Personal, available in all your projects |
+| project | `<project>/.crouter/plugins/<name>/` | Pinned to a specific repo — checked in or vendored |
+
+Project-scope plugins outrank user-scope on resolution. Both outrank marketplace-installed plugins. The builtin `crtr` plugin (ships with the CLI) sits at the bottom.
+
+## Install mechanics
+
+Four ways a plugin lands in a scope:
+
+1. **From a git URL** (`crtr pkg plugin install <url> --scope user`):
+   - Clones into `<scope>/plugins/<name>/` using the manifest's name.
+   - `crtr pkg plugin update --name <name>` does `git pull`.
+   - Independent of any marketplace.
+
+2. **From a marketplace** (`crtr pkg plugin install <mkt>/<name>`):
+   - A marketplace-relative `source` is symlinked from the marketplace checkout; a remote Git `source` is cloned into `<scope>/plugins/<name>/`.
+   - `crtr pkg market update --name <mkt>` refreshes the marketplace and every installed plugin it sources; relative sources follow the checkout, while remote-source checkouts pull their own Git remote.
+   - See [[internal/marketplaces]].
+
+3. **From an HTTP directory archive** (`crtr pkg plugin install --endpoint <url> --name <name> --scope user`):
+   - Fetches one authenticated uncompressed `application/x-tar` archive containing `bundle.json`, `commands.json`, `memory/**/*.md`, and optionally `hooks.json` plus `hooks/**`. crouter validates every member before writing, then materializes the complete package with a synthesized `.crouter-plugin/plugin.json`. The endpoint must use `https:`; `http:` is accepted only for `localhost`, `127.0.0.1`, `[::1]`, `::1`, or `host.docker.internal`, with no credentials or fragment.
+   - The synthesized `bundle` field records the archive endpoint and optional credential variable name for installs and updates. Its distinct `transport` field records the archive endpoint's origin for command invocation. crouter stores the environment variable name, never its token.
+   - Reinstalling a bundle plugin replaces commands and documents together. Fetch or validation failure leaves the prior package intact. A commands-only HTTP plugin predating this archive contract must be removed and reinstalled.
+
+4. **Authored in place** (you're writing the plugin in a working repo):
+   - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
+   - Or `crtr pkg plugin install file://$(pwd) --scope project` to clone-install.
+
+## Local development loop
+
+```bash
+# Scaffold dir + manifest + first doc
+mkdir -p my-plugin/.crouter-plugin my-plugin/memory
+$EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
+cd my-plugin
+$EDITOR my-plugin/memory/my-first-doc.md           # author the doc in the package-file format above
+
+# Symlink for fast iteration — no clone, edits land immediately
+ln -s $(pwd) ~/.crouter/plugins/my-plugin
+
+# Verify
+crtr pkg plugin list                       # my-plugin appears
+crtr pkg plugin show my-plugin             # lists its documents
+crtr canvas read my-plugin/my-first-doc            # resolve it under the plugin's name
+crtr sys doctor                                    # validates the manifest
+# `crtr doc lint` skips package documents; install-time validation checks their frontmatter
+```
+
+When ready to share: push to a git remote; anyone can `crtr pkg plugin install <url> --scope user`.
+
+## Versioning
+
+Standard semver:
+
+| Change | Bump |
+|---|---|
+| Typo, wording polish | patch (0.1.0 → 0.1.1) |
+| New doc, new section, new example | minor (0.1.0 → 0.2.0) |
+| Removed doc, renamed doc, changed manifest schema | major (0.1.0 → 1.0.0) |
+
+`crtr pkg plugin update --name <name>` pulls source updates for ordinary plugins, including source-installed plugins whose command transport is HTTP. An archive plugin instead re-fetches its recorded `bundle` endpoint and replaces its complete package atomically; its version is the first 12 hex characters of the fetched archive SHA-256. A failed named update preserves the prior package and exits nonzero; bulk update reports the failure and continues. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[internal/marketplaces]].
+
+## Enable/disable
+
+`crtr pkg plugin disable <name>` flips the per-scope config without removing files. A disabled plugin's documents are removed from the canvas: they are not listed and `crtr canvas read <plugin>/<name>` no longer finds them. Re-enable with `crtr pkg plugin enable <name>`.
+
+Individual documents inside an enabled plugin are kept out of automatic delivery and listings by giving them no delivery rules plus `unlisted: true` (or a rule whose `if` fails — that suppresses automatic delivery only; an explicit read by name still resolves), not by a command — see `crtr doc write --rule -h`.
+
+## What goes in a plugin
+
+Good plugin scope:
+- A coherent set of related documents (3–15 typical) sharing a theme.
+- All docs serve the same user persona or workflow.
+- Versioned together — a bump means a bump for the whole set.
+
+Bad plugin scope:
+- One mega-plugin with every doc you've ever written. Hard to install selectively, hard to version.
+- A plugin per single doc. No value-add over a document you own with `crtr doc write`.
+
+## Cross-plugin etiquette
+
+If your document conceptually depends on another plugin's document, link it as `[[<plugin>/<doc>]]` (in a `## Related` section). Don't fork content; link it.
+
+## Plugin commands
+
+Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun branches with their own leaves. It does so through one `commands` pointer and one `transport` declaration. `transport.kind` selects how every leaf runs: `exec` direct-spawns a local executable; `http` calls the remote command surface. crtr owns parsing, native help, rendering, and errors for both.
+
+### The manifest pointer and transport
+
+`commands` and `transport` appear together in `plugin.json`; a docs-only plugin declares neither:
+
+```json
+{
+  "name": "deploy-tools",
+  "version": "0.1.0",
+  "description": "...",
+  "commands": "commands.json",
+  "transport": { "kind": "exec", "executable": "bin/cmd.js" }
+}
+```
+
+An HTTP-transport plugin replaces that declaration with:
+
+```json
+"transport": { "kind": "http", "endpoint": "https://example.com", "authEnv": "DEPLOY_TOKEN" }
+```
+
+For `exec`, `executable` is required when the manifest has any executable leaf; a passthrough-only manifest omits it. When declared, it is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. A passthrough `bin` is either a bare command resolved through `PATH` or a plugin-root-relative executable path subject to the same containment and permission checks. For `http`, `transport.endpoint` is the backend origin and `authEnv` is optional. crouter stores only the environment variable **name**, never its credential; it reads the credential when invoking a leaf. A crouter-materialized archive plugin additionally records its archive URL separately in `bundle` for installation and update.
+
+Only an installed, **enabled** plugin's command manifest contributes. Discovery is per-invocation and reads the installed `commands.json` only: enable, disable, update, and remove take effect on the next `crtr` call with no daemon restart, cache clearing, or network fetch.
+
+### commands.json shape
+
+Both transports use a strict, static `commands.json` with `schemaVersion: 1` and a non-empty `mounts` array:
+
+```json
+{
+  "schemaVersion": 1,
+  "mounts": [
+    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } },
+    { "parent": ["app"], "node": { "kind": "branch", "name": "deploy", "...": "..." } }
+  ]
+}
+```
+
+Each mount is `{ parent, node }`. `parent: []` contributes a top-level branch with `rootEntry { concept, description, whenToUse }`; a non-empty parent path attaches a node below a branch in the same plugin's manifest. Inline children and nested mounts form one forest. A nested mount whose parent is in a top-level inline tree resolves regardless of mount order; when one nested mount supplies another's parent, the parent mount comes first. Branches may have empty `children`, so another mount can fill them.
+
+An exec manifest accepts only `schemaVersion` and `mounts`. Its leaves declare `outputKind: "object"`; branches may declare `passthrough`. An HTTP manifest additionally accepts optional absolute HTTP(S) `baseUrl` and positive-integer `timeouts { connectMs?, requestMs?, streamIdleMs? }`. Its leaves declare a `rest` mapping for method, path, parameter placement, and optional NDJSON streaming. The REST mapping is transport detail: generated `-h` presents HTTP and exec commands like native commands.
+
+Every branch child is a branch (without `rootEntry`) or leaf. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. Two client-side affordances ride on a `positional` or `flag`: `encoding: "text"|"base64"` on a `type: "path"` param sends the named local FILE's content instead of the path string, and `defaultFromEnv: "UPPER_SNAKE"` fills an omitted `string`/`path` param from that environment variable on the calling machine, counting as supplied (so it satisfies `required` and is sent) — unlike a static `default`, which is a parse convenience only and never ships. `defaultFromEnv` is rejected alongside `default` or `repeatable`. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, dynamic state, or renderers.
+
+### Extensible branches and repository fragments
+
+Use `"extensible": true` only on a plugin branch mounted at `parent: []` when repositories should add native children beneath that branch. It is mutually exclusive with `passthrough`: a passthrough branch owns all remaining tokens and cannot have contributed children. The marker does not change the plugin's transport or its own children; those children remain first, and a repository root that reuses one of their names rejects the entire fragment.
+
+A repository CLI framework generates one fragment per opted-in branch at `<project-root>/.crouter/commands/<effective-branch>.json`; the repository developer commits the generated file, never hand-writing it. The effective branch is the composed command name, so a cross-plugin collision uses its origin-qualified identity (for example, `first:demo.json` extends only `first:demo`). On every invocation crtr walks the caller's existing project-root chain nearest first and reads only the first matching fragment; a corrected file is live on the next invocation without installation, caching, or restart.
+
+A fragment accepts only `schemaVersion: 1`, its required `exec` `transport`, and non-empty `mounts`; it shares the `commands.json` node, parameter, output, and effects grammar documented above rather than defining another command language. Its executable is project-root-relative, contained in that root, a regular executable file, and is direct-spawned only for an explicit leaf invocation. Fragment roots attach beneath the extensible branch and may be branches or direct leaves, so `parent: []` never declares `rootEntry`; non-empty parents resolve only within the fragment's own forest, and `passthrough` is forbidden everywhere in a fragment. HTTP transport is not supported for fragments.
+
+A contributed exec leaf receives the same one-request/one-envelope protocol described in [Exec protocol](#exec-protocol), with the full walked command path and `context.extension { branch, root }` instead of `context.plugin`; it runs with the caller's cwd and full environment. It is trusted repository code running with the caller's authority, not sandboxed code. Native help renders contributed commands without provenance; when a present fragment is rejected, only that extensible branch's help shows an `<extension-issue>` pointing to the file, while `crtr sys doctor` reports the full `command_extension_invalid` remediation and also catches fragments for branches that are not extensible. Recovery is to fix or regenerate the committed fragment.
+
+### Execution and trust boundaries
+
+An exec leaf direct-spawns its executable (no shell) only on explicit invocation — never on install, help, or discovery — with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. It is **trusted local code running with the caller's authority**: crtr does not sandbox it, filter the environment, mint a credential, or interpret its backend authentication. This is an execution trust boundary, not a sandbox.
+
+An HTTP leaf is **definition plus HTTP only**: crtr fetches its manifest, renders native help from it, and executes the declared REST mapping. There is no local binary to spawn or sandbox. It carries no exec envelope: a non-streaming 2xx body is the bare result object checked against the declared `output`; a non-2xx body uses `{"error":{"code","message","field?","next?"}}`; an invalid 2xx body or an ill-formed or HTTP-reserved non-2xx error code becomes `cli_protocol_error`, while a missing or malformed non-2xx envelope becomes `cli_http_error`. Declared timeouts, bearer-token handling, and NDJSON stream relay apply.
+
+### Context for displayed files
+
+When a local command displays file contents, call `crtr sys context expose -h`, then invoke that leaf with `--json` for the displayed files. Accept `content` only when the subprocess exits 0 and stdout parses as an object; otherwise discard its stdout and write the structured error to stderr. Put a returned block in the same prose output as the displayed files. An envelope-producing plugin captures it in a declared prose output field, never ahead of its JSON envelope. HTTP-only services do not gain local file or node access through this feature.
+
+### Exec protocol
+
+For an exec leaf, crtr writes exactly one JSON request to the executable's stdin:
+
+```json
+{
+  "protocolVersion": 1,
+  "command": ["app", "show"],
+  "input": { "appId": "app_123" },
+  "context": { "cwd": "/caller/cwd", "plugin": { "name": "deploy-tools", "version": "0.1.0", "scope": "project", "root": "/plugin/root" } }
+}
+```
+
+`input` keys are the parser's camelCase form; a declared `stdin` param arrives as an `input` string, not a second stream. The executable writes exactly one JSON envelope to stdout and nothing else — diagnostics go to stderr:
+
+```json
+{ "protocolVersion": 1, "ok": true, "result": { "app_id": "app_123" } }
+{ "protocolVersion": 1, "ok": false, "error": { "code": "authentication_required", "message": "...", "field": "session", "next": "..." } }
+```
+
+`ok` is the source of truth (a valid envelope is honored regardless of exit code). crtr validates `result` against the declared `output` (top-level field presence + type) and renders it; `--json` mirrors the same object. An error envelope becomes a normal crtr error with its lowercase snake_case `code`, except crtr-reserved `internal`, `unknown_path`, `command_collision`, and `plugin_protocol_error`. No envelope at all (invalid JSON, empty, extra stdout, output over 10 MiB, signal kill) becomes `plugin_protocol_error`.
+
+### Keeping command surfaces valid
+
+- **Generate an exec plugin's `commands.json` from its command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's command surface; drifted params or output fields surface as a validation issue or `plugin_protocol_error` at invocation.
+- **Declare output nullability explicitly.** A missing required output field becomes the transport's protocol error — `plugin_protocol_error` for exec, `cli_protocol_error` for HTTP. A present `null` is type-checked; a field that may carry `null` must declare it in its type, for example `path | null`. For a conditionally omitted field, declare it `required: false` and omit it rather than returning `null` for a non-null type.
+- **HTTP archive plugins are complete package bytes.** `crtr pkg plugin install --endpoint <url> --name <name>` fetches and validates the complete archive before replacing the plugin directory. `crtr pkg plugin update` uses the recorded `bundle` provenance to do the same replacement. The installed `commands.json` and memory tree are authoritative with no TTL, ETag, revalidation, or dispatch-time network path.
+
+### Validation and command collisions
+
+crtr validates command manifests statically; it never executes an exec binary to inspect its command surface:
+
+- `crtr pkg plugin show <name>` inventories the plugin manifest, command-manifest path, accepted top-level command names, and validation issues (each with received/expected/next).
+- `crtr sys doctor` validates the command manifest and transport declaration for every effective plugin, including executable-path checks when exec manifests declare executable leaves, and reports structured remediation (disable, update, remove). `--fix` never chmods or rewrites plugin content.
+- `crtr pkg plugin install` and `update` report accepted top-level command names and validation issues.
+
+Core always wins a path collision. A cross-plugin collision drops every claimant with a `command_collision` issue. A fixed manifest goes live on the next invocation; there is nothing to restart.
+
+## External executable requirements
+
+A plugin can name a program it expects another install to provide, without making that program part of the plugin or asking crouter to install it. Use this for a wrapper that dispatches to a separately installed CLI:
+
+```json
+{
+  "name": "dev",
+  "requires": { "grove": "Install Grove, then register this repo with `grove register`." }
+}
+```
+
+Each key is the same safe bare-name grammar as `bin`: `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`. Each value is one non-empty line an agent can act on. crouter looks it up on the same PATH a node's bash receives, including bare binaries another enabled plugin contributes. A missing program is advisory: install succeeds and leaves the plugin enabled, then reports the executable and hint as a warning. `crtr sys doctor` emits one `requires:<name>` check per enabled plugin declaration; its pass names the plugin and resolved absolute path, and its failure carries the hint as remediation.
+
+A malformed `requires` block is different: invalid names, non-strings, empty hints, and multi-line hints fail source-plugin install and update, because the manifest itself is defective. `requires` belongs only in a plugin manifest, never scope `config.json`.
+
+## Bare binaries on the node PATH
+
+A plugin can also ship plain executables that an agent calls by bare name — `mytool --flag`, exactly like `jq` or `rg`. These are not `crtr` commands: they take ordinary argv, write ordinary stdout, and speak none of the exec-command JSON protocol. Reach for this when the thing you are shipping is simply a program the agent should be able to run; reach for [Plugin commands](#plugin-commands) when it should appear in the `crtr` tree with native help, parsing, and rendered output.
+
+Declare them in `plugin.json`:
+
+```json
+{
+  "name": "deploy-tools",
+  "version": "0.1.0",
+  "description": "...",
+  "bin": { "deployctl": "bin/deployctl", "envdiff": "bin/envdiff.py" }
+}
+```
+
+Each value is plugin-root-relative. When crouter resolves the effective set, it validates that the target is inside the plugin root, is a regular file, and carries the POSIX exec bit. Each key is the bare name a node's bash sees: `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`, and never `crtr` or `crtrd`, which crouter owns.
+
+A user or project scope declares the same block in its own `config.json`. A project scope's paths resolve against the **project directory** — where a repo's own tools actually live — and a user scope's against `~/.crouter/`:
+
+```json
+{ "bin": { "repoctl": "tools/repoctl" } }
+```
+
+crouter resolves the effective set for each node's cwd and profile, validates containment at that time, symlinks exactly those names into a shim directory it owns, and prepends that directory to every broker child's `PATH` — the host `PATH` stays intact behind it, so a contribution shadows a same-named host program and nothing else changes. Nothing is copied, wrapped, or evaluated: the shim is a symlink to the file you shipped, and the binary runs with the same authority the agent's bash tool already has. Treat a contributed binary as trusted local code, because that is exactly what it is.
+
+Precedence ascends the same way the rest of the config layers: user-scope plugins, then user `config.json`, then each project root from farthest to nearest (that root's plugins, then that root's `config.json`). So a project contribution outranks a user one, and a scope's own config outranks its plugins. Disabling or removing a plugin removes its bare commands with it.
+
+Two contributors at the same precedence claiming one name is a collision, not a precedence question: crouter installs neither, and `crtr sys doctor` reports the name and both claimants. Rename one of them, or claim the name explicitly at a higher layer.
+
+## Human completion actions
+
+`humanActions` is a scope-config block, never a plugin-manifest contribution. It maps a stable action name (`[A-Za-z0-9][A-Za-z0-9._-]{0,127}`) to exactly `{ "argv": ["executable", "arg"], "cwd": "directory" }`. Declare it only in `~/.crouter/config.json` or `<repo>/.crouter/config.json`.
+
+Both relative `argv[0]` and `cwd` resolve against the declaring scope's authoring root: `~/.crouter/` for user scope, and the repository directory for project scope. `argv[0]` never uses `PATH`: use an absolute executable path or a root-relative script. A creator resolves an action from the nearest project ancestor first, then farther project ancestors, then user scope; the first declaration of the name wins. Profiles and plugins do not contribute actions.
+
+`argv` is a direct process invocation, never shell source: `argv[0]` is an executable file and every other array element is a literal argument, so shell metacharacters have no special meaning. `cwd` must be an existing directory. Request creation snapshots the winning config origin and resolved argv/cwd, so later config edits never redirect pending delivery. `crtr sys doctor` validates names, declaration shape, paths, regular-file status, and execute permission without running an action. `crtr sys config get humanActions` reads one scope's valid entries; use Doctor to diagnose malformed entries, then edit the JSON file directly to change them.
+
+## Validation
+
+`crtr sys doctor` checks each plugin's manifest:
+- Manifest exists and is valid JSON.
+- Manifest `name` matches the directory name.
+- When the plugin declares `commands`, its command manifest and transport declaration are validated statically; an exec executable is never executed during validation — see [Plugin commands](#plugin-commands).
+- When the plugin (or a scope `config.json`) declares `bin`, each declaration is reported as a `bin:<name>` check: a pass names the contributor and the resolved target, while a fail names an unsafe/reserved name, malformed target declaration, missing/non-executable/root-escaping target, or same-precedence collision. Contributed binaries are never executed during validation. Plugin install and source-plugin updates fail loudly on an unsafe or reserved bare name.
+- Each scope `humanActions` declaration is reported as a `humanActions:<name>` check. Doctor validates names, argv shape, cwd, executable existence, and execute permission without executing the action; plugins and profiles never contribute this block.
+- When an enabled plugin declares `requires`, each `requires:<name>` check names the plugin and resolved executable path on pass, or carries its install hint as remediation on fail. The executable is never run; a malformed declaration fails source-plugin install and update, while an absent executable remains advisory.
+
+Install and update validate every `memory/` file's frontmatter against the package-file format above. `crtr doc lint` does not check package documents: it skips documents nobody can change, and only the package's files change a package document. Nothing else checks body length for its delivery, preview shape or `[[links]]` — review them yourself, and read the document back after install (a link to a name that resolves to nothing stays plain text). Other sibling dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
+
+## Cross-publishing with Claude Code
+
+Some plugins also publish a `.claude-plugin/` manifest alongside `.crouter-plugin/` so they can be loaded directly into Claude Code without going through crtr. Optional. Only worth doing when your documents or commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.

package/dist/builtin-memory/internal/storage-tiers.md

@@ -0,0 +1,51 @@
+---
+name: internal/storage-tiers
+kind: knowledge
+description: Where crouter state belongs
+when-and-why-to-read: When locating crtr state on disk or deciding where a new file belongs, this reference should be read so files are found or placed in the right root — and so you do not look for documents on disk, since they are objects in canvas.db, not files.
+short-form: Where crtr state lives on disk — the scope root (prompts, plugins, personas, config), the canvas home (canvas.db with every object and document body, per-node files, human tickets, diagnostics), and the git ref that carries repo documents.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# Where everything lives on disk
+
+Everything on the canvas — documents, nodes, jobs, owners, custom objects — is an **object** in one SQLite database; see [[internal]] for the object model. Two places on disk hold the rest: the **scope root**, for configuration and prepared content that is files by nature, and the **canvas home**, for the database and per-node runtime files. This is the routing contract; precise resolver behavior lives in `src/core/scope.ts` and `src/core/canvas/paths.ts`.
+
+Documents are not a third place. A document is an object row in `canvas.db` plus a content-addressed body (a package document — crtr's own or a plugin's — keeps its body in its package file, read through `source_path`); who may read it comes from its owner and privacy (`crtr doc write --owner -h`), not from a directory. Do not look for documents on disk, and do not write one as a file: use `crtr doc write`, and read with `crtr canvas read`.
+
+## 1. Scope root — configuration and prepared content
+
+`~/.crouter/` (user scope) or `<project>/.crouter/` (project scope), resolved by `src/core/scope.ts`. It holds `prompts/`, `plugins/`, `marketplaces/`, `personas/`, and `config.json`; a file belongs to the scope whose root it sits under (the user's, or the project's). `prompts/<name>.md` becomes `/<name>` in every node, with nested paths becoming colon-namespaced commands and the nearest resolved scope winning. The scope root does not decide document ownership.
+
+`~/.crouter/support/<reference>/` is user-scope prepared local diagnostic material. A reference contains the prepared support bundle and manifest for explicit handling; it is not a document, a node context file, or a project-scoped support store. Preparation is local and zero-egress; submission is an explicit operation to its verified destination. Invocation, output, and artifact details belong on the relevant command leaf `-h` surfaces.
+
+User-wide content with no cwd dimension also belongs here: `~/.crouter/profile-defaults.json` maps realpath'd directories to their selected profile, and `~/.crouter/prompt-reviews/` holds prompt-review exports.
+
+## 2. Canvas home — the object database, per-node files, and bounded diagnostics
+
+`~/.crouter/canvas/` (overridable with `CRTR_HOME`) is the cwd-agnostic node-graph home. `canvas.db` is the SQLite WAL store for every object and its edges, watches, events and rules, including durable tmux-pane focus. `nodes/<node_id>/` owns `meta.json`, `context/` (the node's context directory: scripts, data, logs and page modules — files only, not a way to share writing), `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Human ticket files (`page.json`, `page.tsx`, `page.js`, optional `reply-route.json`, `action.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live under `nodes/`, the single derived ticket root. A ticket is not owned by a node: reply-bearing tickets target the bridge recorded in `reply-route.json`, while a ticket created programmatically has no bridge and outlives the process that created it. `action.json` is the frozen action binding — the declared `humanActions` name, its resolved argv and cwd, and the opaque payload — written once at creation and never rewritten, so a later config edit cannot redirect an existing request. Whichever writer wins settlement is the one that queues delivery; the attempt schedule itself is crtrd scheduling state in `canvas.db`, not a ticket file, and delivery never rewrites the ticket's terminal result. Runtime-authored document bodies are content-addressed files under `bodies/`; a package document (crtr's own or a plugin's) keeps its body in its package file, read through `source_path`. All records, revisions, delivery rules, edges and watches are rows in `canvas.db`. A repo-owned document also travels on the repo's git ref `refs/crtr/docs` (one JSON file per document), which is how collaborators receive it; the checkout's working tree never holds it.
+
+A specification, plan or report is a document its node owns, named `<node-id>/<name>` and shared by `[[pointer]]`. It is deleted with that node unless a kept document links to it or it is given another owner (`crtr doc move --owner`).
+
+**Package documents.** crtr's own documents (`src/builtin-memory/` in the crouter repo, owner app `crtr`) and a plugin's `memory/` folder are the exception: they stay markdown files in their package and the daemon reconciles them into public, read-only document objects. See [[internal/plugins]].
+
+**Legacy memory directories.** Older runtimes kept documents as markdown in `.crouter/memory/` folders under a repo, profile or user root. `crtr sys migrate` imported those once into documents; the files are left on disk and never read again.
+
+### Canonical event streams
+
+Canonical diagnostics are bounded NDJSON `EventEnvelope` streams. The synchronous rotating writer retains one active file plus `.1` and `.2` generations at 5 MiB each, and each complete record is bounded to 64 KiB including its newline. Each long-lived daemon or broker process binds one fixed source and writes only that source's file; no caller selects an arbitrary destination.
+
+- `nodes/<node_id>/job/log.jsonl` is the node broker's canonical event stream. A broker-bound event carries that node identity; daemon events about a node stay in the daemon stream instead.
+- `<crtrHome>/crtrd.log` is the root daemon's canonical event stream. It contains daemon-owned events, including node-scoped data carried as `node_id` fields.
+
+### Current state and raw residue
+
+`nodes/<node_id>/job/fault` is mutable current fault state, not event history. `nodes/<node_id>/job/telemetry.json` is current node telemetry, not a log; both remain runtime state under the canvas home and are read as state rather than merged into canonical history.
+
+`<crtrHome>/crtrd.err` and `nodes/<node_id>/job/broker.log` are raw process/stdout-stderr residue for runtime warnings, third-party output, and last-resort evidence when canonical emission cannot complete. They are not canonical streams, are not parsed as event envelopes, and do not become JSON event output.
+
+`<crtrHome>/bin-shims/<address>/` holds the symlink shims for bare-binary contributions (`bin` in a plugin manifest or a scope `config.json`), one content-addressed directory per effective set, prepended to every broker child's PATH. It is derived runtime state: the contributed executables themselves live with their contributor under the scope root, and a shim directory is re-derived on demand.
+
+The contributor rule: configuration, prompts, plugins and personas → scope root; objects (documents included), node files, human tickets, current state, canonical streams, and raw residue → canvas home. Runtime install generations under `~/.crouter/runtime/generations/` are sealed install machinery, not a place state is stored or an agent workspace.

package/dist/builtin-memory/memory-read-orientation.md

@@ -0,0 +1,13 @@
+---
+kind: knowledge
+when-and-why-to-read: When an agent reads its first document, this knowledge should be read because the inspection and revision affordances stay visible without taxing every later read.
+rationale: The generic follow-up appeared after every memory read even though transcript-scoped delivery can teach it once; Silas asked to move it into a one-time built-in memory on 2026-08-17.
+unlisted: true
+lint-ignore: broad-memory-read
+surfaces:
+  - on: memory-read
+    match: "**"
+    at: content
+---
+
+`crtr canvas read --fields <name>` includes the document's fields. Revise a document with `crtr doc edit` (recorded, with a rationale), or browse the inventory with `crtr canvas list --type document`.

package/dist/builtin-memory/wedged-child-on-runaway-bash.md

@@ -0,0 +1,21 @@
+---
+kind: knowledge
+when-and-why-to-read: When a node is marked wedged or remains active without progress while its inbox accumulates, this reference should be read so recovery restores progress without losing context or killing the wrong process.
+short-form: A node stuck mid-turn is detected from a stale busy heartbeat plus near-zero process-tree CPU. Kill a runaway subprocess when one exists; when the broker itself is stuck, the daemon SIGTERMs it and applies bounded, conditional recovery.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+A base node can wedge mid-turn on a runaway bash command (for example, an unbounded recursive scan from `/`). Its pi turn cannot push or finish while the tool call is blocked.
+
+**Detection is automatic.** The daemon reports a wedge only after both the busy heartbeat has been quiet for 20+ minutes and the broker's whole process tree is near-zero CPU. It records a `daemon→node` `wedged` fault and sends one doctrine wake to subscribers per wedge episode. The canvas marks the node as needing attention.
+
+## Recover the process that is actually stuck
+
+- **A subprocess exists.** The daemon leaves the broker alone because a runaway bash/find/grep is the likely cause. Inspect the broker process tree, kill the scanner subprocess rather than its shell wrapper or node, and let the tool call return. The pi turn then resumes with its context intact. Tell the owning orchestrator if you discovered the wedge before its doctrine wake.
+- **No subprocess exists.** The broker itself is stalled. The daemon SIGTERMs it; its live-exit policy then makes a bounded recovery attempt. An interrupted saved turn resumes in the same conversation with a continuation, whether the broker persisted a clean abort or died abruptly. A pending refresh or pending cycle starts a new cycle from the saved session instead. A broker that never established a session terminalizes rather than entering a respawn loop.
+
+Recovery is not unconditional. Repeated short-lived exits or a boot failure terminalize the node as `dead`; no daemon respawn follows that terminal state. Reopen it explicitly with `crtr node lifecycle revive <id>` (use `--reopen` if it finalized), or deliver an inbox wake where that is the intended control path. If the daemon is down, it cannot detect, signal, or respawn a wedge; restore the daemon before relying on lifecycle recovery.
+
+Do not kill a healthy node merely because it has been working for a long time. The detector intentionally requires both a silent heartbeat and an idle process tree; a long-running tool that is still producing output or consuming CPU is not wedged.

package/dist/builtin-pi-packages/pi-crtr-extensions/README.md

@@ -0,0 +1,49 @@
+# pi-crtr-extensions
+
+crtr's engine-side [pi](https://pi.dev) package — the extensions and prompt
+templates every pi engine (including crouter's brokers) loads. This directory,
+inside the crouter tree, is the canonical and only copy; it ships in crouter's
+`dist/builtin-pi-packages/pi-crtr-extensions` and `crtr sys setup` wires that
+path into the `packages` array of `~/.pi/agent/settings.json` — there is nothing
+to clone or install separately.
+
+The package is excluded from crouter's tsc compile unit; pi loads the `.ts`
+sources directly with its own loader. Imports may reach from here into
+crouter's compiled core (e.g. `lib/subscription-state.ts` imports the model
+ladder from `../../../types.js`), never the other direction.
+
+**Does the OAuth plugin ship with pi? No.** `pi-claude-oauth-adapter` is a
+third-party npm package ([minzique/dotfiles-agents](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)) —
+"Anthropic OAuth / Claude Code compatibility adapter for Pi." pi installs it
+from npm because of the `npm:` prefix; it lands in `~/.pi/agent/npm/node_modules/`.
+If you want Claude-subscription auth, you add this line yourself — it is not bundled.
+(Separately, *this* package's `provider-rotation.ts` extension does its own
+OAuth login/refresh via `@earendil-works/pi-ai/oauth` to rotate across
+subscription credentials — that's a different mechanism, built in here.)
+
+`@earendil-works/pi-coding-agent` is a peer dependency provided by pi at runtime —
+do not install it locally. The one runtime dep (`yaml`) is vendored under this
+directory's `node_modules/`.
+
+## Contents
+
+### Extensions (`extensions/`)
+
+| Extension | What it does |
+|-----------|--------------|
+| `claude-plugin-commands.ts` | Surfaces commands and skills from `~/.claude`, the cwd, every project in the selected crouter profile, and installed plugins as pi slash commands with arg/shell-block execution. Writes shims to `~/.pi/agent/.plugin-command-shims/`. Skips any name pi already serves natively from `~/.pi/agent/prompts/` (e.g. crtr exports a slash command to both `~/.claude/commands` and `~/.pi/agent/prompts`), so the shim never collides with the native prompt. |
+| `memory-slash-commands.ts` | Registers every builtin or scope-owned memory marked `slash: true`, including `/spec` and `/plan`. |
+| `provider-rotation.ts` | Subscription credential rotation across Anthropic / OpenAI-Codex: does its own OAuth login/refresh, rotates on rate-limits, falls back across the model ladder. Registers `/provider-sub <provider> <list\|add\|select\|rm>`. |
+| `crtr-commands/` | Auto-generates a slash command per `crtr` CLI node. The tree is derived in-process from crtr's own `buildRoot()` (no subprocesses, no cache on disk); `filters.json` controls which nodes are exposed. |
+| `sysprompt-window.ts` | Registers `/sysprompt`, which runs `crtr sys context sysprompt --window` without injecting the prompt into context. |
+| `frontmatter-rules/` | Injects `.pi/rules/*.md` whose `when:` frontmatter matches a read markdown file. `.claude/rules` are migrated into substrate docs with read-glob `surfaces` entries via `crtr sys sync project-guidance`. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
+
+Removing pi's self-referential prompt text (the harness identity sentence and
+the pi documentation block) is NOT done here. It runs as a canvas extension, so
+it is ordered ahead of every installed package — including the Claude
+subscription adapter, which otherwise cuts the node's own persona out of the
+system prompt along with the docs block.
+
+## Notes
+
+- Reload after editing any extension: `/reload` in pi.