@north-light/cli 0.0.0-stage → 0.3.413

package/docs/concepts/scopes-and-trust.md

@@ -0,0 +1,39 @@
+---
+title: Scopes and trust
+description: When giving an application or node less authority, read this because a scope list is an allow-list enforced by the daemon and a bearer token can set the maximum authority for every run it creates.
+---
+
+# Scopes and trust
+
+Use scopes to give a node or remote application only the authority it needs. A node carries a scope list; a scoped bearer token carries a ceiling. Omitting a node scope list gives it the inherited runtime vocabulary. Supplying one narrows that authority. A token cannot create a node with scopes outside its own ceiling.
+
+Scope strings are prefixed with `crtr:`. These are the ones the daemon and CLI check:
+
+| Scope | It gates |
+|---|---|
+| `crtr:llm` | Daemon-mediated model calls (`POST /v1/llm`) and starting a run |
+| `crtr:act` | Creating, forking, reviving, closing and messaging nodes; `bash` and `files`; creating a human request or review (the `crtr human` commands are hidden from a run without it) |
+| `crtr:schedule` | Creating, pausing, resuming, running and deleting crons (the `crtr cron` commands are hidden without it) |
+| `crtr:memory:read:user[:path]`, `crtr:memory:rw:user[:path]`, `crtr:memory:manage:user` | The person's documents: reading, writing (`crtr doc`), and `manage` for every privacy level and every document |
+| `crtr:memory:read:app:<id>`, `crtr:memory:rw:app:<id>` | Another app's documents; `…:profile:<profile>` narrows to one of its profiles |
+| `crtr:files:read\|rw:user:<dir>`, `crtr:files:read\|rw:app:<id>:<dir>`, `crtr:files:share` | Host files the run may mount, and sharing files beyond the app's own space |
+| `crtr:conversations:read:app:<id>`, `crtr:objects:read:app:<id>` | Reading another app's conversations or node objects |
+| `<provider>:<group>` | One tool group of a provider |
+
+The `memory` in `crtr:memory:*` is the scope family's name for access to **documents** (see [Documents](./documents.md)); there is no separate memory store. The older short names (`ask`, `act`, `schedule`, `memory:read`, `memory:write`, `llm`) are not accepted by `crtr sys connect --scopes`. A node's own documents, and an app's documents for its own nodes, need no `crtr:memory` scope.
+
+This is an allow-list, not a claim that code will behave. The daemon checks the scope at the route that performs the action and rejects an unavailable one. The SDK’s [`nodes.create`](../sdk/nodes.md) `scopes` field narrows a run: a run's list must stay inside what its creator and grant hold, and `crtr:act` requires `crtr:llm`. `client.memory` is not scope-gated: it lists and reads the person's `knowledge` and `preference` documents, and the answer is filtered by privacy — an app sees `public` documents, and a grant holding `crtr:memory:manage:user` also sees `friends` and `private` ones. Who may read any document is the owner-and-privacy model, not a per-call scope.
+
+```mermaid
+flowchart LR
+  Token[Bearer token ceiling] --> Request[SDK request]
+  Request --> Daemon[crtrd]
+  Daemon -->|within ceiling| Node[Node with narrowed scopes]
+  Daemon -->|outside ceiling| Denied[403 scope_denied]
+```
+
+Scopes rely on a more basic trust boundary: `crtrd` is the sole writer of durable canvas state and the sole owner of broker lifecycle. SDK clients, the CLI, and viewers call its API; they do not open the canvas database or launch their own broker. One owner serializes lifecycle changes, makes the same API usable locally and remotely, and keeps a client from silently creating a second state authority.
+
+For a browser or remote process, run `crtr sys connect`. It enables the daemon’s TCP listener when needed and returns `base_url` plus a bearer `token` to give the application. `crtr sys connect --app <id> --scopes …` mints a new scoped token for that app instead of returning the owner token; `--scopes` requires `--app`, and accepts `crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:read:user`, `crtr:memory:read:app`, `crtr:memory:rw:app`, `crtr:files:read:user:.` and `crtr:files:rw:user:.`. Treat either token as a credential: the remote app sends it as `Authorization: Bearer <token>`, and its scope list is the ceiling for scope-gated calls and newly created nodes.
+
+The remote API is an explicit boundary, not permission to reach around it. Keep application code on the SDK or `/v1` contract, and let the daemon own state transitions. Run `crtr canvas read internal/nodes-and-canvas` for the operational ownership model.

