@north-light/crouter 0.3.331 → 0.3.333

package/docs/cli/canvas-and-dashboard.md

@@ -0,0 +1,56 @@
+---
+title: Canvas and dashboard
+description: When you need to see what your agents are doing or reopen one, read this page because it connects the canvas views to the commands that inspect and revive a node.
+---
+
+# Canvas and dashboard
+
+You can see every agent as a node on one canvas, find work that is blocked, and return to the exact conversation that needs you. Use the dashboard for a quick terminal view and the browser when you want to navigate the graph interactively.
+
+## Read the dashboard
+
+Run:
+
+```sh
+crtr canvas dashboard
+```
+
+The dashboard prints the canvas as an ASCII subscription tree. Each row includes the node id, name, status, kind, mode, context-token count, and pending human asks. Add `--root <node-id>` to limit the tree to one root and its work.
+
+A node's `active` status means its broker process is live; it does not necessarily mean that the model is generating text. A node may be dormant while it waits for an inbox message, a child report, a human answer, or a scheduled event.
+
+## Browse the graph
+
+Run `crtr canvas browse` in a terminal for the interactive graph view. It has tabs, a collapsed tree, and `/` search. Press Enter on a node to focus it, or press `q` or Escape to leave the browser. In a viewer, the graph command opens the same canvas information without losing the conversation you were reading.
+
+```mermaid
+flowchart TD
+  root[Root node] --> research[Research node]
+  root --> build[Build node]
+  build --> review[Review node]
+  human[Your inbox answer] --> build
+```
+
+## Find a blocked node
+
+Use the human-attention view when you want to know which work is waiting for you:
+
+```sh
+crtr canvas attention list
+```
+
+It identifies the nodes that have pending human interactions across the canvas, oldest first. Run `crtr human list` when you need the individual tickets. You can also run `crtr canvas attention count` for a number only.
+
+To inspect one node's neighbors, artifacts, and saved paths, run:
+
+```sh
+crtr node inspect show <node-id>
+```
+
+`crtr node inspect artifacts <node-id>` lists the reports and context documents that node left behind. `crtr canvas history search` searches reports and context documents across the current working directory; `crtr canvas history read <ref>` opens one result in full.
+
+## Reopen work
+
+`crtr surface node focus <node-id>` is the normal way to return to a conversation or inspect finished work. It brings a running viewer into view, opens a parked resident's saved conversation, or shows a finished node's read-only transcript.
+
+Use `crtr node lifecycle revive <node-id>` when you specifically need to relaunch a node's broker and resume its saved conversation. After an outage or reboot, `crtr canvas revive --all` previews every eligible disconnected node but launches nothing. Review that list, then use `crtr node lifecycle revive <node-id>` for the node or nodes you intend to bring back. The canvas preview does not include nodes that are done or canceled by choice.

package/docs/cli/first-session.md

@@ -0,0 +1,55 @@
+---
+title: Your first crtr session
+description: When you have installed crtr and want to start an agent conversation, read this page because it shows the one command that creates a root node and opens its viewer.
+---
+
+# Your first crtr session
+
+You can start an agent in a terminal, talk with it in a tmux pane, then close that pane without stopping the agent. Use a root node for a conversation that you will drive yourself.
+
+## Install and set up
+
+Install crouter globally, then run the setup program once on the machine.
+
+```sh
+npm install -g @north-light/crouter
+crtr sys setup
+```
+
+`crtr sys setup` opens an installer. It signs you in to a model provider, then offers companion packages and system dependencies. It also refreshes crouter's tmux bindings.
+
+## Start a conversation
+
+From the directory where you want the agent to work, create a root node with a clear request.
+
+```sh
+crtr node new --root "Inspect this repository and report the failing tests."
+```
+
+`--root` creates an independent node rather than a child of another agent. It starts the node's detached broker. When you run the command inside tmux, it also opens a viewer pane for that node; type your next message there to continue the conversation. Outside tmux, the command prints the node id instead. Open the viewer in your terminal with:
+
+```sh
+crtr surface attach to <node-id>
+```
+
+The viewer is not the agent process. The broker keeps the node's conversation and session running separately from the pane, so closing the terminal or leaving the viewer does not discard the work. A root node's final report is not sent back to the terminal that created it; open the node again when you want to see its result.
+
+```mermaid
+flowchart LR
+  terminal[Your terminal] --> command[crtr node new --root]
+  command --> broker[Node broker]
+  broker <--> viewer[tmux viewer]
+  broker --> canvas[Canvas state]
+```
+
+## Return to a node
+
+The create command prints the node id. Keep it if you expect to return later. From tmux, focus that node again with:
+
+```sh
+crtr surface node focus <node-id>
+```
+
+For a running node, this brings its viewer into view. For a parked resident node, it opens the saved conversation; sending a message wakes it. For finished work, it opens a read-only saved transcript instead of starting another agent process.
+
+For the controls inside that viewer, continue with [The viewer](./the-viewer.md). For a view of every node, use [Canvas and dashboard](./canvas-and-dashboard.md).

