@north-light/crouter 0.3.330 → 0.3.331

package/dist/builtin-memory/crouter-plugin/INDEX.md

@@ -0,0 +1,12 @@
+---
+kind: knowledge
+when-and-why-to-read: When an application needs to expose operations as crtr commands over HTTP, this knowledge should be read because one typed command definition can provide the handler and install archive without a hand-written manifest drifting from the app.
+short-form: Use @north-light/crouter-plugin to expose an application's typed HTTP operations as crtr commands from one TypeScript command tree.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# `@north-light/crouter-plugin`
+
+Read `crouter-plugin/README` for the authoring overview and the directory pages for the specific plugin surface. The directory listing names every page. Use the directory only to choose a focused page; the reference pages hold the authoring details.

package/dist/builtin-memory/crouter-plugin/README.md

@@ -0,0 +1,25 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Authoring crtr HTTP plugins, this knowledge
+  should be read because `@north-light/crouter-plugin` turns one TypeScript
+  command tree into both a Fetch handler and the archive accepted by `crtr pkg
+  plugin install --endpoint`. Use it when an application should expose typed
+  operations as native `crtr` commands without maintaining `commands.json` or a
+  separate HTTP route definition.
+---
+
+# Authoring crtr HTTP plugins
+
+`@north-light/crouter-plugin` turns one TypeScript command tree into both a Fetch handler and the archive accepted by `crtr pkg plugin install --endpoint`. Use it when an application should expose typed operations as native `crtr` commands without maintaining `commands.json` or a separate HTTP route definition.
+
+Start with the `node_modules/@north-light/crouter-plugin/README.md` for a complete plugin that a developer can paste into an empty file. Then read the page that matches the work at hand:
+
+- [[crouter-plugin/getting-started]] — the deployment and install sequence.
+- [[crouter-plugin/commands]] — command trees and descriptions that let an agent choose a command.
+- [[crouter-plugin/parameters]] — every `param.*` builder and the inferred handler input type.
+- [[crouter-plugin/output]] — every `field.*` builder and handler result validation.
+- [[crouter-plugin/errors]] — `LeafError`, HTTP errors, and NDJSON streaming leaves.
+- [[crouter-plugin/deploying]] — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
+- [[crouter-plugin/bundles-and-memory]] — generating an archive and shipping memory docs.
+
+The package exports only `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, `buildBundle`, `buildCommandManifest`, `createFetchHandler`, `defineBranch`, `defineLeaf`, `definePlugin`, `defineStreamingLeaf`, `field`, `kebab`, and `param`. Those are the complete authoring surface.

package/dist/builtin-memory/crouter-plugin/bundles-and-memory.md

@@ -0,0 +1,32 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Bundles and memory docs, this knowledge
+  should be read because `createFetchHandler` builds and serves the install
+  archive automatically. Use `buildBundle` when you need to inspect or save the
+  generated bytes during an application build. Pass the same mount path where
+  the handler is served.
+---
+
+# Bundles and memory docs
+
+`createFetchHandler` builds and serves the install archive automatically. Use `buildBundle` when you need to inspect or save the generated bytes during an application build. Pass the same mount path where the handler is served.
+
+```ts
+import { writeFile } from 'node:fs/promises';
+import { buildBundle } from '@north-light/crouter-plugin';
+import { plugin } from './crtr-plugin.js';
+
+const bundle = await buildBundle(plugin, { mountPath: '/crtr' });
+await writeFile('commands.json', bundle.commandsJson);
+await writeFile('acme.tar', bundle.tar);
+```
+
+`buildBundle` returns `commandsJson`, `bundleJson`, generated memory members, uncompressed tar bytes, and an ETag. It runs the manifest validator and throws `ManifestInvalidError` when the generated command manifest is invalid. `buildCommandManifest(plugin, { mountPath })` returns the manifest object when archive bytes are not needed.
+
+The tar has exactly `bundle.json`, `commands.json`, and `memory/<name>.md` members for the memory docs declared in `definePlugin`. It does not contain `plugin.json`. For an endpoint install, crouter creates `.crouter-plugin/plugin.json` from the endpoint, `--name`, `--auth-env`, and archive hash.
+
+## Memory docs
+
+Add a `memory` array to `definePlugin` when the app needs to give agents reusable operating knowledge. Each entry has `name`, `kind`, `whenAndWhyToRead`, `body`, and optional `unlisted`. `name` is a safe relative path without the `.md` suffix. The package writes the frontmatter required by the archive installer, so the author supplies no YAML.
+
+`whenAndWhyToRead` is one routing sentence in the form `When <circumstance>, this <kind> should be read because <payoff>.` Keep the body to knowledge the agent needs to use the application. It becomes available under the installed plugin name together with the generated commands.

package/dist/builtin-memory/crouter-plugin/commands.md

@@ -0,0 +1,21 @@
+---
+kind: knowledge
+when-and-why-to-read: "When you need Commands, this knowledge should be read
+  because `definePlugin` declares the top-level crtr command. `name` must be
+  lowercase kebab case. `description`, `whenToUse`, and `summary` are required
+  text for the plugin, every branch, and every leaf. Write them for an agent
+  choosing a command: describe the concrete object or action, state when the
+  command applies, and state the short outcome."
+---
+
+# Commands
+
+`definePlugin` declares the top-level crtr command. `name` must be lowercase kebab case. `description`, `whenToUse`, and `summary` are required text for the plugin, every branch, and every leaf. Write them for an agent choosing a command: describe the concrete object or action, state when the command applies, and state the short outcome.
+
+`rootEntry` describes the top-level command and requires `concept`, `description`, and `whenToUse`. `commands` is an object whose keys are camelCase or lowercase names. The package converts each key to the lowercase kebab name crtr exposes. A key must round-trip, so use `appId` for `app-id`, not a spelling that converts ambiguously.
+
+Use `defineBranch` to group commands and give it `children`. Use `defineLeaf` for a request that returns one object. A leaf requires `params`, `output`, `effects`, and `handler`; `params` may be omitted when the command has no input. `effects` is a non-empty list shown to the agent. Say whether a command mutates an application, creates billable resources, or is read-only.
+
+`defineStreamingLeaf` has the same declaration shape, but its handler returns `AsyncIterable<object>`. It marks the generated REST mapping as streaming and is covered in [[crouter-plugin/errors]].
+
+All command and parameter keys are derived into the manifest. Do not add a route path, HTTP method, REST mapping, or separate manifest to a command definition. The package always generates `POST` with all parameters in the JSON body.

package/dist/builtin-memory/crouter-plugin/deploying.md

@@ -0,0 +1,33 @@
+---
+kind: knowledge
+when-and-why-to-read: "When you need Deployment, this knowledge should be read
+  because `createFetchHandler(plugin, options)` returns `(request: Request) =>
+  Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any
+  framework route that accepts Fetch `Request` and `Response` objects. A
+  framework with different request types needs only an adapter at its boundary;
+  the package itself has no framework dependency."
+---
+
+# Deployment
+
+`createFetchHandler(plugin, options)` returns `(request: Request) => Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any framework route that accepts Fetch `Request` and `Response` objects. A framework with different request types needs only an adapter at its boundary; the package itself has no framework dependency.
+
+The handler serves the archive for every `GET` request and runs a command for a matching `POST` request. It routes a command from the longest matching suffix of the request path, so the same handler works at the origin root, under `/crtr`, and behind a proxy that preserves that path.
+
+## Mount paths
+
+Install the public URL where the handler is mounted. For `https://acme.example.com/crtr`, run `crtr pkg plugin install --endpoint https://acme.example.com/crtr --name acme`. The archive generated for that request declares `/crtr/acme/...` as every `rest.path`.
+
+This prefix is required because crtr stores only `https://acme.example.com` as the command transport endpoint after installation. An archive declaring `/acme/...` for a handler mounted at `/crtr` sends commands to the origin root. Do not use `baseUrl` as a repair; absolute paths replace a base URL path.
+
+Set `baseUrl` only when `request.url` is not the public URL, such as a proxy that rewrites the path or terminates TLS on a different host. Pass the complete public URL, including its mount path, to `createFetchHandler`. The generated `rest.path` must be the public path an agent could request directly.
+
+## Authentication
+
+Pass `token` to require `Authorization: Bearer <token>` on archive and command requests. `--auth-env NAME` tells crtr which environment variable of the calling process holds that value. It does not configure the server. For a command an agent runs, the calling process is its broker, which reads the profile env store (`crtr profile env set <profile> --name NAME`) rather than your shell's exports. Omitting `token` serves without authentication and logs a warning when the handler is created.
+
+## Archive response
+
+The install response is an uncompressed tar with `Content-Type: application/x-tar`. Do not configure a proxy, CDN, or framework middleware to gzip or otherwise compress it. Crtr rejects compressed archive bytes. The handler sends an ETag and supports conditional `If-None-Match` requests automatically.
+
+A non-streaming successful command response is a bare JSON result object. Error responses are JSON error envelopes on non-2xx statuses. See [[crouter-plugin/errors]] for the exact error shape.

