@north-light/crouter 0.3.163 → 0.3.165

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

@@ -5,8 +5,8 @@ when-and-why-to-read: When creating a crtr plugin, packaging memory docs for
   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, and command plugins (top-level
-  CLI commands via commands.json + one executable). Use when creating a plugin,
+  layout, scopes, install mechanics, versioning, and command-capable plugins
+  (commands.json plus an exec or HTTP transport). Use when creating a plugin,
   packaging memory docs, contributing commands, or debugging install/resolution.
 system-prompt-visibility: name
 file-read-visibility: none
@@ -42,7 +42,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
         └── <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 artifact types. A plugin that contributes CLI commands adds a `commands.json` manifest plus its executable — see [Command plugins](#command-plugins).
+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 artifact types. A plugin that contributes CLI commands adds a `commands.json` manifest plus a `transport` declaration — see [Plugin commands](#plugin-commands).
 
 ## The manifest
 
@@ -68,7 +68,8 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `description` | yes | One sentence. |
 | `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
 | `owner` | optional | Author info. |
-| `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. Present ⇒ the plugin contributes top-level `crtr` commands — see [Command plugins](#command-plugins). |
+| `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 a local executable; `{ "kind": "http", "endpoint": "https://…", "authEnv": "TOKEN_NAME" }` calls a remote HTTP command surface. |
 
 ## Scopes
 
@@ -83,7 +84,7 @@ Project-scope plugins outrank user-scope on resolution. Both outrank marketplace
 
 ## Install mechanics
 
-Three ways a plugin lands in a scope:
+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.
@@ -91,11 +92,15 @@ Three ways a plugin lands in a scope:
    - Independent of any marketplace.
 
 2. **From a marketplace** (`crtr pkg plugin install <mkt>/<name>`):
-   - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
-   - `crtr pkg market update --name <mkt>` pulls updates for every installed plugin from that marketplace.
+   - 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. **Authored in place** (you're writing the plugin in a working repo):
+3. **From an HTTP endpoint** (`crtr pkg plugin install --endpoint <url> --name <name> --scope user`):
+   - Fetches the served `commands.json`, then writes the plugin manifest and exact fetched bytes into the selected scope. 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 install fails loudly and writes nothing when that fetch fails. Reinstalling the same HTTP plugin replaces its endpoint/auth-env declaration and stored manifest; it conflicts with an existing non-HTTP plugin of the same name.
+
+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.
 
@@ -131,7 +136,7 @@ Standard semver:
 | 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>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[internal/marketplaces]].
+`crtr pkg plugin update --name <name>` pulls source updates for ordinary and exec-transport plugins, while an HTTP-transport plugin unconditionally refetches and replaces its stored `commands.json`. A failed HTTP refresh preserves the prior bytes and exits nonzero. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[internal/marketplaces]].
 
 ## Enable/disable
 
@@ -154,45 +159,63 @@ Bad plugin scope:
 
 If your memory doc conceptually depends on another plugin's doc, link via `## Related` with `` `<plugin>/<doc>` ``. Don't fork content; link it.
 
-## Command plugins
+## 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.
 
-Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun branches with their own leaves. You declare one pointer in the manifest and ship one executable; crtr owns parsing, help, rendering, and errors, and direct-spawns your executable once per leaf invocation.
+### The manifest pointer and transport
 
-### The manifest pointer
+`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" }
+}
+```
 
-Add `commands` to `plugin.json` — a plugin-root-relative path to one static manifest:
+An HTTP-transport plugin replaces that declaration with:
 
 ```json
-{ "name": "deploy-tools", "version": "0.1.0", "description": "...", "commands": "commands.json" }
+"transport": { "kind": "http", "endpoint": "https://example.com/v1/cli/manifest", "authEnv": "DEPLOY_TOKEN" }
 ```
 
-Only an installed, **enabled** plugin's `commands` manifest contributes. Discovery is per-invocation: enable/disable/update/remove takes effect on the very next `crtr` call — no daemon restart, no cache to clear.
+For `exec`, `executable` is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. For `http`, `endpoint` is an absolute endpoint and `authEnv` is optional. crtr stores only the environment variable **name**, never its credential; it reads the credential when fetching the manifest or invoking a leaf.
+
+Only an installed, **enabled** plugin's command manifest contributes. Discovery is per-invocation: enable, disable, update, and remove take effect on the next `crtr` call — no daemon restart or cache clearing.
 
 ### commands.json shape
 
+Both transports use a strict, static `commands.json` with `schemaVersion: 1` and a non-empty `mounts` array:
+
 ```json
 {
   "schemaVersion": 1,
-  "executable": "bin/cmd.js",
   "mounts": [
-    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } }
+    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } },
+    { "parent": ["app"], "node": { "kind": "branch", "name": "deploy", "...": "..." } }
   ]
 }
 ```
 
-- `schemaVersion` — exactly the integer `1`. Anything else rejects the whole manifest.
-- `executable` — plugin-root-relative path to the one command binary. Must resolve inside the plugin root, be a regular file, and carry the POSIX exec bit.
-- `mounts[]` — each `{ parent: [], node }`. v1 supports **top-level mounts only**: `parent` must be `[]`.
+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.
 
-Every top-level `node` is a **branch** (`kind: "branch"`) carrying a `rootEntry { concept, description, whenToUse }` — the representation crtr renders at root help. Branch children are nested branches (no rootEntry) or leaves. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), `outputKind: "object"`, 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, no dynamic state, no renderers.
+### Execution and trust boundaries
 
-### Execution: the trust boundary
+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.
 
-On explicit leaf invocation — **never on install, help, or discovery** — crtr direct-spawns your executable (no shell) with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. Installed command plugins are **trusted local code running with the caller's authority**: crtr does not sandbox them, filter the environment, mint a credential, or interpret your backend's auth. Your executable owns authentication to its own backend. This is an execution trust boundary, not a sandbox — installed code can already read the caller's files, so env filtering would only imply a security guarantee that does not exist.
+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. HTTP leaf calls retain their declared timeouts, bearer-token handling, NDJSON streaming, and structured HTTP error-envelope handling.
 
-### The protocol
+### Exec protocol
 
-crtr writes exactly one JSON request to your executable's stdin:
+For an exec leaf, crtr writes exactly one JSON request to the executable's stdin:
 
 ```json
 {
@@ -203,44 +226,37 @@ crtr writes exactly one JSON request to your executable's stdin:
 }
 ```
 
-`input` keys are the parser's camelCase form; a declared `stdin` param arrives as an `input` string, not a second stream. Your executable writes exactly one JSON envelope to stdout and nothing else — diagnostics go to stderr:
+`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 your declared `output` (top-level field presence + type) and renders it; `--json` mirrors the same object. An error envelope becomes a normal crtr error with your `code` — lowercase snake_case, never crtr-reserved `internal`, `unknown_path`, `command_collision`, or `plugin_protocol_error`. No envelope at all (invalid JSON, empty, extra stdout, output over 10 MiB, signal kill) becomes `plugin_protocol_error`.
-
-### Two rules that prevent silent breakage
-
-- **Generate `commands.json` from your command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's actual command surface; a hand-maintained copy drifts, and a drifted param or output field surfaces as a validation issue or a `plugin_protocol_error` at invocation. Emit it from the same source your executable dispatches on.
-- **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as *absent* → `plugin_protocol_error`. If a value is genuinely optional, declare it `required: false`; if it's required, always return a real value.
-
-### Validating your command manifest
-
-crtr validates command manifests **statically — it never executes your binary** to check them:
+`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`.
 
-- `crtr pkg plugin show <name>` — inventories the manifest path, executable, accepted top-level command names, and every current validation issue (each with received/expected/next).
-- `crtr sys doctor` — validates the manifest + executable path for every effective command plugin and reports structured remediation (disable/update/remove). `--fix` never chmods or rewrites plugin content.
-- `crtr pkg plugin install` / `update` — report the accepted top-level commands and any issues in their result.
+### Keeping command surfaces valid
 
-A fixed manifest goes live on the next invocation; there is nothing to restart.
+- **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.
+- **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as absent → `plugin_protocol_error`. If a value is optional, declare it `required: false`; if it is required, return a real value.
+- **HTTP plugin manifests are fetched bytes.** `crtr pkg plugin install --endpoint <url> --name <name>` fetches before writing the plugin, then stores the exact response at the plugin's declared `commands` path. `crtr pkg plugin update` unconditionally refetches HTTP plugins; failures preserve the prior bytes and exit nonzero. The stored manifest is authoritative with no TTL, ETag, or revalidation. If its file is missing or unparseable, an unknown-first-token miss fetches each affected HTTP plugin once; diagnostics name `crtr pkg plugin update <name>`.
 
-## Configured CLIs
+### Validation and command collisions
 
-A **configured CLI** is the other way a contributor adds `crtr` commands — the CLI analogue of an MCP client. Where a command plugin ships a local **executable**, a configured CLI is **definition + HTTP only**: crtr fetches a manifest from a remote endpoint, stores it locally, renders native `-h` help from it, and runs each leaf as a declarative REST call. There is no local binary to spawn and nothing to sandbox — a strictly narrower trust surface than a command plugin.
+crtr validates command manifests statically; it never executes an exec binary to inspect its command surface:
 
-The manifest **is** the command-plugin `commands.json` schema (same `schemaVersion 1`, same node/param/output vocabulary, same reject-unknown-keys strictness), differing in exactly three ways: it drops `executable`, allows non-empty mount `parent` paths (a CLI builds a self-contained forest and may mount at depth), and every leaf carries a `rest` mapping (method/path/param placement/streaming flag) instead of `outputKind`. The `rest` mapping is transport — it never appears in generated `-h`, so a configured command is indistinguishable from a native one.
+- `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 for exec transport, 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.
 
-Manage them under `crtr pkg cli` — `register` (records `{name, endpoint, auth-env NAME}` in scope config and fetches+stores the manifest), `remove`, `list`, `show`, `refresh`. crtr stores only the env var **name** holding the bearer token, never the credential. The stored manifest is authoritative with **zero freshness machinery** (no TTL, ETag, or revalidation): it reloads only on a re-register (the guest-boot path — a byte-identical re-register still re-fetches) or an explicit `refresh`, and a registration with no stored manifest (its register-time fetch failed) triggers a one-time hydration fetch on an unknown-first-token miss, the sole moment an absent store is detected. Inspect a CLI's accepted commands and validation/collision issues with `crtr pkg cli show <name>` and `crtr sys doctor`; both read the same unified snapshot dispatch uses. A configured CLI may never mount onto a core, plugin, or other-CLI path — core always wins, cross-contributor path clashes drop all claimants with a `command_collision` issue.
+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.
 
 ## 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 + executable path are validated statically (never executed) — see [Command plugins](#command-plugins).
+- 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).
 
 `crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
 

package/dist/builtin-memory/planning.md

@@ -2,12 +2,9 @@
 kind: knowledge
 when-and-why-to-read: When shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation, this knowledge should be read so implementation receives a right-sized, parallel-safe execution map whose gaps are caught while they are still cheap to fix.
 short-form: Use when shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation.
-system-prompt-visibility: name
+system-prompt-visibility: preview
 file-read-visibility: none
-gate:
-  kind:
-    imatches: '^plan($|/)'
-needs-refinement: true
+gate: {kind: plan}
 rationale: >-
   The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment.
 ---
@@ -18,9 +15,9 @@ rationale: >-
 
 Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choosing the wrong shape wastes a cycle — a flat plan that is too large forces an implementer to hold too much at once; a decomposed plan for something small adds overhead for no gain.
 
-**Use a flat plan** when the work is a single coherent domain, involves fewer than ~6 files, and can be written at consistent task granularity without exceeding roughly 150–200 lines. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
+**Use a flat plan** when the work is a single coherent domain and can be written at consistent task granularity in one plan. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
 
-**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI), involves 6+ files, or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
+**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI) or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
 
 **The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
 

package/dist/builtin-memory/spec.md

@@ -9,12 +9,9 @@ short-form: Use when running a specification effort, shaping a spec roadmap, or
   shape→design→requirements methodology, when to delegate design to a child
   node, the isolation principle behind the design/requirements split, and what a
   finished spec contains.
-system-prompt-visibility: name
+system-prompt-visibility: preview
 file-read-visibility: none
-gate:
-  kind:
-    imatches: '^spec($|/)'
-needs-refinement: true
+gate: {kind: spec}
 ---
 
 ## The Three Stages
@@ -25,9 +22,9 @@ A specification effort runs in exactly this order: **SHAPE** → **DESIGN** →
 
 Shape is the discovery stage — the one place this effort is genuinely interactive. You work the human like a **consultant with a client**: draw out intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
 
-Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer 2–4 concrete options, get a decision, repeat. Two rules keep it sharp. **Never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have answered erodes their trust. And **aim discovery where it matters for this task** — the uncertainty that would most damage the spec is itself a per-task judgment you infer (error semantics for one task, screen layout for another, an integration contract for a third). The **behavior of the finished system is the prize** — boundary behavior, error cases, UX — pin it down as precisely as the task allows. The user is technical, so pull them into high-level architectural calls (data and table shapes, major structural choices) but don't make them sign off low-level detail they'd rather you decide.
+Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer concrete options, get a decision, repeat. Two rules keep it sharp. **Never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have answered erodes their trust. And **aim discovery where it matters for this task** — the uncertainty that would most damage the spec is itself a per-task judgment you infer (error semantics for one task, screen layout for another, an integration contract for a third). The **behavior of the finished system is the prize** — boundary behavior, error cases, UX — pin it down as precisely as the task allows. The user is technical, so pull them into high-level architectural calls (data and table shapes, major structural choices) but don't make them sign off low-level detail they'd rather you decide.
 
-Track these turns carefully. The shape stage is done when: (1) 3–7 named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after several rounds an ambiguity remains genuinely unresolvable, surface it explicitly in the design brief as an open question — do not silently assume an answer.
+Track these turns carefully. The shape stage is done when: (1) the named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after several rounds an ambiguity remains genuinely unresolvable, surface it explicitly in the design brief as an open question — do not silently assume an answer.
 
 Gate: human confirms readiness to proceed to design.
 
@@ -35,7 +32,7 @@ Gate: human confirms readiness to proceed to design.
 
 Design produces the blueprint: components and their topology, end-to-end flows, files and directories affected, locked decisions, and open questions resolved. The altitude is infra/services — no function signatures, no algorithm descriptions, no implementation ordering. Design answers "what shape does this take?" — planning answers "how is it built?"
 
-Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has more than one distinct phase or more than ~5 interacting components, use an orchestrator.
+Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has distinct phases or interacting components that need separate design treatment, use an orchestrator.
 
 Gate: human approves the rendered design artifact.
 
@@ -61,9 +58,9 @@ The isolation is structural, not stylistic. The requirements writer receives: th
 
 After the design is approved, the spec orchestrator runs `crtr node yield` before starting requirements work. This is mandatory, not optional.
 
-Why: the design conversation fills context with reasoning about tradeoffs, rejected alternatives, and design intent. That context biases delegation — it causes the orchestrator to frame the requirements task with assumptions from the design discussion. After yielding, the orchestrator revives fresh against `context/roadmap.md`, which records the finished design artifact path. It reads the design artifact cold and delegates the requirements work from that clean window, anchored on the rendered design rather than on the design conversation.
+Why: the design conversation fills context with reasoning about tradeoffs, rejected alternatives, and design intent. That context biases delegation — it causes the orchestrator to frame the requirements task with assumptions from the design discussion. After yielding, the orchestrator revives fresh against `$CRTR_CONTEXT_DIR/roadmap.md`, which records the finished design artifact path. It reads the design artifact cold and delegates the requirements work from that clean window, anchored on the rendered design rather than on the design conversation.
 
-The roadmap must record the design artifact path and the current stage before yielding. On revive, the first action is to read `context/roadmap.md`, confirm the design is landed, and delegate requirements work.
+The roadmap must record the design artifact path and the current stage before yielding. On revive, the first action is to read `$CRTR_CONTEXT_DIR/roadmap.md`, confirm the design is landed, and delegate requirements work.
 
 ---
 
@@ -77,9 +74,9 @@ After yield-and-revive, `## Strategy / phases` plus `## Active context` must let
 
 ## Delegating Design: Base Node vs. Orchestrator
 
-Spawn a base `design` node (terminal) when: the design surface is bounded, one component or subsystem, no multi-phase structure required. The node produces `context/design.md` and `context/design.json` and returns.
+Spawn a base `design` node when the design surface is bounded: one component or subsystem with no multi-phase structure required. The child writes `design-<subject>.md` in its own context directory and reports that absolute path.
 
-Spawn a `design` orchestrator (resident) when: the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it's finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — rather than spawning a base design node and counting on it to promote itself once it discovers the surface is too big; self-promotion is unreliable, and a node born an orchestrator is strictly more capable than one hoping to become one. Pass it the shape brief as its goal; it owns the decomposition and integration internally and reports a finished design artifact when done.
+Spawn a terminal `design` orchestrator when the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it is finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — so it owns decomposition and integration from the start. Pass it the shape brief as its goal; it writes the integrated `design-<subject>.md` in its own context directory and reports that absolute path when done.
 
 In either case, the spec orchestrator waits for the design to land and the human to approve it before proceeding.
 

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

@@ -1,34 +1,20 @@
 ---
 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 child stuck mid-turn (runaway bash, or a stalled broker with no subprocess) is AUTO-DETECTED by the daemon (⚠ wedged + a doctrine wake) — kill the subprocess if one exists; if none, the daemon SIGTERM-kicks the broker and automatically starts a fresh recovery cycle
+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.
 system-prompt-visibility: preview
 file-read-visibility: none
 ---
 
-A base node can wedge INDEFINITELY on a single runaway bash command (classic: `grep -rln "..." /` — a recursive grep from filesystem root that scans all of disk and never returns; also any unbounded find/scan over `/` or a network mount). The node's pi turn is blocked waiting on the bash call, so it never `push`es and never finishes.
+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 (crtrd, issue #110).** The daemon's supervision tick corroborates two signals on every live/busy node: the busy-marker heartbeat (re-touched on every tool start/stream/end and turn end) gone quiet for 20+ minutes, AND the broker's whole process tree (broker pid + every descendant) reading near-zero CPU. Only when BOTH hold does it fire — routine long tool calls that are genuinely still producing output or burning CPU never trip it. On a 'wedged' verdict the daemon records a `daemon→node`/`wedged` Fault (the local canvas graph and browse UI show ⚠ "wedged · needs you", the same surface provider-fault stalls use) and fans a doctrine wake to the node's subscribers — ONE notice per wedge episode, not a repeat every tick. In the local browse UI, the hanging-node recovery action runs `node lifecycle revive <id> --now`; there is no hanging filter on `node inspect list`.
+**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.
 
-**Remediation branches on whether the tree has a descendant (issue #119):**
+## Recover the process that is actually stuck
 
-- **A subprocess exists (the common case)** — a runaway bash/find/grep is the likely cause. The daemon does NOT touch the engine here; you kill the subprocess yourself (see below).
-- **No subprocess exists** — the broker pid stands alone in its own tree (the engine itself stalled, e.g. mid a `model_change`, with nothing a human could kill). The daemon performs the ONLY remaining remediation itself: it SIGTERMs the broker (the same on-demand kick `node lifecycle revive --now` does). The surviving `job/busy` marker proves the process died mid-turn, so its exit-policy job starts a fresh cycle on the saved session tree. That cycle automatically receives the normal roadmap/feed/context kickoff; it does not reopen the dead turn at an idle prompt, and no manual nudge is required.
+- **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. A broker-certified clean abort resumes the saved session with a continuation. A dirty interrupted turn, pending refresh, or pending cycle starts a new recovery cycle from the saved session instead. A broker that never established a session terminalizes rather than entering a respawn loop.
 
-**Why it used to be invisible to the orchestrator:** the wake spine only fires on a child's push/finalize/crash. A child wedged *mid-turn* does none of those — its row stays `status=active` and the dashboard shows it `●` working. Before #110, the parent got no wake at all, so an entire wave could stall for hours looking healthy; cli-verbs-B2 sat wedged ~2h14m on a `grep /` before a safety-deadline inspection caught it. The daemon-side detection above closes that gap; you should no longer need to notice a wedge by elapsed-time vibes alone — but if you do (the daemon hasn't caught up yet, or the wedge is younger than its grace window), the manual inspection below still works.
+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.
 
-## Subprocess case: kill the runaway command
-
-**How to inspect further / confirm:** `tmux capture-pane -p -t <pane>` shows the live turn (look for `Elapsed NNNNs ⠼ Working...` on one bash command); `pgrep -P <pi_pid>` + `ps -axo pid,ppid,etime,command` reveals the runaway subprocess and how long it's run.
-
-**How to apply:** kill the runaway SUBPROCESS, not the node — `kill <grep_pid>`. The bash call then returns and the pi turn resumes on its own, no context lost, no respawn. (Killing the bash `-c` wrapper can orphan the grep; kill the actual scanner PID. A pipeline `grep / | head` resumes fastest if you kill the first-stage grep — the pipe closes and bash proceeds.) Then notify the OWNING orchestrator (deferred tier) so it steers the child to completion and knows the lost time — the doctrine wake above already does this automatically for a detected wedge, but do it yourself if you found the wedge before the daemon did. Related: the `revive-stuck-orchestrator` doc covers the orchestrator-level false-finish failure mode.
-
-## No-subprocess case: broker wedged mid-stream (`streaming:true` stuck)
-
-The wedge can outlive any subprocess, or exist with none at all. A node (including a top-level **resident orchestrator**, not just a child) can sit stuck with the canvas snapshot showing `streaming: true` and a stale `last_activity` for **days**, while the broker pid is alive but doing nothing (0% CPU) and NO subprocess exists to kill — the engine deadlocked mid-stream (often right after a bash call returned, or after a `model_change`) and never closed the turn. Tells: `job/busy` lockfile present with an old mtime, `job/telemetry.json` `updated_at` frozen, `job/broker.log` stopped growing, inbox piling up (`queued (N)` in the dashboard) because the turn never ends. The `busy` marker alone is harmless (it is always AND-ed with `pidAlive`, so a stale one from a dead pid is ignored) — do not bother deleting it.
-
-**This is now the daemon's own remediation (issue #119) — it auto-kicks the broker for you.** If it hasn't caught up yet (younger than the wedge grace, or the daemon was down), do it manually:
-
-1. `kill -TERM <broker_pid>` — the wedged broker. Confirm it dies (`ps -p <pid>`) and that no orphan subprocess lingers (`ps -o pid,ppid,command | awk '$2==<pid>'`).
-2. The **daemon auto-resumes** it within ~20s on the saved session — a fresh broker pid appears (`node inspect show`), `status=active`, `intent=null`, `view.sock` accepts connections. (No manual `node lifecycle revive` needed if the daemon is up; do it manually only if it doesn't come back.)
-3. **The daemon starts the replacement as a fresh recovery cycle** — the stale `job/busy` marker distinguishes an interrupted turn from an idle crash, so the daemon selects `resume:false`. The saved session tree remains on disk, while the new cycle re-orients from `context/roadmap.md`, feed, reports, and context automatically. Confirm success by watching `telemetry.json` `updated_at` go current and the node run tools again. A manual `--tier critical` message is now only a fallback if the replacement broker itself fails to boot or provider access is still unhealthy.
+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/cli.js

@@ -54,7 +54,7 @@ async function main() {
     ensureProjectScope(process.argv);
     maybeAutoUpdate(process.argv);
     // Pass the one-shot unknown-first-token retry seam: on a first-token miss with
-    // absent configured-CLI stores, hydrate them once, rebuild, and re-walk (§5.1).
+    // absent HTTP-plugin stores, hydrate them once, rebuild, and re-walk.
     // A recognized core first token resolves in `resolveRoot`'s fast path and never
     // reaches a first-token miss, so the seam stays off the core fast path.
     mark('cli.dispatch_start');

package/dist/clients/attach/__tests__/attach-keybindings.test.js

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { resolveKeybindings } from '../../../core/keybindings/index.js';
-import { detachHint, inboxOpenHint, dispatchAttachBinding, matchesAttachBinding, refreshAttachBindingSnapshot, } from '../session/bindings.js';
+import { decodeAttachControlInput, encodeAttachControlInput, extractAttachControlInput, resolveKeybindings, } from '../../../core/keybindings/index.js';
+import { detachHint, inboxOpenHint, dispatchAttachAction, dispatchAttachBinding, matchesAttachBinding, refreshAttachBindingSnapshot, } from '../session/bindings.js';
 import { GraphOverlay } from '../overlays/graph.js';
 const PALETTE = {
     accent: (s) => s,
@@ -23,7 +23,7 @@ function fakeTui() {
         requestRender: () => { },
     };
 }
-test('attach input dispatches only the current configured action', () => {
+test('attach direct and private control input dispatch through the same action map', () => {
     const bindings = resolveKeybindings({
         'crtr.attach.detach': ['ctrl+x'],
         'crtr.attach.clear-or-detach': [],
@@ -33,6 +33,7 @@ test('attach input dispatches only the current configured action', () => {
         'crtr.attach.model-ladder.previous': ['alt+y'],
         'crtr.attach.command.inspect': ['alt+shift+h'],
         'crtr.attach.file-review': [],
+        'crtr.attach.profile-files': [],
     });
     const calls = [];
     const actions = {
@@ -44,6 +45,7 @@ test('attach input dispatches only the current configured action', () => {
         'crtr.attach.model-ladder.previous': () => calls.push('ladder-back'),
         'crtr.attach.command.inspect': () => calls.push('inspect'),
         'crtr.attach.file-review': () => calls.push('review'),
+        'crtr.attach.profile-files': () => calls.push('profile-files'),
     };
     assert.equal(dispatchAttachBinding(bindings, '\x18', actions), true);
     assert.equal(dispatchAttachBinding(bindings, '\x04', actions), false, 'old detach must not reach the listener action');
@@ -55,7 +57,18 @@ test('attach input dispatches only the current configured action', () => {
     assert.equal(dispatchAttachBinding(bindings, '\x1by', actions), true);
     assert.equal(dispatchAttachBinding(bindings, '\x1bM', actions), false, 'old ladder-back key must not reach the listener action');
     assert.equal(dispatchAttachBinding(bindings, '\x1b[72;4u', actions), true);
-    assert.deepEqual(calls, ['detach', 'mode', 'ladder', 'ladder-back', 'inspect']);
+    assert.equal(dispatchAttachBinding(bindings, '\x06', actions), false, 'disabled direct binding must stay disabled');
+    const privateInput = encodeAttachControlInput('crtr.attach.profile-files');
+    const privateAction = decodeAttachControlInput(privateInput);
+    assert.equal(privateAction, 'crtr.attach.profile-files');
+    dispatchAttachAction(privateAction, actions);
+    assert.deepEqual(calls, ['detach', 'mode', 'ladder', 'ladder-back', 'inspect', 'profile-files']);
+    assert.equal(decodeAttachControlInput(`${privateInput}x`), undefined, 'whole-input decoding must be exact');
+    assert.equal(decodeAttachControlInput('\x1b_crtr;crtr.attach.not-real\x1b\\'), undefined, 'unknown actions must stay ordinary input');
+    assert.deepEqual(extractAttachControlInput(`before${privateInput}after`), {
+        actionId: 'crtr.attach.profile-files',
+        remaining: 'beforeafter',
+    });
     assert.equal(detachHint(bindings), 'Ctrl+X', 'disabled clear-or-detach must fall back to enabled detach');
     const noDetach = resolveKeybindings({ 'crtr.attach.detach': [], 'crtr.attach.clear-or-detach': [] });
     assert.equal(detachHint(noDetach), undefined, 'a disabled pair must not render "Disabled to detach"');

package/dist/clients/attach/__tests__/context-message.test.js

@@ -1,23 +1,14 @@
-// Regression coverage for the attach viewer's collapsed hidden-context
-// rendering (render/context-message.ts + its dispatch in render/chat-view.ts).
-//
-// Both hidden-context custom types — `crtr-context` (fresh-birth bearings) and
-// `crtr-situational-context` (an existing node's ambient update, sent by
-// canvas-inbox-watcher.ts) — must render through the same collapsed
-// ContextMessageComponent, never the generic always-expanded
-// CustomMessageComponent: body text stays hidden until the user expands it
-// (Ctrl+O). These tests pin (a) the collapsed component itself never leaks
-// body text before expansion, for both labels it serves, and (b)
-// render/chat-view.ts's source wires the situational customType to that same
-// collapsed component (a full ChatView needs a live TUI/Container from
-// pi-tui, so this source-contract check is the smallest meaningful assertion
-// of the dispatch).
+// Regression coverage for the attach viewer's display-only folding of
+// crouter-generated context. The body must stay agent-visible and expandable,
+// while bearings, situational updates, fresh-revive kickoffs, context nudges,
+// and node inbox digests share one compact renderer by default.
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import test from 'node:test';
 import { fileURLToPath } from 'node:url';
 import { ContextMessageComponent } from '../render/context-message.js';
+import { CONTEXT_NUDGE_CUSTOM_TYPE, REVIVE_KICKOFF_SENTINEL, generatedContextPresentation, } from '../../../shared/generated-context.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 const CHAT_VIEW = readFileSync(join(HERE, '..', 'render/chat-view.ts'), 'utf8');
 const identity = (s) => s;
@@ -37,10 +28,30 @@ test('the crtr-context label/hint keep their defaults when callers omit the new
     assert.match(line, /\[crtr context\]/);
     assert.match(line, /orienting bearings/);
 });
-test('render/chat-view.ts dispatches the situational customType to the collapsed component, not the generic fallback', () => {
-    assert.match(CHAT_VIEW, /SITUATIONAL_CONTEXT_CUSTOM_TYPE/, 'must reference the constant, not a duplicated literal');
-    const situationalBranch = CHAT_VIEW.slice(CHAT_VIEW.indexOf('customType === SITUATIONAL_CONTEXT_CUSTOM_TYPE'));
-    const nextBraceClose = situationalBranch.indexOf('\n          }');
-    const branchBody = situationalBranch.slice(0, nextBraceClose === -1 ? undefined : nextBraceClose);
-    assert.match(branchBody, /new ContextMessageComponent\(/, 'must render collapsed via the same component crtr-context uses, not CustomMessageComponent');
+test('fresh-revive kickoff and both context-nudge roles classify as generated context', () => {
+    const revive = generatedContextPresentation({
+        role: 'user',
+        content: `${REVIVE_KICKOFF_SENTINEL} — full disk bearings`,
+    });
+    assert.equal(revive?.label, 'crtr revive');
+    assert.equal(revive?.summary, 'fresh context kickoff');
+    const body = '[crtr] Context ~150k. Yield when substantial work remains.';
+    const steered = generatedContextPresentation({ role: 'user', content: body });
+    const held = generatedContextPresentation({
+        role: 'custom',
+        customType: CONTEXT_NUDGE_CUSTOM_TYPE,
+        content: body,
+    });
+    assert.equal(steered?.summary, 'Context ~150k');
+    assert.equal(held?.summary, 'Context ~150k');
+    const inbox = generatedContextPresentation({
+        role: 'user',
+        content: 'From child-node-123 — 2 updates:\n  [update] still working',
+    });
+    assert.equal(inbox?.label, 'crtr inbox');
+    assert.equal(inbox?.summary, '2 updates from child-node-123');
+});
+test('render/chat-view.ts routes the shared generated-context classification through the foldable component', () => {
+    assert.match(CHAT_VIEW, /generatedContextPresentation\(message\)/);
+    assert.match(CHAT_VIEW, /new ContextMessageComponent\(/);
 });

package/dist/clients/attach/__tests__/crtr-output-coverage.test.js

@@ -50,7 +50,7 @@ test('the attach viewer covers crtr bash tool calls and crtr-output messages nat
     const chatView = read(join(ROOT, 'clients', 'attach', 'render/chat-view.ts'));
     assert.match(chatView, /CRTR_OUTPUT_CUSTOM_TYPE/);
     assert.match(chatView, /new CrtrOutputMessageComponent\(/);
-    assert.match(chatView, /createCrtrBashToolDefinition\(args\)/);
+    assert.match(chatView, /createCrtrBashToolDefinition\(args,\s*fold\)/);
     // MinimizableToolComponent is the viewer's ToolExecutionComponent subclass (it
     // adds the Ctrl+O minimized state); the crtr tool definition still threads through it.
     assert.match(chatView, /new MinimizableToolComponent\([\s\S]*toolDefinition as never/);