@north-light/crouter 0.3.154

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

@@ -0,0 +1,20 @@
+import { type Rung, type SubstrateDoc } from './schema.js';
+/** The reserved basename (no extension) that marks a directory's index doc. */
+export declare const INDEX_NAME = "INDEX";
+/** Does this path-derived name denote a directory INDEX (`taste/INDEX`, or a
+ *  top-level `INDEX`)? */
+export declare function isIndexName(name: string): boolean;
+/** The directory an INDEX doc represents: `taste/INDEX` → `taste`, `INDEX` → ''. */
+export declare function indexDirOf(name: string): string;
+/** Returns the display path corresponding to a canonical logical identifier. */
+export declare function displayName(name: string): string;
+/** The two visibility surfaces an INDEX can cap. */
+export type Surface = 'systemPromptVisibility' | 'fileReadVisibility';
+/** Build the dir → governing-INDEX map. Precedence is first-occurrence-wins, so
+ *  callers MUST pass docs precedence-ordered (project > user > builtin) — the
+ *  highest-precedence INDEX governs a dir, mirroring the memory resolver. */
+export declare function buildCeilingIndex(docs: SubstrateDoc[]): Map<string, SubstrateDoc>;
+/** A doc's effective rung on `surface` after applying every ancestor INDEX
+ *  ceiling: min(own rung, each ancestor INDEX's rung). A `none` ancestor INDEX
+ *  hides the whole subtree (min with none = none). */
+export declare function effectiveRung(doc: SubstrateDoc, ceil: Map<string, SubstrateDoc>, surface: Surface): Rung;

package/dist/core/substrate/ceiling.js

@@ -0,0 +1,69 @@
+// ceiling.ts — canonical INDEX identifiers and the subtree rung ceiling.
+//
+// A directory index has the canonical logical identifier `<directory>/INDEX`
+// (`INDEX` at the root) and the same substrate frontmatter as any doc. Its rung
+// is a ceiling for every document in its subtree.
+//
+//   effective rung of a descendant = min(own rung, every ancestor INDEX's rung)
+//
+// So a directory's INDEX at `preview` lets its files surface at most at
+// `preview`; an INDEX at `none` hides the whole subtree. This is the single,
+// explicit mechanism for collapsing a directory in agent-facing surfaces (boot
+// render + on-read) — there is no parallel auto-hiding heuristic. See design
+// taste: `crtr memory read taste/document-substrate`.
+import { rungRank } from './schema.js';
+/** The reserved basename (no extension) that marks a directory's index doc. */
+export const INDEX_NAME = 'INDEX';
+/** Does this path-derived name denote a directory INDEX (`taste/INDEX`, or a
+ *  top-level `INDEX`)? */
+export function isIndexName(name) {
+    return name === INDEX_NAME || name.endsWith('/' + INDEX_NAME);
+}
+/** The directory an INDEX doc represents: `taste/INDEX` → `taste`, `INDEX` → ''. */
+export function indexDirOf(name) {
+    return name === INDEX_NAME ? '' : name.slice(0, name.length - INDEX_NAME.length - 1);
+}
+/** Returns the display path corresponding to a canonical logical identifier. */
+export function displayName(name) {
+    return isIndexName(name) ? indexDirOf(name) : name;
+}
+/** Build the dir → governing-INDEX map. Precedence is first-occurrence-wins, so
+ *  callers MUST pass docs precedence-ordered (project > user > builtin) — the
+ *  highest-precedence INDEX governs a dir, mirroring the memory resolver. */
+export function buildCeilingIndex(docs) {
+    const m = new Map();
+    for (const d of docs) {
+        if (!isIndexName(d.name))
+            continue;
+        const dir = indexDirOf(d.name);
+        if (!m.has(dir))
+            m.set(dir, d);
+    }
+    return m;
+}
+function minRung(a, b) {
+    return rungRank(a) <= rungRank(b) ? a : b;
+}
+/** Ancestor directory names of a doc, nearest-last: `a/b/c` → [`a/b`, `a`];
+ *  `a` → []. An INDEX doc's OWN dir is included (a self-cap is a no-op), so a
+ *  nested INDEX still inherits its parents' ceilings. */
+function ancestorDirs(name) {
+    const parts = name.split('/');
+    parts.pop(); // drop the leaf
+    const out = [];
+    for (let i = parts.length; i > 0; i--)
+        out.push(parts.slice(0, i).join('/'));
+    return out;
+}
+/** A doc's effective rung on `surface` after applying every ancestor INDEX
+ *  ceiling: min(own rung, each ancestor INDEX's rung). A `none` ancestor INDEX
+ *  hides the whole subtree (min with none = none). */
+export function effectiveRung(doc, ceil, surface) {
+    let rung = doc[surface];
+    for (const dir of ancestorDirs(doc.name)) {
+        const idx = ceil.get(dir);
+        if (idx)
+            rung = minRung(rung, idx[surface]);
+    }
+    return rung;
+}

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