package/dist/builtin-memory/crouter-plugin/errors.md

@@ -0,0 +1,42 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Errors and streaming, this knowledge should
+  be read because Throw `LeafError` when an expected application error should be
+  reported to crtr. Its `code` must be lowercase snake case and cannot be
+  `internal`, `unknown_path`, `command_collision`, or `cli_protocol_error`.
+  `status` defaults to `400` and must be an integer from `400` through `599`.
+  Use `field`, `next`, and `received` when they make the fix clearer.
+---
+
+# Errors and streaming
+
+Throw `LeafError` when an expected application error should be reported to crtr. Its `code` must be lowercase snake case and cannot be `internal`, `unknown_path`, `command_collision`, or `cli_protocol_error`. `status` defaults to `400` and must be an integer from `400` through `599`. Use `field`, `next`, and `received` when they make the fix clearer.
+
+```ts
+import { LeafError } from '@north-light/crouter-plugin';
+
+function missingApp(appId: string): never {
+  throw new LeafError({
+    code: 'app_not_found',
+    message: `No application ${appId}.`,
+    status: 404,
+    field: 'app-id',
+    next: 'Run acme app create first.',
+  });
+}
+```
+
+The handler turns that error into a non-2xx response with exactly `{ "error": { "code", "message", "field?", "next?", "received?", "manifest_stale?" } }`. A `400`, `401`, `403`, or `422` response is a crtr usage error; `404` is not found; `409` is ambiguous; other statuses are general errors. `cli_protocol_error` is reserved for crtr itself.
+
+For a non-streaming leaf, an unexpected exception calls `onError(error, commandPath)` when supplied to `createFetchHandler`, then returns status `500` with code `handler_failed`. A streaming handler that throws before it yields its first frame follows the same path. After the first frame starts the `200 application/x-ndjson` response, a later exception calls `onError` and interrupts the response; it cannot send a `handler_failed` envelope or append an error frame. `LeafError({ manifestStale: true })` adds `manifest_stale: true` to the error response. Crtr refetches the archive and replays the original command once, so use it only when the refreshed manifest differs and replaying the command is safe.
+
+A streaming handler declared with `defineStreamingLeaf` returns an async iterable. Each yielded object becomes `JSON.stringify(frame) + '\n'` in an `application/x-ndjson` response. Crtr relays each nonblank line without parsing it, so streaming frames have no package-defined schema and there is no terminal frame to yield. The declared output fields describe frames in command help but are not validated during streaming.
+
+```ts
+async function* lines(): AsyncIterable<object> {
+  yield { line: 'Starting deployment.' };
+  yield { line: 'Deployment complete.' };
+}
+```
+
+Pass `lines` as a `defineStreamingLeaf` handler when the yielded objects match the fields you want agents to see.

