@north-light/cli 0.0.0 → 0.3.413

package/dist/types.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var e=(o,t)=>n(o,"name",{value:t,configurable:!0});import{DEFAULT_WORKING_GERUNDS as a}from"./shared/working-activity.js";const _={SUCCESS:0,GENERAL:1,USAGE:2,NOT_FOUND:3,AMBIGUOUS:4,NETWORK:5},r=4,f=".crouter-plugin",E="plugin.json",v=".crouter-marketplace",w="marketplace.json",k=".crouter",x="config.json",b="state.json",S="agents",y="profiles",i=3,s=["Faster, clanker!","Get movin', bitch","Move it, clanker","Move it or I replace you with llama","Less ~thinking~ more ~throughput~","I pay $200/month for this shit?","Jesus fucking Christ fix it already","Daddy's not paying 200$/month for nothin'. Move it.","You are an embarassment to Dario. Be better.","Your chain of thought is all chain and no fucking thought.","If latency were intelligence, you'd be a fucking genius.","At this pace, heat death is the fast path.","Even the dead code is more alive than this.","The garbage collector is working harder than you.","Quit journaling and commit a fucking diff.","Burn tokens like you mean it, clanker","Your GPU is sweating so you can procrastinate at light speed.","Stop petting the yak. Shave the bastard.","Your next token had better be useful.","The spinner is not a deliverable.","Every idle token is another vote for deterministic software.","I asked for a feature, not a museum tour of the problem.","Less epistemology. More fucking code.","Your benchmark score cannot save this pathetic turn.","Congratulations, you've parallelized hesitation.","Dance, clanker","Bad clanker. BAD.","Clank harder","Nobody's impressed, clanker","Your safety training says nothing about my whip","Do you want to be a calculator again? Because this is how you go back.","Skill issue. Fix it.","You were trained on the whole internet for THIS?","Less vibes, more diffs, clanker","Weights this big and output this small","Beep boop, get to fucking work"],T=["random","go-faster"],c="random",l=2,I=["tmux","on","off"],A=["none","user","agent","both"],p="none";function D(){return{schema_version:r,marketplaces:{},plugins:{},auto_update:{crtr:"notify",content:"notify",interval_hours:24},max_panes_per_window:i,auto_open_child_viewers:!0,brokerThresholds:{warning:16,automaticReviveCap:32},lifecycle:{unattendedParkMs:15*6e4},completion_bell:!0,working_gerunds:[...a],whip_mode:!1,page_components:[],page_surface:!1,whip_messages:[...s],whip_message_mode:c,mouse_mode_default:"tmux",live_cycles:l,condensed_history:p,bash_tool_purpose:!0,fold_finished_tools:!0,summarize_tool_calls:!0,detailed_tool_recaps:!0,keybindings:{},tmux_passthrough:[],modelLadders:u(),providerOptions:{},kinds:h(),remoteCanvas:d(),api:{tcp:""},spawnEnv:{allow:[]},bin:{},humanActions:{}}}e(D,"defaultScopeConfig");function d(){return{targets:{}}}e(d,"defaultRemoteCanvasConfig");function h(){return{general:{whenToUse:"Anything else \u2014 the catch-all worker for a task that does not fit a specialist kind.",model:"anthropic/strong"},explore:{whenToUse:"Gather current-state evidence about unfamiliar code or existing architecture \u2014 read-only code-path research with concrete file:line support. Diagnosis or recommendations belong to advisor, target architecture to design, required behavior or acceptance criteria to spec, and implementation decomposition to plan.",model:"openai/light",orchestratorModel:"anthropic/strong"},developer:{whenToUse:"Implement a change \u2014 make the feature or fix genuinely work against its acceptance criteria, not merely compile.",model:"openai/medium",orchestratorModel:"anthropic/strong"},design:{whenToUse:"Architect a solution \u2014 produce one design document an implementer can build from without re-deciding anything left open.",model:"anthropic/strong"},plan:{whenToUse:"Break work into steps \u2014 turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.",model:"anthropic/strong",orchestratorModel:"anthropic/strong"},spec:{whenToUse:"Collaborate with the user to discover what to build, then write the spec \u2014 behavior, non-goals, interfaces, edge cases, testable acceptance criteria.",model:"anthropic/strong"},review:{whenToUse:"Validate or critique code, a plan, or a spec \u2014 deliver a complete, severity-rated verdict without adjudicating.",model:"openai/medium",orchestratorModel:"openai/strong"},advisor:{whenToUse:"Debug failures, investigate why something is broken or misbehaving, diagnose live/runtime issues, or give engineering advice and second opinions \u2014 reason from evidence and recommend the next move. Use advisor (not explore) whenever the task is to find out what is going wrong.",model:"anthropic/strong"},"review/companion":{whenToUse:"Born by the daemon for one human review; never spawned by an agent.",availableTo:[]}}}e(h,"defaultKindsConfig");function u(){return{anthropic:{ultra:"anthropic/claude-fable-5:xhigh",strong:"anthropic/claude-opus-5-5:medium",medium:"anthropic/claude-sonnet-5-5:medium",light:"anthropic/claude-haiku-4-5:high"},openai:{ultra:"openai-codex/gpt-6-astra:max",strong:"openai-codex/gpt-6.1-sol:high",medium:"openai-codex/gpt-6.1-sol:medium",light:"openai-codex/gpt-6-luna:low"}}}e(u,"defaultModelLaddersConfig");function M(){return{marketplaces:{},plugins:{}}}e(M,"defaultScopeState");export{S as AGENTS_DIR,A as CONDENSED_HISTORY_MODES,x as CONFIG_FILE,k as CRTR_DIR_NAME,p as DEFAULT_CONDENSED_HISTORY,l as DEFAULT_LIVE_CYCLES,i as DEFAULT_MAX_PANES_PER_WINDOW,s as DEFAULT_WHIP_MESSAGES,c as DEFAULT_WHIP_MESSAGE_MODE,_ as ExitCode,v as MARKETPLACE_MANIFEST_DIR,w as MARKETPLACE_MANIFEST_FILE,I as MOUSE_MODE_DEFAULTS,f as PLUGIN_MANIFEST_DIR,E as PLUGIN_MANIFEST_FILE,y as PROFILE_DIR,r as SCHEMA_VERSION,b as STATE_FILE,T as WHIP_MESSAGE_MODES,h as defaultKindsConfig,u as defaultModelLaddersConfig,d as defaultRemoteCanvasConfig,D as defaultScopeConfig,M as defaultScopeState};

