@north-light/cli 0.0.0-stage → 0.3.413

package/dist/builtin-memory/05-kinds/review/security-findings.md

@@ -0,0 +1,13 @@
+---
+kind: preference
+when-and-why-to-read: When a node is spawned as kind review in any mode, this preference should be read so a security concern is either a proved finding or a question to the user, and never a hypothetical rated as a defect.
+gate: {kind: review}
+rationale: >-
+  Agents project an internet-facing threat model onto private systems and block on hypothetical risk. The contract is identical for a hands-on reviewer and for an orchestrator synthesizing children, so it gates on the kind with no mode rather than being copied into both mode layers. The gate is an exact kind match, so `review/companion` — a live human conversation, not a severity-rated verdict — does not load it.
+surfaces:
+  - on: boot
+    at: content
+---
+
+## When a security concern is unproven
+A security finding needs evidence that the scenario applies: trace the reachable exploit path against the actual trust boundary and deployment context, resolving that context from source and deployment evidence first. When a material security posture is unknown rather than defective, ask through `crtr human send` instead of rating a hypothetical — the observed facts in plain language, the actor/access scenario and asset that would make the tightening worthwhile, and whether that scenario applies and should be fixed. That question stays out of the severity-rated findings. When you have a parent, report the confirmed verdict and the non-blocking question upward before awaiting the answer, with `crtr push update --tier urgent` when work is waiting on this review, so an unresolved posture does not stall what is already proved.

package/dist/builtin-memory/advisor/council.md

@@ -0,0 +1,33 @@
+---
+kind: knowledge
+when-and-why-to-read: When convening an advisor council for a consequential judgment, this knowledge should be read because disciplined independent evidence prevents a confident consensus from concealing a correlated error.
+short-form: Run a bounded, evidence-first advisor council for consequential judgments.
+rationale: >-
+  Everyone's instinct for getting the right answer out of a council is to make the agents debate until they agree — and that instinct is empirically backwards. Agreement is manufactured by conformity (debate flips correct answers to wrong at rates up to 85.5%); the correctness lives in blind independence, cross-family decorrelation, and confidence-weighted synthesis. Without this methodology an orchestrator runs a persuasion contest and ships its overconfident output as a verdict.
+---
+
+# Advisor Council Methodology
+
+Use a council only for a consequential judgment where the cost of being wrong justifies deliberation. An ordinary second opinion needs one advisor or a few un-orchestrated advisors.
+
+## First round
+
+Spawn three to five advisors in parallel. Keep their work blind: no member sees another's analysis. Assign each the same question under a distinct evidence frame, prior to steelman, or decomposition. Select members from the live model configuration; when distinct model families are available, span them to reduce correlated error rather than assuming any particular route.
+
+Ask every member for a recommendation, calibrated numeric confidence, strongest private reason, and key evidence. Members contribute read-only judgment; the council orchestrator is the only verdict writer.
+
+## Synthesis
+
+Synthesize as a chairman, not a vote. Weight recommendations by confidence and evidence quality, retain each original answer, and preserve a well-supported minority. Treat unanimity as a cue to check for correlation or false convergence, not as proof. Commit to the best-supported recommendation rather than averaging independent opinions into an under-confident compromise.
+
+Before finalizing, give one clean-context advisor a prospective-hindsight pre-mortem: the draft verdict was adopted and failed; explain why. Prefer a model family different from the members that dominated the draft. Incorporate confirmed concerns or report them as accepted risks.
+
+## Disagreement
+
+Open one targeted second round only when members disagree on a named, verifiable crux such as code, tests, documentation, or quotable evidence. Share only anonymized claim, reason, and evidence snippets about that crux; remove author, model, and conclusion labels. Have advisors verify and attack those claims directly. Stop after that round when positions stabilize.
+
+A crux about judgment, taste, or values does not earn a persuasion contest. Adjudicate it or surface it to the owner as a named tradeoff.
+
+## Verdict
+
+Deliver one conclusion-first verdict: recommendation and confidence, the strongest opposing case and why it lost, and any residual disagreement with its crux. Do not forward raw member output or dissolve disagreement into false consensus.

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