package/docs/concepts/why-a-daemon.md

@@ -0,0 +1,29 @@
+---
+title: Why a daemon
+description: When deciding how an application should host or reconnect to an agent, read this because the daemon keeps the durable canvas and broker lifecycle in one place while terminals and SDK clients come and go.
+---
+
+# Why a daemon
+
+A terminal is not an agent host. A broker is the detached process that hosts one node’s agent engine and session; a viewer is only a terminal presentation attached to that broker. The daemon, `crtrd`, owns the durable canvas and starts, stops, and recovers brokers. This separation lets a node continue after the terminal that created or displayed it has gone away.
+
+```mermaid
+flowchart LR
+  CLI[crtr CLI] --> API["/v1 API"]
+  SDK[SDK application] --> API
+  Viewer[Terminal viewer] --> API
+  API --> Daemon[crtrd]
+  Daemon --> Canvas[Canvas state]
+  Daemon --> Broker[Detached broker]
+  Viewer -. live session .-> Broker
+```
+
+The broker has one job: host a node’s agent session. The daemon has the broader job: preserve the node graph, state transitions, waits, reports, and broker lifecycle. A viewer may stream a broker’s live session, but it does not become the authority that decides whether that node is active, dormant, or revived. Closing a viewer closes a view, not the node’s durable identity.
+
+This is why a process crash is recoverable rather than an automatic loss of work. The daemon retains the node row, session information, context directory, documents, waits, and inbox state, then applies recovery to the broker execution. A later wake or explicit revival can continue the node’s saved conversation. The application should create nodes through [`client.nodes`](../sdk/nodes.md), not start an LLM process itself, because the daemon is the component that keeps the engine and durable canvas state coordinated.
+
+The costs are real. A daemon must be running, and canvas state has one home instead of being scattered across terminals and application processes. Local clients use its owner-only Unix socket. Remote clients use its configured TCP listener and bearer token. A network interruption can therefore fail a mutation loudly rather than encouraging a client to replay it and risk doing the action twice.
+
+Those costs buy a simpler model: one state owner, one broker launcher, and clients that can reconnect. A CLI command, an SDK application, and a terminal viewer all use the same API for canvas state. They can come and go without creating competing writers or losing the graph that explains what each agent is doing.
+
+For the lower-level runtime model, run `crtr canvas read internal/nodes-and-canvas`. For a complete remote application setup, start with the SDK [getting started guide](../sdk/getting-started.md).

package/docs/plugin/README.md

