@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/builtin-memory/crouter-development/marketplaces.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When a task relates to marketplaces
-why: How to author a crtr marketplace — marketplace.json index, plugin entries,
-  symlink-based install, auto-bump CI, dual-publishing. Use when creating a
-  marketplace or contributing plugins to one.
+when-and-why-to-read: When creating a crtr marketplace or contributing plugins
+  to one, this skill should be read.
 short-form: How to author a crtr marketplace — marketplace.json index, plugin
   entries, symlink-based install, auto-bump CI, dual-publishing. Use when
   creating a marketplace or contributing plugins to one.

package/dist/builtin-memory/crouter-development/personas/base-prompt.md

@@ -1,10 +1,8 @@
 ---
 kind: skill
-when: When a task relates to base prompt
-why: How to write a base persona prompt (the mode=base PERSONA.md) — the system
-  prompt for a single-window worker node. Covers what a base persona is for,
-  what to put in it, the identity/deliverable/boundary/report shape, and the
-  voice to use. Use when writing or revising a <kind>/PERSONA.md.
+when-and-why-to-read: When writing or revising a base persona prompt (a
+  <kind>/PERSONA.md, the system prompt for a single-window worker node), this
+  skill should be read.
 short-form: How to write a base persona prompt (the mode=base PERSONA.md) — the
   system prompt for a single-window worker node. Covers what a base persona is
   for, what to put in it, the identity/deliverable/boundary/report shape, and

package/dist/builtin-memory/crouter-development/personas/orchestrator-prompt.md

@@ -1,11 +1,8 @@
 ---
 kind: skill
-when: When a task relates to orchestrator prompt
-why: How to write an orchestrator persona prompt (orchestrator.md) — the system
-  prompt for a resident coordinator node. Covers the kernel-vs-kind split, what
-  belongs in the per-kind body, naming the child pipeline, the roadmapSkill
-  pointer, and the @include rule. Use when writing or revising a
-  <kind>/orchestrator.md.
+when-and-why-to-read: When writing or revising an orchestrator persona prompt (a
+  <kind>/orchestrator.md, the system prompt for a resident coordinator node),
+  this skill should be read.
 short-form: How to write an orchestrator persona prompt (orchestrator.md) — the
   system prompt for a resident coordinator node. Covers the kernel-vs-kind
   split, what belongs in the per-kind body, naming the child pipeline, the

package/dist/builtin-memory/crouter-development/personas.md

@@ -1,11 +1,7 @@
 ---
 kind: skill
-when: When a task relates to personas
-why: How to define a custom node kind (persona) for crtr — the
-  PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse),
-  nested sub-personas, scope resolution and overrides, and how to write the
-  prose. Use when adding a new `--kind`, overriding a builtin agent, or
-  debugging persona resolution.
+when-and-why-to-read: When adding a new `--kind`, overriding a builtin agent, or
+  debugging persona resolution, this skill should be read.
 short-form: How to define a custom node kind (persona) for crtr — the
   PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse),
   nested sub-personas, scope resolution and overrides, and how to write the

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When a task relates to plugins
-why: How to author a crtr plugin — plugin.json manifest, directory layout,
-  scopes, install mechanics, versioning. Use when creating a new plugin,
-  packaging skills for distribution, or debugging install/resolution.
+when-and-why-to-read: When creating a crtr plugin, packaging skills for
+  distribution, or debugging install/resolution, this skill should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
   layout, scopes, install mechanics, versioning. Use when creating a new plugin,
   packaging skills for distribution, or debugging install/resolution.

package/dist/builtin-memory/design.md

@@ -1,9 +1,7 @@
 ---
 kind: skill
-when: When shaping a design roadmap or producing an architecture/interface design
-why: covers what a design deliverable is, the design-artifact shape, when to go
-  top-down vs bottom-up, and how to decompose a large design into composable
-  sub-designs.
+when-and-why-to-read: When shaping a design roadmap or producing an
+  architecture/interface design, this skill should be read.
 short-form: Use when shaping a design roadmap or producing an
   architecture/interface design — covers what a design deliverable is, the
   design-artifact shape, when to go top-down vs bottom-up, and how to decompose