package/dist/builtin-memory/crouter-plugin/getting-started.md

@@ -0,0 +1,28 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Getting started, this knowledge should be
+  read because Install `@north-light/crouter-plugin`, copy the complete
+  TypeScript file in the `node_modules/@north-light/crouter-plugin/README.md`,
+  and deploy its default export at the URL crtr will reach. The application must
+  provide `ACME_CRTR_TOKEN` to its handler and the machine running crtr must
+  provide the same value.
+---
+
+# Getting started
+
+Install `@north-light/crouter-plugin`, copy the complete TypeScript file in the `node_modules/@north-light/crouter-plugin/README.md`, and deploy its default export at the URL crtr will reach. The application must provide `ACME_CRTR_TOKEN` to its handler and the machine running crtr must provide the same value.
+
+```bash
+npm install @north-light/crouter-plugin
+export ACME_CRTR_TOKEN='replace-with-a-secret'
+crtr pkg plugin install --endpoint https://acme.example.com/crtr --name acme --auth-env ACME_CRTR_TOKEN
+crtr acme app create my-app --region eu-west
+```
+
+`export` covers commands you type yourself. An agent's `crtr acme …` runs inside its broker, whose env comes from the profile env store, not from your shell — so for agents, store the token there too: `echo -n "$ACME_CRTR_TOKEN" | crtr profile env set <profile> --name ACME_CRTR_TOKEN`. Nodes launched under that profile from then on carry it.
+
+The endpoint receives `GET` to provide the install archive and `POST` to run a command. A successful non-streaming command response is the bare JSON object returned by the handler, for example `{ "appId": "app_my-app", "url": "https://my-app.eu-west.acme.example.com" }`. It is not an exec-style protocol envelope.
+
+Run `crtr pkg plugin show acme` after installation to inspect the installed command tree, and `crtr sys doctor` to check the installed package. A plugin name collision with crtr or another installed plugin is determined during installation and cannot be predicted from an application repository alone.
+
+Continue with [[crouter-plugin/deploying]] before mounting the handler below the origin root or behind a proxy.