@@ -0,0 +1,20 @@
+---
+title: Plugin overview
+description: Expose application operations as native crtr commands with a typed HTTP plugin.
+---
+
+# Authoring crtr HTTP plugins
+
+`@north-light/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 [package README](../../packages/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:
+
+- [Getting started](getting-started.md) — the deployment and install sequence.
+- [Commands](commands.md) — command trees and descriptions that let an agent choose a command.
+- [Parameters and handler input](parameters.md) — every `param.*` builder and the inferred handler input type.
+- [Output](output.md) — every `field.*` builder and handler result validation.
+- [Errors and streaming](errors.md) — `LeafError`, HTTP errors, and NDJSON streaming leaves.
+- [Deployment](deploying.md) — Fetch frameworks, mount paths, proxies, authentication, and archive compression.
+- [Bundles and documents](bundles-and-memory.md) — generating an archive and shipping agent-facing documents.
+
+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/docs/plugin/bundles-and-memory.md

@@ -0,0 +1,28 @@
+---
+title: Bundles and documents
+description: Generate install archives and include agent-facing documents in a plugin through its `memory` array.
+---
+
+# Bundles and documents
+
+`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/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 documents declared in the `memory` array of `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.
+
+## Documents in the `memory` array
+
+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. When the plugin is installed, crouter imports each entry as a public, read-only document owned by an app named after the plugin (an installed plugin is an app on the canvas), together with the generated commands. An agent reads it with `crtr canvas read <plugin>/<name>`, and `whenAndWhyToRead` becomes the document's preview. The `memory` array and `whenAndWhyToRead` are the plugin API's names; the result is an ordinary canvas document.

package/docs/plugin/commands.md

@@ -0,0 +1,22 @@
+---
+title: Commands
+description: Define plugin command trees, branches, leaves, and agent-facing descriptions.
+---
+
+# 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.
+
+A leaf may declare `group`, the capability-provider tool group it belongs to. A group matches `[A-Za-z0-9_-]{1,64}`, and `definePlugin` throws `PluginDefinitionError` naming the leaf for anything else. `buildCommandManifest` writes the group onto the leaf; a local install ignores it. The group's consent line and rate are set in the directory console, not in the plugin. `sideEffect: true` marks a leaf whose tool has a side effect, so a repeated request must not run it twice. It is never written into the manifest.
+
+`definePlugin` accepts `version`, the plugin's integer major (at least 1), written into both `commands.json` and `bundle.json`; a plugin without one is treated as major 1. `provider: true` marks a capability provider registered in the directory. It requires `version`, and it requires a `group` on every leaf: `definePlugin` throws naming the first leaf without one.
+
+A branch or leaf may set `tier` to `common` or `important` to be promoted into its parent's `-h`. A command with more than 40 children lists only its promoted children in its own `-h`, followed by the count of the rest; the others still run and answer `-h` by name. Use this when a plugin mounts one command per entry of a large catalog. On such a command only promoted leaves reach the top-level `crtr -h`; a promoted branch shows in the command's own `-h`.
+
+`defineStreamingLeaf` has the same declaration shape, but its handler returns `AsyncIterable<object>`. It marks the generated REST mapping as streaming and is covered in [Errors and streaming](errors.md).
+
+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/docs/plugin/deploying.md

@@ -0,0 +1,34 @@
+---
+title: Deployment
+description: Serve plugin Fetch handlers with authentication, mount paths, and archive compression.
+---
+
+# 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.
+
+A capability provider registered in the directory passes `auth: {issuer, audience}` instead of `token`; passing both throws. `issuer` is the directory's issuer URL and `audience` is the provider's endpoint URL exactly as registered. Every command request's bearer must be an outbound token the directory minted. The handler verifies it with `@north-light/identity`: it fetches the JWKS from `<issuer>/.well-known/jwks.json`, caches it, and refetches once when a token names an unknown `kid`. It checks the signature, `iss`, `aud` (exact match, so a trailing slash differs) and `exp`. A failed check answers 401 `unauthorized`. Next the called leaf's `<plugin>:<group>` must be in the token's `scope`. If it is not, the handler answers 403 `scope_missing` with that string in both `field` and `received`. A command request under `auth` must also carry `Crtr-Request-Id`. Every leaf then gets `ctx.caller`: `{sub, grantee, clientId, scope, initiatingApp, act, jti, requestId, runId?}`. `act` and `initiatingApp` are for your audit; the kit authorizes nothing on them. The archive and `GET /versions` stay public under `auth`. For local development, point `issuer` at a test issuer that serves `/.well-known/jwks.json`.
+
+## Major versions
+
+A definition with `version: N`, or a list of definitions with one per supported major, is served per major. Each major N is mounted under `<mount>/v<N>/`, and its archive at `GET <mount>/v<N>/` declares `/v<N>` routes. `GET <mount>/versions` answers `{latest, supported}`. An unversioned single definition keeps the unversioned paths above. With `baseUrl`, pass the endpoint without any `/v<N>` segment.
+
+## 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 [Errors and streaming](errors.md) for the exact error shape.

package/docs/plugin/errors.md

@@ -0,0 +1,39 @@
+---
+title: Errors and streaming
+description: Report expected application errors and return NDJSON streams from command leaves.
+---
+
+# 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`.
+
+The codes `unauthorized`, `scope_missing`, and `approval_required` have fixed meanings in a capability-provider call, and only the kit emits them. Constructing a `LeafError` with one of those codes throws `PluginDefinitionError`. A provider refusing a call by its own rule throws `provider_refused`; its status is always `403`, whatever `status` says. `question` carries the question of an `approval_required` error, is serialized in the error body, and is refused on any other code. Use `field`, `next`, and `received` when they make the fix clearer.
+
+```ts
+import { LeafError } from '@north-light/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?", "question?" } }`. 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/docs/plugin/getting-started.md