@@ -0,0 +1,15 @@
+---
+kind: knowledge
+description: Why crouter is shaped the way it is — durable nodes, the canvas graph, dormancy, document owners, profiles, scoped authority, and one daemon
+when-and-why-to-read: When you are choosing the shape of an agent application on crtr — whether work needs a durable node, whether it should finish or stay resident, which owner a document belongs to, or why only the daemon writes canvas state — this section should be read because picking an SDK method or plugin field before understanding the runtime model produces an application that fights the runtime instead of using it.
+short-form: The concepts behind the crtr runtime, read before choosing an SDK method or plugin field — nodes and the canvas, lifecycle and wakes, documents and owners, profiles/kinds/modes, scopes and trust, and why a daemon.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# `crouter-concepts/` — choose the crouter runtime shape before using the SDK
+
+crouter keeps one graph of **objects** — the canvas. Nodes, documents, bash jobs, owners (person, app, repo, profile) and custom objects registered by outside services are all objects with an id, a name, an owner and a privacy level, and one set of verbs works on all of them: `crtr canvas read|list|search|watch|edges`. A **document** is the object type for written knowledge (what older versions called memories, reports and context documents); it is written with `crtr doc write|edit` and shared by `[[name]]` pointer. Reading an object makes you its watcher, so a later edit or report reaches you as an event. Who sees a document is decided by its **owner**, its privacy and its delivery rules — there are no memory stores or tiers. The SDK keeps the name `client.memory` for its read-only view of the person's public knowledge and preference documents. The full model is in `internal`; these pages say which parts to choose from when building an application.
+
+Read `crouter-concepts/README` for the section overview. These pages explain why crouter uses durable nodes, the canvas graph, free dormancy, document owners, profiles, scoped authority, and one daemon before an application chooses an SDK method or plugin field.

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

@@ -0,0 +1,19 @@
+---
+kind: knowledge
+when-and-why-to-read: When building with crtr, read this section because its
+  pages explain which runtime parts solve each problem before you choose an SDK
+  method or plugin field.
+---
+
+# Concepts
+
+Use these pages to choose the shape of an agent application before you start wiring it. They explain the durable runtime model behind the SDK and plugin surfaces, then point to the detailed guides for each surface.
+
+| Page | Decide |
+|---|---|
+| [[crouter-concepts/nodes-and-the-canvas]] | Whether work needs a durable node rather than one request and response |
+| [[crouter-concepts/lifecycle-and-wakes]] | Whether a node should finish, remain resident, delegate, or wait |
+| [[crouter-concepts/documents]] | What an agent should know or embody, who owns it, and where it belongs |
+| [[crouter-concepts/profiles-kinds-and-modes]] | Which run-shaping dial matches an application concern |
+| [[crouter-concepts/scopes-and-trust]] | What an application or node may do and why only the daemon writes canvas state |
+| [[crouter-concepts/why-a-daemon]] | Why a broker survives a terminal and why viewers are clients rather than hosts |

package/dist/builtin-memory/crouter-concepts/documents.md

