@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,165 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Testing your app, this knowledge should be
+  read because FakeCloud from @north-light/sdk/testing — a fake directory and
+  runtime your real OAuth2Client and Crouter talk to through fetch.
+---
+
+# Testing your app
+
+`@north-light/sdk/testing` exports `FakeCloud`, a fake crouter cloud: the directory (discovery, token refresh, JWKS) and each person's runtime (grant, runs, memory, providers, run notices). It answers through `fetch`. Your app's production path — `new OAuth2Client(...)`, `oauth.client(userId)`, `runs`, `memory`, `grant`, `providers`, `watchRuns`, `watchGrants`, `onRefusal`, `forwardRunEvents`, `verifyRunNotice` — runs against it unchanged. The only differences from production are the `fetch` and `issuer` you pass in.
+
+There is no mock `Crouter`. An object typed as `Crouter` would re-implement `RunReply`, `RunStream`, the watchers, retries and error mapping, so your tests would check a copy of the SDK instead of the SDK. FakeCloud fakes only the wire, so every SDK behaviour under test is the one you ship.
+
+The subpath is Node-only (it uses `node:crypto`), adds no dependency, and imports no test framework: it works with `node:test`, vitest, jest or anything else. Nothing listens on a port.
+
+## Setup
+
+```ts
+import { OAuth2Client, MemoryConnectionStore } from '@north-light/sdk';
+import { FakeCloud } from '@north-light/sdk/testing';
+
+const cloud = new FakeCloud({ clientId: 'doppel' });
+const store = new MemoryConnectionStore();                   // or your own ConnectionStore
+await cloud.connect(store, 'user:o1', { scopes: ['crtr:llm', 'crtr:act', 'sms:send'] });
+
+const oauth = new OAuth2Client({
+  clientId: 'doppel', issuer: cloud.issuer, fetch: cloud.fetch,
+  privateKey, redirectUri: 'https://app.test/callback', store,
+});
+const client = await oauth.client('user:o1');               // first call refreshes through the fake directory
+```
+
+`cloud.connect(store, userId, {scopes?, dependencies?})` makes the person's grant active (default scopes `crtr:llm`, `crtr:act`) and saves a `Connection` in your store with its access token already expired, so the first call refreshes through the directory exactly as in production.
+
+`cloud.crouter(userId)` returns a real `Crouter` on that person's runtime with a fresh token and no refresh. Refusals and refreshes never reach it. Use it only for code whose production signature takes a `Crouter`. Code that goes through `OAuth2Client` in production should go through `oauth.client` in tests too.
+
+Options: `new FakeCloud({clientId, issuer = 'https://directory.test', runtimeUrl = 'https://runtime.test' (or (userId) => url), runtimeId = 'runtime:test', runtimeClientId = 'runtime-client', runtimeVersion?, streamIdleMs = 60000, accountAppUriTemplate = '<issuer>/account/apps/{client_id}' (null omits it), runNotice?, isolatedRuns = 'available'})`.
+
+### Isolated runs
+
+The fake stands in for a crouter cloud guest, where the Linux root launcher always exists, so `runs.start({isolated: true})` starts a run by default and `run.params.isolated` is `true`. The checks `startRun` makes without the launcher are mirrored: `isolated` must be a boolean, `cwd` is accepted only with `isolated: true` and must be an absolute path inside the run's root folder, `/apps/<clientId>/nodes/<run id>` (else 400 `invalid_request`, `param: cwd`), and `worktree` is refused. Nothing in the fake enforces the sandbox itself (no network, no `files/` mount).
+
+`isolatedRuns: 'unavailable'` models a runtime without the launcher, such as a local daemon on a Mac: every isolated start answers 503 `isolated_unavailable` (`param: isolated`, retryable, so `runs.start` sends it three times before throwing). Use it to test your app's handling of that refusal.
+
+## Driving runs
+
+Nothing in the fake runs a model. A run stays `running` until your test drives it, either directly or through a responder:
+
+```ts
+cloud.runs.respond(({ run }) => run.reply(`echo: ${run.pending.at(-1)?.text ?? run.params.prompt}`));  // every user
+cloud.user('user:o1').runs.respond(null);                                          // per-user override
+```
+
+A responder gets `{run, kind: 'start' | 'message', messages}`. It is called after the fake answers a `run.start`, or a `run.message` with `start_turn` true, and never for an idempotent replay. A responder that throws is recorded in `cloud.responderErrors` and fails nothing else. An `async` responder can await your app's state mid-reply.
+
+`cloud.runs` and `cloud.user(id).runs` have one shape, `{all: FakeRun[], respond(fn)}`: `all` lists the runs in start order (a deleted run stays, with `deleted` set), so `expect(user.runs.all).toEqual([])` works. Each entry is a `FakeRun`:
+
+| Method | Effect |
+|---|---|
+| `reply(text, {chunks = 2, messageIds?})` | One turn: `node.turn.started`, text deltas, `node.output_text.done`, `node.turn.completed`. Delivers `messageIds` (default: every pending message). The run goes `idle` (`waiting_on_user` with an open question). |
+| `failTurn({code: 'model_error' \| 'content_refused', message})` | The same turn ending `stop_reason: 'error'`; `runs.get` shows `last_turn_error`; `runs.reply(...).collect()` ends `error`. |
+| `setActivity(activity, {at?})` | Fake-only: status `running` with this `activity` until the next event. The only way to reach `writing` or a streaming tool call. |
+| `settle(ending)` | `{result}`, `{declined: {reason, code, retryable}}`, `{failure: 'canceled' \| 'deadline_exceeded'}`, or `{runtimeError: reason}`. Emits `node.settled` with the outcome the runtime writes. |
+| `idle()` | Goes idle without a new turn (stopped without submitting). |
+| `ask({title, slots?})` | Opens a question (`waiting_on_user`); returns its id. Your app's `questions.answer` records the answer. |
+| `delete()` | As if the runtime deleted it: reads 404, streams close, its idempotency keys are dropped. |
+| `emit(type, fields, {nodeId?})` | Appends any run event; another `nodeId` is a child node's event. Status and activity re-derive from the log. |
+| `closeIdle()`, `expireEvents(upTo)` | Idle-close open streams now; drop old events so `stream_gap` is reachable. |
+
+Read-only members: `id`, `userId`, `params` (the `run.start` body, `isolated` and `cwd` included), `idempotencyKey`, `messages`, `pending`, `status`, `activity`, `outcome`, `result`, `lastTurnError`, `events`.
+
+What a turn's input is: `reply` and `failTurn` deliver `messageIds` (default: every pending message), and the turn's `node.turn.started` input text is those messages' text. A turn that delivers none (`messageIds: []`, or nothing pending) uses the run's `prompt` as its input on the run's first turn only, and an empty input after that; it still emits a full root turn with the text you pass. So `reply('', {messageIds: []})` is not a turn that answers nothing. To script a child node that works and answers nothing, or any event outside a root turn, use `emit(type, fields, {nodeId: 'child-1'})`: for example `run.emit('node.turn.started', {input: {text: 'x', message_ids: []}, entry_id: 'c1'}, {nodeId: 'child-1'})` followed by `node.turn.completed` with the same `nodeId`. Events with another `nodeId` never complete the app's `runs.reply`, which waits for the root's turn.
+
+Messages follow the runtime: `start_turn` true makes the run `running` at once and calls the responder; `start_turn` false only records it. A message to a run settled `canceled` or `deadline_exceeded` is refused 409 `run_settled`; to a run settled any other way it reopens the run. A deleted run answers 404.
+
+Idempotency follows the runtime too: the same `Idempotency-Key` with the same body replays the first answer (no new run, no responder call); the same key with a different body, or reused between `run.start` and `run.message`, is 409 `idempotency_conflict`. After a run is deleted, its start key creates a new run.
+
+## Grants and setup state
+
+`cloud.user(id).grant`: `state` (the `GrantGetDTO`, or null), `set({dependencies?, resolved_scopes?, spend_cap?})` (a new `rev`), `setup(provider, state, {message?})` (a dependency change without a `rev` bump), `sync()` (unchanged content: no version change, no wake), `revoke(code = 'grant_revoked')`, `restore(patch?)`.
+
+`grant.get` with `wait` and `since` is held until the version changes, exactly as the runtime holds it, so `oauth.watchGrants` works unmodified. `user.reads` lists the person's `grant.get` calls and `user.holding` counts reads held now.
+
+## Refusals
+
+- `user.refuse(code)` leaves the grant alone: the directory refuses each refresh with `code` (`grant_removed`, `grant_suspended`, `refresh_token_expired`, `refresh_token_reused`, `grant_revoked`), and tokens issued before the call get 401, so the next call refreshes and is refused. `refuse('ok')` clears it.
+- `grant.revoke('grant_removed')` deactivates the grant: calls answer 401 `grant_revoked`, held reads wake to it, open streams get an error frame, and the next refresh is refused with that code.
+- `user.expireTokens()` forces a refresh without a refusal.
+
+The real `OAuth2Client` handles all of it: your `onRefusal` runs with the refusal, the stored connection is removed, and the thrown error has `refusalOf(e)` set. `await cloud.refusalError(code)` returns that exact error for unit tests that need the value.
+
+## Memory and providers
+
+`user.memory.put({name, body, privacy = 'public', kind = 'knowledge', ...})` and `remove(name)`. Without `crtr:memory:manage:user` in the grant, only `public` documents are listed and others read as 404, as on the runtime. List items carry the full `MemoryListItem` fields.
+
+```ts
+cloud.providers.define('sms', { tools: { send: { group: 'send', handler: ({ userId, arguments: args }) => ({ sent: true }) } } });
+```
+
+A call is checked against the grant's `<provider>:<group>` scope (403 `scope_missing`). A handler that throws `FakeCloud.error({...})` answers that envelope; any other throw is 502 `provider_error`. `status: 'install_failed'` lists the provider with its `error` and answers calls 503 `provider_unavailable`.
+
+## Failures, gates and the directory
+
+`intercept(op, fn, {user?, times?})` runs `fn` before an operation; it may await, act, or return an answer. `failNext(op, answer, {user?, times = 1})` is the shorthand. `gate(op)` holds every matching request until you call the `release()` it returns. `op` is a runtime operation name (`run.start`, `grant.get`, `memory.list`, …), `'*'` for every runtime operation, or `directory.discovery`, `directory.token`, `directory.jwks`.
+
+| Answer | Runtime operation | `directory.discovery` | `directory.token` | `directory.jwks` |
+|---|---|---|---|---|
+| `'unreachable'` | fetch rejects; the SDK throws `APIConnectionError` | fetch rejects | fetch rejects; no `onRefusal` | fetch rejects; `verifyRunNotice` throws `RunNoticeError` |
+| a status number | that status with a runtime envelope | that status; discovery fails | that status; an `InternalServerError` for 5xx coded `invalid_request`, origin `directory`; connection kept | that status |
+| `FakeCloud.error({status, code, message?, origin?, retryable?, details?, param?})` | that envelope | not allowed | not allowed (use `user.refuse`) | not allowed |
+
+Retries are the SDK's, so a scripted failure the SDK retries is absorbed unless `times` covers every attempt. One SDK call makes these attempts (`maxRetries` defaults to 2; a call's `maxRetries` option changes it):
+
+| What the fake answers | Operations | SDK behaviour | `times` to surface it |
+|---|---|---|---|
+| 401 (any code) | every runtime operation called through `oauth.client` | refreshes the token once, then repeats the call once | 2 |
+| a status number ≥ 500, or 429 | GET and DELETE operations: `grant.get`, `run.get`, `run.list`, `run.delete`, `trace.get`, `question.get`, `memory.list`, `memory.get`, `provider.tools`, `profile.list` | retried `maxRetries` times with backoff (250 ms, 500 ms) | 3 |
+| `'unreachable'` | the same GET and DELETE operations | retried `maxRetries` times | 3 |
+| `FakeCloud.error({..., retryable: true})` (the default for a 503), or `'unreachable'` | `run.start`, `run.message` (keyed sends) | resent with the same `Idempotency-Key` `maxRetries` times, waiting 500 ms, 1 s (or the envelope's `retry_after_s`) | 3 |
+| a status number, or an envelope with `retryable: false` | `run.start`, `run.message` | not retried (a status number answers `retryable: false`) | 1 |
+| anything else | the other POSTs: `run.interrupt`, `run.cancel`, `run.rename`, `question.answer`, `provider.call` | never retried | 1 |
+| anything | `run.events` (the SDK's `RunStream`) | a retryable error reconnects from the cursor with backoff; a non-retryable one, `stream_error` or `stream_dropped`, ends the stream | `Infinity` for a retryable one |
+
+The rows compose: one 401 followed by three 500s on `grant.get` surfaces the 500 (the call repeated after the refresh has its own two retries), so a 401 surfaces only when the repeat gets one too. A test that wants an operation to fail no matter what scripts `times: Infinity` and removes it afterwards with `intercept`'s returned function, or calls `cloud.reset()`.
+
+Discovery is memoized per `OAuth2Client`. A test that fails discovery should use a fresh `FakeCloud` and `OAuth2Client`.
+
+A runtime outage on an ordinary call: `user.expireTokens(); cloud.failNext('directory.token', 503, {user})`. An unreachable runtime: `cloud.failNext('*', 'unreachable', {user, times: Infinity})`. With `runtimeVersion` older than the SDK's minimum, calls fail with `RuntimeVersionError` (426).
+
+## Run notices and forwarding
+
+```ts
+const cloud = new FakeCloud({ clientId: 'chat', runNotice: { url: 'https://app.test/run-notices', deliver: (request) => app.handleNotice(request) } });
+```
+
+The fake sends notices by the runtime's rules: one is owed when an event is appended with no `run.events` stream open, or when the last stream closes with events unread; a burst coalesces into one; up to three attempts; a 401 re-mints the token once; a 5xx, a thrown `deliver`, or no answer within 10 s is retried; any other status ends the send. A run whose person has no active grant is owed nothing. The waits default to 0 so tests stay fast. Pass the runtime's values (`retryWaitsMs: [3000, 5000]`, `ackGapMs: 5000`, `failGapMs: 60000`) to test timing. Every attempt is recorded in `cloud.notices`.
+
+In your route, pass the cloud's `fetch` to `verifyRunNotice`:
+
+```ts
+await verifyRunNotice(request, { runNoticeUrl, issuer: cloud.issuer, grantee: 'app:chat', fetch: cloud.fetch });
+```
+
+Keys are cached per `(issuer, fetch)`, and each cloud has its own signing key, so several clouds on one issuer verify independently. `forwardRunEvents` needs nothing special: it reads the fake's event stream, idle close included (`streamIdleMs`).
+
+## Two app processes
+
+Build two app instances (two `OAuth2Client`s) on the same `cloud`. They see the same runs, grants and held reads. If they keep separate stores, the second refresh with a superseded token is refused `refresh_token_reused`, as it would be in production; a shared store with `lock` prevents it.
+
+## Asserting
+
+- `cloud.calls`: every runtime request as `{userId, op, runId, questionId, method, path, query, body, idempotencyKey, status, at}`.
+  - `userId` is the bearer token's `sub` whenever it names a person this cloud knows (created by `connect` or `user(id)`), whatever their grant or refresh-token state, so a call refused 401 still carries it. It is `null` only for a missing or undecodable bearer, or a `sub` the cloud has never seen.
+  - `runId` is the run the call addresses: the path's id for `run.get`, `run.message`, `run.events`, `run.interrupt`, `run.cancel`, `run.delete`, `run.rename` and `trace.get` (as sent, even when no such run exists), and for `question.get` and `question.answer` the run holding the question (null when none of the caller's runs does). `questionId` is the path's id on the two question operations. Both are `null` on every other operation.
+  - `body` is a parsed copy for your assertions; mutating it from an intercept is not a supported way to change what the fake handles.
+- `cloud.directoryCalls` and `cloud.refreshes`: directory requests, with `answer` (`ok`, a refusal code, a status or `unreachable`).
+- `run.params`, `run.messages`, `run.idempotencyKey`: what your app sent.
+- `cloud.notices`: every notice attempt, with its decoded token claims and your route's status.
+- `cloud.reset()` clears runs, calls, intercepts, responders, memory, idempotency keys and notices, and keeps grants and refresh tokens so stored connections stay valid.
+
+## Fidelity
+
+FakeCloud is checked against the real runtime on every crouter release: one set of conformance scenarios runs on the fake and on the real app listener (run start and idempotency, messages, reply streams, long-poll, every settle outcome, delete, the event stream's edges, grant holds, memory, providers, run notices). Two behaviours are fake-only because the runtime cannot be scripted that way: a successful provider call (the real side needs an installed provider), and `setActivity`. An isolated run that starts is checked only against `startRun`'s documented checks: the real listener in the suite runs without the Linux root launcher, so on it the `isolatedRuns: 'unavailable'` refusal is what is conformance-checked.
+
+Not faked: sign-in (`authorizeUrl`, `exchangeCode`, ID tokens — start from `cloud.connect`), token revocation, the owner and local-daemon surface (`nodes`, `canvas`, `crons`, `files`, …), and several apps on one cloud. `trace.get`, `run.rename`, `run.interrupt` and `profile.list` answer the right shape only.

package/dist/builtin-memory/explore/exploration-doc.md

@@ -0,0 +1,27 @@
+---
+kind: knowledge
+when-and-why-to-read: When an explore node is about to write, extend, or synthesize an exploration doc, this knowledge should be read because the shared shape lets whoever receives the map act from the high level and drill into depth only where their task needs it.
+gate: {kind: explore}
+rationale: >-
+  Scout results arrived as one-off prose in whatever shape each node improvised: parents could not hand a map forward, follow-up scouts started over instead of extending, and orchestrators reassembled transcripts by hand — one layer revision even prescribed cp-and-rename of scout reports. A single named artifact contract replaces all of that.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# Exploration docs
+
+An exploration document is the durable form of a mapping result: `explore-<topic>`, written with `crtr doc write` and owned by the node that mapped it, shared by its pointer `[[<node-id>/explore-<topic>]]`. An orchestrator's synthesis is `explore-map` — the high-level picture, with pointers into the `explore-*` documents that carry depth.
+
+Sections:
+
+- **Scope** — one or two lines: what this maps and where the boundary sits.
+- **The map** — the current state, organized by the subject's real seams (subsystem, layer, sub-question). Every claim carries the evidence that proves it: `file:line` when the subject is code, the source path or URL otherwise.
+- **Pointers** — `[[<node-id>/<name>]]` pointers to the exploration documents holding deeper detail, one line each naming what depth it holds. Omit when there are none.
+- **Gaps** — what remains unmapped or unverified, stated explicitly so a reader does not mistake silence for verified absence.
+
+Rules:
+
+- When a task points at an existing `explore-*` document, that document is your deliverable: extend and correct it in place with `crtr doc edit` — never write a parallel copy beside it.
+- Current state only. Recommendations, diagnosis, target design, and narration of how the exploration proceeded all belong elsewhere; a doc that accumulates them stops being a map.
+- These are goal-scoped documents owned by the node that wrote them. A durable reusable truth uncovered while mapping still goes through [[insights/capture]].

package/dist/builtin-memory/insights/capture.md

@@ -0,0 +1,49 @@
+---
+kind: knowledge
+when-and-why-to-read: When directly received user material supports a proposed reusable principle, this knowledge should be read because review by the user keeps durable guidance grounded in their actual judgment.
+short-form: Extract the why behind one user-derived principle, review its truth and destination, then write only what the user approves.
+rationale: Agents have missed deeper user insight hidden in ordinary feedback, saved their own unreviewed interpretation as fundamental truth, and — when the user corrected a behavior — proposed the corrected behavior itself as the insight when the durable truth was the reason the user made the correction. The earlier proposal template compounded this by framing capture as correction (a "Current truth" section) and burying destination and source in prose sections.
+---
+
+# Confirm a user-derived insight before saving it
+
+Insight capture collects alpha from the user: truth from their head that is stored in no code, no document, and no model weights. It is additive — new truth entering documents, not a correction of stored state. This workflow owns reviewed extraction and writing for a qualifying episode identified by [[runtime-base/insight-capture]] or an active domain listener. No document is written until the user approves both the durable truth and its destination.
+
+## Extract the why, not the behavior
+
+When the episode is the user requesting or correcting a behavior, the behavior is usually not the durable truth — it is one application of it. The insight is why the user made the correction: the underlying truth that generated it, which future agents can apply to situations the user never addressed. A candidate that restates the user's instruction as a standing rule is a failed extraction; ask what made the user want it, and propose that.
+
+## Find the home before drafting
+
+Search the proposed destination for an existing principle. If the episode refines, bounds, or strengthens one, propose a rewrite of that document; create a new document only for a distinct read trigger that can evolve independently.
+
+The destination can be an existing canonical document, an active listener, an existing organizing router, a flat principle, or a proposed active domain. An organizing router only gains an approved principle link; it never becomes a listener. Propose a new domain only when review can approve its scope, boundary, and first principle together. A single principle stays flat when no domain index is warranted.
+
+## Review one coherent principle
+
+Write the proposal as a small document with `crtr doc write` and submit it with `crtr human review new <name>`. Do not batch unrelated principles or ask a separate confirmation question first.
+
+```markdown
+# Proposed insight: <short principle name>
+
+- **destination:** <canonical name (owner) — existing doc to rewrite, new flat doc, or link into a listener or router — with the neighbouring listing, so the placement is judgeable without a lookup>
+- **visibility:** <the delivery rules the document will carry, or none, and why that reach is right>
+- **source:** <the episode in one line, quoting the user's pivotal words>
+
+## Proposed durable truth
+
+- <Terse truth, with a material boundary or excluded alternative when it matters, and the concise why future agents need.>
+- <Another plausible formulation only when the deeper principle is uncertain.>
+```
+
+`destination` and `visibility` are proposals to approve, never questions to ask: decide both and state the reason. Quote only enough of the user's words in `source` for them to judge the inference. Candidate bullets are hypotheses, not polished prose: several alternatives are allowed when the deeper principle is uncertain; do not pad, explain every bullet, or hide uncertainty in a long essay.
+
+The review is asynchronous. Continue unrelated work or wait dormant, but do not finish while this review is outstanding. An approval settles only this candidate; do not recapture it as a new insight unless the user introduces a genuinely separate principle.
+
+## Apply only approved truth
+
+Apply direct line edits and explicit comments. If feedback requires a materially new formulation, update the open review document or submit a replacement review; review the revised formulation before writing it. If no candidate survives, save nothing.
+
+Run `crtr doc write -h` for the writing contract, then reach only the approved destination — `crtr doc write --owner <owner>` to create it, `crtr doc edit` to revise one that exists. A new principle is normally knowledge, and a preference only when its use is behavioral; give it no delivery rule unless review approves a boot rule. Keep its body to the approved truth, any material boundary, and the concise why. Update the selected active listener or organizing router with the canonical link without duplicating the principle.
+
+Source context and agent reasoning stay only in the review document. Do not copy them into the principle's body or fields. Run `crtr doc lint` after every create or rewrite and fix every finding.

package/dist/builtin-memory/insights/init.md

@@ -0,0 +1,88 @@
+---
+kind: knowledge
+when-and-why-to-read: When the user invokes /insights:init to begin gathering user-derived insight about a domain, this knowledge should be read because a correctly scoped listener preserves uniquely valuable knowledge without creating a parallel store or background system.
+short-form: Initialize passive insight gathering for a domain at the narrowest durable owner; create one routed topic index that reviews user-derived principles before saving them.
+slash: true
+rationale: Ordinary conversations, corrections, answers to `crtr human send`, and review comments carry unique user knowledge that agents inconsistently recognize or save; when agents do infer a deeper principle, they have written it without first letting the user correct the extrapolation.
+---
+
+# /insights:init — begin domain listening
+
+Initialize an ordinary document that listens for user-derived insight about this domain.
+
+**Requested domain and mode:** $ARGUMENTS
+
+## Check for --active flag
+
+If `$ARGUMENTS` contains `--active`, follow the **active mode** steps below. Otherwise, follow the **passive mode** steps.
+
+## Establish the topic and owner
+
+Turn the request into a short path-safe topic slug and a compact domain boundary that preserves the user's meaning rather than reducing it to a single keyword. If the request is empty or too vague to distinguish relevant from unrelated information, ask one focused question through `crtr human send`.
+
+Choose the narrowest durable owner that reaches every future conversation where this domain matters:
+
+- repo when the insight is meaningful only inside one repository;
+- profile when it spans the selected profile's projects but should not follow the user elsewhere; or
+- user when it concerns the person, a market, a craft, or a domain that crosses workspaces.
+
+Infer the owner from the request and current workspace. Ask through `crtr human send` only when more than one owner is genuinely plausible, and settle the owner before writing anything. Never make a node the owner of an ongoing listener.
+
+Search the chosen owner before creating. Use `insights/<topic>` under the chosen owner (`--owner repo`, `--owner profile` or `--owner user`); if that name already represents the same domain, refine that listener rather than creating an overlapping one.
+
+## Create the listener
+
+Run `crtr doc write -h`, then create the listener document under the chosen owner, named `insights/<topic>`, as a preference with the rule `on: boot`, `deliver: preview` (`--rule`, see `crtr doc write --rule -h`).
+
+Its preview must name the actual domain trigger: when user-supplied information, a correction, or a user response relates to this domain, read the preference because recognizing the underlying principle preserves knowledge future decisions can use.
+
+Keep the body short. It contains:
+
+- the domain boundary, including exclusions needed to prevent false triggers;
+- a directive to follow [[insights/capture]] whenever a source episode may reveal a reusable principle; and
+- an `Approved insights` section containing links to the principle documents as they are approved.
+
+Do not copy the capture workflow into the listener. The link keeps that process in one maintained place. Do not create placeholder principle documents.
+
+Run `crtr doc lint`, fix every finding, then report the canonical listener name, selected owner, and the domain boundary. Initialization is complete once the routed listener exists; no independent work follows.
+
+## Active mode: research and surface claims
+
+When `--active` is present, do not stop after creating the listener. After initialization:
+
+### 1. Create the listener first
+
+Follow the passive mode steps above through "Initialization is complete." The listener document must exist before spawning the explorer.
+
+### 2. Spawn the explorer child
+
+Run this exact command, replacing `<topic>` with the topic slug you chose above:
+
+```bash
+crtr node new --kind explore --name "explore-<topic>" <<'TASK'
+Investigate the domain "<topic>" thoroughly. Your goal is to surface 3–5 distinct, falsifiable claims or questions about how this domain works, what its gaps are, or what fundamental principles govern it. Each claim should be specific enough that the user can confirm it, refine it, or reject it outright.
+
+Gather evidence from code, docs, existing understanding, and the repo's own files. Then present your claims clearly:
+
+**Claim 1:** [claim text]
+**Evidence:** [why you believe this]
+**Question:** [what would prove or disprove this?]
+
+Repeat for each claim. Write findings as the document `claims` with `crtr doc write`, and point at it in your report as `[[<node-id>/claims]]`.
+TASK
+```
+
+Do not wait for the explorer to finish—it runs in parallel. Move to the next step while it works.
+
+### 3. Coordinate user responses and capture flow
+
+When the explorer reports, share its claims with the user. For each claim, ask:
+- Does this ring true?
+- Is it incomplete or wrong?
+- What's the actual principle?
+
+For each user response, use [[insights/capture]] to extract and review the insight. Apply approved insights directly to the listener document's `Approved insights` section.
+
+### 4. Report completion
+
+Once claims have been surfaced and user guidance has generated approved insights, report that active initialization is complete. The listener document now passively captures this domain as new user material emerges.

package/dist/builtin-memory/internal/INDEX.md

@@ -0,0 +1,40 @@
+---
+kind: knowledge
+when-and-why-to-read: When you hit a question about how the crtr runtime itself works or how to extend it — what objects and documents are, how nodes and the canvas behave, where state lives on disk, how to add plugins/commands/marketplaces to crtr, or how the primitives compose into real systems — this index should be read so runtime-sensitive work follows the canonical model instead of fragile inferences from scattered command help.
+short-form: internal/ is the runtime's self- and developer-documentation — the canvas object model (objects, documents, owners, names, watches, jobs, custom objects), nodes and the canvas, where state lives on disk, document delivery, plugin and marketplace authoring, and worked examples. Open it to understand how crtr works or to extend it.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# internal/ — how the crtr runtime works, and how to extend it
+
+This directory is the runtime's **self- and developer-documentation**: operational references covering how crtr behaves and how to extend or reconfigure it, so any agent operating under it can route to the canonical model rather than reconstruct it from scattered `-h` output. It ships with crtr, as documents owned by the app `crtr`.
+
+## The object model, in one page
+
+crtr keeps one graph of **objects** in one SQLite database (`canvas.db`). Documents, nodes, bash jobs, owners (person, app, repo, profile) and custom objects are all objects: each has an id, a name, an owner and a privacy level, and **the same verbs work on all of them** — `crtr canvas read`, `list`, `search`, `watch`, `unwatch`, `edges`. What differs is the object's *type*, which decides what events it can emit and how it renders. There are no memory stores, tiers or scopes: a thing an agent writes is a document, and who sees it is decided by its owner, its privacy and its delivery rules.
+
+- **Documents** are the one object type for written knowledge: what used to be called memories, reports and context documents. Write them with `crtr doc write|edit|move|history|delete|lint`; read them with `crtr canvas read`. Each has a required one-line **preview** ("When …, read this because …"), a body, optional summary, privacy (`public` default, `friends`, `private`), delivery **rules**, and revisions — an edit is made from the revision you last read and is refused if the document moved on. A document's `kind` is `knowledge` (consulted) or `preference` (directs behavior); `report` documents are created only by `crtr push`. `crtr doc write -h` is the writing guide.
+- **Owners** are objects too: a node, the person (`user`), a profile, an app, or a repo. The owner decides who may read and change a document, where it syncs, and what deletes it. The default owner is the writing node (the document goes away with the node unless a kept document links to it); `--owner user|profile|app|repo` makes it outlive the node. A repo owns only public documents and syncs them to collaborators over the git ref `refs/crtr/docs`. An installed plugin is an app (`app:<plugin>`); crtr's own documents belong to the app `crtr`. Which owner to pick: [[internal/agent-shaping]].
+- **Names and pointers.** A document's full name is `<owner-handle>/<path>`; a node's handle is its id, so a node's report is `<node-id>/reports/<ts>-<id>-<kind>`. Point at an object as `[[name]]`, never by file path. In a document body each `[[link]]` attaches the target's preview wherever the body is delivered in full, and creates a `links-to` edge. A bare name resolves in the reader's view — own node, repos nearest-first, profile, app, then the person, installed plugins, and `crtr` last — so a repo document can shadow one of crtr's own. Moving a document (`doc move`) keeps its id and its links.
+- **Watches and events.** Every object publishes events — all kinds share created, read, watched, deleted and configured; each kind adds its own (a document `edited`, a node `report.update`, a job `exited`) — each with a level 1–10. **Reading an object, writing a document, messaging a node, spawning one or starting a job makes you its watcher**, and its later events reach your inbox — an edit to a document you read can steer you while you run. `crtr canvas watch` adds a watch with a pattern or listening config; `crtr canvas unwatch` ends one when the object no longer bears on your work. `list`, `search` and `edges` record nothing. `crtr canvas edges` shows `acted-on`, `links-to` and `watches` edges.
+- **Jobs** are backgrounded bash commands: object type `job`, readable with `crtr canvas read` (command, status, exit code, log path). A job emits `exited` and `killed` events to its watchers.
+- **Custom objects** are objects an outside service, script or app registers with `crtr custom-object register` — a dotted kind, a declared event catalog with fixed levels, and optionally a receiver (`queue` pulled with `receive`/`ack`, an HTTPS `url`, or an `argv` command). They `publish` declared events to watchers and, with `crtr canvas watch --as <object>`, can watch other objects. Use one when something outside crtr must surface state on the canvas or react to canvas events.
+- **What is still files.** A node's context directory (`$CRTR_CONTEXT_DIR`) holds scripts, data, logs and page modules — never the way to share writing. Package documents (crtr's own and a plugin's `memory/` folder) stay markdown files in their package and are imported as public, read-only documents; see [[internal/plugins]].
+
+## Contents
+
+- **nodes-and-canvas** — the agent-runtime model: nodes as objects on the canvas graph, spawn/delegate, the push/feed spine and watches, lifecycle (mode + lifecycle axes), jobs and custom objects, and revive (manual + daemon auto-revive).
+- **storage-tiers** — where state lives on disk: the scope root (prompts, plugins, personas, config), the canvas home (`canvas.db`, content-addressed document bodies, per-node files, diagnostics) and what git carries for repo documents.
+- **memory-loading** — how documents load into a node: the delivery events, `deliver` levels, `if` conditions, listings, boot-render ordering and the reader's view — read when diagnosing why a document did or didn't load.
+- **agent-shaping** — the when-to-use-which layer over the four dials that shape a node: kinds (the builtin roster, sub-kinds, custom personas), modes (base vs orchestrator), profiles, and document owners (node/profile/repo/user).
+- **plugins** — authoring a crtr plugin: the plugin.json manifest, directory layout, the package-file format of its `memory/` documents, scopes, install mechanics, versioning, command-capable plugins and bare binaries on every node's PATH.
+- **marketplaces** — authoring a crtr marketplace: the marketplace.json index, local-link and remote-Git plugin sources, auto-bump CI, dual-publishing.
+- **examples/** — worked compositions of the primitives into complete systems, e.g. the iMessage assistant node.
+
+Adjacent, outside this dir: writing documents (kind, delivery rules, preview, the asked-to-remember workflow) is owned by `crtr doc write -h` and its focused `--owner -h`/`--rule -h` — the guide lives on that `-h` surface so it is delivered exactly when you write. Finding and reading objects is `crtr canvas -h`; registering a custom object is `crtr custom-object -h`.
+
+Briefly: **plugins** package documents and commands, with command execution selected by `plugin.json.transport` (`exec` for a trusted local executable or `http` for a fetched remote REST manifest); **marketplaces** index and distribute plugins. Plugin commands enter the **external-command** fallthrough, leaving the core fast-path untouched.
+
+The individual files surface at their canonical names (open the one the situation calls for); this document is delivered at `preview` under the name `internal`, and `crtr canvas read internal` prints only its body to stdout; the names under it reach the node in the same tool result after command output.

package/dist/builtin-memory/internal/agent-shaping.md

@@ -0,0 +1,80 @@
+---
+kind: knowledge
+when-and-why-to-read: When you are choosing how to shape a node — which kind to spawn, base vs orchestrator, which profile, or which owner a document belongs to — this reference should be read so each task gets the right role, orchestration depth, identity, and guidance reach instead of paying for a mismatched agent shape.
+short-form: The four orthogonal dials that shape a node — kind (role + model tier), mode (base vs orchestrator), profile (identity + purview), and document owner (who sees a document) — plus when to reach for each over its alternatives.
+rationale: Agents pick shaping dials by reflex from the one-line `-h` blurbs and get the discriminators wrong — delegating debugging to explore instead of advisor, grinding an orchestrator-shaped job in base, minting a duplicate document under the wrong owner or with the wrong reach. The per-kind base docs carry the rationale but only the running node of that kind ever sees them; nothing gave a chooser the cross-cutting "which one, and why it's built this way" view before committing.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# Agent shaping — kinds, modes, profiles, and document owners
+
+Four orthogonal dials shape every node. This is the **when-to-use-which** layer over them — the philosophy of each and how to choose between alternatives. It does not cover mechanics: the node/canvas/lifecycle model is `internal/nodes-and-canvas`, where state lives is `internal/storage-tiers`, and the writing and delivery-rule contract for documents is `crtr doc write -h`. Point at those; this doc decides which dial to turn.
+
+The dials are independent — you set each without constraining the others:
+
+- **kind** — the node's role and expertise (`explore`, `developer`, a custom persona). Carries a model tier and a tool set.
+- **mode** — `base` (do it yourself; yield hands-on when an unsplittable task needs another window) vs `orchestrator` (delegate and hold a roadmap across cycles).
+- **profile** — the node's identity: which project dirs it can see and which owner-held documents and config it resolves against.
+- **document owner** — which owner object holds a document (node, profile, repo, user), which with its privacy and delivery rules decides who can read it and who has it loaded for them.
+
+A fifth axis, **lifecycle** (`terminal` vs `resident`), is orthogonal too but belongs to the runtime model — see `internal/nodes-and-canvas`. Terminal owes a final up the spine and reaps; resident stays interactable and is never forced to submit. Orchestrating never earns residency on its own.
+
+## Kinds — role, model tier, and tools
+
+A kind starts with a **`KindConfig`** in the launch registry: its one-line `whenToUse`, default model tier, tools and extensions, and which sub-personas it may spawn. Core or an enabled plugin can add role guidance with ordinary documents whose boot rule carries an `if` on `{kind, mode}`. Set the kind at spawn with `crtr node new --kind`, or change it live with `crtr node config --kind` / `crtr node promote --kind`.
+
+**Why kinds exist at all.** Two payoffs a per-task instruction can't buy. First, **model-tier economics ride the kind boundary**: `explore` defaults to a fast/cheap model (right for mapping and summarization, wrong for judgment); `advisor` defaults to the slow, expensive think-y tier (right for debugging and tradeoffs). Fencing the tier into the kind is what stops an orchestrator from delegating debugging to a cheap explore scout. Second, a kind is **standing role discipline** that survives across every task of that type — the reviewer's neutral priming, the developer's done-bar, the planner's decision-resolution — rather than prose you must restate and that erodes each spawn.
+
+### The builtin roster
+
+| kind | what it's for | reach for it when |
+|---|---|---|
+| **general** | catch-all worker | no specialist role fits |
+| **explore** | read-only current-state and code-path mapping | you need evidence about unfamiliar code or architecture, not diagnosis or recommendations |
+| **advisor** | diagnosis, debugging, tradeoff analysis, and engineering second opinions | you need to explain a failure or judge a consequential call |
+| **spec** | define what outcome and behavior to build | the requirement itself is unsettled |
+| **design** | decide the structural shape of a solution | the implementation has consequential architectural choices |
+| **plan** | sequence implementation of an approved specification or design | the outcome and structure are settled but the build path is not |
+| **developer** | implement a change | you are building the feature or fix |
+| **review** | independently critique code or a document | substantive work needs a severity-rated verdict |
+
+The discriminators that get missed are **explore vs advisor** (mapping vs judgment), **spec vs design** (what to build vs how it is structured), and **design vs plan** (decide the shape vs sequence a decided shape).
+
+### Sub-kinds
+
+Specialist sub-personas hang off a parent kind. They are not in the top-level `--kind` list but are valid by exact registered path. Use one for a narrowly targeted assignment, not as a mandatory roster; discover the roles available from a kind with `crtr sys context prompt-review --list --kind <kind>`. Core and plugins register sub-kinds through the same launch registry.
+
+### Custom personas
+
+The roster is extensible. Add a `kinds.<name>` entry to a `config.json` at user or project scope (any subset of `whenToUse`, `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo` — an entry field-merges over a kind a lower layer defines, so `{"whenToUse": "…"}` alone re-glosses a builtin kind without touching its model tier; a NEW kind requires `whenToUse`) and author the persona prose as documents named `kinds/<name>/00-base` (and `01-orchestrator`) whose boot-content rule carries `if: {kind: <name>, mode: ...}` (in a package file, the `gate` frontmatter key). A standing personal assistant, for example, is a scope-configured custom `personal-assistant` kind rather than a builtin kind. The registry merges **project > user > builtin**, so a custom kind can add a new role or shadow a builtin one without restating the rest. A plugin can ship a kind the same way — a `kinds` block in its manifest plus persona documents gated the same way in its `memory/` folder; an enabled plugin's entries layer directly below its host scope's own `config.json` (see `internal/plugins`). Reach for a custom kind when a **recurring role** wants its own standing discipline and model/tool defaults that outlast any single task — not for a one-off instruction, which belongs in the spawn prompt.
+
+## Modes — base vs orchestrator
+
+Every kind has both a `base` and an `orchestrator` persona; mode picks which one splices in.
+
+- **base** — hands-on. Do the work yourself and deliver the result. Your scarce resource is the task. Spawn a child only for a cleanly separable unit, never as your first move. When an unsplittable task needs another context window, `crtr node yield` and continue hands-on as base.
+- **orchestrator** — you own a goal with enough independent parallel work that coordination is now your primary job. Decompose it, delegate each piece, integrate what comes back, hold its document `roadmap`, which loads at every new session, and yield (`crtr node yield`) into a clean window when context fills. Your scarce resource is your own context window; the moment you start grinding the whole goal out by hand you've lost the plot. The shared loop lives in the `orchestration-kernel` doc (auto-gated for orchestrators).
+
+**When to reach for orchestrator over base.** Both conditions must hold: the remaining work contains genuinely independent units that can proceed in parallel, and the task is large or valuable enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after delegation and synthesis costs. Promote early (`crtr node promote`) once coordination and integration should replace hands-on execution as your primary job; a base node that merely spawns one helper stays base. Task duration, phase count, context exhaustion, and sequential or tightly coupled work do not qualify — yield and continue hands-on instead. Create a bounded child directly as a sub-orchestrator (`crtr node new --mode orchestrator`) only when its own assignment passes the same test.
+
+## Profiles — identity, purview, and its own documents
+
+A profile is a stable **agent identity** — itself an owner object: a fixed id, a display name, the documents it owns, and a **purview** of project directories it resolves documents and config from. Select it at spawn with `crtr node new --profile <id-or-name>`; omit and a child inherits the caller's profile. Pin a directory's default profile with `crtr profile default` so the startup chooser stops asking. Manage the identity and purview with `crtr profile new/show/project/rename/delete` (see `crtr profile -h`). `profile rename` changes the name and the profile's canvas handle together (the id stays), so `[[name/x]]` links and `owner=` listings follow it; it refuses when another live profile already holds the new name.
+
+Each project in the purview carries the profile's delivery limit per owner (today set per project), capping how much of that repo's documents reach a node's automatic boot and workspace-open context from any directory that node works in. Give `content` to the repos whose front doors the profile's nodes should operate inside, `preview` or `name` to a project the profile must know exists but rarely enters, and `none` to purview held for config, plugins, and deliberate reads alone. Key a limit by repo handle, or `repo:<handle>` when another owner (such as a profile) shares that handle; the profile's own documents are never capped. It is a delivery dial, not an access one: `crtr canvas read` and `file-read`/`command` rules still reach those documents.
+
+Reach for a **new** profile when a distinct body of work has its own set of directories and its own conventions worth dedicated documents — not for every repo. **The profile as owner** is exactly where cross-repo conventions and your stance toward that body of work belong (see the owners below); a profile spanning several related dirs lets one document reach every node working anywhere in that bundle.
+
+## Owners — who owns a document sets its reach
+
+An owner is itself an object (a node, the person, a profile, an app, a repo), and a document's full name starts with its owner's handle: `<owner-handle>/<name>`. Ownership decides who may read and change the document, where it syncs and what deletes it; together with the document's privacy (`public` default, `friends`, `private`) and its delivery rules it decides who gets it. The wider the owner, the more agents pay to carry it, forever. Choose the **narrowest owner that still reaches the next agent who needs it**, and revise an existing document (`crtr doc edit`) rather than adding a near copy under a second owner. Moving a document between owners (`crtr doc move --owner`) keeps its id and every `[[link]]`. The owner decides *eligibility*; a rule decides *loading* (`internal/memory-loading`); a node can always read what it is pointed at with `crtr canvas read`. Where state lives on disk is `internal/storage-tiers`; the field and rule contract is `crtr doc write -h`. The owners an agent chooses between, narrowest reach to widest:
+
+- **node** — the default owner of what a node writes. Only this node's view includes it; it is deleted with the node unless a kept document links to it. One goal's cross-refresh state.
+- **profile** (`--owner profile`) — every node running under that profile, across all the dirs in its purview. Cross-repo conventions and the user's stance toward that bundle of work.
+- **repo** (`--owner repo`) — any agent operating in that one repo. Facts and procedures tied to that codebase. Every clone and worktree shares one set, synced over the repo's git ref `refs/crtr/docs`; a repo owns only public documents.
+- **user** (`--owner user`) — person-wide facts and preferences that follow the user everywhere, regardless of repo or profile.
+- **crtr's own documents** (owned by the app `crtr`; markdown files in `src/builtin-memory/` of the crouter repo, imported as read-only documents) — ships inside crtr, so *every crtr user on every host* carries it. This owner holds the runtime's own self-documentation (this document lives here); a change here is a change to the product. Write here only for guidance every crouter user needs, never for anything person- or repo-specific.
+
+An **app** (`--owner app`) is a separate axis: the application that runs the node keeps documents there, readable by that app's nodes. An installed plugin is an app too, and its shipped documents are public and read-only.

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -0,0 +1,16 @@
+---
+kind: knowledge
+when-and-why-to-read: When you want a worked end-to-end composition of crouter primitives — not what one command does but how several combine into a real standing system — open this dir so you can reuse a proven shape instead of re-deriving how the primitives fit or relying on unverified OS assumptions.
+short-form: Worked examples composing crouter primitives into complete systems (like pi's examples/ dir). Currently — the iMessage assistant node.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# internal/examples/ — worked compositions of crouter primitives
+
+The other internal/ docs explain the primitives one at a time; this dir shows them composed into complete, buildable systems — the crtr analogue of pi's `examples/` directory. Each example is grounded: its OS-level mechanics and command contracts were verified before being written down.
+
+- **imessage-assistant** — an OpenClaw-style always-on assistant: resident root node with its own dir and persona, woken event-style by a launchd watcher via `node message send`, reading `chat.db` (with the attributedBody gotcha), replying via osascript, remembering people through documents its repo owns.
+
+Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it. Read `internal/examples` for this overview and its immediate example listing; this directory's `INDEX.md` file becomes the document named `internal/examples`; `INDEX` is not part of the name.

package/dist/builtin-memory/internal/examples/imessage-assistant.md

@@ -0,0 +1,101 @@
+---
+kind: knowledge
+when-and-why-to-read: When you are building a standing assistant node bridged to an external channel — iMessage, email, a chat service — this example should be read so you can reuse a proven event-driven shape and avoid rediscovering macOS messaging traps.
+short-form: Worked example — an always-on iMessage assistant built from crouter primitives. Resident root node + launchd watcher → node message send wakes + chat.db reads + osascript sends + documents.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# Example: an iMessage assistant node (OpenClaw-style)
+
+A standing assistant that lives on the canvas, sleeps for free, wakes when a text arrives, reads the conversation, replies over iMessage, and accumulates documents about the people it talks to. Everything here composes existing primitives — no new runtime machinery.
+
+## The shape
+
+| Need | Primitive |
+|---|---|
+| Its own home | Dedicated dir (e.g. `~/assistants/imessage/`), node spawned with `--cwd` pinned there |
+| Event-driven conversation | `--root` spawn → resident lifecycle; after unattended completion, the retained node revives on the next normal message |
+| Hears incoming texts | launchd watcher on `chat.db-wal` → `crtr node message send <body> --to <id>` (event-driven; the message delivers and revives, the node never polls) |
+| Reads messages | sqlite against `~/Library/Messages/chat.db`, cursored by ROWID |
+| Sends replies | `osascript` → Messages.app |
+| Durable knowledge | Documents the assistant's repo owns (`--owner repo`) for durable knowledge; context dir for the cursor |
+| Identity/behavior | A custom persona kind |
+| Crash recovery | The daemon makes bounded recovery attempts for interrupted live exits; after terminalization, use `node lifecycle revive` or let the watcher's `node message send` wake the resident target |
+
+## 1. Persona
+
+Define a kind (e.g. `imessage-assistant`) as a custom node kind. The persona body carries: who it speaks for, which senders it may auto-reply to (allowlist — never reply to arbitrary numbers), voice, the wake loop below, and the documentation protocol (when to write a contact note vs. keep it in-thread). Behavior lives in the persona, not in the watcher.
+
+## 2. Spawn
+
+```bash
+mkdir -p ~/assistants/imessage
+crtr node new --root --kind imessage-assistant --cwd ~/assistants/imessage --name imessage <<'EOF'
+You are the standing iMessage assistant. Initialize: read your persona's wake loop, record the current chat.db max ROWID as your cursor, then go dormant. From now on a watcher wakes you via inbox message whenever iMessage activity lands.
+EOF
+```
+
+`--root` makes it independent and resident — top-level on the canvas, no parent to report to, never forced to finish. Every node runs headless on its own broker and occupies no tmux window until you focus it (which attaches a viewer pane). Record the returned node id for the watcher.
+
+## 3. Wake: event-driven, not polled
+
+A trivial launchd agent watches the Messages write-ahead log and pokes the node's inbox. `node message send` wakes the resident target by itself, including after a recoverable disconnection, so the watcher is the *only* off-canvas piece.
+
+```xml
+<!-- ~/Library/LaunchAgents/com.user.imessage-watch.plist (key parts) -->
+<key>WatchPaths</key><array><string>/Users/YOU/Library/Messages/chat.db-wal</string></array>
+<key>ProgramArguments</key><array>
+  <string>/bin/zsh</string><string>-c</string>
+  <string>crtr node message send "iMessage activity — check chat.db since your cursor" --to NODE_ID</string>
+</array>
+```
+
+Multiple bursts while the node is mid-turn just append to its inbox and coalesce — no dedupe logic needed. Trust the runtime: do **not** also arm a recurring cron as a backstop. A cron that sends a self-message is only appropriate if you choose not to run a watcher at all (pure polling — workable, but pays a window per tick and adds latency).
+
+## 4. Reading chat.db (the verified gotchas)
+
+- The process querying needs **Full Disk Access** (the node's shell inherits the terminal/launchd grant). Read-only — never write to chat.db.
+- Cursor on `message.ROWID`, persisted in the node's context dir (e.g. `$CRTR_CONTEXT_DIR/cursor`); filter `is_from_me = 0`.
+- **On modern macOS `message.text` is often NULL** — the body lives in the `attributedBody` blob (NSAttributedString archive). Extract with:
+
+```python
+import re
+m = re.search(rb'NSString.{1,10}?\+?(.{1,200}?)\x86', attributed_body, re.S)
+text = m.group(1).decode('utf-8', 'ignore') if m else None
+```
+
+- Join for sender + thread:
+
+```sql
+SELECT m.ROWID, h.id AS sender, c.chat_identifier, m.text, m.attributedBody
+FROM message m
+JOIN handle h ON m.handle_id = h.ROWID
+JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+JOIN chat c ON c.ROWID = cmj.chat_id
+WHERE m.ROWID > :cursor AND m.is_from_me = 0
+ORDER BY m.ROWID;
+```
+
+## 5. Sending
+
+```bash
+osascript -e 'tell application "Messages" to send "reply text" to buddy "+15551234567" of (service 1 whose service type is iMessage)'
+```
+
+Group chats target the chat instead: `send "..." to chat id "iMessage;+;chat123..."` (the `chat.guid` column). First send prompts a one-time **Automation** permission grant for Messages.app.
+
+## 6. Durable knowledge and working state
+
+Two places, matching [[internal/storage-tiers]]:
+
+- **Durable knowledge** → documents owned by the node's repo (`crtr doc write --owner repo`): one per contact/thread (who they are, open loops, tone), delivered by rules on the node's boots. The persona says when to write or update them with `crtr doc write`/`crtr doc edit`.
+- **Working state** → the node's context dir: the ROWID cursor, drafts, a running log.
+
+## The wake loop (persona-side)
+
+1. Wake on inbox message → read new rows past the cursor.
+2. Decide per message: reply (allowlisted + warranted), note silently, or ignore.
+3. Send via osascript; write anything durable to the contact's document.
+4. Advance the cursor, end turn, go dormant. No wake armed — the watcher delivers the next event.