package/docs/cli/human-inbox.md

@@ -0,0 +1,34 @@
+---
+title: Answering agents in the human inbox
+description: When an agent needs your decision or review, read this page because it explains the inbox pages it sends and how your answer resumes its work.
+---
+
+# Answering agents in the human inbox
+
+You can answer an agent without finding its terminal pane when it sends a decision or review to the human inbox. Your answer is delivered back to the asking node, which can continue from the decision instead of guessing. A live display is separate: it opens in a tmux pane and is not an inbox ticket.
+
+## A decision
+
+A decision arrives as a page with a title, a one-line subtitle, and one question at a time. The page may offer a small set of choices or a text field. Read the question, choose or write your answer, then submit it. The agent receives the completed answer in its inbox.
+
+An agent creates this kind of page with `crtr human send`. It can keep the page inside the conversation or project it into the inbox. You can see pending interactions from a terminal with:
+
+```sh
+crtr human list
+```
+
+## A document review
+
+A document review opens the current file beside the agent conversation with a companion agent available to discuss it. Add comments where the document needs change, then approve it when it is ready. The asking agent receives the approval, or a notice that the document changed and must be read again.
+
+Agents create a review with `crtr human review new <file> --subtitle "..."`. The file stays live: edits made while you review are visible in the review.
+
+## A live display
+
+A live display is not a question. It opens a rendered Markdown file in a tmux pane and keeps it up to date as the file changes. Use it when the agent needs you to watch a plan, status board, or other document while work continues.
+
+Agents open one with `crtr human show <path>`. A live display does not create a job or require an answer; it is only a view of the file.
+
+## What needs your attention
+
+`crtr canvas attention list` identifies the nodes with pending human interactions across the canvas. Use `crtr canvas attention count` when you only need the number. When an agent needs a choice, answering it is the fastest way to let its dormant node continue; no separate restart command is needed.

package/docs/cli/memory-and-preferences.md