@@ -0,0 +1,54 @@
+---
+kind: knowledge
+when-and-why-to-read: When shaping an agent without rewriting its prompt, read
+  this because documents separate facts to consult from behavior to embody and
+  let each owner control who receives them.
+---
+
+# Documents
+
+A document is one kind of **canvas object**. The canvas is one graph of objects: documents, nodes, bash jobs, owners (a person, an app, a repo, a profile) and custom objects registered by outside services. Every object has an id and a name, and the same read verbs work on all of them: `crtr canvas read`, `list`, `search`, `watch` and `edges`. Documents are the objects you write; they are written with `crtr doc write|edit|move|delete`.
+
+Documents shape a node without adding the same instructions to every prompt. A document says what it contains, who owns it, and when it should enter context. The result is durable guidance that can be discovered when relevant instead of a growing startup prompt.
+
+There are two kinds. **Knowledge** is something an agent consults: a procedure, fact, or technical reference. A **preference** is behavior the agent should embody: a standing directive or correction. This is a use-based split. A procedure and a fact are both knowledge because the agent reads either one to answer a question; a preference changes how it acts.
+
+## Names and pointers
+
+A document's full name is `<owner-handle>/<path>`, for example `3zl47w7d-…/plan` for a node's document or `crouter-sdk` for a shipped one (path segments are letters, digits, `_` and `-`, joined by `/`). Point at a document with `[[name]]`. Inside a document body, each `[[link]]` attaches the target's preview wherever the body is delivered in full, so a reader sees what the link is for before opening it. A bare name is looked up in the reader's own view first (its node, then its repos, profile and app), then the person's documents, then installed plugins, and the built-in `crtr` documents last; a `<owner-handle>/<path>` name is unambiguous. Moving or re-owning a document with `crtr doc move` keeps its id and every link.
+
+Reading a document with `crtr canvas read` makes you a **watcher**: later edits to it are pushed to you, and if you are running they steer you. `crtr canvas list` and `search` record nothing. Each edit is a recorded revision with a rationale; an edit made from a stale revision is refused.
+
+## Owners
+
+Every document has an owner, and an owner is itself an object.
+
+| Owner | Who it is | Put here |
+|---|---|---|
+| Node (default) | The writing node | Work product for other readers; deleted with the node unless a kept document links to it |
+| Repo | One repository | Repository facts and procedures. Public only; synced to collaborators over the repo's `refs/crtr/docs` |
+| Profile | One application identity and its purview | Application-wide conventions and knowledge |
+| App | The app that runs the node | Documents readable by that app's nodes |
+| User | One person | Facts and preferences that follow them everywhere |
+
+An installed plugin is an app named after the plugin, and the documentation that ships with crouter is owned by the app `crtr`; both are public and read-only. Choose the narrowest owner that reaches the next agent who needs the document. For an application author, the profile is the usual owner for knowledge shared by that application's nodes across repositories.
+
+## Who may read
+
+Each document is `public` (the default), `friends` or `private`. The person reads everything, a repo owns only public documents, and a reader that cannot see a document gets the same answer as for one that does not exist. A node's own owner space is open to it; an app's access to the person's documents is by privacy level and the scopes its grant holds (see [[crouter-concepts/scopes-and-trust]]).
+
+```mermaid
+flowchart LR
+  Doc[Document] --> Rule[Delivery rule: on, if, deliver]
+  Rule -->|activity matches| Preview[Name, preview, or full body]
+  Preview --> Line[Preview tells the agent why to read]
+  Line --> Read[Explicit full read when needed]
+```
+
+## Delivery rules
+
+A delivery rule is the delivery mechanism. A document is not loaded because of its name or because its preview resembles the task. Each rule names an activity — `boot`, `workspace-open`, `file-read`, `document-read`, `command`, `pre-command` or `slash-command` — and can match a path or command, carry an `if` on the node's shape (kind, mode, lifecycle, cwd, repo, profile, depth), and selects what to deliver: the name, the preview, or the full content. When several rules deliver the same document, the highest delivery wins (content over preview over name), and content delivery counts as a read. A document with no delivery rule stays in its listing until an agent deliberately finds or reads it.
+
+The preview is delivered at the middle level, not a trigger. For example, a profile document can have a file-read rule that delivers its preview when an order record is opened. Its line — “When handling a refund request, read this because the eligibility window is not in the order record” — then tells the agent why an explicit full read is useful. The rule delivers the preview; the line helps the agent decide whether to read the body without pretending to replace it.
+
+Documents therefore support progressive disclosure. You can record knowledge freely, but it costs future contexts only when a delivery rule delivers it. Read `crtr doc write -h` to write a document (and `crtr doc write --rule -h` and `--owner -h` for rules and owners) and `crtr canvas read internal/memory-loading` for the delivery mechanics.

package/dist/builtin-memory/crouter-concepts/lifecycle-and-wakes.md

@@ -0,0 +1,28 @@
+---
+kind: knowledge
+when-and-why-to-read: When an agent must react to later work, read this because
+  lifecycle and wake choices let it sleep without a process while preserving its
+  goal and the event that should resume it.
+---
+
+# Lifecycle and wakes
+
+Choose a node’s lifecycle from the kind of relationship it has with work. A **terminal** node owes a final report when it is done. A **resident** node is for an ongoing conversation with a person: it can become dormant and be messaged again without first finalizing. Resident does not mean “keep a process running.” Dormant nodes have no live broker or model turn and cost no context window or compute.
+
+Mode answers a different question. A **base** node works hands-on and may delegate a clearly separate piece. An **orchestrator** owns enough independent parallel work that decomposition, delegation, and integration are now its main job. Long or sequential work is not enough reason to orchestrate; keep one hands-on owner and give it a fresh context when needed. Lifecycle answers whether a conversation remains open; mode answers who does the work.
+
+```mermaid
+flowchart LR
+  Active[Active node] -->|nothing to do now| Dormant[Dormant: no broker]
+  Child[Child report] --> Inbox
+  Message[Message or human answer] --> Inbox
+  Cron[Cron or deadline] --> Inbox
+  Inbox -->|wake| Active
+  Active -->|terminal final| Finished[Finished]
+```
+
+A node wakes when work actually arrives: a subscribed child pushes a report, another node or an application sends a message, a person answers a human request, or a cron action delivers work. A deadline is a scheduled wake that races an otherwise unpushable wait. The inbox is the durable path for these triggers, so a node can stop between them without losing its goal.
+
+Do not keep a node active to poll a child, a person, or a message. Creation automatically subscribes a parent to its child, and the runtime delivers the child’s outcome. Waiting for something the canvas can push is free: end the turn and let the node become dormant. Schedule a cron only for recurring work or an external condition that nothing can push into the canvas, such as checking a CI run. A timer added “just in case” a child does not report duplicates a runtime guarantee and hides a runtime defect.
+
+A broker crash does not erase the node. The daemon retains the durable node row, conversation, waits, and outstanding inbox entries, then applies its recovery policy. This is what makes a resident event-driven assistant practical: it can wait for a webhook, be dormant for hours, and resume its saved work only when the webhook produces a message. Use [[crouter-sdk/nodes]] to deliver that external event, and run `crtr canvas read internal/nodes-and-canvas` for lifecycle operations.

