@crouton-kit/crouter 0.3.36 → 0.3.38

package/dist/clients/web/web-cmd.js

@@ -36,11 +36,11 @@ function openBrowser(url) {
 }
 const webServeLeaf = defineLeaf({
     name: 'serve',
-    description: 'start the crouter web UI server — the shell, the source/command bridge, and a browser ⇄ broker relay',
-    whenToUse: 'you want the crouter web UI: a browser shell to watch the canvas and drive headless nodes, instead of a terminal pane. It starts ONE long-running server (default 127.0.0.1) that serves the shell SPA, the source + command bridge (POST /__crtr/source — views\' reads AND `crtr` command writes), an SSE change-invalidation lane (GET /__crtr/events), and a VERBATIM browser ⇄ broker relay on /node/<id> (the browser becomes the same protocol peer as surface attach: one controller drives, extra viewers follow read-only). If you bind a non-loopback host, pass --token so the remote-capable bridge, SSE, and relay endpoints can authorize the page. The relay NEVER starts an engine — each node must already have a running headless broker (focus or revive it first); all writes flow through `crtr` subprocesses the bridge runs. Pass --dev for Vite middleware (HMR) while iterating on the shell. The server runs until ctrl+c; the node is picked in the browser via the URL, not on the command line.',
+    description: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
+    whenToUse: 'you want the crouter web UI in a browser instead of a tmux pane — watching the canvas and driving headless nodes from a page rather than a terminal surface. Binds 127.0.0.1 by default; pass --host to bind elsewhere, in which case --token is required so the page can authorize. Pass --dev only if you are iterating on the shell itself (Vite HMR) rather than just running it. The node is picked in the browser via the URL, not on the command line; the server runs until ctrl+c.',
     help: {
         name: 'web serve',
-        summary: 'start the long-running crouter web UI server: serves the shell SPA, the POST /__crtr/source bridge, the GET /__crtr/events SSE lane, and a VERBATIM browser ⇄ node-broker relay (browser picks the node via /node/<id>)',
+        summary: 'start the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
         params: [
             {
                 kind: 'flag',
@@ -125,14 +125,14 @@ export function registerWeb() {
     return defineBranch({
         name: 'web',
         rootEntry: {
-            concept: 'the crouter web UI server — one host serving the browser shell, the source/command bridge, an SSE change lane, and a VERBATIM relay to nodes\' running brokers',
+            concept: 'the crouter web UI server — the browser alternative to a tmux pane for watching the canvas and driving headless nodes',
             desc: 'serve the crouter web UI for the canvas and headless nodes',
-            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes. It runs one long-lived server that serves the shell SPA, runs view sources and crtr command writes over POST /__crtr/source, streams canvas-change invalidations over GET /__crtr/events, and relays a browser connection VERBATIM to a node\'s already-running broker on /node/<id>. The node is selected in the browser via the URL; if the server is bound off-loopback, the page must carry a token so the relay and bridge can authorize.',
+            useWhen: 'you want the crouter web UI in a browser instead of a tmux pane: watch the canvas and drive headless nodes from a page. Binds 127.0.0.1 by default; a non-loopback bind requires a token so the page can authorize. The node is selected in the browser via the URL, not on the command line.',
         },
         help: {
             name: 'web',
-            summary: 'serve the crouter web UI: the shell SPA, the source/command bridge, the SSE change lane, and a VERBATIM relay to headless nodes\' brokers',
-            model: 'The branch is a long-running browser surface. `serve` starts the unified server on the bound host and port, serves the shell SPA, exposes the source/command bridge and SSE change lane, and relays browser frames to a node\'s running broker. The node is chosen in the browser via the URL; the server itself only hosts the surface and never spawns an engine.',
+            summary: 'serve the crouter web UI — the browser alternative to a tmux pane for the canvas and headless nodes',
+            model: 'The branch is a long-running browser surface, an alternative to a tmux pane. `serve` binds a host and port (loopback by default; --token required off-loopback) and runs until interrupted. The node is chosen in the browser via the URL, not on the command line; the server itself only hosts the surface and never spawns an engine.',
         },
         children: [webServeLeaf],
     });

package/dist/commands/__tests__/human.test.js

@@ -100,7 +100,7 @@ describe('human show: params', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// human ask — --context-file (context-file kind, key=deckFile) + --wait bool
+// human ask — --context-file (context-file kind, key=deckFile)
 //
 // NOTE: The argv parser hardcodes the CLI token as `--context-file` regardless
 // of the param's `name` field. The `name` field ("deckFile") becomes the key
@@ -111,7 +111,6 @@ describe('human show: params', () => {
 describe('human ask: params', () => {
     const params = [
         { kind: 'context-file', name: 'deckFile', required: true, constraint: 'Humanloop deck JSON.' },
-        { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Presence-only.' },
     ];
     test('--context-file parses JSON file and yields input.deckFile', async () => {
         const deck = { interactions: [{ id: 'q', title: 'Go?', options: [{ id: 'yes', label: 'Yes' }] }] };
@@ -132,18 +131,6 @@ describe('human ask: params', () => {
         writeFileSync(p, 'not json at all');
         await assert.rejects(() => parseArgv(params, ['--context-file', p]), (err) => { assert.match(err.message, /not valid JSON/); return true; });
     });
-    test('--wait absent → false', async () => {
-        const deck = { interactions: [] };
-        const path = tmpJson(deck);
-        const result = await parseArgv(params, ['--context-file', path]);
-        assert.equal(result['wait'], false);
-    });
-    test('--wait present → true', async () => {
-        const deck = { interactions: [] };
-        const path = tmpJson(deck);
-        const result = await parseArgv(params, ['--context-file', path, '--wait']);
-        assert.equal(result['wait'], true);
-    });
 });
 // ---------------------------------------------------------------------------
 // human ask — shorthand question + strict --context-file deck
@@ -159,7 +146,6 @@ describe('human ask: shorthand', () => {
     test('parses a positional question into input.question', async () => {
         const result = await parseArgv(humanAsk.help.params ?? [], ['Should we ship today?']);
         assert.equal(result['question'], 'Should we ship today?');
-        assert.equal(result['wait'], false);
     });
     test('parses --context-file into input.deck while keeping the strict deck path', async () => {
         const deck = {

package/dist/commands/attention.js

@@ -1,9 +1,11 @@
 // `crtr canvas attention` — aggregate pending human asks across the canvas.
 //
 // Pending asks are stored per-cwd by humanloop. This subtree surfaces two
-// views:
-//   count  — a single integer (stdout.count is parsed by nav chrome)
+// public views:
+//   count  — a single integer (stdout.count is machine-parseable)
 //   list   — itemised entries with cwd, node id, and per-cwd ask count
+// `map` (hidden) is the batched per-node form the attach viewer's nav chrome
+// polls; it is not an agent-facing decision.
 //
 // All three scope modes share the same underlying helpers in attention.ts:
 //   --node <id>   → countAsks(id)             (one cwd)
@@ -21,7 +23,7 @@ import { countAsks, pendingAsksForView, asksAcrossCanvas, asksForNodes, } from '
 const attentionCount = defineLeaf({
     name: 'count',
     description: 'total pending ask count (machine-parseable stdout.count)',
-    whenToUse: 'getting a single pending-ask count for a script or nav chrome to read; scope it to a node or a sub-DAG, or default to canvas-wide',
+    whenToUse: 'a lightweight summary when you just need the number, not which cwds are blocked — scope it to a node or a sub-DAG, or default to canvas-wide. Use `list` when you need to act on where to go answer.',
     help: {
         name: 'canvas attention count',
         // stdout.count is parsed directly by the nav chrome — keep the contract.
@@ -93,7 +95,7 @@ const attentionCount = defineLeaf({
 const attentionList = defineLeaf({
     name: 'list',
     description: 'itemised list of cwds with pending asks',
-    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when a script just needs the number, or `canvas attention map` for per-node counts to label a UI',
+    whenToUse: 'finding which agents are blocked waiting on a human — an itemised list of the cwds with pending asks, oldest first, so you know where to go answer. Scope it to a sub-DAG or list canvas-wide. Use `canvas attention count` instead when you just need the number.',
     help: {
         name: 'canvas attention list',
         summary: 'list nodes with pending human asks, grouped by cwd, oldest first',
@@ -145,6 +147,7 @@ const attentionMap = defineLeaf({
     name: 'map',
     description: 'per-node ask counts for a visible set, batched in one pass',
     whenToUse: 'labelling every node in a UI with its pending-ask count in one batched pass — the form nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
+    tier: 'hidden',
     help: {
         name: 'canvas attention map',
         summary: 'per-node pending-ask counts for a visible set of nodes in ONE pass — the batched form the nav chrome polls (one process, one JSON blob) instead of N count shell-outs',
@@ -211,11 +214,11 @@ const attentionMap = defineLeaf({
 export const attentionBranch = defineBranch({
     name: 'attention',
     description: 'count/list pending human asks across the graph',
-    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks, list the cwds that have them, or map per-node counts. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
+    whenToUse: 'checking whether any agent on the canvas is blocked waiting on a human, and where: count the pending asks or list the cwds that have them. Scope it to a node or a sub-DAG, or go canvas-wide. Use `canvas dashboard` instead for the graph SHAPE, or `node inspect list` for a plain node roster',
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human asks across the canvas',
-        model: 'Human asks are stored per-cwd by humanloop. `count` returns a single integer (stdout.count is parsed by nav chrome); `list` returns itemised entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
+        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised entries — the cwds with pending asks, oldest first. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide.',
     },
     children: [attentionCount, attentionList, attentionMap],
 });

package/dist/commands/canvas-history/search.js

@@ -1,7 +1,7 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { buildCorpus, } from '../../core/canvas/index.js';
-const TYPES = ['report', 'doc', 'roadmap', 'meta'];
+const TYPES = ['report', 'doc', 'roadmap', 'meta', 'inbox'];
 const NODE_KINDS = ['advisor', 'developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
 const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
 const SORTS = ['relevance', 'recency', 'oldest'];
@@ -86,7 +86,7 @@ export const searchLeaf = defineLeaf({
             { kind: 'flag', name: 'all-cwds', type: 'bool', required: false, constraint: 'Search every cwd on the canvas. Mutually exclusive with --cwd.' },
             { kind: 'flag', name: 'under', type: 'string', required: false, constraint: 'Restrict to a node and its subscription descendants (one initiative / sub-DAG).' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Restrict to specific node ids. Comma-separated for several.' },
-            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: `Corpus to search; comma-separated for several. One of: ${TYPES.join(', ')}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind. Default: all.` },
+            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: `Corpus to search; comma-separated for several. One of: ${TYPES.join(', ')}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind; inbox = raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies (diagnostic, not curated work). Default: report, doc, roadmap, meta — inbox is opt-in only, pass --type inbox explicitly.` },
             { kind: 'flag', name: 'report-kind', type: 'enum', choices: ['final', 'update'], required: false, constraint: 'Narrow reports to outcome summaries (final) or progress (update). Implies --type report.' },
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: `Node kind; comma-separated for several. One of: ${NODE_KINDS.join(', ')}.` },
             { kind: 'flag', name: 'status', type: 'string', required: false, constraint: `Node lifecycle status; comma-separated for several. One of: ${STATUSES.join(', ')} (e.g. done = completed work only).` },

package/dist/commands/canvas-history/show.js

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound } from '../../core/errors.js';
 import { getNode, nodeArtifacts } from '../../core/canvas/index.js';
 import { statSync } from 'node:fs';
-const TYPES = ['report', 'doc', 'roadmap'];
+const TYPES = ['report', 'doc', 'roadmap', 'inbox'];
 export const showLeaf = defineLeaf({
     name: 'show',
     description: 'enumerate one node\'s artifacts as refs',
@@ -12,12 +12,12 @@ export const showLeaf = defineLeaf({
         summary: 'list one node\'s artifacts (reports + context docs) as refs ready for `canvas history read`',
         params: [
             { kind: 'positional', name: 'node-id', required: true, constraint: 'The node whose artifacts to list.' },
-            { kind: 'flag', name: 'type', type: 'enum', choices: [...TYPES], required: false, constraint: 'Narrow to one corpus: report | doc | roadmap. Default: all.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...TYPES], required: false, constraint: 'Narrow to one corpus: report | doc | roadmap | inbox. Default: report, doc, roadmap (inbox is opt-in only — the node\'s raw inbox.jsonl history, cursor-independent and including full un-clipped direct-message bodies; a diagnostic surface, not curated past work).' },
             { kind: 'flag', name: 'sort', type: 'enum', choices: ['recency', 'oldest'], required: false, constraint: 'Order by artifact timestamp. Default recency.' },
         ],
         output: [
             { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
-            { name: 'artifacts', type: 'object[]', required: true, constraint: 'Each: {ref, source, ts, detail}. source = report:<kind> | doc | roadmap. detail = report title / doc heading + size. ref passes verbatim to `canvas history read`.' },
+            { name: 'artifacts', type: 'object[]', required: true, constraint: 'Each: {ref, source, ts, detail}. source = report:<kind> | doc | roadmap | inbox. detail = report title / doc heading + size (inbox: `[kind] label`, no size). ref passes verbatim to `canvas history read`.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',

package/dist/commands/canvas-history.js

@@ -23,7 +23,7 @@ export const historyBranch = defineBranch({
     help: {
         name: 'canvas history',
         summary: 'search and recall the canvas\'s record of past work in this cwd',
-        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref; `show` lists everything one node left. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. To reopen a node you found, use `canvas revive`; for its place in the graph, `node inspect show`.',
+        model: 'The accumulated record of every node that ran in a cwd and the artifacts it left — its reports (final/update outcome summaries) and context docs (specs, designs, roadmaps, findings). `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `read` pulls one hit\'s full body by its <node-id>:<relpath> ref; `show` lists everything one node left. This is the episodic record of what was DONE — distinct from `crtr memory`, which is curated semantic knowledge. A node\'s raw inbox history (`--type inbox`) is a separate, opt-in diagnostic corpus — the full cursor-independent inbox.jsonl for one node, including un-clipped direct-message bodies; reach for it only when the curated reports/docs above don\'t already answer the question. To reopen a node you found, use `canvas revive`; for its place in the graph, `node inspect show`.',
         dynamicState: corpusBlock,
     },
     children: [searchLeaf, readLeaf, showLeaf],

package/dist/commands/canvas-issue.js

@@ -66,6 +66,7 @@ export const issueNewLeaf = defineLeaf({
     name: 'new',
     description: 'capture a todo/idea/bug note into a GitHub issue (or a .todos/ markdown note)',
     whenToUse: 'the alt+c \u2192 i chord runs this inside a tmux popup; rarely run by hand',
+    tier: 'hidden',
     help: {
         name: 'canvas issue new',
         summary: 'Capture a free-text note as a GitHub issue labeled with its type (idea|bug). Reads the note from the popup TTY, auto-generates the title via a headless pi call, and files it with `gh issue create` when the cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Bound to the alt+c \u2192 i prefix chord.',

package/dist/commands/canvas-snapshot.js

@@ -5,6 +5,7 @@ export const canvasSnapshotLeaf = defineLeaf({
     name: 'snapshot',
     description: 'emit the browser canvas roster as structured data',
     whenToUse: 'you need a machine-readable roster of every canvas node for a browser or local tool; use dashboard for the human-readable tree',
+    tier: 'hidden',
     help: {
         name: 'canvas snapshot',
         summary: 'machine-readable snapshot of the whole canvas roster',

package/dist/commands/canvas.js

@@ -1,20 +1,18 @@
 // `crtr canvas` — observe and supervise the whole graph.
 //
-// Where `node` operates on one node and `push`/`feed` are a node's own spine
-// I/O, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
+// Where `node` operates on one node and `push` is a node's own spine write
+// verb, `canvas` is the bird's-eye / supervisor surface over the entire canvas:
 // render the subscription forest (`dashboard`), see who is blocked on a human
-// (`attention`), bring a node back (`revive`), and manage the supervisor
-// process (`daemon`). It assembles leaves/branches the sibling command files
-// own, so each piece declares its own help one level down.
+// (`attention`), and bring a node back (`revive`). It assembles leaves/branches
+// the sibling command files own, so each piece declares its own help one level
+// down.
 import { defineBranch } from '../core/command.js';
 import { dashboardLeaf } from './dashboard.js';
 import { canvasSnapshotLeaf } from './canvas-snapshot.js';
 import { browseLeaf } from './canvas-browse.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
-import { daemonBranch } from './daemon.js';
 import { chordLeaf } from './chord.js';
-import { tmuxSpreadLeaf } from './canvas-tmux-spread.js';
 import { canvasPruneLeaf } from './canvas-prune.js';
 import { canvasRebuildIndexLeaf } from './canvas-rebuild-index.js';
 import { historyBranch } from './canvas-history.js';
@@ -23,6 +21,7 @@ export const issueBranch = defineBranch({
     name: 'issue',
     description: 'capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)',
     whenToUse: 'the alt+c \u2192 i chord uses this; capture a passing thought without leaving your pane',
+    tier: 'hidden',
     help: {
         name: 'canvas issue',
         summary: 'capture a quick todo/idea/bug into a GitHub issue',
@@ -34,15 +33,15 @@ export function registerCanvas() {
     return defineBranch({
         name: 'canvas',
         rootEntry: {
-            concept: 'the whole agent graph at a glance — render it, see who is blocked, revive a node, supervise the daemon',
+            concept: 'the whole agent graph at a glance — render it, see who is blocked, revive a node',
             desc: 'bird\'s-eye view and supervision of the entire canvas',
-            useWhen: 'surveying the full graph, finding blocked agents, or managing revival/the daemon',
+            useWhen: 'surveying the full graph, finding blocked agents, or reviving a node',
         },
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL.',
         },
-        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, daemonBranch, chordLeaf, tmuxSpreadLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
+        children: [dashboardLeaf, canvasSnapshotLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, chordLeaf, issueBranch, canvasPruneLeaf, canvasRebuildIndexLeaf],
     });
 }

package/dist/commands/chord.js

@@ -154,6 +154,7 @@ export const chordLeaf = defineLeaf({
     name: 'chord',
     description: 'tmux prefix-menu dispatcher (bound by alt+c; not run by hand)',
     whenToUse: 'never directly — the alt+c menu routes node-relative actions through it',
+    tier: 'hidden',
     help: {
         name: 'canvas chord',
         summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, interpolate --run against it, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',

package/dist/commands/human/prompts.js

@@ -40,7 +40,6 @@ export const humanAsk = defineLeaf({
         params: [
             { kind: 'positional', name: 'question', type: 'string', required: false, constraint: 'Bare-question shorthand for a simple open-text ask. Mutually exclusive with `--context-file`.' },
             { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict complex-ask deck JSON. Use this when you need multiple interactions, options, or other deck structure. Mutually exclusive with the question shorthand.', shape: DECK_SCHEMA_HINT },
-            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Accepted for symmetry with the job contract; the kickoff never blocks.' },
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },

package/dist/commands/human/queue.js

@@ -520,6 +520,7 @@ export const humanResolve = defineLeaf({
     name: 'resolve',
     description: 'resolve one humanloop deck from stdin answers',
     whenToUse: 'a browser or local tool is submitting answers for a pending human interaction; this writes through the crouter/humanloop finalize path',
+    tier: 'hidden',
     help: {
         name: 'human resolve',
         summary: 'write deck answers atomically and deliver them back to the asking node',

package/dist/commands/memory/read.js

@@ -7,19 +7,19 @@ import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project stack > profile > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
         summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: project > user > builtin, with leaf-name fallback.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: project stack > profile > user > builtin, with leaf-name fallback.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, user, or builtin.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, profile, user, or builtin.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — edit this file directly to tweak the doc in place.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },

package/dist/commands/memory/shared.d.ts

@@ -1,16 +1,21 @@
-import type { Scope } from '../../types.js';
+import type { MemoryScope } from '../../core/memory-resolver.js';
 export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
 export declare const VISIBILITY_RUNGS: readonly ["none", "name", "preview", "content"];
-export declare const MEMORY_SCOPES: readonly ["user", "project"];
-/** Scope sort weight matching resolution precedence (project > user > builtin).
- *  Used by `list` for its "scope then kind then name" ordering. */
-export declare function scopeRank(scope: Scope): number;
+export declare const MEMORY_SCOPES: readonly ["user", "project", "profile"];
+/** Scope sort weight matching resolution precedence (project stack > profile >
+ *  user > builtin). Used by `list` for its "scope then kind then name"
+ *  ordering. */
+export declare function scopeRank(scope: MemoryScope): number;
 /** Resolve the write target scope + its memory dir. Default: project when a
  *  project scope exists for the cwd, else user. An explicit `--scope project`
  *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
- *  always resolves. Returns the absolute `<root>/memory` dir to write under. */
-export declare function resolveWriteTarget(scopeArg: string | undefined): {
-    scope: Scope;
+ *  always resolves. `--scope profile` is NEVER a default — it requires a
+ *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
+ *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
+ *  `loadProfileManifest` (never a raw path join). Returns the absolute
+ *  `<root>/memory` dir to write under. */
+export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string): {
+    scope: MemoryScope;
     memoryDir: string;
 };
 /** Map a path-derived name (`topic` or `area/topic`) to its file path under a

package/dist/commands/memory/shared.js

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
 import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
 // `--kind` enum choices everywhere.
@@ -15,27 +16,40 @@ export const MEMORY_KINDS = ['knowledge', 'preference'];
 // content). Shared by --system-prompt-visibility and --file-read-visibility.
 export const VISIBILITY_RUNGS = ['none', 'name', 'preview', 'content'];
 // Scope choices for filtering / targeting (builtin is read-only, not writable).
-export const MEMORY_SCOPES = ['user', 'project'];
-/** Scope sort weight matching resolution precedence (project > user > builtin).
- *  Used by `list` for its "scope then kind then name" ordering. */
+export const MEMORY_SCOPES = ['user', 'project', 'profile'];
+/** Scope sort weight matching resolution precedence (project stack > profile >
+ *  user > builtin). Used by `list` for its "scope then kind then name"
+ *  ordering. */
 export function scopeRank(scope) {
-    return scope === 'project' ? 0 : scope === 'user' ? 1 : 2;
+    return scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
 }
 /** Resolve the write target scope + its memory dir. Default: project when a
  *  project scope exists for the cwd, else user. An explicit `--scope project`
  *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
- *  always resolves. Returns the absolute `<root>/memory` dir to write under. */
-export function resolveWriteTarget(scopeArg) {
+ *  always resolves. `--scope profile` is NEVER a default — it requires a
+ *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
+ *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
+ *  `loadProfileManifest` (never a raw path join). Returns the absolute
+ *  `<root>/memory` dir to write under. */
+export function resolveWriteTarget(scopeArg, profileArg) {
     let scope;
-    if (scopeArg === 'user' || scopeArg === 'project') {
+    if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile') {
         scope = scopeArg;
     }
     else if (scopeArg !== undefined) {
-        throw usage(`invalid --scope: ${scopeArg} (expected user|project)`);
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project|profile)`);
     }
     else {
         scope = projectScopeRoot() !== null ? 'project' : 'user';
     }
+    if (scope === 'profile') {
+        const profileIdOrName = profileArg && profileArg !== '' ? profileArg : process.env['CRTR_PROFILE_ID'] || '';
+        if (profileIdOrName === '') {
+            throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
+        }
+        const { profileId } = loadProfileManifest(profileIdOrName);
+        return { scope: 'profile', memoryDir: profileMemoryDir(profileId) };
+    }
     let memoryDir = scopeMemoryDir(scope);
     if (!memoryDir && scope === 'project') {
         // Explicit --scope project with no project root yet → scaffold it.

package/dist/commands/memory/write.js

@@ -27,13 +27,14 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`; ignored for any other --scope.' },
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin, or passed as the bare positional after <name>.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user or project.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document — edit this file directly for later body tweaks instead of re-running write.' },
             { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
@@ -47,8 +48,9 @@ export const writeLeaf = defineLeaf({
         const name = input['name'];
         const kind = input['kind'];
         const scopeArg = input['scope'];
+        const profileArg = input['profile'];
         const body = input['body'] ?? '';
-        const { scope, memoryDir } = resolveWriteTarget(scopeArg);
+        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg);
         const path = memoryFilePath(memoryDir, name);
         const created = !pathExists(path);
         // CREATE requires the read-routing line that becomes the preview — without

package/dist/commands/node-snapshot.js

@@ -63,6 +63,7 @@ export const nodeSnapshotLeaf = defineLeaf({
     name: 'snapshot',
     description: 'read a dormant node session snapshot without launching its broker',
     whenToUse: 'you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node',
+    tier: 'hidden',
     help: {
         name: 'node inspect snapshot',
         summary: 'read-only dormant node snapshot in the broker welcome shape',