package/dist/builtin-memory/development.md

@@ -1,8 +1,8 @@
 ---
 kind: skill
-when: When shaping or reshaping a build roadmap
-why: choosing a development style, selecting a phase skeleton, or setting exit
-  criteria for a software goal.
+when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a
+  development style, selecting a phase skeleton, or setting exit criteria for a
+  software goal — this skill should be read.
 short-form: Use when shaping or reshaping a build roadmap — choosing a
   development style, selecting a phase skeleton, or setting exit criteria for a
   software goal.

package/dist/builtin-memory/planning.md

@@ -1,9 +1,8 @@
 ---
 kind: skill
-when: When shaping a planning roadmap, deciding plan structure, or fanning out
-  plan-review specialists before declaring a plan ready
-why: Use when shaping a planning roadmap, deciding plan structure, or fanning
-  out plan-review specialists before declaring a plan ready.
+when-and-why-to-read: When shaping a planning roadmap, deciding plan structure,
+  or fanning out plan-review specialists before declaring a plan ready, this
+  skill should be read.
 short-form: Use when shaping a planning roadmap, deciding plan structure, or
   fanning out plan-review specialists before declaring a plan ready.
 system-prompt-visibility: name

package/dist/builtin-memory/spec.md

@@ -1,15 +1,8 @@
 ---
 kind: skill
-when: When running a specification effort, shaping a spec roadmap, or deciding
-  how to stage design and requirements work. Covers the three-stage
-  shape→design→requirements methodology, when to delegate design to a child
-  node, the isolation principle behind the design/requirements split, and what a
-  finished spec contains
-why: Use when running a specification effort, shaping a spec roadmap, or
-  deciding how to stage design and requirements work. Covers the three-stage
-  shape→design→requirements methodology, when to delegate design to a child
-  node, the isolation principle behind the design/requirements split, and what a
-  finished spec contains.
+when-and-why-to-read: When running a specification effort, shaping a spec
+  roadmap, or deciding how to stage design and requirements work, this skill
+  should be read.
 short-form: Use when running a specification effort, shaping a spec roadmap, or
   deciding how to stage design and requirements work. Covers the three-stage
   shape→design→requirements methodology, when to delegate design to a child

package/dist/builtin-personas/orchestration-kernel.md

@@ -52,7 +52,7 @@ Separate from the roadmap (your live plan and state) you have a persistent docum
 
 **Reading.** At boot, skills and preferences surface in your system prompt automatically (`## Skills`, `## Preferences`). References surface in your `<crtr-context>` block (`## References`). To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
 
-**Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind`, `when`, and `why` in its frontmatter, plus a body. The `kind` governs which section it surfaces in at boot and how it loads:
+**Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind` and `when-and-why-to-read` in its frontmatter, plus a body. `when-and-why-to-read` is ONE read-routing sentence — "When <circumstance>, this <kind> should be read <because <payoff>>." — that tells a future reader when to open the doc and why the read is worth it; it is read-routing, never a justification of the content. It becomes the preview line verbatim. The `kind` governs which section it surfaces in at boot and how it loads:
 
 - `skill` — a workflow or methodology to adopt. Surfaces by name in `## Skills`; load with `crtr memory read`.
 - `preference` — how you should work. Surfaces as a `###` routing line in `## Preferences` at boot (default `system-prompt-visibility: preview`).

package/dist/commands/canvas-history/read.d.ts

@@ -0,0 +1 @@
+export declare const readLeaf: import("../../core/command.js").LeafDef;

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

