@north-light/crouter 0.3.208 → 0.3.210

package/dist/core/memory-resolver.js

@@ -305,8 +305,7 @@ function matchNormalizedChild(dir, segment, want, ext = '.md') {
 /** Resolve a NORMALIZED (numeric-prefix-stripped) segment path against a
  *  physical memory dir: walk intermediate segments matching each as a
  *  directory by normalized name, then resolve the final segment as either a
- *  `.md` file or a directory (the bare-dir -> INDEX.md fallback needs the dir
- *  match even when a same-named file also exists). Either half is null when
+ *  `.md` file or a directory. Either half is null when
  *  the segment path does not resolve that way. This is what makes
  *  `00-runtime-base.md` findable as `runtime-base` and `01-spine/00-has-manager`
  *  findable as `spine/has-manager` — the physical path keeps its pins, only
@@ -329,28 +328,16 @@ function resolveNormalizedPath(baseDir, segments, ext = '.md') {
  *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
  *  resolution rules so a log outlives its doc under the same name the doc had:
  *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
- *  `.history/00-topic.jsonl` still answers to `topic`) and a bare directory
- *  name falls back to its INDEX log. Returns null when nothing resolves. */
+ *  `.history/00-topic.jsonl` still answers to `topic`). Returns null when
+ *  nothing resolves. */
 export function resolveHistoryLogPath(historyDir, segments) {
-    const { filePath, dirPath } = resolveNormalizedPath(historyDir, segments, '.jsonl');
-    if (filePath)
-        return filePath;
-    if (dirPath) {
-        const index = matchNormalizedChild(dirPath, 'INDEX', 'file', '.jsonl');
-        if (index)
-            return index;
-    }
-    return null;
+    return resolveNormalizedPath(historyDir, segments, '.jsonl').filePath;
 }
 /** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
  *  source's single hit, or undefined — a source can produce at most one direct
  *  match (native wins over plugin within the source, and at most one plugin's
- *  name can match).
- *
- *  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.)
+ *  name can match). A directory name matches NO doc here: the read leaf
+ *  answers a directory with its listing, never a stand-in document.
  *
  *  `name`'s segments are already normalized (a caller-supplied identifier is
  *  never authored with a numeric prefix); resolution against the physical tree
@@ -362,40 +349,26 @@ function findMemoryMatchInSource(name, segments, source) {
     // precedence), then its enabled plugins.
     const dir = source.memoryDir;
     if (dir) {
-        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
+        const { filePath } = resolveNormalizedPath(dir, segments);
         if (!isLegacySkillDoc && filePath !== null)
             return loadMemoryDoc(source.scope, dir, filePath, name);
-        if (dirPath !== null) {
-            const indexPath = join(dirPath, 'INDEX.md');
-            if (pathExists(indexPath))
-                return loadMemoryDoc(source.scope, dir, indexPath, name);
-        }
     }
     // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
     // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
-    // enumerates — `read` must resolve what `list` shows). A BARE plugin name
-    // (no slash) resolves the plugin-root INDEX.md, mirroring the native
-    // bare-dir-name -> INDEX.md contract for the plugin mount root.
+    // enumerates — `read` must resolve what `list` shows).
     const slash = name.indexOf('/');
-    const pluginName = slash > 0 ? name.slice(0, slash) : name;
-    const rest = slash > 0 ? name.slice(slash + 1) : '';
+    if (slash <= 0)
+        return undefined;
+    const pluginName = name.slice(0, slash);
+    const rest = name.slice(slash + 1);
     for (const p of source.plugins) {
         if (p.name !== pluginName)
             continue;
         const pdir = pluginMemoryDir(p);
-        const restSegments = rest ? rest.split('/') : [];
-        if (rest) {
-            const { filePath } = resolveNormalizedPath(pdir, restSegments);
-            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
-                return loadMemoryDoc(source.scope, pdir, filePath, name);
-        }
-        // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
-        const pIndexDir = rest ? resolveNormalizedPath(pdir, restSegments).dirPath : pdir;
-        if (pIndexDir !== null) {
-            const pindex = join(pIndexDir, 'INDEX.md');
-            if (pathExists(pindex))
-                return loadMemoryDoc(source.scope, pdir, pindex, name);
-        }
+        const restSegments = rest.split('/');
+        const { filePath } = resolveNormalizedPath(pdir, restSegments);
+        if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
+            return loadMemoryDoc(source.scope, pdir, filePath, name);
     }
     return undefined;
 }

package/dist/core/runtime/bearings.d.ts

@@ -1,4 +1,5 @@
 import { type Cron } from '../canvas/index.js';
+import type { InjectedDocs } from '../substrate/injected-store.js';
 /** The bearings custom type is shared with every attached renderer. */
 export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
 /** The `<project_context>` block — the `<environment>` snapshot only: a
@@ -71,10 +72,10 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *      from.
  *   2. `<memory kind="knowledge">` — the consultable boot catalog, a SIBLING of
  *      the bearings (never nested under the context dir). Dropped when empty.
- *   3. `<auto-loaded-context>` — memories whose `applies-to: "."` fires because
- *      cwd/profile mounted their owning project store. Dropped when empty.
+ *   3. `<auto-loaded-context>` — memories whose `on: workspace-open` entry fires
+ *      because cwd/profile mounted their owning project store. Dropped when empty.
  *   4. `<project_context>` — the cwd/git environment snapshot. pi's own
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
  *      the directory's `.crouter/memory/INDEX.md` front door. */