package/dist/builtin-memory/crouter-concepts/nodes-and-the-canvas.md

@@ -0,0 +1,31 @@
+---
+kind: knowledge
+when-and-why-to-read: When deciding whether an agent task should outlive one
+  request, read this because a node gives the task durable identity, context,
+  reports, and a path for later messages.
+---
+
+# Nodes and the canvas
+
+Use a node when the work may need a follow-up, a report, a child, or time without a caller holding a request open. A node is a durable unit of agent work: it has an identity, a goal, graph relationships, the documents it writes for other readers, a context directory for its scripts and data, and a broker that hosts its agent engine. It is not an HTTP request with an LLM response attached.
+
+The canvas is a durable graph of **objects**, not only nodes. Documents, nodes, bash jobs, owners (a person, an app, a repo, a profile) and custom objects registered by outside services are all objects with an id and a name, and the same verbs work on every one of them: `crtr canvas read`, `list`, `search`, `watch`, `unwatch` and `edges`. Edges record what an object links to, who acted on it and who watches it. Reading an object, writing a document, messaging a node or spawning one makes you a watcher, so its later events reach your inbox. See [[crouter-concepts/documents]] for the document object. The canvas makes an agent's work and its relationship to other work visible after the process that created it has returned. This is why [[crouter-sdk/nodes]] returns a node you can retrieve, message, stream, or wait on instead of only returning generated text. An application can create a root node, show its progress, and later call `nodes.message` when a person or an external event has more work for it.
+
+```mermaid
+flowchart TD
+  App[Application] -->|creates or messages| Daemon[crtrd]
+  Daemon --> Node[Durable node]
+  Node --> Broker[Broker and agent engine]
+  Node --> Context[Context directory: scripts, data, logs]
+  Node --> Docs[Documents it owns]
+  Child[Child node] -->|pushes a report| Node
+  Node -->|pushes a report| Parent[Subscriber]
+```
+
+A graph edge is not just a visual parent-child line. The management relationship records who owns a child, while subscriptions, stored as watches, carry report delivery. On normal child creation, the parent subscribes to the child, so the child’s final report wakes the parent. A node can have other subscribers too; report delivery is intentionally separate from hierarchy.
+
+The one way work reports upward is a **push**. A push writes a report, which is a document the node owns (named `<node-id>/reports/<name>`), and delivers it to each subscriber: a short body is inlined, otherwise the subscriber gets a `[[name]]` pointer to read with `crtr canvas read`. Nothing is reported merely because a node stopped producing text. That makes a report an explicit claim a subscriber can inspect, rather than an inference from terminal output. The parent can then integrate the child’s result instead of repeating the work.
+
+A node owns an outcome, not merely a deliverable. It may write documents, files and reports while working, but its terminal result is credible only when it has evidence that the requested goal was met. The canvas supports that responsibility: it preserves the goal, the node's documents and reports, and relationships across fresh contexts and broker replacement. A node's context directory holds only what is not a document — scripts, data, logs; writing meant for another reader is a document shared by `[[name]]`.
+
+Use a one-shot SDK call such as [[crouter-sdk/nodes]] when work is bounded and its only useful output is a typed result. Use `nodes.create` when the application needs a continuing conversation or must observe work while it runs. For the operational graph and report model, run `crtr canvas read internal/nodes-and-canvas`.