package/dist/builtin-memory/crouter-plugin/output.md

@@ -0,0 +1,30 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Output fields, this knowledge should be read
+  because Each leaf declares an `output` object. Field object keys are returned
+  verbatim in the result object, so `appId` stays `appId`; unlike command and
+  parameter keys, output keys are not converted to kebab case.
+---
+
+# Output fields
+
+Each leaf declares an `output` object. Field object keys are returned verbatim in the result object, so `appId` stays `appId`; unlike command and parameter keys, output keys are not converted to kebab case.
+
+| Builder | Required handler value |
+| --- | --- |
+| `field.string(constraint, options?)` | `string` |
+| `field.int(constraint, options?)` | integer `number` |
+| `field.number(constraint, options?)` | `number` |
+| `field.bool(constraint, options?)` | `boolean` |
+| `field.object(constraint, options?)` | object |
+| `field.array(constraint, options?)` | array |
+| `field.markdown(constraint, options?)` | `string` |
+| `field.path(constraint, options?)` | `string` |
+| `field.of(type, constraint, options?)` | `unknown` |
+| `field.nullable(field)` | the wrapped field value or `null` |
+
+Fields are required by default. Pass `{ required: false }` for a field that can be absent. `field.nullable(field.string('...'))` declares a present field that can be `string | null`; it does not make the field optional.
+
+The handler result type is inferred from `output`. TypeScript reports a missing required field or a wrong value type at the `defineLeaf` call. The Fetch handler checks the returned object again before sending it. It rejects missing fields, known type mismatches, and keys that were not declared, returning a non-2xx `handler_output_invalid` error instead of a JSON success response.
+
+`field.of` accepts any non-empty manifest type string. Its handler value is `unknown` because crtr only has built-in runtime checks for its recognized type grammar. Use one of the named builders when the result type is known.

package/dist/builtin-memory/crouter-plugin/parameters.md

@@ -0,0 +1,29 @@
+---
+kind: knowledge
+when-and-why-to-read: "When you need Parameters and handler input, this
+  knowledge should be read because Parameter object keys become handler input
+  keys. The generated manifest uses their kebab-case form: `appId` becomes
+  `app-id`, while the handler receives `input.appId`."
+---
+
+# Parameters and handler input
+
+Parameter object keys become handler input keys. The generated manifest uses their kebab-case form: `appId` becomes `app-id`, while the handler receives `input.appId`.
+
+Every `param.*` builder takes constraint text first. Parameters are optional unless `required: true` is supplied. `repeatable: true` makes a string, integer, enum, or positional parameter an array. It cannot be used with boolean or path parameters. A parameter with `default` remains optional in handler input because crtr applies that default while parsing its command line; the server does not apply it.
+
+| Builder | Handler value | Options |
+| --- | --- | --- |
+| `param.string(constraint, options?)` | `string` | `required`, `repeatable`, `default` |
+| `param.int(constraint, options?)` | `number` | `required`, `repeatable`, `default` |
+| `param.bool(constraint, options?)` | `boolean` | `required`, `default` |
+| `param.enum(choices, constraint, options?)` | a member of `choices` | `required`, `repeatable`, `default` |
+| `param.path(constraint, options?)` | `string` for `encoding: 'text'`, `Uint8Array` for `encoding: 'base64'` | `required`, `encoding` |
+| `param.positional(constraint, options?)` | `string` | `required`, `repeatable` |
+| `param.stdin(constraint, options?)` | `string` | `required` |
+
+`param.positional` is the one positional argument a leaf may have. `param.stdin` receives the command's standard input. `param.path` receives the contents of the local file named by the crtr caller, never the path string. Text is UTF-8. Base64 mode decodes the caller's file bytes into a `Uint8Array` before the handler runs.
+
+The handler input is inferred from the parameter object with no manual annotation. In the `node_modules/@north-light/crouter-plugin/README.md`, `input` is inferred as `{ name: string; region?: 'us-east' | 'eu-west' }`. A required parameter is present, optional parameters can be absent, enum choices remain literal values, and repeatable parameters are arrays.
+
+`definePlugin` checks parameter descriptor objects when the module loads. A malformed hand-built descriptor throws `PluginDefinitionError` at that call. Use the builders instead of constructing descriptor objects.