-export declare function buildContextBearings(nodeId: string, seen?: Set<string>): string;
+export declare function buildContextBearings(nodeId: string, seen?: InjectedDocs): string;

package/dist/core/runtime/bearings.js

@@ -340,8 +340,8 @@ function managedWorktreeNote(node) {
  *      from.
  *   2. `<memory kind="knowledge">` — the consultable boot catalog, a SIBLING of
  *      the bearings (never nested under the context dir). Dropped when empty.
- *   3. `<auto-loaded-context>` — memories whose `applies-to: "."` fires because
- *      cwd/profile mounted their owning project store. Dropped when empty.
+ *   3. `<auto-loaded-context>` — memories whose `on: workspace-open` entry fires
+ *      because cwd/profile mounted their owning project store. Dropped when empty.
  *   4. `<project_context>` — the cwd/git environment snapshot. pi's own
  *      AGENTS.md/CLAUDE.md injection stays suppressed (`noContextFiles` in
  *      broker.ts); `crtr sys sync project-guidance` imports that guidance into
@@ -365,8 +365,8 @@ export function buildContextBearings(nodeId, seen) {
         bearings.push('', orchestratorContextNote(nodeId));
     bearings.push('</crtr-bearings>');
     // The consultable catalog rides BESIDE the bearings, not inside them.
-    const knowledge = renderKnowledgeBlock(nodeId);
-    // A workspace mount is the initial read of its root (`applies-to: "."`).
+    const knowledge = renderKnowledgeBlock(nodeId, seen);
+    // A workspace mount is the initial read of its root (`on: workspace-open`).
     const workspaceContext = renderWorkspaceOpenDocs(nodeId, seen);
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
     // — the stored `situational` card, placed in the bearings BODY, so it is a

package/dist/core/runtime/broker-extension-render.d.ts

@@ -1,3 +1,4 @@
+import type { InjectedDocs } from '../substrate/injected-store.js';
 import type { BrokerExtensionNodeDTO, BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
 export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO): string;
 /** Same environment-only project context rendered at normal boot, without a
@@ -6,9 +7,9 @@ export declare function buildProjectContextBlockForBroker(cwd: string): string;
 /** `situational` is the node's stored situational card, placed in the bearings
  *  BODY — the one place in the system where a runtime card nests inside
  *  another (see situational-context.ts). '' when none is set. */
-export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: Set<string>): string;
+export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: InjectedDocs): string;
 export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
-export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO): string;
+export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO, seen?: InjectedDocs): string;
 /** A canonical report ref has already been validated by crtrd in state. The
  * broker reads only its local filesystem content; no canvas accessor is needed. */
 export declare function reportPathFromRef(ref: string, reportNodes: ReadonlyMap<string, unknown>): string | null;

package/dist/core/runtime/broker-extension-render.js