@@ -0,0 +1,13 @@
+import type { SubstrateDoc } from './schema.js';
+import type { NodeConfigSubject } from './subject.js';
+/** Does `doc` pass its gate for `subject`?
+ *
+ *  - No gate (field absent) ⇒ `true`: always eligible (the common case).
+ *  - A gate present ⇒ the matcher engine's verdict. An empty `gate: {}` is inert
+ *    and returns `false` (never matches) per design §4 — so an author cannot
+ *    write an always-eligible-via-empty-predicate doc.
+ *
+ *  Eligibility only. A failing gate excludes the doc from BOTH automatic hooks
+ *  for this node; it remains findable by `crtr memory find` (search ignores
+ *  gate + rung). */
+export declare function gatePasses(doc: SubstrateDoc, subject: NodeConfigSubject): boolean;

package/dist/core/substrate/gate.js

@@ -0,0 +1,21 @@
+// gate.ts — gate evaluation. A document's optional `gate` predicate decides
+// whether it is ELIGIBLE to surface at all for a given node (orthogonal to the
+// rung, which decides how much). See design-substrate.md §4 + §6. Pure function
+// over (parsed doc, assembled subject); the matcher engine in predicate.ts does
+// the actual matching — we do NOT reimplement it here.
+import { evalCondition } from '../predicate.js';
+/** Does `doc` pass its gate for `subject`?
+ *
+ *  - No gate (field absent) ⇒ `true`: always eligible (the common case).
+ *  - A gate present ⇒ the matcher engine's verdict. An empty `gate: {}` is inert
+ *    and returns `false` (never matches) per design §4 — so an author cannot
+ *    write an always-eligible-via-empty-predicate doc.
+ *
+ *  Eligibility only. A failing gate excludes the doc from BOTH automatic hooks
+ *  for this node; it remains findable by `crtr memory find` (search ignores
+ *  gate + rung). */
+export function gatePasses(doc, subject) {
+    if (doc.gate === undefined)
+        return true;
+    return evalCondition(doc.gate, subject);
+}

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

@@ -0,0 +1,11 @@
+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 { 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, effectiveRung, } from './ceiling.js';
+export type { Surface } from './ceiling.js';
+export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
+export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -0,0 +1,25 @@
+// substrate/ — the unified document-substrate keystone: the frontmatter schema,
+// the 4-rung visibility ladder, the node-config subject assembly, and gate
+// evaluation. Pure + well-typed; the shared base the CLI verbs, boot render,
+// on-read render, and migrator all build on. See design-substrate.md §4 +
+// plan-substrate.md §2.
+export { 
+// kinds
+KINDS, isDocKind, 
+// ladder
+RUNGS, rungRank, rungAtLeast, 
+// fallback floor
+FALLBACK_RUNG, 
+// parse + render-shared helpers
+parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, 
+// display-name normalization
+normalizeNameSegment, normalizeDocName, 
+// substrate identity (explicit-name-then-path-fallback)
+resolveDocName, } from './schema.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, effectiveRung, } from './ceiling.js';
+export { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock } from './render-node.js';
+export { renderOnReadDocs } from './on-read.js';

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