package/dist/builtin-memory/crouter-sdk/INDEX.md

@@ -0,0 +1,13 @@
+---
+kind: knowledge
+description: Driving a crouter daemon from an application with @north-light/crouter-sdk
+when-and-why-to-read: When you are writing or reviewing application code that runs a crtr agent — installing @north-light/crouter-sdk, constructing a client, creating a node, watching its event stream, reading its result, reading or writing memory, or connecting a browser to a daemon — this reference should be read because `generate()` and `local()` were deleted, while the typed client keeps daemon transport and agent outcomes distinct.
+short-form: The ESM-only application-facing client for a crtrd daemon. Construction and transports, `client.nodes` create/wait/parse/stream, activity snapshots, phase-2 resources including files and bash, `client.memory`, the returned-not-thrown outcome union, and error classes.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# `@north-light/crouter-sdk`
+
+Read `crouter-sdk/README` for the SDK overview and the directory pages for the specific client surface. The directory listing names every page.

package/dist/builtin-memory/crouter-sdk/README.md

@@ -0,0 +1,65 @@
+---
+kind: knowledge
+when-and-why-to-read: "When you need `@north-light/crouter-sdk`, this knowledge
+  should be read because The ESM-only client an application installs to drive a
+  crouter daemon: create agent runs, watch streamed events, wait for typed
+  results, read and write memory, and reach the rest of the daemon's `/v1` API."
+---
+
+# `@north-light/crouter-sdk`
+
+The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, read and write memory, and reach the rest of the daemon's `/v1` API.
+
+One package, one class. `new Crouter()` in Node talks to the owner's unix socket. `new Crouter({ baseURL, token })` in a browser or a remote process talks to the daemon's TCP listener with a bearer token. Resource methods issue `/v1` requests; `createAndWait`, `parse`, and `auth.status` compose more than one request. crtrd stays the sole owner of canvas state.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+
+const run = await client.nodes.parse({
+  prompt: 'Summarize the failing tests in this repo.',
+  cwd: '/path/to/repo',
+  output_schema: z.object({ failures: z.array(z.string()), root_cause: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.root_cause);
+```
+
+## Pages
+
+| Page | Covers |
+|---|---|
+| [[crouter-sdk/getting-started]] | Install, `new Crouter()` on the owner's socket, `client.auth.status()` and `crtr sys connect` for a browser or remote app, Chrome's local-network prompt |
+| [[crouter-sdk/client]] | Every constructor option and its environment-variable fallback; per-request options |
+| [[crouter-sdk/nodes]] | `create` parameters, the outcome union, `parse()` with a zod schema, `waitForOutcome`, `message`, `cancel`, nested resources |
+| [[crouter-sdk/streaming]] | The event table, `stream()` / `events()`, the activity helper, resume with `after`, `stream_gap` and `stream_dropped` |
+| [[crouter-sdk/memory]] | The scope object and every `client.memory` method |
+| [[crouter-sdk/files]] | Absolute-path reads, writes, and one-level lists |
+| [[crouter-sdk/bash]] | One bounded command and its output result |
+| [[crouter-sdk/resources]] | Every namespace with its phase, what is deliberately excluded, and the `client.request()` escape hatch |
+| [[crouter-sdk/errors]] | The error class table and the retry policy |
+| [[crouter-sdk/docker]] | `start()`, `attach()`, `connection()` from `@north-light/crouter-env-docker` |
+| [[crouter-sdk/migration]] | Moving off `generate()` and `local()` — a hard cut, with before/after |
+
+## Phases
+
+The surface ships in three cuts. Phase 3 memory methods are shipped.
+
+| Phase | What lands | State |
+|---|---|---|
+| **Phase 1** | Client construction and transports; `client.auth.status()`; `client.nodes.create`, `retrieve`, `list`, `outcome`, `waitForOutcome`, `createAndWait`, `parse`, `message`, `cancel`, and `interrupt`; `nodes.reports.list`; `profiles.ensure` and `retrieve`; `system.status` and `health`; the error hierarchy; per-request options; `crtr sys connect`; and `env-docker.connection()` | Shipped |
+| **Phase 2 namespaces** | Node lifecycle, job, worktree, and result; canvas and canvas history; crons; human requests and inbox; models; `client.files.read` through `/v1/files/peek`, `write`, and `list`; and `client.bash.run` | Shipped |
+| **Phase 2 streaming** | `GET /v1/nodes/{id}/events`, `nodes.stream(params, options?)`, `nodes.events(id, options?)`, `NodeStream`, and the activity helper | Shipped |
+| **Phase 3** | Memory routes and `client.memory`, plus the review, comment, and chat-inventory namespaces | Memory shipped; remaining namespaces not shipped |
+
+The per-run `scopes` create field ships in phase 1. `nodes.update` scope support remains phase 2 and is not in the shipped client or wire declarations.
+
+## Verification status
+
+The SDK declarations, streaming examples, and memory examples are verified.
+
+## Where the agents read this
+
+The same content routed for agents lives in the builtin memory document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr memory read crouter-sdk` and does not need this repository checked out.

package/dist/builtin-memory/crouter-sdk/bash.md

@@ -0,0 +1,41 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need `client.bash`, this knowledge should be read
+  because `client.bash.run` executes one bounded `bash -c` command through the
+  daemon.
+---
+
+# `client.bash`
+
+`client.bash.run` executes one bounded `bash -c` command through the daemon.
+
+```ts
+const result = await client.bash.run({
+  command: 'printf "%s\\n" "$MESSAGE"',
+  cwd: '/absolute/path/to/project',
+  env: { MESSAGE: 'hello' },
+  timeout_s: 30,
+  profile: 'my-app',
+});
+
+if (result.exit_code !== 0) console.error(result.stderr);
+```
+
+`run(params, options?)` returns `Promise<BashRunDTO>`. Its final `options` object is the normal request-options object: `headers`, `signal`, `timeout`, and `maxRetries`.
+
+| Result field | Type | Meaning |
+|---|---|---|
+| `exit_code` | `number \| null` | Process exit code, or `null` after a timeout. A non-zero code is returned, not thrown. |
+| `signal` | `string \| null` | Signal that ended the process, when one did. |
+| `stdout` / `stderr` | `string` | Captured output prefix. |
+| `stdout_truncated` / `stderr_truncated` | `boolean` | Whether that output stream exceeded its 256 KiB capture limit. |
+| `timed_out` | `boolean` | `true` after the daemon terminates the process group for a timeout. |
+| `duration_ms` | `number` | Command duration in milliseconds. |
+
+`cwd` is required, absolute, and must name an existing directory. The daemon never uses its own working directory as a fallback. `timeout_s` defaults to 60, must be greater than 0, and cannot exceed 600. The SDK keeps the HTTP request open for the command timeout plus 15 seconds, unless its configured request timeout is already longer.
+
+Pass dynamic values through `env` and reference them from the command as `"$NAME"`, rather than interpolating them into shell source. The command receives the daemon's default-deny operational environment, selected profile environment, then your `env` values.
+
+## Authority
+
+The token is the owner credential. Anyone holding it can already create an agent with a bash tool, so this command runs with the daemon user's authority and does not provide a restricted command area.

package/dist/builtin-memory/crouter-sdk/client.md

@@ -0,0 +1,98 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Client construction, this knowledge should
+  be read because `Crouter` is the default export and the only class an
+  application constructs. `CrtrClient` from `@north-light/crouter-api` is an
+  implementation detail and is not re-exported.
+---
+
+# Client construction
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+
+const localClient = new Crouter();                                          // owner's own daemon, unix socket
+const remoteClient = new Crouter({ baseURL: 'http://localhost:8787', token: 'token' }); // TCP with a bearer token
+const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }); // an explicit socket
+```
+
+`Crouter` is the default export and the only class an application constructs. `CrtrClient` from `@north-light/crouter-api` is an implementation detail and is not re-exported.
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `baseURL` | `string` | `CRTR_BASE_URL`, else unset | `http(s)://host:port` of a daemon TCP listener. |
+| `socketPath` | `string` | `CRTR_SOCKET`, else `${CRTR_HOME}/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock` | Unix socket. Node only; throws in a browser. |
+| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
+| `timeout` | `number` (ms) | `30_000` | Per-request wall clock. Does not apply to a stream. |
+| `maxRetries` | `number` | `2` | Transient-failure retries. Never applied to `POST` or `PATCH` — see [[crouter-sdk/errors]]. |
+| `defaultHeaders` | `Record<string, string>` | `{}` | Merged into every request. |
+| `headers` | `Record<string, string>` | unset | Merged after `defaultHeaders`; a matching name wins unless `token` is set, in which case the generated `Authorization` header wins at construction. |
+| `fetch` | `typeof fetch` | global `fetch`, or the socket implementation when `socketPath` is used | Transport override, for proxies and instrumentation. |
+| `autostart` | `boolean` | `true` for a socket, `false` for `baseURL` | On a cold socket, run `crtr sys daemon start` and retry once. Node only. |
+
+### Environment-variable fallbacks
+
+Every fallback above is read at construction, not at request time.
+
+| Variable | Fills |
+|---|---|
+| `CRTR_BASE_URL` | `baseURL` |
+| `CRTR_SOCKET` | `socketPath` |
+| `CRTR_HOME` | the directory the default socket path is resolved under (`$CRTR_HOME/crtrd.sock`) |
+| `CRTRD_TOKEN` | `token` |
+
+An explicit option always beats its environment variable.
+
+## Transport selection
+
+`baseURL` wins if it is set; otherwise `socketPath`; otherwise the default socket path. **Passing both `baseURL` and `socketPath` throws `TypeError` at construction** — exactly one transport per client. In a browser, `new Crouter({})` has no daemon transport; give it the saved `baseURL` and token before making requests.
+
+There is one request path. The client issues every request through the Web `fetch` API, which a browser and Node both supply globally. The unix socket is not a second transport — it is a `fetch` implementation the SDK installs when `socketPath` is set, built on `node:http` with `{ socketPath }`, returning a standard `Response` whose `body` is a `ReadableStream`. Streaming, abort, headers, and error parsing therefore have exactly one implementation, and the browser build never sees Node code.
+
+## Autostart
+
+With `autostart` on (the default for a socket), a request that finds a cold socket runs `crtr sys daemon start`, waits for the daemon to serve, and retries the request once. This is what makes `npm i -g @north-light/crouter` followed by `new Crouter()` work on a machine that has never run the daemon.
+
+Autostart is Node-only and applies only to the socket transport. A `baseURL` client cannot start a daemon it may not even share a machine with, so `autostart` defaults to `false` there; setting it to `true` on a `baseURL` client throws `CrouterError` (`autostart is only valid for the local socket transport`).
+
+## Per-request options
+
+Every request-capable method accepts an options object as its last argument, after any path, body, or query arguments. Each field overrides the client-level default for that one request.
+
+```ts
+const id = 'example-node';
+const signal = new AbortController().signal;
+
+await client.nodes.retrieve(id, {
+  signal,                       // AbortSignal — real cancellation, passed straight to fetch
+  timeout: 5_000,               // ms, this request only
+  maxRetries: 0,                // this request only
+  headers: { 'x-trace': 't-9' } // merged over defaultHeaders
+});
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `signal` | `AbortSignal` | Aborts the underlying `fetch`. Raises `APIUserAbortError`. |
+| `timeout` | `number` (ms) | Overrides the client `timeout`. |
+| `maxRetries` | `number` | Overrides the client `maxRetries`. |
+| `headers` | `Record<string, string>` | Merged over `defaultHeaders`, client `headers`, and the token-generated header; a matching name, including `Authorization`, wins. |
+
+`signal` is real cancellation. The long-polling helpers (`waitForOutcome`, `createAndWait`, `parse`) honour it between polls and during the in-flight request, and aborting them stops the client — it does not cancel the node. To stop the run itself, call `client.nodes.cancel(id)` or `client.nodes.interrupt(id)`. Streams use `NodeEventsOptions`: the same fields except `timeout`, plus `after` for `nodes.events`; see [[crouter-sdk/streaming]].
+
+## What is not on the client
+
+| Convention | Why it is absent |
+|---|---|
+| `.withResponse()` / `.asResponse()` | They exist to hand back the raw `Response` and an `x-request-id`. The daemon emits no request id, and a caller who needs raw bytes uses `client.request()`. |
+| `local()` and the `Environment` interface | Deleted. The client *is* the connection — `new Crouter()` covers what `local()` did. See [[crouter-sdk/migration]]. |
+| `apiKey` | The daemon's credential is a token (`CRTRD_TOKEN`) everywhere in the product. `apiKey` would be a second name for one thing. |
+| Resource-prefixed ids | Node ids have their own format. The SDK validates unsafe path identifiers locally with `TypeError`, and the daemon validates the request too; nothing is re-prefixed. |
+
+## Wire naming
+
+Wire fields are `snake_case` — `output_schema`, `root_lifecycle`, `pin_cwd`, `final_report_path`. The SDK does not camelize them. Namespaces and method names are camelCase (`client.nodes.waitForOutcome`, `client.nodes.worktree`).
+
+Timestamps are ISO-8601 strings (`created`, `settled_at`, `finalized_at`, `deadline_at`), not Unix seconds.

package/dist/builtin-memory/crouter-sdk/docker.md

@@ -0,0 +1,72 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Docker environment, this knowledge should be
+  read because `@north-light/crouter-env-docker` runs a crouter daemon in a
+  container and tells you how to reach it. It is a separate package because
+  container lifecycle is real work the SDK does not otherwise do — and it **has
+  no dependencies**, including on the SDK itself.
+---
+
+# Docker environment
+
+Phase 1.
+
+`@north-light/crouter-env-docker` runs a crouter daemon in a container and tells you how to reach it. It is a separate package because container lifecycle is real work the SDK does not otherwise do — and it **has no dependencies**, including on the SDK itself.
+
+```bash
+npm i @north-light/crouter-env-docker
+```
+
+## Starting a container and connecting to it
+
+```ts
+import { start } from '@north-light/crouter-env-docker';
+import Crouter from '@north-light/crouter-sdk';
+
+const env = await start({ volume: 'my-agent-home' });
+const client = new Crouter(env.connection());
+
+await client.nodes.create({ prompt: 'Do the thing.', root: true });
+
+await env.stop();
+```
+
+`connection()` returns `{ baseURL, headers }` — exactly the shape the `Crouter` constructor takes, so the result passes straight through with no adapter.
+
+## Methods
+
+| Method | What it does |
+|---|---|
+| `start(opts?)` | Starts a container running `crtrd` and returns an environment handle. |
+| `attach(name)` | Returns a handle for the already-running container named `name`. |
+| `stop()` | On a `start()` handle, stops and removes the container. On an `attach()` handle, stops it without removing it. |
+| `connection()` | `Connection` (`{ baseURL: string; headers?: Record<string, string> }`) — returned synchronously and passed to `new Crouter()`. |
+
+| `start()` option | Type | Default | Effect |
+|---|---|---|---|
+| `image` | `string` | `ghcr.io/vallum-security/crtrd:latest` | Image to run. |
+| `env` | `Record<string, string>` | unset | Extra container environment variables; they are not logged. |
+| `name` | `string` | generated name | Container name for later `attach(name)`. |
+| `volume` | `string` | unset | Named volume mounted at `/home/agent/.crouter`. |
+| `port` | `number` | Docker-assigned port | Host port bound on `127.0.0.1`. |
+
+## `connection()` replaced `daemon()`
+
+`daemon()` is gone, along with the package's `Environment` type. The new name says what the method returns, and its field is spelled `baseURL` to match the constructor option rather than `baseUrl`.
+
+```text
+// before
+const env = await start({ volume: 'my-agent-home' });
+const { baseUrl, headers } = await env.daemon();
+const client = new CrtrClient({ baseUrl, headers });
+
+// after
+const env = await start({ volume: 'my-agent-home' });
+const client = new Crouter(env.connection());
+```
+
+`connection()` is typed structurally — `{ baseURL: string; headers?: Record<string, string> }` — which is how the package stays dependency-free while producing something the SDK accepts directly.
+
+## The volume is the agent's home
+
+The `volume` you pass is the container's canvas home: nodes, transcripts, artifacts, memory, and profiles all live there. Reuse the same volume across `start` calls and the agent keeps everything it learned; use a fresh one and it starts from nothing. `start()` mounts an existing named volume unchanged; it does not inspect or reject it based on the crouter version that last wrote it.