@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/core/canvas/history.js

@@ -0,0 +1,389 @@
+// canvas history — the scan-first engine over the per-cwd episodic record.
+//
+// The canvas accumulates a high-signal corpus per cwd: every node that ran
+// there plus the artifacts it left — its `reports/` (append-only push history:
+// final/update/urgent outcome summaries) and `context/` docs (specs, designs,
+// roadmaps, findings). This module is the ONE place that scans that corpus; it
+// lives in the canvas data-access layer, so it resolves every node + path
+// through canvas.ts + paths.ts and never hand-joins. No persistent index —
+// node facets (cwd/kind/status) are filtered cheaply against the db FIRST, then
+// only the surviving nodes' artifact files are read. FTS5/bm25 is the future
+// upgrade; the surface above is backend-independent.
+import { statSync, readdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { getNode, listNodes, view } from './canvas.js';
+import { contextDir, reportsDir, nodeDir } from './paths.js';
+import { readTextIfExists, walkFiles, pathExists } from '../fs-utils.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+/** The cwd the caller means by default: the calling node's cwd (resolved from
+ *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
+ *  when not run as a node. */
+export function callerCwd() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id !== undefined && id !== '') {
+        const node = getNode(id);
+        if (node !== null)
+            return node.cwd;
+    }
+    return process.cwd();
+}
+/** Compact report stamp `20260607T075536` → `2026-06-07T07:55:36`. */
+function compactToIso(stamp) {
+    const m = stamp.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})$/);
+    if (m === null)
+        return stamp;
+    return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}`;
+}
+function toMs(ts) {
+    const n = Date.parse(ts);
+    return Number.isNaN(n) ? 0 : n;
+}
+/** First markdown heading (`# …`) or first non-empty line, trimmed. */
+function firstHeading(body) {
+    const lines = body.split('\n');
+    for (const l of lines) {
+        const t = l.trim();
+        if (t.startsWith('#'))
+            return t.replace(/^#+\s*/, '').trim();
+    }
+    for (const l of lines) {
+        const t = l.trim();
+        if (t !== '')
+            return t.length > 120 ? t.slice(0, 120) : t;
+    }
+    return '';
+}
+/** A memoized body loader for a file artifact — reads + strips frontmatter once. */
+function fileBodyLoader(absPath) {
+    let cached = null;
+    const load = () => {
+        if (cached !== null)
+            return cached;
+        const raw = readTextIfExists(absPath);
+        cached = raw === null ? '' : parseFrontmatterGeneric(raw).body;
+        return cached;
+    };
+    // Read the head eagerly for ts/title derivation (the file is small markdown).
+    const raw = readTextIfExists(absPath);
+    const head = raw === null ? '' : raw;
+    if (raw !== null)
+        cached = parseFrontmatterGeneric(raw).body;
+    return { load, head };
+}
+function reportArtifact(row, desc, filename) {
+    const abs = join(reportsDir(row.node_id), filename);
+    const m = filename.match(/^([0-9]{8}T[0-9]{6})-(\w+)\.md$/);
+    const { load, head } = fileBodyLoader(abs);
+    const fm = parseFrontmatterGeneric(head).data;
+    const reportKind = (typeof fm?.['kind'] === 'string' ? fm['kind'] : undefined) ?? (m ? m[2] : 'report');
+    const ts = (typeof fm?.['ts'] === 'string' ? fm['ts'] : undefined) ??
+        (m ? compactToIso(m[1]) : new Date(statSync(abs).mtimeMs).toISOString());
+    const body = load();
+    return {
+        ref: `${row.node_id}:reports/${filename}`,
+        nodeId: row.node_id,
+        relpath: `reports/${filename}`,
+        source: 'report',
+        reportKind,
+        ts,
+        tsMs: toMs(ts),
+        title: firstHeading(body),
+        nodeName: row.name,
+        nodeKind: row.kind,
+        nodeStatus: row.status,
+        nodeCwd: row.cwd,
+        nodeDesc: desc,
+        path: abs,
+        loadBody: load,
+    };
+}
+function docArtifact(row, desc, abs) {
+    const rel = relative(nodeDir(row.node_id), abs).split(sep).join('/');
+    const isRoadmap = rel === 'context/roadmap.md';
+    const { load } = fileBodyLoader(abs);
+    let ts;
+    try {
+        ts = new Date(statSync(abs).mtimeMs).toISOString();
+    }
+    catch {
+        ts = row.created;
+    }
+    const body = load();
+    return {
+        ref: `${row.node_id}:${rel}`,
+        nodeId: row.node_id,
+        relpath: rel,
+        source: isRoadmap ? 'roadmap' : 'doc',
+        ts,
+        tsMs: toMs(ts),
+        title: firstHeading(body) || rel.replace(/^context\//, ''),
+        nodeName: row.name,
+        nodeKind: row.kind,
+        nodeStatus: row.status,
+        nodeCwd: row.cwd,
+        nodeDesc: desc,
+        path: abs,
+        loadBody: load,
+    };
+}
+function metaArtifact(row, desc) {
+    const body = `${row.name}\n${desc}\n${row.kind}`;
+    return {
+        ref: `${row.node_id}:meta`,
+        nodeId: row.node_id,
+        relpath: 'meta',
+        source: 'meta',
+        ts: row.created,
+        tsMs: toMs(row.created),
+        title: row.name,
+        nodeName: row.name,
+        nodeKind: row.kind,
+        nodeStatus: row.status,
+        nodeCwd: row.cwd,
+        nodeDesc: desc,
+        path: null,
+        loadBody: () => body,
+    };
+}
+/** List the markdown reports a node left, newest filename first. */
+function listReportFiles(nodeId) {
+    const dir = reportsDir(nodeId);
+    if (!pathExists(dir))
+        return [];
+    try {
+        return readdirSync(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Enumerate every context markdown doc a node left (recursive). */
+function listDocFiles(nodeId) {
+    const dir = contextDir(nodeId);
+    if (!pathExists(dir))
+        return [];
+    try {
+        return walkFiles(dir, (name) => name.endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** The node desc lives in meta.json, not the row — read it once per survivor. */
+function nodeDescOf(nodeId) {
+    const n = getNode(nodeId);
+    return n?.description ?? '';
+}
+/** Build the searchable artifact set for a scope + corpus filter. Node facets
+ *  are applied against the db rows first (cheap); only surviving nodes' files
+ *  are read. */
+export function buildCorpus(scope, corpus) {
+    const rows = scopedRows(scope);
+    // Node-facet narrowing (cheap, on the row).
+    const kinds = corpus.kinds;
+    const statuses = corpus.statuses;
+    const survivors = rows.filter((r) => {
+        if (kinds !== undefined && kinds.length > 0 && !kinds.includes(r.kind))
+            return false;
+        if (statuses !== undefined && statuses.length > 0 && !statuses.includes(r.status))
+            return false;
+        return true;
+    });
+    // --report-kind implies type=report.
+    const wantReportKind = corpus.reportKind;
+    const types = corpus.types !== undefined && corpus.types.length > 0
+        ? corpus.types
+        : wantReportKind !== undefined
+            ? ['report']
+            : ['report', 'doc', 'roadmap', 'meta'];
+    const want = new Set(types);
+    const out = [];
+    for (const row of survivors) {
+        const desc = want.has('meta') || want.has('report') || want.has('doc') || want.has('roadmap')
+            ? nodeDescOf(row.node_id)
+            : '';
+        if (want.has('meta'))
+            out.push(metaArtifact(row, desc));
+        if (want.has('report')) {
+            for (const f of listReportFiles(row.node_id)) {
+                const a = reportArtifact(row, desc, f);
+                if (a === null)
+                    continue;
+                if (wantReportKind !== undefined && a.reportKind !== wantReportKind)
+                    continue;
+                out.push(a);
+            }
+        }
+        if (want.has('doc') || want.has('roadmap')) {
+            for (const abs of listDocFiles(row.node_id)) {
+                const a = docArtifact(row, desc, abs);
+                if (a.source === 'roadmap' && !want.has('roadmap'))
+                    continue;
+                if (a.source === 'doc' && !want.has('doc'))
+                    continue;
+                out.push(a);
+            }
+        }
+    }
+    // Time window on artifact ts.
+    return out.filter((a) => {
+        if (corpus.sinceMs !== undefined && a.tsMs < corpus.sinceMs)
+            return false;
+        if (corpus.untilMs !== undefined && a.tsMs > corpus.untilMs)
+            return false;
+        return true;
+    });
+}
+/** Resolve the scope to the node rows in play. */
+function scopedRows(scope) {
+    const all = listNodes();
+    const byId = new Map(all.map((r) => [r.node_id, r]));
+    if (scope.nodes !== undefined && scope.nodes.length > 0) {
+        return scope.nodes.map((id) => byId.get(id)).filter((r) => r !== undefined);
+    }
+    if (scope.under !== undefined && scope.under !== '') {
+        const ids = [scope.under, ...view(scope.under)];
+        return ids.map((id) => byId.get(id)).filter((r) => r !== undefined);
+    }
+    if (scope.allCwds === true)
+        return all;
+    const cwd = scope.cwd !== undefined && scope.cwd !== '' ? scope.cwd : callerCwd();
+    return all.filter((r) => r.cwd === cwd);
+}
+/** Resolve a `<node-id>:<relpath>` handle to its content. Returns null when the
+ *  node is unknown or the artifact does not exist. Throws on path traversal. */
+export function resolveRef(ref) {
+    const idx = ref.indexOf(':');
+    if (idx === -1)
+        return null;
+    const nodeId = ref.slice(0, idx);
+    const relpath = ref.slice(idx + 1);
+    const node = getNode(nodeId);
+    if (node === null)
+        return null;
+    if (relpath === 'meta') {
+        const body = `# ${node.name}\n\n- kind: ${node.kind}\n- status: ${node.status}\n- cwd: ${node.cwd}\n- created: ${node.created}\n\n${node.description ?? ''}`;
+        return {
+            nodeId,
+            relpath,
+            source: 'meta',
+            ts: node.created,
+            nodeName: node.name,
+            body,
+            raw: null,
+            path: null,
+        };
+    }
+    if (relpath.includes('..') || relpath.startsWith('/')) {
+        throw new Error(`illegal relpath in ref: ${relpath}`);
+    }
+    const abs = join(nodeDir(nodeId), relpath);
+    const raw = readTextIfExists(abs);
+    if (raw === null)
+        return null;
+    const { body, data: fm } = parseFrontmatterGeneric(raw);
+    const isReport = relpath.startsWith('reports/');
+    const isRoadmap = relpath === 'context/roadmap.md';
+    let ts;
+    if (typeof fm?.['ts'] === 'string')
+        ts = fm['ts'];
+    else {
+        try {
+            ts = new Date(statSync(abs).mtimeMs).toISOString();
+        }
+        catch {
+            ts = node.created;
+        }
+    }
+    return {
+        nodeId,
+        relpath,
+        source: isReport ? 'report' : isRoadmap ? 'roadmap' : 'doc',
+        reportKind: isReport && typeof fm?.['kind'] === 'string' ? fm['kind'] : undefined,
+        ts,
+        nodeName: node.name,
+        body,
+        raw,
+        path: abs,
+    };
+}
+/** Enumerate one node's artifacts (for `history show`). */
+export function nodeArtifacts(nodeId, types) {
+    const node = getNode(nodeId);
+    if (node === null)
+        return [];
+    const row = {
+        node_id: node.node_id,
+        name: node.name,
+        kind: node.kind,
+        mode: node.mode,
+        lifecycle: node.lifecycle,
+        status: node.status,
+        cwd: node.cwd,
+        host_kind: node.host_kind ?? null,
+        parent: node.parent ?? null,
+        created: node.created,
+        intent: node.intent ?? null,
+        pi_pid: node.pi_pid ?? null,
+        window: node.window ?? null,
+        tmux_session: node.tmux_session ?? null,
+        pane: node.pane ?? null,
+    };
+    const want = new Set(types !== undefined && types.length > 0 ? types : ['report', 'doc', 'roadmap']);
+    const desc = node.description ?? '';
+    const out = [];
+    if (want.has('report')) {
+        for (const f of listReportFiles(nodeId)) {
+            const a = reportArtifact(row, desc, f);
+            if (a !== null)
+                out.push(a);
+        }
+    }
+    if (want.has('doc') || want.has('roadmap')) {
+        for (const abs of listDocFiles(nodeId)) {
+            const a = docArtifact(row, desc, abs);
+            if (a.source === 'roadmap' && !want.has('roadmap'))
+                continue;
+            if (a.source === 'doc' && !want.has('doc'))
+                continue;
+            out.push(a);
+        }
+    }
+    return out;
+}
+/** Bounded per-cwd aggregate for the branch `-h` `<corpus>` block. Counts files
+ *  on disk without reading bodies. */
+export function corpusStats(cwd) {
+    const rows = listNodes().filter((r) => r.cwd === cwd);
+    let reports = 0;
+    let docs = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const row of rows) {
+        const cMs = toMs(row.created);
+        if (cMs > 0) {
+            if (cMs < min)
+                min = cMs;
+            if (cMs > max)
+                max = cMs;
+        }
+        for (const f of listReportFiles(row.node_id)) {
+            reports++;
+            const m = f.match(/^([0-9]{8}T[0-9]{6})-/);
+            if (m !== null) {
+                const t = toMs(compactToIso(m[1]));
+                if (t > 0) {
+                    if (t < min)
+                        min = t;
+                    if (t > max)
+                        max = t;
+                }
+            }
+        }
+        docs += listDocFiles(row.node_id).length;
+    }
+    const span = min !== Infinity && max !== -Infinity
+        ? { from: new Date(min).toISOString().slice(0, 10), to: new Date(max).toISOString().slice(0, 10) }
+        : null;
+    return { cwd, nodes: rows.length, reports, docs, span };
+}

package/dist/core/canvas/index.d.ts

@@ -2,6 +2,7 @@ export * from './types.js';
 export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './history.js';
 export * from './focuses.js';
 export * from './wakeups.js';
 export * from './telemetry.js';

package/dist/core/canvas/index.js

@@ -4,6 +4,7 @@ export * from './types.js';
 export * from './labels.js';
 export * from './paths.js';
 export * from './canvas.js';
+export * from './history.js';
 export * from './focuses.js';
 export * from './wakeups.js';
 export * from './telemetry.js';

package/dist/core/config.js

@@ -1,8 +1,7 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, SCHEMA_VERSION, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState, defaultCanvasNavConfig } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot } from './scope.js';
-import { diag } from './io.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -24,24 +23,7 @@ export function readConfig(scope) {
     const existing = readJsonIfExists(configPathFor(root));
     if (!existing)
         return defaultScopeConfig();
-    const cfg = mergeConfig(existing);
-    if ((existing.schema_version ?? 0) < SCHEMA_VERSION) {
-        migrateSkillConfigKeys(cfg, scope, root);
-    }
-    return cfg;
-}
-function migrateSkillConfigKeys(cfg, scope, root) {
-    const colonKeys = Object.keys(cfg.skills).filter((k) => k.includes(':'));
-    if (colonKeys.length > 0) {
-        for (const key of colonKeys) {
-            const newKey = key.replace(/:/g, '/');
-            cfg.skills[newKey] = cfg.skills[key];
-            delete cfg.skills[key];
-        }
-        diag(`crtr: migrated ${colonKeys.length} skill config keys to slash form in ${scope}`);
-    }
-    cfg.schema_version = SCHEMA_VERSION;
-    writeJson(configPathFor(root), cfg);
+    return mergeConfig(existing);
 }
 export function readState(scope) {
     const root = scopeRoot(scope);
@@ -121,7 +103,6 @@ function mergeConfig(partial) {
     const schema_version = partial.schema_version === undefined ? defaults.schema_version : partial.schema_version;
     const marketplaces = partial.marketplaces === undefined ? {} : partial.marketplaces;
     const plugins = partial.plugins === undefined ? {} : partial.plugins;
-    const skills = partial.skills === undefined ? {} : partial.skills;
     const au = partial.auto_update;
     const rawInterval = au && typeof au.interval_hours === 'number' ? au.interval_hours : undefined;
     const interval_hours = rawInterval !== undefined && Number.isFinite(rawInterval) && rawInterval >= 0
@@ -140,7 +121,7 @@ function mergeConfig(partial) {
     // The merge drops unknown keys, so `headless` must be carried explicitly or it
     // is lost on every read-modify-write of config.json.
     const headless = typeof partial.headless === 'boolean' ? partial.headless : defaults.headless;
-    return { schema_version, marketplaces, plugins, skills, auto_update, max_panes_per_window, canvasNav, headless };
+    return { schema_version, marketplaces, plugins, auto_update, max_panes_per_window, canvasNav, headless };
 }
 export function updateConfig(scope, mutate) {
     const cfg = readConfig(scope);

package/dist/core/help.d.ts

@@ -94,7 +94,7 @@ export interface RootEntry {
     useWhen: string;
     /** Optional bounded block this subtree contributes to its <name> block at
      *  root. Returns a complete self-named state element (build it with
-     *  stateBlock), e.g. `<skills count="42">…</skills>`. Aggregate, never an
+     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
      *  unbounded enumeration on a cold path. Soft-fails to omission on
      *  null/throw. */
     dynamicState?: () => string | null;
@@ -141,7 +141,7 @@ export interface BranchHelp {
      *  child's purpose lives in its own listing row). */
     model?: string;
     /** Bounded runtime aggregate as a complete self-named state element (build
-     *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
+     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
      *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
     /** Parent-level listing assembled by defineBranch from the actual child defs.

package/dist/core/help.js

@@ -105,7 +105,7 @@ export function renderRoot(h) {
         for (const l of rootSubcommandLines(c))
             lines.push(l);
         // dynamicState returns a complete self-named element (e.g.
-        // <skills count="42">…</skills>) — emit it as-is, nested in the command.
+        // <kinds count="7">…</kinds>) — emit it as-is, nested in the command.
         const state = evalDynamic(c.dynamicState);
         if (state !== null)
             lines.push(state);

package/dist/core/memory-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from '../types.js';
+import type { InstalledPlugin, Scope } from '../types.js';
 /**
  * Thin memory-document resolver for the document substrate. Mirrors the SHAPE
  * of the skill resolver (qualifier parse → scope precedence → direct path
@@ -31,8 +31,15 @@ export declare function memoryDocId(doc: MemoryDoc): string;
 /** All memory docs in one scope's memory/ dir, scanned recursively for *.md
  *  (topical subdirs supported), sorted by path-derived name. */
 export declare function listMemoryDocs(scope: Scope): MemoryDoc[];
+/** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
+ *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
+ *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
+ *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
+export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: Scope): MemoryDoc[];
 /** All memory docs across the resolved scopes, in precedence order
- *  (project, then user, then builtin), each scope's docs name-sorted within. */
+ *  (project, then user, then builtin). Within each scope, native docs are
+ *  emitted FIRST, then that scope's enabled-plugin docs — so native wins on the
+ *  caller's first-wins (scope,name) dedup. Each group is name-sorted within. */
 export declare function listAllMemoryDocs(scope?: Scope): MemoryDoc[];
 /**
  * Resolve a path-derived name to a single memory document.

package/dist/core/memory-resolver.js

@@ -1,10 +1,10 @@
 import { join, relative, sep } from 'node:path';
 import { pathExists, readText, walkFiles } from './fs-utils.js';
 import { parseFrontmatterGeneric } from './frontmatter.js';
-import { parseSkillQualifier } from './resolver.js';
+import { listInstalledPlugins, parseSkillQualifier } from './resolver.js';
 import { ambiguous, notFound, usage } from './errors.js';
 import { warn } from './output.js';
-import { projectScopeRoot, scopeMemoryDir } from './scope.js';
+import { pluginMemoryDir, projectScopeRoot, scopeMemoryDir } from './scope.js';
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export function memoryDocId(doc) {
     return `${doc.scope}/${doc.name}`;
@@ -50,14 +50,50 @@ export function listMemoryDocs(scope) {
     }
     return docs.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
+ *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
+ *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
+ *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
+export function listPluginMemoryDocs(plugin, scope) {
+    const dir = pluginMemoryDir(plugin);
+    if (!pathExists(dir))
+        return [];
+    const docs = [];
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+        const derived = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        if (!derived)
+            continue;
+        const name = `${plugin.name}/${derived}`;
+        try {
+            docs.push(loadMemoryDoc(name, scope, file));
+        }
+        catch (e) {
+            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+            warn(`invalid frontmatter in ${file}: ${msg}`);
+        }
+    }
+    return docs.sort((a, b) => a.name.localeCompare(b.name));
+}
 /** All memory docs across the resolved scopes, in precedence order
- *  (project, then user, then builtin), each scope's docs name-sorted within. */
+ *  (project, then user, then builtin). Within each scope, native docs are
+ *  emitted FIRST, then that scope's enabled-plugin docs — so native wins on the
+ *  caller's first-wins (scope,name) dedup. Each group is name-sorted within. */
 export function listAllMemoryDocs(scope) {
-    return scopesInPrecedence(scope).flatMap(listMemoryDocs);
+    return scopesInPrecedence(scope).flatMap((s) => [
+        ...listMemoryDocs(s),
+        ...listInstalledPlugins(s)
+            .filter((p) => p.enabled)
+            .flatMap((p) => listPluginMemoryDocs(p, s)),
+    ]);
 }
 /** Direct full-path lookup of memory/<name>.md across scopes, precedence-first.
  *  Returns every scope's hit in precedence order; the resolver takes the first
- *  (highest-precedence) one — a fully-specified name is never ambiguous. */
+ *  (highest-precedence) one — a fully-specified name is never ambiguous.
+ *
+ *  A directory INDEX is the cleaner contract: when `<name>.md` is absent but
+ *  `<name>/INDEX.md` exists, the bare dir name (`taste`) resolves to the dir's
+ *  INDEX doc — carrying the dir name as its identity. (`taste/INDEX` still
+ *  resolves directly as the file path.) */
 function findMemoryMatches(name, scope) {
     const matches = [];
     for (const s of scopesInPrecedence(scope)) {
@@ -65,9 +101,13 @@ function findMemoryMatches(name, scope) {
         if (!dir)
             continue;
         const path = join(dir, ...name.split('/')) + '.md';
-        if (!pathExists(path))
+        if (pathExists(path)) {
+            matches.push(loadMemoryDoc(name, s, path));
             continue;
-        matches.push(loadMemoryDoc(name, s, path));
+        }
+        const indexPath = join(dir, ...name.split('/'), 'INDEX.md');
+        if (pathExists(indexPath))
+            matches.push(loadMemoryDoc(name, s, indexPath));
     }
     return matches;
 }

package/dist/core/render.d.ts

@@ -1,9 +1,10 @@
 import type { LeafHelp } from './help.js';
 import type { ErrorPayload } from './io.js';
-/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
  *  Field order follows the leaf's declared output schema; any extra keys append
- *  after. Scalars become attributes or a bullet list, prose and collections
- *  become their own fenced blocks. */
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
 export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
 /** Render a structured failure as an instruction-shaped block: what broke, what
  *  was received, and the recovery road sign — the same recovery info the JSON