@@ -0,0 +1,61 @@
+import { defineLeaf } from '../../core/command.js';
+import { notFound, usage } from '../../core/errors.js';
+import { resolveRef } from '../../core/canvas/index.js';
+export const readLeaf = defineLeaf({
+    name: 'read',
+    description: 'read one search hit\'s full body by its ref',
+    whenToUse: 'you picked a hit from `canvas history search` (or `canvas history show`) and want its full content — pass the `<node-id>:<relpath>` ref verbatim. Strips frontmatter by default; add --frontmatter to keep the YAML header.',
+    help: {
+        name: 'canvas history read',
+        summary: 'resolve a <node-id>:<relpath> ref to its full artifact body',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: 'The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node\'s identity).' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'Include the artifact\'s YAML frontmatter. Stripped by default.' },
+        ],
+        output: [
+            { name: 'ref', type: 'string', required: true, constraint: 'Echo of the resolved ref.' },
+            { name: 'node', type: 'string', required: true, constraint: 'Node name + id.' },
+            { name: 'source', type: 'string', required: true, constraint: 'report | doc | roadmap | meta (+ report-kind for reports).' },
+            { name: 'ts', type: 'string', required: true, constraint: 'Artifact timestamp.' },
+            { name: 'content', type: 'string', required: true, constraint: 'Full body. Frontmatter stripped unless --frontmatter.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ref = input['ref'].trim();
+        const includeFrontmatter = input['frontmatter'] === true;
+        if (!ref.includes(':')) {
+            throw usage(`ref must be <node-id>:<relpath>; received: ${ref}`, {
+                received: ref,
+                next: 'Get a valid ref from `canvas history search` or `canvas history show <node-id>`.',
+            });
+        }
+        let resolved;
+        try {
+            resolved = resolveRef(ref);
+        }
+        catch (e) {
+            throw usage(`ref rejected: ${e.message}`, { received: ref, next: 'Refs come verbatim from `canvas history search`; do not hand-construct relpaths.' });
+        }
+        if (resolved === null) {
+            throw notFound(`no artifact for ref: ${ref}`, {
+                ref,
+                next: 'The node or file may not exist. Re-run `canvas history search` for a current ref, or `canvas history show <node-id>` to list a node\'s artifacts.',
+            });
+        }
+        const source = resolved.source === 'report' && resolved.reportKind ? `report:${resolved.reportKind}` : resolved.source;
+        const content = includeFrontmatter && resolved.raw !== null ? resolved.raw : resolved.body;
+        return {
+            ref,
+            node: `${resolved.nodeName} (${resolved.nodeId})`,
+            source,
+            ts: resolved.ts,
+            content,
+        };
+    },
+    render: (r) => {
+        const head = `${r['node']}  |  source: ${r['source']}  |  ts: ${r['ts']}  |  ref: ${r['ref']}`;
+        return `${head}\n\n${String(r['content']).trim()}`;
+    },
+});

package/dist/commands/canvas-history/search.d.ts

@@ -0,0 +1 @@
+export declare const searchLeaf: import("../../core/command.js").LeafDef;

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