@@ -0,0 +1,10 @@
+/** 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
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export declare function clearInjectedDocs(nodeId: string): void;

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

@@ -0,0 +1,55 @@
+// injected-store.ts — durable per-node dedup set for on-read doc injection.
+//
+// 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.
+//
+// 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.
+//
+// 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';
+/** 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 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'));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** 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 function saveInjectedDocs(nodeId, seen) {
+    try {
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...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
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export function clearInjectedDocs(nodeId) {
+    try {
+        rmSync(injectedDocsPath(nodeId), { force: true });
+    }
+    catch {
+        // ignore — absence is the desired state anyway
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Render the substrate docs that should surface alongside a just-read file.
+ *
+ * @param nodeId        the canvas node whose subject gates the docs.
+ * @param readFilePath  the path the `read` tool returned (absolute or not — it
+ *                      is resolved to a realpath internally).
+ * @param seen          the CALLER-owned, per-session set of already-injected
+ *                      doc realpaths. Docs already present are skipped; newly
+ *                      injected docs are added. Pass the same set across reads
+ *                      within a session (clear it on session_start) to get the
+ *                      once-per-session dedup; omit it for a standalone render.
+ * @returns the `<auto-loaded-context>` envelope, or '' when nothing surfaces.
+ */
+export declare function renderOnReadDocs(nodeId: string, readFilePath: string, seen?: Set<string>): string;

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