@@ -158,7 +158,7 @@ export function buildContextBearingsFromState(state, projectContext, situational
     if (node.mode === 'orchestrator')
         bearings.push('', `Because you persist across refresh cycles, your context directory (${contextDir(node.node_id)}) is also where a future cycle of you resumes the work — keep the working notes and decisions a refreshed you would need there, alongside the docs you share with the nodes you spawn.`);
     bearings.push('</crtr-bearings>');
-    const knowledge = renderKnowledgeForSubject(state.subject, node.node_id);
+    const knowledge = renderKnowledgeForSubject(state.subject, node.node_id, seen);
     const workspace = renderWorkspaceOpenDocsForSubject(state.subject, node.cwd, node.profile_id, seen);
     return [bearings.join('\n'), knowledge, workspace, situational, projectContext].filter((part) => part !== '').join('\n');
 }
@@ -186,8 +186,8 @@ export function buildForkBearingsFromState(state, situational = '') {
     bearings.push('', 'The first real user message after these bearings is your mandate.', '</crtr-bearings>');
     return [bearings.join('\n'), situational].filter((part) => part !== '').join('\n');
 }
-export function renderPreferencesFromState(state) {
-    return interpolateNodePaths(renderPreferencesForSubject(state.subject).block, state.node.node_id);
+export function renderPreferencesFromState(state, seen) {
+    return interpolateNodePaths(renderPreferencesForSubject(state.subject, seen).block, state.node.node_id);
 }
 /** A canonical report ref has already been validated by crtrd in state. The
  * broker reads only its local filesystem content; no canvas accessor is needed. */

package/dist/core/runtime/memory.js

@@ -1,9 +1,8 @@
 // memory.ts — the node-local substrate document store.
 //
 // One scope lives here: node-local memory, a `memory/` directory of substrate
-// documents (.md files with typed frontmatter — kind, when, why,
-// system-prompt-visibility, gate) inside a node's context dir; it dies with the
-// node. User-global and project memory are scope-resolved stores — see
+// documents (.md files with typed frontmatter — kind, when-and-why-to-read,
+// surfaces, gate) inside a node's context dir; it dies with the node. User-global and project memory are scope-resolved stores — see
 // `scopeMemoryDir` in core/scope.ts.
 import { join } from 'node:path';
 // Import the pure path helper from paths.ts directly, NOT the canvas/index.js

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

@@ -1,11 +1,14 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
-export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, SURFACE_EVENTS, SURFACE_RUNGS, bootRung, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, normalizeNameSegment, normalizeDocName, resolveDocName, } from './schema.js';
+export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc, SurfaceEntry, SurfaceEvent, SurfaceRung } from './schema.js';
+export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
+export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
+export { deliveredAtOrAbove, recordDelivery, mergeInjectedDocs } from './injected-store.js';
+export type { InjectedDocs } from './injected-store.js';
 export { scopeForCwd, profileNameFor } from './subject-fields.js';
 export type { NodeConfigSubject } from './subject-fields.js';
 export { spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
-export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveSystemPromptRung, } from './ceiling.js';
 export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
 export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
-export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject } from './on-read.js';
+export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, renderCandidateBlocks, memoryReadDocBlocks } from './on-read.js';
 export { renderOnReadDocs, renderWorkspaceOpenDocs } from './on-read-node.js';

package/dist/core/substrate/index.js

@@ -8,19 +8,21 @@ export {
 KINDS, isDocKind, 
 // ladder
 RUNGS, rungRank, rungAtLeast, 
-// fallback floor
-FALLBACK_RUNG, 
+// surfaces (event routing)
+SURFACE_EVENTS, SURFACE_RUNGS, bootRung, 
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
 // display-name normalization
 normalizeNameSegment, normalizeDocName, 
 // substrate identity (explicit-name-then-path-fallback)
 resolveDocName, } from './schema.js';
+export { matchesReadEntry, matchesMemoryReadEntry, matchesCommandEntry, readDeliveryRung, workspaceOpenRung, memoryReadDeliveryRung, commandDeliveryRung, owningRootOf, underOwningRoot } from './surface-match.js';
+export { dirDedupKey, docsByName, isDirName, ancestorDirsOf, renderDirListing } from './listings.js';
+export { deliveredAtOrAbove, recordDelivery, mergeInjectedDocs } from './injected-store.js';
 export { scopeForCwd, profileNameFor } from './subject-fields.js';
 export { spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
-export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveSystemPromptRung, } from './ceiling.js';
 export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
 export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