@@ -0,0 +1,270 @@
+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 NODE_KINDS = ['developer', 'spec', 'design', 'review', 'explore', 'plan', 'general'];
+const STATUSES = ['active', 'idle', 'done', 'dead', 'canceled'];
+const SORTS = ['relevance', 'recency', 'oldest'];
+const REL_UNITS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+    mo: 2_592_000_000,
+    y: 31_536_000_000,
+};
+/** ISO 8601 (`2026-06-01`) → epoch ms (absolute); relative (`7d`, `2w`, `1mo`)
+ *  → now minus the duration. Throws usage on an unparseable value. */
+function parseWhen(field, raw) {
+    const rel = raw.match(/^(\d+)(mo|[smhdwy])$/);
+    if (rel !== null)
+        return Date.now() - Number(rel[1]) * REL_UNITS[rel[2]];
+    const abs = Date.parse(raw);
+    if (!Number.isNaN(abs))
+        return abs;
+    throw usage(`--${field} must be ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo); received: ${raw}`);
+}
+function splitCsv(v) {
+    if (v === undefined || v === '')
+        return undefined;
+    return v.split(',').map((s) => s.trim()).filter((s) => s !== '');
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), 'utf8').toString('base64');
+}
+function decodeCursor(c) {
+    const n = Number(Buffer.from(c, 'base64').toString('utf8'));
+    if (!Number.isInteger(n) || n < 0)
+        throw usage(`invalid --cursor: ${c}`);
+    return n;
+}
+/** One snippet block: the matching line(s), `lines` deep. Falls back to the
+ *  title or the first body lines when nothing matched on the body. */
+function snippet(a, terms, lines) {
+    const body = a.loadBody();
+    const rows = body.split('\n');
+    if (terms.length > 0) {
+        const idx = rows.findIndex((r) => {
+            const lc = r.toLowerCase();
+            return terms.some((t) => lc.includes(t));
+        });
+        if (idx !== -1) {
+            return rows
+                .slice(idx, idx + lines)
+                .map((r) => r.trim())
+                .filter((r) => r !== '')
+                .join(' ⏎ ');
+        }
+    }
+    const lead = rows.map((r) => r.trim()).filter((r) => r !== '').slice(0, lines).join(' ⏎ ');
+    return lead !== '' ? lead : a.title;
+}
+function sortArtifacts(arts, mode, scored) {
+    const out = [...arts];
+    if (mode === 'relevance' && scored !== undefined) {
+        out.sort((x, y) => (scored.get(y.ref) ?? 0) - (scored.get(x.ref) ?? 0) || y.tsMs - x.tsMs || x.ref.localeCompare(y.ref));
+    }
+    else if (mode === 'oldest') {
+        out.sort((x, y) => x.tsMs - y.tsMs || x.ref.localeCompare(y.ref));
+    }
+    else {
+        out.sort((x, y) => y.tsMs - x.tsMs || x.ref.localeCompare(y.ref));
+    }
+    return out;
+}
+export const searchLeaf = defineLeaf({
+    name: 'search',
+    description: 'ranked content search across the cwd\'s node history',
+    whenToUse: 'you want to find past work by what it SAYS — a design, a final report, a roadmap, a finding — across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node, or switch to --grep for an exact regex over bodies. Use `canvas history read <ref>` to read a hit in full, `canvas history show <node-id>` to list one node\'s artifacts, and `canvas revive <id>` to reopen a node you found.',
+    help: {
+        name: 'canvas history search',
+        summary: 'ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta)',
+        params: [
+            { kind: 'positional', name: 'query', required: false, constraint: 'Whitespace-separated terms, matched case-insensitively and weighted across node name/description, report titles, and doc headings (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies). Under --grep: an ECMAScript regex matched against bodies (line hits).' },
+            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Search another project\'s record. Default: the calling node\'s cwd (process cwd when not a node). Mutually exclusive with --all-cwds.' },
+            { 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: '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).` },
+            { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo).' },
+            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'Upper bound on artifact timestamp. ISO 8601 or relative.' },
+            { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex matched against bodies (one hit per matching line) instead of weighted ranking. Requires a query. Mutually exclusive with --body.' },
+            { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh full body text in the ranking (default weighs name/title/heading only). Ignored under --grep.' },
+            { kind: 'flag', name: 'sort', type: 'enum', choices: SORTS, required: false, constraint: 'relevance (default with a query) ranks by score; recency (default without a query) / oldest order by artifact timestamp.' },
+            { kind: 'flag', name: 'snippet-lines', type: 'int', required: false, default: 1, constraint: 'Context lines per hit. Default 1.' },
+            { kind: 'flag', name: 'full', type: 'bool', required: false, constraint: 'Inline each hit\'s full body. Off by default; pair with a small --limit. Ignored under --grep.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Page size. Default 20, hard max 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from a prior next_cursor; omit on the first call.' },
+        ],
+        output: [
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked/sorted hits, each: {ref, node, kind, source, ts, score?, snippet}. Under --grep: {ref, node, ts, line, text} per matching body line, sorted by ref then line. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`.' },
+            { name: 'next_cursor', type: 'string|null', required: true, constraint: 'Token for the next page; null is the only end-of-list signal.' },
+            { name: 'total', type: 'int', required: true, constraint: 'Total matching artifacts (exact).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const query = (input['query'] ?? '').trim();
+        const cwd = input['cwd'];
+        const allCwds = input['allCwds'] === true;
+        const under = input['under'];
+        const nodes = splitCsv(input['node']);
+        const grep = input['grep'] === true;
+        const weighBody = input['body'] === true;
+        const full = input['full'] === true;
+        const snippetLines = Math.max(1, input['snippetLines'] ?? 1);
+        const limit = Math.min(100, Math.max(1, input['limit'] ?? 20));
+        const cursor = input['cursor'];
+        if (cwd !== undefined && allCwds)
+            throw usage('--cwd and --all-cwds are mutually exclusive.');
+        if (grep && weighBody)
+            throw usage('--grep and --body are mutually exclusive (--grep always scans bodies).');
+        if (grep && query === '')
+            throw usage('--grep requires a query (the regex). Omit --grep to browse by recency.');
+        const reportKind = input['reportKind'];
+        const types = splitCsv(input['type']);
+        if (types !== undefined) {
+            const bad = types.find((t) => !TYPES.includes(t));
+            if (bad !== undefined)
+                throw usage(`--type must be one of: ${TYPES.join(', ')}; received: ${bad}`);
+        }
+        const scope = { cwd, allCwds, under, nodes };
+        const corpus = {
+            types,
+            reportKind,
+            kinds: splitCsv(input['kind']),
+            statuses: splitCsv(input['status']),
+            sinceMs: input['since'] !== undefined ? parseWhen('since', input['since']) : undefined,
+            untilMs: input['until'] !== undefined ? parseWhen('until', input['until']) : undefined,
+        };
+        const arts = buildCorpus(scope, corpus);
+        const offset = cursor !== undefined ? decodeCursor(cursor) : 0;
+        // --- grep mode: regex over bodies, one row per matching line ---
+        if (grep) {
+            let re;
+            try {
+                re = new RegExp(query, 'i');
+            }
+            catch {
+                throw usage(`invalid regex pattern: ${query}`);
+            }
+            const lineHits = [];
+            for (const a of arts) {
+                const rows = a.loadBody().split('\n');
+                rows.forEach((text, i) => {
+                    if (re.test(text))
+                        lineHits.push({ ref: a.ref, node: `${a.nodeName} (${a.nodeId})`, ts: a.ts, line: i + 1, text: text.trim() });
+                });
+            }
+            lineHits.sort((x, y) => x.ref.localeCompare(y.ref) || x.line - y.line);
+            const page = lineHits.slice(offset, offset + limit);
+            const nextCursor = offset + limit < lineHits.length ? encodeCursor(offset + limit) : null;
+            return {
+                hits: page,
+                next_cursor: nextCursor,
+                total: lineHits.length,
+                follow_up: 'Read a hit with `canvas history read <ref>`. Drop --grep for a ranked topic search; narrow with `canvas history search -h`.',
+            };
+        }
+        // --- ranked / browse mode ---
+        const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+        let pool = arts;
+        let scored;
+        const sortMode = input['sort'] ?? (terms.length > 0 ? 'relevance' : 'recency');
+        if (terms.length > 0 && sortMode === 'relevance') {
+            scored = new Map();
+            const matched = [];
+            for (const a of arts) {
+                const titleLc = a.title.toLowerCase();
+                const nameLc = a.nodeName.toLowerCase();
+                const descLc = a.nodeDesc.toLowerCase();
+                const bodyLc = weighBody ? a.loadBody().toLowerCase() : null;
+                let score = 0;
+                for (const t of terms) {
+                    if (titleLc.includes(t))
+                        score += 10;
+                    if (nameLc.includes(t))
+                        score += 5;
+                    if (descLc.includes(t))
+                        score += 3;
+                    if (bodyLc !== null && bodyLc.includes(t))
+                        score += 1;
+                }
+                if (score > 0) {
+                    scored.set(a.ref, score);
+                    matched.push(a);
+                }
+            }
+            pool = matched;
+        }
+        else if (terms.length > 0) {
+            // Query present but a timeline sort requested: filter by match, order by ts.
+            pool = arts.filter((a) => {
+                const hay = `${a.title}\n${a.nodeName}\n${a.nodeDesc}${weighBody ? '\n' + a.loadBody() : ''}`.toLowerCase();
+                return terms.some((t) => hay.includes(t));
+            });
+        }
+        const sorted = sortArtifacts(pool, sortMode, scored);
+        const page = sorted.slice(offset, offset + limit);
+        const nextCursor = offset + limit < sorted.length ? encodeCursor(offset + limit) : null;
+        const hits = page.map((a) => {
+            const base = {
+                ref: a.ref,
+                node: `${a.nodeName} (${a.nodeId})`,
+                kind: a.nodeKind,
+                source: a.source === 'report' && a.reportKind ? `report:${a.reportKind}` : a.source,
+                ts: a.ts,
+            };
+            if (sortMode === 'relevance' && scored !== undefined)
+                base['score'] = scored.get(a.ref) ?? 0;
+            if (full)
+                base['body'] = a.loadBody();
+            else
+                base['snippet'] = snippet(a, terms, snippetLines);
+            return base;
+        });
+        return {
+            hits,
+            next_cursor: nextCursor,
+            total: sorted.length,
+            follow_up: 'Read a hit with `canvas history read <ref>`; narrow with `canvas history search -h`.',
+        };
+    },
+    render: (r) => renderSearch(r),
+});
+function renderSearch(r) {
+    const hits = r['hits'];
+    const total = r['total'];
+    const nextCursor = r['next_cursor'];
+    const full = hits.length > 0 && Object.prototype.hasOwnProperty.call(hits[0], 'body');
+    const parts = [];
+    if (hits.length === 0) {
+        parts.push('0 hits.');
+    }
+    else if (full) {
+        parts.push(`${hits.length} of ${total} hits:`);
+        for (const h of hits) {
+            const head = `### ${h['ref']}\n- node: ${h['node']}  |  kind: ${h['kind']}  |  source: ${h['source']}  |  ts: ${h['ts']}`;
+            parts.push(`${head}\n\n${String(h['body'] ?? '').trim()}`);
+        }
+    }
+    else {
+        parts.push(`${hits.length} of ${total} hits:`);
+        const cols = Object.keys(hits[0]).filter((c) => c !== 'body');
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = hits
+            .map((h) => `| ${cols.map((c) => String(h[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`)
+            .join('\n');
+        parts.push(`${head}\n${sep}\n${body}`);
+    }
+    parts.push(`- next_cursor: ${nextCursor ?? 'null'}\n- total: ${total}`);
+    parts.push(String(r['follow_up']));
+    return parts.join('\n\n');
+}

package/dist/commands/canvas-history/show.d.ts

@@ -0,0 +1 @@
+export declare const showLeaf: import("../../core/command.js").LeafDef;

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

@@ -0,0 +1,79 @@
+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'];
+export const showLeaf = defineLeaf({
+    name: 'show',
+    description: 'enumerate one node\'s artifacts as refs',
+    whenToUse: 'you have a node id and want to see everything it left behind — its reports and context docs as refs ready for `canvas history read`. The bridge from "found the node" to "read its artifacts". Use `node inspect show` instead for the node\'s topology/neighbors, not its content.',
+    help: {
+        name: 'canvas history show',
+        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: '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: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nodeId = input['nodeId'].trim();
+        const type = input['type'];
+        const sort = input['sort'] ?? 'recency';
+        if (getNode(nodeId) === null) {
+            throw notFound(`unknown node: ${nodeId}`, {
+                received: nodeId,
+                next: 'List nodes with `crtr node inspect list`, or find one with `canvas history search`.',
+            });
+        }
+        const arts = nodeArtifacts(nodeId, type !== undefined ? [type] : undefined);
+        arts.sort((a, b) => (sort === 'oldest' ? a.tsMs - b.tsMs : b.tsMs - a.tsMs) || a.ref.localeCompare(b.ref));
+        const artifacts = arts.map((a) => {
+            let size = 0;
+            try {
+                if (a.path !== null)
+                    size = statSync(a.path).size;
+            }
+            catch {
+                /* ignore */
+            }
+            return {
+                ref: a.ref,
+                source: a.source === 'report' && a.reportKind ? `report:${a.reportKind}` : a.source,
+                ts: a.ts,
+                detail: a.title + (size > 0 ? `  (${size}B)` : ''),
+            };
+        });
+        const node = getNode(nodeId);
+        return {
+            node: `${node?.name} (${nodeId})`,
+            artifacts,
+            follow_up: 'Read one with `canvas history read <ref>`; reopen the node with `canvas revive ' + nodeId + '`.',
+        };
+    },
+    render: (r) => {
+        const arts = r['artifacts'];
+        const parts = [`node: ${r['node']}`];
+        if (arts.length === 0) {
+            parts.push('0 artifacts.');
+        }
+        else {
+            const cols = Object.keys(arts[0]);
+            const head = `| ${cols.join(' | ')} |`;
+            const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+            const body = arts
+                .map((a) => `| ${cols.map((c) => String(a[c] ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ')).join(' | ')} |`)
+                .join('\n');
+            parts.push(`${arts.length} artifacts:\n\n${head}\n${sep}\n${body}`);
+        }
+        parts.push(String(r['follow_up']));
+        return parts.join('\n\n');
+    },
+});

package/dist/commands/canvas-history.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare const historyBranch: BranchDef;

package/dist/commands/canvas-history.js

@@ -0,0 +1,33 @@
+// `canvas history` — search and recall the canvas's record of past work in a
+// cwd. The accumulated episodic record of every node that ran here and the
+// artifacts it left: its reports (final/update/urgent outcome summaries) and
+// context docs (specs, designs, roadmaps, findings). Distinct from `crtr
+// memory`, which is curated semantic knowledge held independent of any episode.
+// This branch owns CONTENT; it never duplicates the graph (use `canvas revive`
+// to reopen a found node, `node inspect show` for its topology).
+import { defineBranch } from '../core/command.js';
+import { searchLeaf } from './canvas-history/search.js';
+import { readLeaf } from './canvas-history/read.js';
+import { showLeaf } from './canvas-history/show.js';
+import { callerCwd, corpusStats } from '../core/canvas/index.js';
+/** The bounded per-cwd `<corpus>` aggregate for the branch -h — pre-empts a
+ *  `search` call just to gauge the corpus (cli-design §15: aggregate, never
+ *  enumerate). Soft-fails to omission if the db is unreachable. */
+function corpusBlock() {
+    const cwd = callerCwd();
+    const s = corpusStats(cwd);
+    const span = s.span !== null ? `${s.span.from} → ${s.span.to}` : 'n/a';
+    return `<corpus cwd="${cwd}" nodes="${s.nodes}" reports="${s.reports}" docs="${s.docs}" span="${span}"/>`;
+}
+export const historyBranch = defineBranch({
+    name: 'history',
+    description: 'search and recall the canvas\'s record of past work in this cwd',
+    whenToUse: 'you want to find or re-read what was DONE in a cwd — a past design, a final report, a roadmap, a finding — across every node that ran there. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',
+    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`.',
+        dynamicState: corpusBlock,
+    },
+    children: [searchLeaf, readLeaf, showLeaf],
+});

package/dist/commands/canvas.js

@@ -15,6 +15,7 @@ import { daemonBranch } from './daemon.js';
 import { tmuxSpreadLeaf } from './tmux-spread.js';
 import { chordLeaf } from './chord.js';
 import { canvasPruneLeaf } from './canvas-prune.js';
+import { historyBranch } from './canvas-history.js';
 export function registerCanvas() {
     return defineBranch({
         name: 'canvas',
@@ -26,8 +27,8 @@ export function registerCanvas() {
         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; `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 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.',
         },
-        children: [dashboardLeaf, browseLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
+        children: [dashboardLeaf, browseLeaf, attentionBranch, reviveLeaf, historyBranch, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
     });
 }