@@ -0,0 +1,404 @@
+// on-read.ts — the file-read-visibility render for the document substrate.
+//
+// When a `read` tool call returns, the canvas-doc-substrate pi extension calls
+// renderOnReadDocs() to surface the substrate docs that should appear ALONGSIDE
+// the file just read — each at its FILE-READ-VISIBILITY rung (NOT the
+// system-prompt rung the boot render uses). Three triggers decide which docs
+// surface (design §4/§6; Stream A native rules):
+//
+//   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
+//     ancestor PROJECT `.crouter/memory/` surfaces (a doc surfaces when a file
+//     beside/under its own project scope dir is read), UNLESS it carries an
+//     explicit read-trigger (see D5 below). This is the substrate's own
+//     ancestor walk keyed on `.crouter/memory/` — project guidance that starts
+//     in CLAUDE.md/AGENTS.md or `.claude/rules` now lives here after
+//     `crtr sys sync project-guidance` migrates it. The user-global
+//     `~/.crouter/memory/` store is NOT positional; user docs only fire on
+//     reads through explicit `applies-to` / `read-when` triggers.
+//   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
+//     whose `appliesTo` glob matches the read file path surfaces, regardless of
+//     where the read file sits relative to the doc.
+//   • read-when FRONTMATTER (Stream A) — any RESOLVED doc whose `readWhen`
+//     condition matches the READ FILE's own parsed frontmatter (markdown only),
+//     via `evalCondition` against that YAML rather than the node subject.
+//
+// D5 — an EXPLICIT read-trigger (applies-to OR read-when) SUPPRESSES the
+// positional default for that doc: an author who declared a trigger meant it, so
+// the doc fires only on its trigger, never positionally on every read under its
+// scope. The two explicit triggers compose by OR.
+//
+// D6 — an explicitly-triggered doc also PIERCES the INDEX ceiling: it surfaces at
+// its OWN fileReadVisibility, not min(own, ancestor INDEX rungs). The ceiling is
+// the mechanism for collapsing a subtree's BOOT + POSITIONAL on-read surface; a
+// cross-cutting applies-to/read-when trigger is the author deliberately opting
+// ONE doc into surfacing when a specific file is read, so a `none`-capped
+// ancestor INDEX (the default for a reference plugin pulled by name) must not
+// veto it. Same stance as D5 — the explicit trigger is the more specific signal.
+//
+// Each candidate runs the substrate pipeline at its fileReadVisibility rung:
+//   parse → gatePasses(doc, assembleNodeSubject(nodeId)) → render
+//   (content → body, preview → previewLine, name → bare tag, none → skip).
+// The result is the faithful envelope (verdict n1):
+//   <auto-loaded-context>
+//   <memory kind="…" name="…" src="…">…body/preview…</memory>
+//   </auto-loaded-context>
+// Returns '' when nothing surfaces.
+//
+// Pure + defensive: reads disk + the resolver + canvas-db subject assembly; no
+// writes, no side effects. Every disk/parse/glob step is wrapped so one bad doc
+// can never throw the whole render (the extension is additionally inert on
+// error). The CALLER owns the per-session `seen` realpath set (cleared on
+// session_start) and threads it in, so a given doc is injected at most once per
+// session across repeated reads.
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, matchesGlob, parse, relative, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { evalCondition } from '../predicate.js';
+import { listAllMemoryDocs } from '../memory-resolver.js';
+import { userScopeRoot } from '../scope.js';
+import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
+import { cachedSubstrateDocs } from './session-cache.js';
+// Ancestor dirs we never look inside for a `.crouter/memory/` store (the read
+// file may live under a build/dependency tree; `.crouter` is NOT junk here — it
+// is the segment we explicitly join onto each surviving ancestor).
+const JUNK_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', '.yalc']);
+// ---------------------------------------------------------------------------
+// Small path helpers (mirror the on-read precedent established by
+// frontmatter-rules so the injected envelope keeps the faithful substrate
+// shape).
+// ---------------------------------------------------------------------------
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Escape a value for an XML-ish attribute in the injected envelope. */
+function attr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+/** Nearest enclosing git repo root for a path (walk up looking for `.git`). */
+function gitRootOf(p) {
+    let d = p;
+    const root = parse(d).root;
+    while (true) {
+        if (pathExists(join(d, '.git')))
+            return d;
+        if (d === root)
+            return null;
+        const parent = dirname(d);
+        if (parent === d)
+            return null;
+        d = parent;
+    }
+}
+/** Display a path relative to its nearest git repo root, else absolute. */
+function disp(p) {
+    const root = gitRootOf(p);
+    if (!root)
+        return p;
+    const rel = relative(root, p);
+    return rel === '' ? '.' : rel;
+}
+function isJunkAncestor(dir) {
+    return dir.split(sep).some((seg) => JUNK_DIRS.has(seg));
+}
+/** Load one positionally-discovered `.crouter/memory/` file into a SubstrateDoc,
+ *  or null when it is not a substrate doc / unreadable. `scope` is cosmetic here
+ *  (gate eval keys off the NODE subject, render off name/body/rung). */
+function loadPositionalDoc(file, memDir, scope) {
+    try {
+        const raw = relative(memDir, file)
+            .replace(/\.md$/i, '')
+            .split(sep)
+            .join('/');
+        const fallbackName = normalizeDocName(raw);
+        if (fallbackName === '')
+            return null;
+        const { data, body } = parseFrontmatterGeneric(readText(file));
+        const schema = parseSubstrateFrontmatter(data);
+        if (schema === null)
+            return null;
+        // ONE substrate-identity rule (schema.ts's resolveDocName), shared with the
+        // resolver's loadMemoryDoc: an explicit frontmatter `name` wins over the
+        // path-derived fallback, so a positionally-discovered doc surfaces on-read
+        // under the SAME identity the boot resolver would give it.
+        const name = resolveDocName(data, fallbackName);
+        return { ...schema, name, scope, path: file, body };
+    }
+    catch {
+        return null;
+    }
+}
+function safeWalkMd(dir) {
+    try {
+        return walkFiles(dir, (n) => n.toLowerCase().endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Does the doc declare an EXPLICIT read-trigger? (applies-to glob OR read-when
+ *  frontmatter condition). D5: an explicit trigger SUPPRESSES the positional
+ *  default — such a doc fires only on its declared trigger, never positionally. */
+function hasExplicitTrigger(doc) {
+    return (doc.appliesTo !== undefined && doc.appliesTo.length > 0) || doc.readWhen !== undefined;
+}
+/** POSITIONAL trigger: every substrate doc in an ancestor PROJECT dir's
+ *  `.crouter/memory/`, walking from the read file up to $HOME (or the
+ *  filesystem root for a read outside $HOME), skipping junk ancestors. The
+ *  user-global `~/.crouter/memory/` store is deliberately skipped: otherwise
+ *  every file read under $HOME would surface unrelated user-wide preferences.
+ *
+ *  The crouter home (`~/.crouter`, the user scope root) is skipped for the same
+ *  reason it is never a project scope root (scope.ts's `isProjectScopeDir`): it
+ *  is the user scope, not a project ancestor. Without this fence, reading any
+ *  canvas runtime artifact (`~/.crouter/canvas/nodes/.../reports|context/...`)
+ *  walks up THROUGH `~/.crouter` and would inject whatever lives at
+ *  `~/.crouter/.crouter/memory/` — e.g. a differently-scoped node whose cwd
+ *  resolved its project store there — leaking one node's private memory into
+ *  every unrelated node that reads a canvas file. */
+function positionalCandidates(absReadFile) {
+    const out = [];
+    const seenDocPaths = new Set();
+    const home = realpathOrSelf(homedir());
+    const userRoot = realpathOrSelf(userScopeRoot());
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    let depth = 0;
+    while (true) {
+        if (dir !== home && dir !== userRoot && !isJunkAncestor(dir)) {
+            const memDir = join(dir, CRTR_DIR_NAME, 'memory');
+            if (pathExists(memDir)) {
+                for (const file of safeWalkMd(memDir)) {
+                    const real = realpathOrSelf(file);
+                    if (seenDocPaths.has(real))
+                        continue;
+                    seenDocPaths.add(real);
+                    const doc = loadPositionalDoc(file, memDir, 'project');
+                    // D5: a doc with an explicit read-trigger (applies-to/read-when) does
+                    // NOT fire positionally — it surfaces only via that trigger.
+                    if (doc && !hasExplicitTrigger(doc))
+                        out.push({ doc, realpath: real, order: depth, explicit: false });
+                }
+            }
+        }
+        if (dir === home || dir === fsRoot)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        depth += 1;
+    }
+    return out;
+}
+/** The user/project scope root that owns a resolved doc: `<root>/.crouter/memory/…`
+ *  → `<root>`. Builtin docs (no `.crouter` segment) return null. Used to test an
+ *  `appliesTo` glob against a read path RELATIVE to the doc's own project root. */
+function owningRootOf(doc) {
+    const parts = doc.path.split(sep);
+    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
+    if (idx <= 0)
+        return null;
+    return parts.slice(0, idx).join(sep) || sep;
+}
+function globMatches(glob, absReadFile, owningRoot) {
+    const targets = [absReadFile, basename(absReadFile)];
+    if (owningRoot)
+        targets.push(relative(owningRoot, absReadFile));
+    return targets.some((t) => {
+        try {
+            return matchesGlob(t, glob);
+        }
+        catch {
+            return false; // an invalid glob never matches
+        }
+    });
+}
+/** applies-to GLOB trigger: every RESOLVED substrate doc whose `appliesTo` glob
+ *  matches the read path. `taken` carries the realpaths already claimed by the
+ *  positional pass, so a doc found both ways is not double-counted.
+ *  Uses the per-session cache so the corpus is not re-walked+re-parsed on every
+ *  read tool call (O(reads × corpus) without the cache). */
+function appliesToCandidates(absReadFile, taken) {
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const doc of docs) {
+        const globs = doc.appliesTo;
+        if (!globs || globs.length === 0)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (taken.has(real))
+            continue;
+        if (!globs.some((g) => globMatches(g, absReadFile, owningRootOf(doc))))
+            continue;
+        taken.add(real);
+        out.push({ doc, realpath: real, order: -1, explicit: true });
+    }
+    return out;
+}
+/** Parse the READ FILE's own YAML frontmatter once (markdown only), the subject
+ *  a `read-when` condition is evaluated against. Non-markdown reads (and any
+ *  unreadable / frontmatter-less file) yield `{}` — no `read-when` rule can then
+ *  match (mirrors pi's frontmatter-rules, which only consider .md/.mdx/.markdown). */
+function readFileFrontmatter(absReadFile) {
+    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
+        return {};
+    try {
+        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** read-when FRONTMATTER trigger (Stream A): every RESOLVED substrate doc whose
+ *  `readWhen` condition matches the read file's own frontmatter. `taken` carries
+ *  the realpaths already claimed by earlier passes so a doc is not double-counted.
+ *  Uses the per-session cache (same corpus the glob pass walks). Returns [] when
+ *  the read file has no frontmatter — no condition can match an empty subject. */
+function readWhenCandidates(readFileFm, taken) {
+    if (Object.keys(readFileFm).length === 0)
+        return [];
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const doc of docs) {
+        if (doc.readWhen === undefined)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (taken.has(real))
+            continue;
+        if (!evalCondition(doc.readWhen, readFileFm))
+            continue;
+        taken.add(real);
+        out.push({ doc, realpath: real, order: -1, explicit: true });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Per-doc envelope render.
+// ---------------------------------------------------------------------------
+/** One memory as a `<memory …>` element at its fileReadVisibility rung, or null
+ *  when that rung is `none`. `content` → full body; `preview` → the routing
+ *  line; `name` → a bare self-closed tag (the `name=` attribute IS the surface). */
+function renderDocEnvelope(doc) {
+    const rung = doc.fileReadVisibility;
+    if (rung === 'none')
+        return null;
+    let body = '';
+    if (rung === 'content')
+        body = doc.body.trim();
+    else if (rung === 'preview')
+        body = previewLine(doc);
+    // 'name' → body stays '' (the tag's name attribute is the whole surface).
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" src="${attr(disp(doc.path))}"`;
+    return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
+}
+// ---------------------------------------------------------------------------
+// Public entry point.
+// ---------------------------------------------------------------------------
+/**
+ * Render the substrate docs that should surface alongside a just-read file.
+ *
+ * @param nodeId        the canvas node whose subject gates the docs.
+ * @param readFilePath  the path the `read` tool returned (absolute or not — it
+ *                      is resolved to a realpath internally).
+ * @param seen          the CALLER-owned, per-session set of already-injected
+ *                      doc realpaths. Docs already present are skipped; newly
+ *                      injected docs are added. Pass the same set across reads
+ *                      within a session (clear it on session_start) to get the
+ *                      once-per-session dedup; omit it for a standalone render.
+ * @returns the `<auto-loaded-context>` envelope, or '' when nothing surfaces.
+ */
+export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
+    let subject;
+    try {
+        subject = assembleNodeSubject(nodeId);
+    }
+    catch {
+        return '';
+    }
+    if (subject === null)
+        return '';
+    const absReadFile = realpathOrSelf(readFilePath);
+    let candidates;
+    try {
+        const positional = positionalCandidates(absReadFile);
+        const taken = new Set(positional.map((c) => c.realpath));
+        const byGlob = appliesToCandidates(absReadFile, taken);
+        const byReadWhen = readWhenCandidates(readFileFrontmatter(absReadFile), taken);
+        candidates = [...positional, ...byGlob, ...byReadWhen];
+    }
+    catch {
+        return '';
+    }
+    // Outermost-first: the nearest/most-specific doc reads last — closest to the
+    // file content that follows it (the applies-to set, order -1, trails).
+    candidates.sort((a, b) => b.order - a.order);
+    // INDEX ceiling: build the dir → governing-INDEX map over the whole resolved
+    // corpus PLUS the candidate docs, so a dir's INDEX caps (or `none`-hides) its
+    // subtree on-read exactly as it does at boot. The candidate's own
+    // fileReadVisibility and name are overridden by the effective rung / dir entry.
+    let ceil;
+    try {
+        const resolved = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+        ceil = buildCeilingIndex([...resolved, ...candidates.map((c) => c.doc)]);
+    }
+    catch {
+        ceil = buildCeilingIndex(candidates.map((c) => c.doc));
+    }
+    const rendered = [];
+    for (const c of candidates) {
+        // Never re-surface the doc the agent is literally reading.
+        if (c.realpath === absReadFile)
+            continue;
+        // Once-per-session dedup (caller-owned set).
+        if (seen.has(c.realpath))
+            continue;
+        let block;
+        try {
+            if (!gatePasses(c.doc, subject))
+                continue; // gated out for this node
+            // D6: an explicit applies-to/read-when trigger pierces the INDEX ceiling
+            // and renders at the doc's own rung; positional docs honor the ceiling.
+            const rung = c.explicit
+                ? c.doc.fileReadVisibility
+                : effectiveRung(c.doc, ceil, 'fileReadVisibility');
+            const doc = rung === c.doc.fileReadVisibility && displayName(c.doc.name) === c.doc.name
+                ? c.doc
+                : { ...c.doc, fileReadVisibility: rung, name: displayName(c.doc.name) };
+            block = renderDocEnvelope(doc);
+        }
+        catch {
+            continue; // a single bad doc never breaks the read
+        }
+        if (block === null)
+            continue; // fileReadVisibility 'none' — not a read surface
+        seen.add(c.realpath); // mark injected only once it actually surfaces
+        rendered.push(block);
+    }
+    if (rendered.length === 0)
+        return '';
+    return `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
+}

package/dist/core/substrate/render-node.d.ts

@@ -0,0 +1,11 @@
+/** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
+ *  the node's subject from the canvas-db, render the pure block, then swap the
+ *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
+ *  so agents don't paste it into the non-expanding Write tool (see
+ *  interpolateNodePaths). A null subject (unknown id) still renders the
+ *  always-present memory-usage guidance frame. */
+export declare function renderPreferencesSection(nodeId: string): string;
+/** The first-message `<memory kind="knowledge">` block for `nodeId`: assemble
+ *  the node's subject from the canvas-db and render the consultable catalog.
+ *  Returns '' for an unknown id or when nothing is eligible. */
+export declare function renderKnowledgeBlock(nodeId: string): string;