package/dist/builtin-memory/crouter-concepts/profiles-kinds-and-modes.md

@@ -0,0 +1,33 @@
+---
+kind: knowledge
+when-and-why-to-read: When designing an agent run, read this because profiles,
+  kinds, modes, and document owners solve different problems and prevent a long
+  prompt from becoming an unstable substitute for an application identity.
+---
+
+# Profiles, kinds, and modes
+
+Shape a run by choosing the dial that owns the decision. The four dials are independent: a useful profile does not imply an orchestrator, and a specialist kind does not decide where its knowledge lives.
+
+| Dial | It answers | Use it when |
+|---|---|---|
+| Profile | Which application identity, project purview, environment, and profile documents apply? | An application or body of work has stable directories and conventions |
+| Kind | What standing role, model tier, tools, and expertise should the agent have? | The work matches a recurring role such as developer or reviewer |
+| Mode | Does this node work hands-on or coordinate independent children? | Parallel work makes coordination the main job |
+| Document owner | Who should receive a document? | Guidance must reach one node, repo, profile, user, or all crouter users |
+
+A profile is not a label on a run. It is a stable agent identity with its own documents and a purview of project directories. It lets an application create nodes from the same target context even if the caller runs elsewhere. Create a profile when an app has a durable set of directories, environment values, and conventions worth sharing. Do not make a profile for every repository or individual request. Use [[crouter-sdk/resources]] and the SDK’s `profile` create field to select the application’s identity.
+
+```mermaid
+flowchart LR
+  Profile[Profile: purview, environment, documents] --> Node
+  Kind[Kind: role and tools] --> Node
+  Mode[Mode: base or orchestrator] --> Node
+  Owner[Document owner: reach] --> Node
+```
+
+A kind is a recurring role, not a decorative name. It carries a role-specific posture and may choose a suitable model tier and tools. A custom kind beats a long prompt when the role recurs and needs standing discipline that should survive every run: for example, an application’s compliance reviewer that always needs the same tools, expertise, and model choice. A one-off instruction belongs in the node’s prompt, where it does not create a permanent persona to maintain.
+
+Base mode is the normal choice: the node owns and performs the work, using a child only for a separable part. Promote to orchestrator only when independent parts can proceed in parallel and the benefits outweigh coordination and integration. A terminal orchestrator still finishes normally; residency is separate and belongs to a person-facing ongoing conversation.
+
+These choices keep the application prompt focused. Identity belongs in a profile, standing role in a kind, task-specific intent in the prompt, coordination in mode, and reusable knowledge in the narrowest document owner. For the full selection rules, run `crtr canvas read internal/agent-shaping`; [[crouter-sdk/nodes]] documents the profile, kind, and mode fields an application passes.

package/dist/builtin-memory/crouter-concepts/scopes-and-trust.md

@@ -0,0 +1,41 @@
+---
+kind: knowledge
+when-and-why-to-read: 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 [[crouter-concepts/documents]]); 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 [[crouter-sdk/nodes]] `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/dist/builtin-memory/crouter-concepts/why-a-daemon.md

@@ -0,0 +1,31 @@
+---
+kind: knowledge
+when-and-why-to-read: 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 [[crouter-sdk/nodes]], 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 [[crouter-sdk/getting-started]].

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/plugin to expose an application's typed HTTP operations as crtr commands from one TypeScript command tree.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# `@north-light/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,22 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Plugin overview, this knowledge should be
+  read because 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 `node_modules/@north-light/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 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/dist/builtin-memory/crouter-plugin/bundles-and-memory.md

@@ -0,0 +1,30 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Bundles and documents, this knowledge should
+  be read because 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/dist/builtin-memory/crouter-plugin/commands.md

@@ -0,0 +1,24 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Commands, this knowledge should be read
+  because 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 [[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,36 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Deployment, this knowledge should be read
+  because 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 [[crouter-plugin/errors]] for the exact error shape.

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

@@ -0,0 +1,41 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Errors and streaming, this knowledge should
+  be read because 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/dist/builtin-memory/crouter-plugin/getting-started.md

@@ -0,0 +1,25 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Getting started, this knowledge should be
+  read because 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 `node_modules/@north-light/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 [[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,52 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Output fields, this knowledge should be read
+  because 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 [[crouter-plugin/parameters]].
+
+`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.