@@ -0,0 +1,50 @@
+---
+title: Memory and preferences
+description: When you want later agents to retain a fact or follow an instruction, read this page because it explains where memory is stored and how to inspect or revise it.
+---
+
+# Memory and preferences
+
+You can give future agents useful context without pasting the same background into every conversation. Ask an agent to remember a durable fact or instruction, then inspect the saved memory yourself from the terminal.
+
+## Tell an agent what should persist
+
+Say what should be remembered and where it applies.
+
+| If you want to save | Tell the agent |
+|---|---|
+| A fact or procedure | “Remember that our staging database is reset every Friday.” |
+| An instruction about how to work | “Remember that I want a short recommendation before any production change.” |
+| Something for every project you use | “Remember this as a user preference.” |
+| Something only agents in this repository need | “Remember this for this project.” |
+
+A preference tells an agent how to act. Knowledge gives it facts or a procedure to consult. The narrowest useful store is best: a user memory follows you everywhere, while a project memory belongs to one repository. For the explanation of memory tiers and loading, see [Memory](../concepts/memory.md).
+
+## Browse what was saved
+
+List the memory documents available in your current context:
+
+```sh
+crtr memory list
+```
+
+Read one by its name from that list:
+
+```sh
+crtr memory read <name>
+```
+
+`crtr memory read` resolves the current winning document when the same name exists at more than one scope. Add `--scope user` to read only user memory, or `--dir <project-directory>` to inspect one exact project store.
+
+## Edit a memory document
+
+Memory revisions are intentional and recorded. To replace a document's body, pipe the complete replacement text to `crtr memory edit` and give the reason for the revision:
+
+```sh
+printf '%s\n' 'Production changes need an explicit approval.' | \
+  crtr memory edit <name> --rationale "Updated the approval rule."
+```
+
+`crtr memory edit` replaces the whole body you pipe; it does not append text. Use `crtr memory history <name>` to read the revision history. If you want to create a document yourself, use `crtr memory write`; it requires a kind, a routing sentence that tells agents when to read it, and the document body.
+
+Memory is for reusable current truth and durable instructions, not a transcript of one conversation. When a fact changes, update the existing document rather than saving a second version.

package/docs/cli/the-viewer.md

@@ -0,0 +1,79 @@
+---
+title: The viewer
+description: When you are watching or driving a node in tmux, read this page because it lists the viewer controls, slash commands, and the difference between a prompt, a steer, and an interrupt.
+---
+
+# The viewer
+
+You can read a node's live conversation, send it more work, interrupt it, search its transcript, and open canvas tools without running another agent process. `crtr surface attach to <node-id>` opens the viewer in the current terminal pane; `crtr surface node focus <node-id>` brings the node's managed viewer into view.
+
+The viewer is a client of the broker. Detaching or quitting the viewer leaves the broker running. The default controls below can be changed in `~/.pi/agent/keybindings.json`.
+
+## Send a message or interrupt work
+
+Type in the editor and press Enter. When the agent is idle, Enter sends a prompt. While it is streaming, Enter sends a steer: an instruction for the current turn. The dedicated follow-up action has no default key binding; if you bind it, it sends a follow-up frame and clears the editor. Use a steer when the current answer needs to change; wait until idle when you want a normal next prompt.
+
+Press Escape during a streaming turn to abort it. Press Control+C once to clear the editor. Press it a second time within one second to cancel a streaming turn. When nothing is running, the second Control+C does not cancel anything.
+
+## Viewer controls
+
+| Key | Action |
+|---|---|
+| Control+D | Detach from the viewer. |
+| Escape | Abort a streaming turn; otherwise use the editor's normal escape behavior. |
+| Control+C | Clear the editor; repeat within one second to cancel a streaming turn. |
+| Control+Z | Suspend the viewer. |
+| Shift+Tab | Cycle the thinking level. |
+| Control+P / Shift+Control+P | Move to the next / previous model. |
+| Control+L | Open the model selector. |
+| Control+O | Toggle tool output. |
+| Control+T | Toggle thinking. |
+| Control+G | Open the external editor. |
+| Alt+Up | Restore queued messages. |
+| Alt+V / Control+V | Paste an image. |
+| Alt+Enter / Shift+Enter | Insert a newline in the editor. |
+| Alt+G | Toggle the canvas graph. |
+| Alt+Shift+K | Open keyboard help. |
+| Alt+U | Jump to pending human requests. |
+| Alt+M / Alt+Shift+M | Select the next / previous model-ladder rung. |
+| Alt+Shift+H | Inspect the loaded slash command. |
+| Alt+Shift+R | Review a transcript file. |
+| Control+F | Search profile files. |
+| Alt+/ | Search the displayed transcript. |
+| Shift+Up / Shift+Down | Scroll one transcript line. |
+| Page Up / Page Down | Scroll one transcript page. |
+| Shift+End | Return to the live end of the transcript. |
+| Alt+Shift+O | Toggle mouse reporting. |
+| Alt+Shift+Y | Copy the newest visible message. |
+
+While transcript search is open, press `n` or Shift+`n` for the next or previous match, `/` to edit the query, and Escape to close search.
+
+Press Alt+C to open crouter's action menu. Its Attach actions menu offers the same everyday controls: detach, clear or cancel, graph, help, inbox, pending requests, model changes, profile-file search, and transcript search. Alt+] and Alt+[ move to the next and previous node; Alt+I opens the inbox.
+
+## Slash commands
+
+Type `/` in the editor to see the available commands. These commands are provided by crouter's viewer:
+
+| Command | What it opens or changes |
+|---|---|
+| `/clear` | Clear the conversation display. |
+| `/graph` | Open the canvas graph. |
+| `/inbox` | Open the human inbox. |
+| `/promote [kind]` | Promote the current node, optionally selecting a kind. |
+| `/resume` | Open the canvas navigator to choose a node. |
+| `/resume-session [session-path]` | Switch to the supplied saved session file. |
+| `/context` | Open node context and reports. |
+| `/plugins` | Open plugins. |
+| `/node-metadata` | Show node metadata. |
+| `/mcp [server]` | Open MCP controls, optionally for one server. |
+| `/rename <name>` | Rename the current node. |
+| `/color <color\|none>` | Set or clear the node color. |
+| `/mouse` | Toggle mouse support. |
+| `/copy-message` | Copy a message. |
+| `/copy-tool` | Copy tool output. |
+| `/copy-transcript` | Copy the transcript. |
+| `/fold-tools` | Fold or unfold tool output. |
+
+The viewer also provides these pi commands: `/settings`, `/model`, `/scoped-models`, `/export`, `/import`, `/share`, `/copy`, `/name`, `/session`, `/changelog`, `/hotkeys`, `/fork`, `/clone`, `/tree`, `/login`, `/logout`, `/new`, `/compact`, `/reload`, and `/quit`. `/quit` detaches the viewer but leaves the shared broker running.
+
+Use [Canvas and dashboard](./canvas-and-dashboard.md) when the conversation leads you to another node, and [Human inbox](./human-inbox.md) when the agent needs your answer.