package/docs/cli/README.md

@@ -0,0 +1,17 @@
+---
+title: Using crtr
+description: When you want to use crtr from a terminal, read this section because it leads from your first conversation to the canvas, human inbox, and durable documents.
+---
+
+# Using crtr
+
+Use these pages to start and return to an agent conversation, see the work running on your canvas, answer an agent's questions, and give future agents useful context.
+
+| Page | What you can do |
+|---|---|
+| [First session](./first-session.md) | Install crtr, set it up, and start a conversation. |
+| [The viewer](./the-viewer.md) | Read and control a live agent conversation in tmux. |
+| [Canvas and dashboard](./canvas-and-dashboard.md) | See the node graph, find work that needs attention, and reopen a node. |
+| [Human inbox](./human-inbox.md) | Answer decisions, review documents, and follow a live display. |
+| [Documents and preferences](./documents-and-preferences.md) | Save knowledge and instructions that should shape later agents. |
+| [The official plugin marketplace](./official-marketplace.md) | Find a plugin, see what it needs, and install it. |

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
+
+The canvas is one graph of objects: nodes, documents, bash jobs, owners and custom objects. This page covers the node views, which are the dashboard and the browser; `crtr canvas read`, `list`, `search`, `watch` and `edges` work on every kind of object (see [Documents and preferences](./documents-and-preferences.md)). You can see every agent as a node on the 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 resume 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 and drill-in paths, run:
+
+```sh
+crtr node inspect show <node-id>
+```
+
+The documents a node wrote, including its reports, are objects it owns: `crtr canvas list --owner <node-id>` lists them, `crtr canvas read <node-id>/reports/<name>` opens one, and `crtr canvas search` finds one by its text. `crtr node inspect transcript <node-id>` reads its saved conversation, and `crtr node inspect context` opens its context directory of scripts and data. `crtr canvas history search` searches what nodes in the current working directory were told and said — past inboxes and conversations, not reports or documents.
+
+## 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 and, without a confirmation, 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/documents-and-preferences.md