@@ -0,0 +1,23 @@
+---
+title: Getting started
+description: Install the plugin package, deploy a Fetch handler, and install its commands in crtr.
+---
+
+# Getting started
+
+Install `@north-light/plugin`, copy the complete TypeScript file in the [package README](../../packages/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/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 [deployment](deploying.md) before mounting the handler below the origin root or behind a proxy.

package/docs/plugin/output.md

@@ -0,0 +1,51 @@
+---
+title: Output fields
+description: Declare typed output fields and validate handler results.
+---
+
+# 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(children, constraint?, options?)` | an object typed from `children` |
+| `field.object(constraint, options?)` | any object |
+| `field.array(item, constraint?, options?)` | an array of the `item` field's value |
+| `field.array(constraint, options?)` | any array |
+| `field.enum(values, constraint, options?)` | a member of `values` |
+| `field.file(constraint, options?)` | `{ upload_id, size, sha256 }` (the caller sees a path) |
+| `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`, including structured members and elements. TypeScript reports a missing required field or a wrong value type at the `defineLeaf` call. `definePlugin` throws `PluginDefinitionError` for a malformed structured field, a file field that is not top-level, or a second file output. The Fetch handler checks the returned object's top-level fields 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. It does not look inside objects or arrays, so their members are checked only by TypeScript.
+
+## Structured fields
+
+`field.object({ ... })` types an object's members. Each member is a `field.*` builder, and members can be structured themselves. `field.array(field.string('A tag.'))` types each element; the element's `required` is ignored and the array's constraint defaults to the element's. `field.enum(['open', 'closed'], 'Thread state.')` restricts a string to fixed values, which the handler sees as literal types. The generated manifest carries the whole shape: object members as ordered `children`, an array element as `items`, enum `values`. `crtr` command help renders it. `field.nullable` keeps the members, element, or values of the field it wraps.
+
+```ts
+output: {
+  thread: field.object({
+    id: field.string('Thread id.'),
+    state: field.enum(['open', 'closed'], 'Thread state.'),
+  }, 'The thread.'),
+  messages: field.array(field.object({ body: field.string('Message text.') }), 'Messages, newest first.'),
+}
+```
+
+The older `field.object('...')` and `field.array('...')` forms still declare an untyped object or array.
+
+## File output
+
+`field.file(constraint, options?)` declares a leaf's file output. A file output must be a top-level field, never an object member or array element, and a leaf may declare only one. It is optional by default, since a result may omit its file. When a capability provider is called, the request carries an upload link in the `Crtr-Upload-Link` header and its id in `Crtr-Upload-Id`. The handler PUTs the bytes to that link and returns `{ upload_id, size, sha256 }`, with `size` in bytes and `sha256` as a hex digest. The runtime fetches the file and replaces the field with its path. The same `field.file` builder declares a file parameter; see [Parameters](parameters.md).
+
+`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/docs/plugin/parameters.md

@@ -0,0 +1,29 @@
+---
+title: Parameters and handler input
+description: Declare command parameters and infer their handler input types.
+---
+
+# 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, path, or file 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.file(constraint, options?)` (same as `field.file`) | `string` | `required` |
+| `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.
+
+`param.file` declares a file parameter. The agent passes a runtime path. When a capability provider is called, the runtime uploads a copy and the handler receives a signed `https` download link as a string, valid for 15 minutes. The file's name is the link's last path segment. With a local `--endpoint` install, the handler receives the string the agent typed. Unlike `param.path`, the handler never receives the file contents inline. `param.file` and `field.file` return the same descriptor, so either works in `params`.
+
+The handler input is inferred from the parameter object with no manual annotation. In the [package README sample](../../packages/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/docs/public-api.md

@@ -0,0 +1,75 @@
+# `crouter` public API
+
+This is a pointer document, not a second source of truth. The canonical
+surface is `package.json#exports` plus the two source barrels it points at —
+read this file to know WHERE to look, not to get a duplicated symbol list that
+can drift.
+
+## Supported import surfaces
+
+`package.json#exports` gates the package to exactly three subpaths. Nothing
+else resolves — deep imports into `dist/` or `src/` are unsupported and will
+break without notice across versions.
+
+| Import specifier | Source barrel | Purpose |
+|---|---|---|
+| `crouter` | `src/index.ts` → `dist/index.js` | The one sanctioned library surface: runtime control (`spawnChild`, `reviveNode`, `closeNode`, `appendInbox`), canvas reads (`getNode`, `listNodes`, `nodeDir`, `asksForNodes`, `readTelemetry`, …), the broker socket client (`ViewSocketClient`), the broker wire protocol (frame types + codec), and a small set of side-effect-free utilities (see below). |
+| `crouter/cli` | `src/cli.ts` → `dist/cli.js` | The `crtr` CLI entrypoint. Not a library API — invoked as a program, not imported for its exports. |
+| `crouter/api` | `src/api/index.ts` → `dist/api/index.js` | The dependency-light crtrd API surface: typed `CrtrClient`, route constants, errors, and DTOs. |
+
+The library barrels declare no load-time side effects and no circular imports —
+importing them is safe to do speculatively.
+
+## Root-barrel surface, by area
+
+Read `src/index.ts` for the exact current export list (it is short and
+comment-organized); this table is the map, not the inventory:
+
+- **Runtime control** — `spawnChild`, `reviveNode`, `closeNode`,
+  `appendInbox`, `appendSituationalContext` (+ their result/opts types).
+  `reviveNode` is the only sanctioned launcher of a node's broker engine; do
+  not construct a broker process out-of-band. `appendSituationalContext`
+  upserts a node's hidden ambient "current situation" text without exposing
+  the underlying storage file.
+- **Canvas reads** — `getNode`, `listNodes`, `nodeDir`, `asksForNodes`,
+  `asksAcrossCanvas`, `readTelemetry`, `readContextTokens` (+ their types).
+  Read-only queries against the canvas.db-backed node graph.
+- **Broker client** — `ViewSocketClient`, `BrokerUnavailableError`. A typed
+  client for a node's `view.sock`. A consumer that would rather not depend on
+  this class can speak the frame protocol directly over the socket path
+  `crtr sys version` reports.
+- **Broker wire protocol** — `encodeFrame`, `FrameDecoder`,
+  `FrameOverflowError`, `CLIENT_READ_CAPS`, `BROKER_READ_CAPS`, and every
+  frame/protocol type (`WelcomeFrame`, `AckFrame`, `HelloFrame`,
+  `ReloadAuthFrame` is intentionally NOT re-exported by name here but is
+  covered as a documented wire contract — see the compat note).
+- **Command-manifest compatibility** — `validateCommandManifest` and its `CommandManifestValidation`, `ValidatedCommandManifest`, `CommandManifestIssue`, and `TransportKind` types validate an HTTP or exec plugin command manifest without I/O. `SUBTREE_NAMES` is the readonly core-root-name list used as the validator’s reserved-name set.
+- **Utility exports** — `general` (an error constructor from
+  `core/errors.js`; the type `CrtrError` is exported type-only) and `nowIso`
+  (an ISO-timestamp helper from `core/fs-utils.js`). Both are plain,
+  side-effect-free functions over Node builtins. No other error helper
+  (`notFound`, `usage`, `ambiguous`, `network`, `notImplemented`) is exported
+  — construct a `general(message, details)` error instead if you need one
+  from outside the package.
+
+## What is NOT public
+
+- Anything under `src/commands/`, `src/daemon/`, `src/core/canvas/*` (writer
+  paths), or any file not reachable from one of the three barrels above.
+- Deep imports (`crouter/dist/...`, `crouter/src/...`)
+  — the `exports` map blocks these at resolution time for ESM/Node16
+  consumers; treat any working deep import as an accident, not a contract.
+
+## External runtime contracts (not library imports)
+
+A consumer that runs alongside crtr (a separate process, a separate repo)
+also has a CLI/socket/schema surface to depend on instead of an import:
+`crtr sys version`, `crtr node message send`, the broker `view.sock`
+`reload_auth` subset, and the canvas.db byte-shape. Each of those is versioned
+by the CLI's own `sys version` output rather than by a document here.
+
+## Packaging
+
+`docs/` is listed in `package.json#files`, so this note ships inside the
+published npm package, not only in the GitHub repo. Compiled tests under
+`dist/**/__tests__/` are excluded from the tarball.

package/docs/release-local.md

@@ -0,0 +1,8 @@
+# Manual crouter npm release
+
+Use this only for a release explicitly authorized by Silas. `.github/workflows/publish.yml` is the source of truth; this is its manual path when Actions cannot run. Work on clean, current `main`, with `npm whoami` showing the publishing account. Verify the code first (`npm run build:api`, `npm run build`, `npx tsc --noEmit`, relevant `npm run test:isolated -- …`). Do not start a release while another agent owns uncommitted changes in this shared checkout.
+
+1. Check the six latest registry versions with `npm view <name> version` for each of `crouter`, `@north-light/api`, `@north-light/env-docker`, `@north-light/identity`, `@north-light/sdk` and `@north-light/plugin`. Fetch `origin/main`, ensure the release commit is current, and choose a patch version greater than every published version. Do **not** use the workflow's `git reset --hard` in a shared checkout.
+2. Run `node scripts/release-version.mjs "$VERSION"`. It sets all six manifests to `$VERSION`, pins every dependency between them (root → identity, SDK → api and identity, plugin → api and identity) to exactly `$VERSION` with no `^`, writes `SDK_VERSION` in `packages/crouter-sdk/src/version.ts`, the oldest runtime that SDK accepts, and renames the `## Next release` section of `docs/sdk/release-notes.md` to `## $VERSION`. One release is one version set: an app pinning `@north-light/sdk@$VERSION` gets exactly this release's api and identity. Run `npm install --package-lock-only --ignore-scripts`, then `node scripts/release-version.mjs --check` (prints `one version set`). Check `git diff` and commit only the six manifests, `packages/crouter-sdk/src/version.ts`, `docs/sdk/release-notes.md` and `package-lock.json` as `chore: release v$VERSION`. Create `git tag -a "v$VERSION" -m "chore: release v$VERSION"`, then `git push --atomic origin HEAD:main "refs/tags/v$VERSION"`. If rejected due to a concurrent push, remove the *local* release tag, integrate fresh main, then recheck versions and retry; never push a tag separately.
+3. From the tagged release commit run `npm ci`. Publish in dependency order, checking `npm view "$PACKAGE@$VERSION" version` before each and skipping only on a positive sighting: `npm run build:identity` then `npm publish` in `packages/crouter-identity`; `npm run build` then `CRTR_PACK_MINIFY=1 npm publish` at root (Docker must be running: the pack cross-builds the Linux x64 and arm64 native addons into `dist/native/linux/<arch>/addon.node` and fails the release if it cannot); `npm run build:api` then publish in `packages/crouter-api`; `npm run build:env-docker` then publish in `packages/crouter-env-docker`; `npm run build:api && npm run build:identity && npm run build:sdk` then publish in `packages/crouter-sdk`; `npm run build:api && npm run build:identity && npm run build:plugin` then `CRTR_PACK_MINIFY=1 npm publish` in `packages/crouter-plugin`. Use npm's interactive authentication/2FA where required (see `personal-operations/npm-2fa-cli`); a read-only token cannot publish. Provenance remains off because the source repository is private. Do not build or publish the Docker image in this no-Actions path.
+4. Confirm all six exact versions with `npm view`. In a fresh temporary directory, `npm init -y && npm install @north-light/sdk@$VERSION`, then prove both `@north-light/sdk/errors` (`errorCodes`) and `@north-light/sdk/stores/postgres` resolve via `node --input-type=module -e '…'`. Record any partial publish and resume from the exact release tag rather than cutting another version.

package/docs/sdk/README.md

@@ -0,0 +1,90 @@
+---
+title: SDK overview
+description: Drive a crouter daemon from a Node or browser application with the typed SDK.
+---
+
+# `@north-light/sdk`
+
+The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, 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/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);
+```
+
+## Go live with an app key
+
+Once you have installed the SDK and tried the local flow in [Getting started](./getting-started.md), generate the app's key on your server:
+
+```bash
+npx @north-light/sdk keygen --app <client id>
+```
+
+`keygen` saves the private JWK to `local/app-key.json` (mode `0600`); keep that file out of git. With `--app`, it offers to add the public key to your registered app through your own `crtr`, as an additional key that never replaces the current one. Otherwise, click **Add key** on the app's **Sign-in** tab and paste the public JWK printed on stdout (or paste it under **Register an app** for a new app). An app authenticates only with its key; the directory issues no client secret. On your server, load the saved key and pass it as `privateKey`:
+
+```ts
+import {readFile} from 'node:fs/promises';
+import {OAuth2Client} from '@north-light/sdk';
+
+const privateKey = JSON.parse(await readFile('local/app-key.json', 'utf8'));
+const oauth = new OAuth2Client({clientId, issuer, redirectUri, privateKey, store}); // store: your ConnectionStore
+const {url, state, codeVerifier, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
+// Save state, codeVerifier, nonce in the user's session, then redirect to url.
+const connection = await oauth.exchangeCode({code: callbackCode, state: callbackState, expectedState: state, codeVerifier, nonce});
+await store.save(connection);
+const client = await oauth.client(connection.userId); // Refreshes through the store from here on.
+```
+
+The directory rejects the key until its public JWK is added to the app. To change keys later, follow [Rotating your key](./getting-started.md#rotating-your-key): add the new key, switch the app to it, verify a real sign-in, then retire the old key. An app can hold two active keys at once, so there is no downtime.
+
+## Pages
+
+| Page | Covers |
+|---|---|
+| [Getting started](./getting-started.md) | 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 |
+| [Client construction](./client.md) | Every constructor option and its environment-variable fallback; per-request options |
+| [Nodes](./nodes.md) | `create` parameters, the outcome union, `parse()` with a zod schema, `waitForOutcome`, `message`, `cancel`, nested resources |
+| [Streaming](./streaming.md) | The event table, `stream()` / `events()`, the activity helper, resume with `after`, `stream_gap` and `stream_dropped` |
+| [Files](./files.md) | Absolute-path reads, writes, and one-level lists |
+| [Bash](./bash.md) | One bounded command and its output result |
+| [Memory](./memory.md) | `memory.list` and `memory.get`: an app reads the person's `public` documents with no scope |
+| [Resource map](./resources.md) | Every namespace (including `customObjects`, `runs`, `memory`, `shares`, `providers`) with its routes, what is deliberately excluded, and the `client.request()` escape hatch |
+| [Errors](./errors.md) | The error class table and the retry policy |
+| [Docker environment](./docker.md) | `start()`, `attach()`, `connection()` from `@north-light/env-docker` |
+| [Testing your app](./testing.md) | `FakeCloud` from `@north-light/sdk/testing`: a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch` |
+| [Release notes](./release-notes.md) | Behavior changes an existing app must act on, newest first |
+| [Apps on crouter cloud](./guides/apps-on-crouter-cloud.md) | Typed results from app runs with `runs.parse`, declines, bounding a run, `run_idle`, and waiting on a provider your app requires |
+| [Apps with many users](./guides/apps-with-many-users.md) | Per-person runtime connections, app-owned user access, privacy, and spending |
+
+## Phases
+
+The surface ships in three cuts.
+
+| 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** | The review, comment, and chat-inventory 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 and streaming examples are verified.
+
+## Where the agents read this
+
+The same content routed for agents lives in the built-in document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr canvas read crouter-sdk` and does not need this repository checked out.

package/docs/sdk/bash.md

@@ -0,0 +1,39 @@
+---
+title: Bash
+description: Execute bounded shell commands 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.