-export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject } from './on-read.js';
+export { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject, renderOnCommandDocsForSubject, renderCandidateBlocks, memoryReadDocBlocks } from './on-read.js';
 export { renderOnReadDocs, renderWorkspaceOpenDocs } from './on-read-node.js';

package/dist/core/substrate/injected-store.d.ts

@@ -1,16 +1,28 @@
-/** The process-shared dedup set for a node: loaded from disk once, then the
- *  SAME Set instance on every call, so all hooks in this pi process grow and
- *  consult one set. Daemon-side deliveries (a warm-spare claim) write the disk
+import { type Rung } from './schema.js';
+/** realpath → highest rung rank delivered this transcript (1=name, 2=preview,
+ *  3=content — `rungRank` of the delivered rung). */
+export type InjectedDocs = Map<string, number>;
+/** Already delivered at `rung` or above? — the skip test every channel runs
+ *  before rendering a doc (or a listing line, at preview) again. */
+export declare function deliveredAtOrAbove(seen: InjectedDocs, realpath: string, rung: Rung): boolean;
+/** Record a delivery at `rung`, keeping the highest rank seen. */
+export declare function recordDelivery(seen: InjectedDocs, realpath: string, rung: Rung): void;
+/** Max-merge `source` into `target` — used to fold an out-of-process delivery
+ *  (the daemon's warm-spare bearings push) into a live process's shared map. */
+export declare function mergeInjectedDocs(target: InjectedDocs, source: InjectedDocs): void;
+/** The process-shared dedup map for a node: loaded from disk once, then the
+ *  SAME Map instance on every call, so all hooks in this pi process grow and
+ *  consult one map. Daemon-side deliveries (a warm-spare claim) write the disk
  *  file from another process; consumers that must see those merge the plain
  *  `loadInjectedDocs` result in before rendering. */
-export declare function sharedInjectedDocs(nodeId: string): Set<string>;
-/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
- *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
- *  has not yet surfaced any on-read doc). */
-export declare function loadInjectedDocs(nodeId: string): Set<string>;
-/** Persist a node's on-read dedup set. Called after each read that surfaced a
- *  new doc, so the grown set survives a later dormancy. */
-export declare function saveInjectedDocs(nodeId: string, seen: Set<string>): void;
-/** Drop a node's persisted dedup set. Called by the launch paths that start a
+export declare function sharedInjectedDocs(nodeId: string): InjectedDocs;
+/** Rehydrate a node's dedup map from disk. Returns an empty map when the file
+ *  is absent, unreadable, or malformed (a fresh transcript, or a node that has
+ *  not yet surfaced any doc). */
+export declare function loadInjectedDocs(nodeId: string): InjectedDocs;
+/** Persist a node's dedup map. Called after each delivery that grew it, so
+ *  the grown map survives a later dormancy. */
+export declare function saveInjectedDocs(nodeId: string, seen: InjectedDocs): void;
+/** Drop a node's persisted dedup map. Called by the launch paths that start a
  *  FRESH transcript, so the new conversation surfaces docs from scratch. */
 export declare function clearInjectedDocs(nodeId: string): void;

package/dist/core/substrate/injected-store.js

@@ -1,32 +1,63 @@
-// injected-store.ts — durable per-node dedup set for on-read doc injection.
+// injected-store.ts — durable per-node dedup map for substrate doc delivery.
 //