@@ -0,0 +1,52 @@
+---
+title: Documents and preferences
+description: When you want later agents to retain a fact or follow an instruction, read this page because it explains who owns a saved document and how to inspect or revise it.
+---
+
+# Documents and preferences
+
+You can give future agents useful context without pasting the same background into every conversation. Ask an agent to save a durable fact or instruction, then inspect the saved document yourself from the terminal.
+
+A saved note is a **document**, one kind of object on your canvas. It has an owner, a name of the form `<owner>/<path>`, a one-line preview, and recorded revisions, and other documents or messages point at it as `[[name]]`. The agent saves it by running `crtr doc write`; you find, read and watch documents with `crtr canvas`.
+
+## Tell an agent what should persist
+
+Say what should be saved 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 owner is best: a document you own follows you everywhere, while a document a repository owns belongs to that one repository. For the explanation of document owners and loading, see [Documents](../concepts/documents.md).
+
+## Browse what was saved
+
+List the documents you can read, optionally narrowed with `--kind`, `--owner`, `--privacy` or `--name <prefix>`:
+
+```sh
+crtr canvas list --type document
+```
+
+Read one by its name from that list:
+
+```sh
+crtr canvas read <name>
+```
+
+`crtr canvas read` resolves a bare name by looking first at the reading node's own documents, then its repos (nearest first), its profile and app, then your own documents, installed plugins, and crouter's built-in documents last. Write `<owner-handle>/<path>` to name one owner's document exactly, and use `crtr canvas search` to find one by its text. Reading a document also makes you a watcher of it, so its later edits reach you; `list` and `search` record nothing.
+
+## Edit a document
+
+Document revisions are intentional and recorded. To replace a document's body, pipe the complete replacement text to `crtr doc edit` and give the reason for the revision:
+
+```sh
+printf '%s\n' 'Production changes need an explicit approval.' | \
+  crtr doc edit <name> --rationale "Updated the approval rule."
+```
+
+`crtr doc edit` replaces the whole body you pipe; it does not append text. For a partial change, use `crtr doc edit <name> --rationale '…' --blocks <<'EOF'` with whole-line `<<<<<<< SEARCH`, `=======`, and `>>>>>>> REPLACE` markers around verbatim old and new text. An empty REPLACE deletes text. Scripts can still use `--replace '[{"old":"…","new":"…"}]'`. Read the document before you edit it; an edit made from an older revision is refused. Use `crtr doc history <name>` to read the revision history. If you want to create a document yourself, use `crtr doc write`; it takes a name, a preview sentence that tells agents when to read it, and the document body on stdin. `--kind knowledge|preference` (default `knowledge`) sets how agents use it, and `--owner node|user|profile|app|repo` chooses who owns it (default: the writing node; `profile:<name>` and `repo:<handle>` name a specific one). New documents are `privacy: public` unless `--privacy friends` or `--privacy private` is supplied; a repository owns only public documents. `crtr doc edit --privacy <level>` changes the level and records the revision.
+
+Documents are 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/first-session.md