package/docs/concepts/README.md

@@ -0,0 +1,17 @@
+---
+title: Concepts
+description: 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 |
+|---|---|
+| [Nodes and the canvas](./nodes-and-the-canvas.md) | Whether work needs a durable node rather than one request and response |
+| [Lifecycle and wakes](./lifecycle-and-wakes.md) | Whether a node should finish, remain resident, delegate, or wait |
+| [Memory](./memory.md) | What an agent should know or embody, who owns it, and where it belongs |
+| [Profiles, kinds, and modes](./profiles-kinds-and-modes.md) | Which run-shaping dial matches an application concern |
+| [Scopes and trust](./scopes-and-trust.md) | What an application or node may do and why only the daemon writes canvas state |
+| [Why a daemon](./why-a-daemon.md) | Why a broker survives a terminal and why viewers are clients rather than hosts |

package/docs/concepts/lifecycle-and-wakes.md

@@ -0,0 +1,26 @@
+---
+title: Lifecycle and wakes
+description: 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 [`nodes.message`](../sdk/nodes.md#sending-a-follow-up) to deliver that external event, and run `crtr memory read internal/nodes-and-canvas` for lifecycle operations.

package/docs/concepts/memory.md

@@ -0,0 +1,34 @@
+---
+title: Memory
+description: When shaping an agent without rewriting its prompt, read this because memory documents separate facts to consult from behavior to embody and let each owner control who receives them.
+---
+
+# Memory
+
+Memory shapes a node without adding the same instructions to every prompt. A memory 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.
+
+| Tier | Owner | Put here |
+|---|---|---|
+| Node | One running node | A note needed across that node’s fresh contexts |
+| Project | One repository or workspace | Repository facts and procedures |
+| Profile | One application identity and its purview | Application-wide conventions and knowledge |
+| User | One person | Facts and preferences that follow them everywhere |
+| Builtin | crouter | Runtime documentation that ships to every user |
+
+Choose the narrowest tier that reaches the next agent who needs the document. For an application author, the profile store is the usual home for knowledge shared by that application’s nodes across repositories. [`client.memory`](../sdk/memory.md) names a target for every operation, so the daemon resolves the application’s profile rather than its own current directory. A node’s `memory:read` and `memory:write` scopes can respectively permit reading while denying changes.
+
+```mermaid
+flowchart LR
+  Doc[Memory document] --> Surface[Surface entry: event, gate, rung]
+  Surface -->|event matches| Preview[Name, preview, or full body]
+  Preview --> Route[Routing line tells the agent why to read]
+  Route --> Read[Explicit full read when needed]
+```
+
+A surface entry is the delivery mechanism. A document is not loaded because it sits in a particular folder or because its routing line resembles the task. Its frontmatter names an event such as boot, workspace-open, file read, memory read, command, or pre-command; that entry can also match a path or gate on the node’s shape and selects a rung: its name, a preview, or its full content. A document with no surface entry stays in its directory listing until an agent deliberately finds or reads it.
+
+The routing line is the preview at the middle rung, not a trigger. For example, a profile document can have a file-read surface that delivers a 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 event delivers the preview; the line helps the agent decide whether to read the body without pretending to replace it.
+
+Memory therefore supports progressive disclosure. You can record knowledge freely, but it costs future contexts only when an explicit surface route delivers it. Read `crtr memory write -h` to author a document and `crtr memory read internal/memory-loading` for the routing mechanics. The SDK [memory page](../sdk/memory.md) shows how an application creates and revises its profile documents.

package/docs/concepts/nodes-and-the-canvas.md

@@ -0,0 +1,28 @@
+---
+title: Nodes and the canvas
+description: 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, a context directory for artifacts, and a broker that hosts its agent engine. It is not an HTTP request with an LLM response attached.
+
+The canvas is the durable graph of those nodes. It makes an agent's work and its relationship to other work visible after the process that created it has returned. This is why [`client.nodes.create`](../sdk/nodes.md) 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 and artifacts]
+  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 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 durable report and puts a reference in each subscriber’s feed. 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 an artifact. It may write 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, durable artifacts, reports, and relationships across fresh contexts and broker replacement.
+
+Use a one-shot SDK call such as [`nodes.parse`](../sdk/nodes.md#parse-and-structured-output) 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 memory read internal/nodes-and-canvas`.

package/docs/concepts/profiles-kinds-and-modes.md

@@ -0,0 +1,31 @@
+---
+title: Profiles, kinds, and modes
+description: When designing an agent run, read this because profiles, kinds, modes, and memory tiers 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 memory 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 |
+| Memory tier | Who should receive a document? | Guidance must reach one node, project, profile, user, or all crouter users |
+
+A profile is not a label on a run. It is a stable agent identity with its own memory store 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 [`client.profiles`](../sdk/resources.md) and the SDK’s `profile` create field to select the application’s identity.
+
+```mermaid
+flowchart LR
+  Profile[Profile: purview, environment, memory] --> Node
+  Kind[Kind: role and tools] --> Node
+  Mode[Mode: base or orchestrator] --> Node
+  Tier[Memory tier: 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 memory tier. For the full selection rules, run `crtr memory read internal/agent-shaping`; [`nodes.create`](../sdk/nodes.md) documents the profile, kind, and mode fields an application passes.

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

@@ -0,0 +1,32 @@
+---
+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 family | It gates |
+|---|---|
+| `ask` | Human requests and review actions |
+| `act` | Node creation on behalf of a node and node messaging |
+| `schedule` | Creating scheduled work |
+| `memory:read` / `memory:write` | Reading or changing memory through a node target |
+| `llm`, `net`, and parameterized forms such as `files:<dir>` | Declared capability categories; some performers are recorded rather than enforced in the current beta |
+
+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; `client.memory` additionally checks `memory:read` or `memory:write` when you make a request on behalf of a node. A node may be allowed to consult its application’s knowledge while being unable to rewrite it.
+
+```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 --scopes …` mints a new scoped token instead of returning the owner token. 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 memory 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, artifacts, 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 memory 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

@@ -1,3 +1,8 @@
+---
+title: Plugin overview
+description: Expose application operations as native crtr commands with a typed HTTP plugin.
+---
+
 # Authoring crtr HTTP plugins
 
 `@north-light/crouter-plugin` turns one TypeScript command tree into both a Fetch handler and the archive accepted by `crtr pkg plugin install --endpoint`. Use it when an application should expose typed operations as native `crtr` commands without maintaining `commands.json` or a separate HTTP route definition.

package/docs/plugin/bundles-and-memory.md

@@ -1,3 +1,8 @@
+---
+title: Bundles and memory docs
+description: Generate install archives and include agent-facing memory documents in a plugin.
+---
+
 # Bundles and memory docs
 
 `createFetchHandler` builds and serves the install archive automatically. Use `buildBundle` when you need to inspect or save the generated bytes during an application build. Pass the same mount path where the handler is served.

package/docs/plugin/commands.md

@@ -1,3 +1,8 @@
+---
+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.

package/docs/plugin/deploying.md

@@ -1,3 +1,8 @@
+---
+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.

package/docs/plugin/errors.md

@@ -1,3 +1,8 @@
+---
+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`. Use `field`, `next`, and `received` when they make the fix clearer.

package/docs/plugin/getting-started.md

@@ -1,3 +1,8 @@
+---
+title: Getting started
+description: Install the plugin package, deploy a Fetch handler, and install its commands in crtr.
+---
+
 # Getting started
 
 Install `@north-light/crouter-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.

package/docs/plugin/output.md

@@ -1,3 +1,8 @@
+---
+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.

package/docs/plugin/parameters.md

@@ -1,3 +1,8 @@
+---
+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`.

package/docs/sdk/README.md

@@ -1,3 +1,8 @@
+---
+title: SDK overview
+description: Drive a crouter daemon from a Node or browser application with the typed SDK.
+---
+
 # `@north-light/crouter-sdk`
 
 The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, read and write memory, and reach the rest of the daemon's `/v1` API.

package/docs/sdk/bash.md

@@ -1,3 +1,8 @@
+---
+title: Bash
+description: Execute bounded shell commands through the daemon.
+---
+
 # `client.bash`
 
 `client.bash.run` executes one bounded `bash -c` command through the daemon.

package/docs/sdk/client.md

@@ -1,3 +1,8 @@
+---
+title: Client construction
+description: Configure local socket and remote HTTP connections, authentication, and request options.
+---
+
 # Client construction
 
 ```ts
@@ -16,7 +21,7 @@ const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }
 |---|---|---|---|
 | `baseURL` | `string` | `CRTR_BASE_URL`, else unset | `http(s)://host:port` of a daemon TCP listener. |
 | `socketPath` | `string` | `CRTR_SOCKET`, else `${CRTR_HOME}/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock` | Unix socket. Node only; throws in a browser. |
-| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
+| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. The owner token or a scoped token from `crtr sys connect`; a scoped token's ceiling is enforced per request (see [Getting started](./getting-started.md#a-token-that-holds-less-than-the-owner)). Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
 | `timeout` | `number` (ms) | `30_000` | Per-request wall clock. Does not apply to a stream. |
 | `maxRetries` | `number` | `2` | Transient-failure retries. Never applied to `POST` or `PATCH` — see [Errors](./errors.md). |
 | `defaultHeaders` | `Record<string, string>` | `{}` | Merged into every request. |

package/docs/sdk/docker.md

@@ -1,3 +1,8 @@
+---
+title: Docker environment
+description: Run a crouter daemon in a container with the separate Docker environment package.
+---
+
 # Docker environment
 
 Phase 1.