-// The on-read substrate hook (canvas-doc-substrate.ts → renderOnReadDocs) dedups
-// so a given doc surfaces at most once per conversation. That set USED to live
-// only in the pi process heap, cleared on session_start. But a node's logical
-// session — the .jsonl transcript — spans MULTIPLE pi processes: a dormancy →
-// revive(resume) cycle exits the old process and launches a fresh `pi --session`
-// that REUSES the same transcript. The fresh process started with an empty set,
-// so any doc already injected before dormancy got injected AGAIN on the next
-// read — the "fires a second time per session" bug.
+// Delivery channels (boot render seeding, workspace-open, on-read, memory-read
+// listings and events, command events) dedup so a given doc surfaces at most
+// once per conversation AT A GIVEN DISCLOSURE. The map keys on realpath and
+// carries the highest rung rank delivered so far; higher rungs pierce lower —
+// a listing line (preview rank) must not block a later explicit content
+// delivery, while a content delivery silences everything after it. Directory
+// listings participate under the directory's own realpath (a directory never
+// collides with a file's realpath).
 //
-// This module persists the set to `nodes/<id>/injected-docs.json` so the resumed
-// process rehydrates it and skips docs already present in the transcript. The
-// one launch path that begins a FRESH transcript (reviveNode with resume=false,
-// in runtime/revive.ts) calls clearInjectedDocs(), so a new conversation starts
-// with an empty set.
+// The map USED to live only in the pi process heap, cleared on session_start.
+// But a node's logical session — the .jsonl transcript — spans MULTIPLE pi
+// processes: a dormancy → revive(resume) cycle exits the old process and
+// launches a fresh `pi --session` that REUSES the same transcript. This module
+// persists the map to `nodes/<id>/injected-docs.json` so the resumed process
+// rehydrates it and skips docs already present in the transcript. The one
+// launch path that begins a FRESH transcript (reviveNode with resume=false, in
+// runtime/revive.ts) calls clearInjectedDocs(), so a new conversation starts
+// empty. CLI processes (the `memory read` leaf) load/save the same file.
 //
-// All ops are best-effort: a failed read/write degrades to a possible re-inject,
-// never a crash — a dedup miss must never break a read or a revive.
+// Disk format: `{"v":2,"docs":{"<realpath>":<rank 1|2|3>}}` (rank =
+// rungRank of the delivered rung). A legacy v1 string-array rehydrates at
+// content rank — its entries were recorded under never-re-deliver semantics.
+//
+// All ops are best-effort: a failed read/write degrades to a possible
+// re-inject, never a crash — a dedup miss must never break a read or a revive.
 import { readFileSync, writeFileSync, rmSync } from 'node:fs';
 import { injectedDocsPath } from '../canvas/paths.js';
-/** Per-process cache behind `sharedInjectedDocs`: one Set instance per node,
+import { rungRank } from './schema.js';
+/** Already delivered at `rung` or above? — the skip test every channel runs
+ *  before rendering a doc (or a listing line, at preview) again. */
+export function deliveredAtOrAbove(seen, realpath, rung) {
+    const have = seen.get(realpath);
+    return have !== undefined && have >= rungRank(rung);
+}
+/** Record a delivery at `rung`, keeping the highest rank seen. */
+export function recordDelivery(seen, realpath, rung) {
+    const rank = rungRank(rung);
+    const have = seen.get(realpath);
+    if (have === undefined || have < rank)
+        seen.set(realpath, rank);
+}
+/** Max-merge `source` into `target` — used to fold an out-of-process delivery
+ *  (the daemon's warm-spare bearings push) into a live process's shared map. */
+export function mergeInjectedDocs(target, source) {
+    for (const [real, rank] of source) {
+        const have = target.get(real);
+        if (have === undefined || have < rank)
+            target.set(real, rank);
+    }
+}
+/** Per-process cache behind `sharedInjectedDocs`: one Map instance per node,
  *  shared by every extension in the pi process (context-intro's workspace-open
  *  render and doc-substrate's on-read hook), so a doc delivered by one hook is
- *  already in the set the other dedups against. */
+ *  already in the map the other dedups against. */
 const cache = new Map();
-/** The process-shared dedup set for a node: loaded from disk once, then the
- *  SAME Set instance on every call, so all hooks in this pi process grow and
- *  consult one set. Daemon-side deliveries (a warm-spare claim) write the disk
+/** The process-shared dedup map for a node: loaded from disk once, then the
+ *  SAME Map instance on every call, so all hooks in this pi process grow and
+ *  consult one map. Daemon-side deliveries (a warm-spare claim) write the disk
  *  file from another process; consumers that must see those merge the plain
  *  `loadInjectedDocs` result in before rendering. */
 export function sharedInjectedDocs(nodeId) {
@@ -37,31 +68,47 @@ export function sharedInjectedDocs(nodeId) {
     }
     return seen;
 }