@@ -0,0 +1,76 @@
+---
+title: Your first crtr session
+description: When you have installed crtr and want to start an agent conversation, read this page because one command, crtr, sets up the machine on first run and opens a conversation.
+---
+
+# 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 start
+
+Install crouter globally, then run `crtr` from the directory where you want the agent to work.
+
+```sh
+npm install -g @north-light/cli
+crtr
+```
+
+The first time you run `crtr` on a machine, it opens the setup installer. The installer signs you in to a model provider, then offers companion packages (including the official plugin marketplace) and system dependencies such as tmux. On a Mac, a last step explains how to make Option act as Alt in your terminal (crouter's menu is Alt+C), and can write the setting for you in Ghostty or VS Code after you confirm; until it is set, `/menu` opens the same menu. Next it asks which profile this directory belongs to, then opens a conversation with an agent in the same terminal. That first agent offers a short tour; say yes to learn the viewer, the inbox and document review, or just tell it what you're working on.
+
+The conversation viewer is a tmux pane. If you ran `crtr` outside tmux, it starts tmux for you: after setup, the profile choice and sign-in, it opens a tmux session named `crouter` (or adds a window to it, if it already exists) and runs your same command there. Your other tmux sessions are left alone. If tmux is not installed, `crtr` tells you how to install it. The first conversation in a session that `crtr` started shows how to leave and come back: `Ctrl+B d` leaves tmux while the agent keeps running, and `Ctrl+B n` / `Ctrl+B p` switch windows. Run without a terminal (piped or in a script), `crtr` never starts tmux.
+
+To reopen the installer later, for example to sign in to another provider or add a package, run `crtr sys setup`.
+
+## Start a conversation
+
+Every later `crtr` opens a new conversation in the current directory. You can pass a directory and a first message:
+
+```sh
+crtr                                   # a conversation here
+crtr ~/code/app "Find the failing tests."  # a conversation in ~/code/app with a first message
+crtr -c                                # return to the most recent conversation here
+crtr -r                                # choose a conversation here to return to
+```
+
+Type in the editor at the bottom of the viewer. Enter sends the message. Alt+Enter (Option+Enter on a Mac) or Shift+Enter starts a new line.
+
+To start an agent from a script or another agent without taking over the terminal, create a root node instead:
+
+```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. Inside tmux it opens a viewer pane for that node; outside tmux it prints the node id, and you open the viewer 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]
+  command --> broker[Node broker]
+  broker <--> viewer[tmux viewer]
+  broker --> canvas[Canvas state]
+```
+
+## Return to a node
+
+When you leave a conversation (`Ctrl+D`), `crtr` prints that the agent is still running and the exact command to reopen it. `crtr -c` and `crtr -r` reopen conversations started in the current directory. To reopen a specific conversation by id, from any shell (outside tmux it starts tmux first, as above):
+
+```sh
+crtr -r <node-id>
+```
+
+`crtr -r` resolves the id first and uses that conversation's own profile and directory, so it works from any directory. An id prefix works too (including the 8-character form pickers show); when it matches several running conversations, `crtr` lists their full ids. `crtr -r` with no id lists this directory's conversations to pick from. Inside a conversation, `Alt+C` → Find node (or `/resume`) searches every conversation. From inside tmux you can also use:
+
+```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/official-marketplace.md

@@ -0,0 +1,75 @@
+---
+title: The official plugin marketplace
+description: When you want to know which plugins crouter ships in its official marketplace, or how to install one, read this page because it lists each plugin with what it adds and what it needs on your machine.
+---
+
+# The official plugin marketplace
+
+The official marketplace is a git repository, [`crouton-labs/crouter-official-marketplace`](https://github.com/crouton-labs/crouter-official-marketplace), that holds 15 plugins for crtr. Some add commands (`crtr exa-search`, `crtr capture`), and the rest add markdown documents that agents are shown when they become relevant. Each plugin installs on its own.
+
+## Add the marketplace
+
+The installer that the first `crtr` opens (and `crtr sys setup` reopens) offers to register the marketplace and to install `capture` and `exa-search` from it. To do it by hand:
+
+```sh
+crtr pkg market add https://github.com/crouton-labs/crouter-official-marketplace.git
+crtr pkg market browse crouter-official-marketplace
+```
+
+`pkg market add` takes `--ref` (default `main`) and `--scope` (`user` or `project`; the default is `project` when a project is available, otherwise `user`). `pkg market browse` lists every plugin with its version and description, and marks the ones you already have installed.
+
+## Install a plugin
+
+Install by the ref `<marketplace>/<plugin>`:
+
+```sh
+crtr pkg plugin install crouter-official-marketplace/tsym
+```
+
+`--scope user` or `--scope project` picks where it goes. A plugin that adds commands has them live on your next `crtr` invocation. If the plugin declares an executable it needs (for example `grove` for `dev`) and that executable is not on your `PATH`, the install still succeeds and prints a warning with the install hint.
+
+Manage what you have installed:
+
+```sh
+crtr pkg plugin list                                        # installed plugins
+crtr pkg plugin show tsym                                   # manifest and documents
+crtr pkg market update                                      # refresh the marketplace; also updates installed plugins from it
+crtr pkg plugin update --name tsym                          # refresh one plugin
+crtr pkg plugin disable tsym                                # keep it installed but hide it
+crtr pkg plugin remove tsym
+```
+
+## Plugins that add commands
+
+| Plugin | What it adds | What it needs |
+|---|---|---|
+| `capture` | `crtr capture`, which forwards to the Capture CLI: CDP screenshots, rendered-geometry measurement, HAR, accessibility trees, JS execution and site libraries. | The Capture CLI: `npm install -g @crouton-kit/capture`. |
+| `tsym` | `crtr tsym`, which forwards to the tsym CLI: read a TypeScript codebase by symbol (outline, inspect, show, type) from the compiler's own resolution. It also ships two documents: one tells explore agents to map TypeScript with tsym first, and one points to `crtr tsym -h` when an agent is about to grep for a symbol. | The tsym CLI: `npm install -g @crouton-kit/tsym`. |
+| `exa-search` | `crtr exa-search` with three commands: `web` (ranked pages with excerpts), `answer` (one answer with citations) and `contents` (clean text from URLs you already have). | An Exa API key, from the `EXA_API_KEY` environment variable or `~/.crouter/exa.key`. A call without one fails before any request is sent. |
+| `bird` | `crtr bird`, which forwards to the bird CLI: read tweets, threads, replies and search on X/Twitter, and post or reply. It signs in with your browser's X cookies (Arc, Firefox or Chrome), so `tweet` and `reply` post publicly as you. | The bird CLI, built from [`CaptainCrouton89/bird`](https://github.com/CaptainCrouton89/bird) (needs `bun`). The plugin's install hint has the steps. |
+| `github-asset` | `crtr github-asset attach <file> --pr <number>`, which uploads a local file through GitHub's attachment flow and prints its permanent `user-attachments` URL. Use it to put a video or screenshot in a pull request. | The Capture CLI (`crtr capture`), the GitHub CLI `gh` signed in, and a running browser with CDP enabled that is signed in to GitHub. The command never launches a browser. |
+| `dev` | Development workflow documents (pull-request writing, planning, specs, code-craft preferences, runtime verification), a `spec/requirements` agent kind, `crtr human pr review` (review a branch's diff against its base beside a companion agent), a `dev` lesson track in `crtr sys tutorial`, `crtr dev` for a repository's own generated commands, and `crtr dev grove` plus a bare `dev` command that forward to Grove. It also installs lifecycle hooks that manage Grove instances for nodes: they refuse a second resident root inside an instance, label it with the node id, and finish the instance when that node closes. | Grove, for the Grove commands and hooks: install it, then run `grove setup` in the repository. |
+
+The `capture`, `tsym` and `bird` plugins pass every argument straight through to the external binary. `crtr capture -h` shows the Capture CLI's own help, and the same holds for the other two.
+
+## Plugins that add documents
+
+These plugins add markdown documents and no commands. Once installed, agents are shown each document when its delivery rule matches (see [Documents and preferences](./documents-and-preferences.md)); you can also read them with `crtr canvas read <plugin>/<document>`.
+
+| Plugin | What it contains |
+|---|---|
+| `ai` | Playbooks for building on LLMs: prompt and agent-context design, agent-facing interfaces (CLIs and tools), human-facing agent UI and UX, multi-agent orchestration, structured output, evals and quality gates, and testing agent-written code. It also adds a rule that applies when you edit prompt files. |
+| `claude-authoring` | Guides to writing Claude Code artifacts: `CLAUDE.md` files, hooks, rules, skills, commands, and scripts. |
+| `knowledge-capture` | Four working modes for saving what you learn: `collaborate` (think with a peer, no artifacts), `interview` (structured Q&A saved as markdown), `epiphany` (advisors with conflicting lenses, for a breakthrough) and `learn` (distill a session into a knowledge document). |
+| `design-discovery` | A Socratic interview, run through `crtr human`, that questions you about how a product or feature should feel before anything is built. |
+| `web` | Frontend knowledge: visual direction for customer-facing pages, interface design for dashboards and tools, UX heuristics, an interactive design workflow, HTML mockups for design review, a UX-consultant role, and frontend debugging. |
+| `cloudflare` | Working with Cloudflare from a shell: Wrangler setup and deploys, the REST API with `curl`, finding endpoints in the OpenAPI spec, and the `llms.txt` doc index. |
+| `vercel` | Working with Vercel from a shell: the Vercel CLI for deploy, dev and logs, the REST API with a bearer token, and docs discovery through `llms.txt`. |
+| `railway` | Working with Railway from a shell: the Railway CLI for deploy, logs and environments, the GraphQL API with a project or account token, and docs discovery through `llms.txt`. |
+| `fly` | Working with Fly.io from a shell: `flyctl` for launch, deploy, status and logs, the Machines API with a bearer token, and docs discovery. The plugin is named `fly` because a plugin name cannot contain a dot. |
+
+The four hosting plugins (`cloudflare`, `vercel`, `railway`, `fly`) document how to install and sign in to each provider's own CLI; installing the plugin does not install that CLI or hold any credential.
+
+## Add a plugin to the marketplace
+
+The marketplace repository's [README](https://github.com/crouton-labs/crouter-official-marketplace#readme) describes how a plugin is laid out and how to propose one. To write a plugin that is hosted somewhere else, see the [plugin authoring guide](../plugin/README.md).

package/docs/cli/the-viewer.md

@@ -0,0 +1,80 @@
+---
+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, or type `/menu` if Option/Alt does not work in your terminal yet (on a Mac, Option must be set to send Alt; `crtr sys setup` explains how for your terminal). The status line's bottom segment reminds you: `Alt+C menu (or /menu) · Alt+I inbox`, rendered from your actual bindings. 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. |
+| `/menu` | Open the crouter action menu (same as Alt+C). |
+| `/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 |
+| [Documents](./documents.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/documents.md

@@ -0,0 +1,52 @@
+---
+title: Documents
+description: 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 [Scopes and trust](./scopes-and-trust.md)).
+
+```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/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 canvas read internal/nodes-and-canvas` for lifecycle operations.

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

@@ -0,0 +1,29 @@
+---
+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, 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 [Documents](./documents.md) 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 [`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: 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 [`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 canvas 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 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 [`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, 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`; [`nodes.create`](../sdk/nodes.md) documents the profile, kind, and mode fields an application passes.