-/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
- *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
- *  has not yet surfaced any on-read doc). */
+const CONTENT_RANK = rungRank('content');
+/** Rehydrate a node's dedup map from disk. Returns an empty map when the file
+ *  is absent, unreadable, or malformed (a fresh transcript, or a node that has
+ *  not yet surfaced any doc). */
 export function loadInjectedDocs(nodeId) {
     try {
-        const arr = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
-        if (!Array.isArray(arr))
-            return new Set();
-        return new Set(arr.filter((x) => typeof x === 'string'));
+        const raw = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
+        const out = new Map();
+        if (Array.isArray(raw)) {
+            // legacy v1: bare realpath array, never-re-deliver semantics
+            for (const x of raw)
+                if (typeof x === 'string')
+                    out.set(x, CONTENT_RANK);
+            return out;
+        }
+        if (raw !== null && typeof raw === 'object') {
+            const docs = raw.docs;
+            if (docs !== null && typeof docs === 'object' && !Array.isArray(docs)) {
+                for (const [real, rank] of Object.entries(docs)) {
+                    if (typeof rank === 'number' && rank >= 1 && rank <= CONTENT_RANK)
+                        out.set(real, rank);
+                }
+            }
+        }
+        return out;
     }
     catch {
-        return new Set();
+        return new Map();
     }
 }
-/** Persist a node's on-read dedup set. Called after each read that surfaced a
- *  new doc, so the grown set survives a later dormancy. */
+/** Persist a node's dedup map. Called after each delivery that grew it, so
+ *  the grown map survives a later dormancy. */
 export function saveInjectedDocs(nodeId, seen) {
     try {
-        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...seen]));
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify({ v: 2, docs: Object.fromEntries(seen) }));
     }
     catch {
         // best-effort — a failed persist only risks a re-inject, never a crash
     }
 }
-/** Drop a node's persisted dedup set. Called by the launch paths that start a
+/** Drop a node's persisted dedup map. Called by the launch paths that start a
  *  FRESH transcript, so the new conversation surfaces docs from scratch. */
 export function clearInjectedDocs(nodeId) {
     cache.delete(nodeId);

package/dist/core/substrate/listings.d.ts

@@ -0,0 +1,21 @@
+import type { MemoryDoc } from '../memory-resolver.js';
+import { type InjectedDocs } from './injected-store.js';
+/** Dedup key for a whole directory's listing. Realpath keys start with `/`,
+ *  so the scheme prefix never collides with a doc entry. */
+export declare function dirDedupKey(dir: string): string;
+/** First-occurrence-wins name map over a precedence-ordered corpus: the doc
+ *  that renders a name's line is the doc a read of that name would return. */
+export declare function docsByName(corpus: readonly MemoryDoc[]): Map<string, MemoryDoc>;
+/** Is `name` a directory in the merged name tree — i.e. does any doc live
+ *  beneath it? The corpus root ('') is never a directory here: store roots
+ *  merge into the whole catalog, which `memory list` owns. */
+export declare function isDirName(byName: ReadonlyMap<string, MemoryDoc>, name: string): boolean;
+/** The dirs a doc read discloses: the doc's own directory, then each ancestor
+ *  walking up, the root excluded. `a/b/c` → `['a/b', 'a']`. */
+export declare function ancestorDirsOf(name: string): string[];
+/** Render one directory's listing lines: `[[name]]: <when-and-why>` per
+ *  member doc (bare `[[name]]` when the doc carries no routing line), a bare
+ *  `[[name]]` per subdirectory. `unlisted` members are omitted always;
+ *  `filterDelivered` additionally drops members already delivered at preview
+ *  rank or higher. Rendered members record at preview rank into `seen`. */
+export declare function renderDirListing(byName: ReadonlyMap<string, MemoryDoc>, dir: string, seen: InjectedDocs | null, filterDelivered: boolean): string[];

package/dist/core/substrate/listings.js

@@ -0,0 +1,88 @@
+// listings.ts — system-owned directory listings over the merged name tree.
+//
+// Reading a doc discloses where it sits: `ls` semantics over the corpus
+// namespace (directories merge across stores), consulting no frontmatter
+// except `unlisted`. A listing renders one when-and-why line per member doc
+// and one bare name per subdirectory — never recursive contents, never gates.
+//
+// Two render modes share one function. An EXPLICIT directory read (`crtr
+// memory read <dir>`) is a deliberate act, so every line renders (unlisted
+// excluded) — mirroring how an explicit doc read always returns content. The
+// AUTOMATIC neighborhood listings a doc read prepends are unsolicited, so
+// each member line dedup-filters against the transcript set and whole
+// directories dedup under a synthetic `dir://<name>` key (a name-tree
+// directory spans stores, so no single physical realpath identifies it).
+// Either mode records rendered member docs at preview rank — a listing line
+// IS a preview-rank render — when a dedup map is supplied.
+import { realpathOrSelf } from '../fs-utils.js';
+import { parseSubstrateDoc, previewLine } from './schema.js';
+import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
+/** Dedup key for a whole directory's listing. Realpath keys start with `/`,
+ *  so the scheme prefix never collides with a doc entry. */
+export function dirDedupKey(dir) {
+    return `dir://${dir}`;
+}
+/** First-occurrence-wins name map over a precedence-ordered corpus: the doc
+ *  that renders a name's line is the doc a read of that name would return. */
+export function docsByName(corpus) {
+    const byName = new Map();
+    for (const d of corpus)
+        if (!byName.has(d.name))
+            byName.set(d.name, d);
+    return byName;
+}
+/** Is `name` a directory in the merged name tree — i.e. does any doc live
+ *  beneath it? The corpus root ('') is never a directory here: store roots
+ *  merge into the whole catalog, which `memory list` owns. */
+export function isDirName(byName, name) {
+    if (name === '')
+        return false;
+    const prefix = name + '/';
+    for (const n of byName.keys())
+        if (n.startsWith(prefix))
+            return true;
+    return false;
+}
+/** The dirs a doc read discloses: the doc's own directory, then each ancestor
+ *  walking up, the root excluded. `a/b/c` → `['a/b', 'a']`. */
+export function ancestorDirsOf(name) {
+    const dirs = [];
+    const segs = name.split('/');
+    for (let i = segs.length - 1; i >= 1; i--)
+        dirs.push(segs.slice(0, i).join('/'));
+    return dirs;
+}
+/** Render one directory's listing lines: `[[name]]: <when-and-why>` per
+ *  member doc (bare `[[name]]` when the doc carries no routing line), a bare
+ *  `[[name]]` per subdirectory. `unlisted` members are omitted always;
+ *  `filterDelivered` additionally drops members already delivered at preview
+ *  rank or higher. Rendered members record at preview rank into `seen`. */
+export function renderDirListing(byName, dir, seen, filterDelivered) {
+    const prefix = dir + '/';
+    const memberLines = new Map();
+    const subdirs = new Set();
+    for (const [name, doc] of byName) {
+        if (!name.startsWith(prefix))
+            continue;
+        const rest = name.slice(prefix.length);
+        const slash = rest.indexOf('/');
+        if (slash >= 0) {
+            subdirs.add(rest.slice(0, slash));
+            continue;
+        }
+        const sub = parseSubstrateDoc(doc);
+        if (sub?.unlisted)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (filterDelivered && seen !== null && deliveredAtOrAbove(seen, real, 'preview'))
+            continue;
+        const line = sub === null ? '' : previewLine(sub);
+        memberLines.set(rest, line === '' ? `[[${name}]]` : `[[${name}]]: ${line}`);
+        if (seen !== null)
+            recordDelivery(seen, real, 'preview');
+    }
+    return [
+        ...[...memberLines.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, l]) => l),
+        ...[...subdirs].sort((a, b) => a.localeCompare(b)).map((s) => `[[${prefix}${s}]]`),
+    ];
+}

package/dist/core/substrate/on-read-node.d.ts

@@ -1,9 +1,9 @@
+import type { InjectedDocs } from './injected-store.js';
 /** Surface docs matched by a successful read tool call. An unknown node id or
  *  an unreadable canvas renders nothing. */
-export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: Set<string>): string;
+export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: InjectedDocs): string;
 /** Surface workspace-wide docs during first-message assembly, using the node's
- *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile” (and, on the
- *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  recorded cwd and selected profile: docs in mounted project stores carrying
+ *  a `workspace-open` surfaces entry deliver here. `seen` is the
  *  transcript-scoped dedup set shared with the on-read hook. */
-export declare function renderWorkspaceOpenDocs(nodeId: string, seen?: Set<string>): string;
+export declare function renderWorkspaceOpenDocs(nodeId: string, seen?: InjectedDocs): string;

package/dist/core/substrate/on-read-node.js

@@ -8,7 +8,7 @@ import { assembleNodeSubject } from './subject.js';
 import { renderOnReadDocsForSubject, renderWorkspaceOpenDocsForSubject } from './on-read.js';
 /** Surface docs matched by a successful read tool call. An unknown node id or
  *  an unreadable canvas renders nothing. */
-export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
+export function renderOnReadDocs(nodeId, readFilePath, seen = new Map()) {
     let subject;
     try {
         subject = assembleNodeSubject(nodeId);
@@ -21,11 +21,10 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     return renderOnReadDocsForSubject(subject, readFilePath, seen);
 }
 /** Surface workspace-wide docs during first-message assembly, using the node's
- *  recorded cwd and selected profile. `.` is a reserved applies-to target
- *  meaning “when this project store is mounted by cwd/profile” (and, on the
- *  read event, “a file under the store's owning dir was read”). `seen` is the
+ *  recorded cwd and selected profile: docs in mounted project stores carrying
+ *  a `workspace-open` surfaces entry deliver here. `seen` is the
  *  transcript-scoped dedup set shared with the on-read hook. */
-export function renderWorkspaceOpenDocs(nodeId, seen = new Set()) {
+export function renderWorkspaceOpenDocs(nodeId, seen = new Map()) {
     try {
         const subject = assembleNodeSubject(nodeId);
         const node = getNode(nodeId);

package/dist/core/substrate/on-read.d.ts

@@ -1,9 +1,30 @@
+import { type InjectedDocs } from './injected-store.js';
+import { type Rung, type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: Set<string>): string;
+/** Render candidates at their matched rungs, gate-checked and deduped against
+ *  the transcript set (higher rungs pierce lower; a delivery records at its
+ *  rendered rung). A `null` subject means no node identity is available for
+ *  gate evaluation: gated docs are skipped, ungated docs still deliver. */
+export declare function renderCandidateBlocks(subject: NodeConfigSubject | null, candidates: Array<{
+    doc: SubstrateDoc;
+    rung: Rung;
+}>, seen: InjectedDocs): string[];
+/** Surface docs whose `read` entries match a successfully read file, using
+ * the caller-supplied daemon snapshot subject. */
+export declare function renderOnReadDocsForSubject(subject: NodeConfigSubject, readFilePath: string, seen?: InjectedDocs): string;
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
  * beneath its store. */
-export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: Set<string>): string;
+export declare function renderWorkspaceOpenDocsForSubject(subject: NodeConfigSubject, cwd: string, profileId: string | null, seen?: InjectedDocs): string;
+/** Inner `<memory>` blocks for the memory-read event: docs whose
+ * `memory-read` entries match the doc a `crtr memory read` just resolved
+ * (known by `targetNames`; `excludeRealpath` keeps the resolved doc from
+ * delivering itself). Returns unwrapped blocks — the read leaf composes one
+ * `<auto-loaded-context>` envelope from these plus the directory listings. */
+export declare function memoryReadDocBlocks(subject: NodeConfigSubject | null, excludeRealpath: string, targetNames: string[], seen: InjectedDocs): string[];
+/** Surface docs whose `command` entries match an executed bash command
+ * string. The corpus is the resolved cwd/profile set only — a command has no
+ * file to walk enclosing stores from. `seen` is the same transcript-scoped
+ * dedup set as the other channels. */
+export declare function renderOnCommandDocsForSubject(subject: NodeConfigSubject, command: string, seen?: InjectedDocs): string;