@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/runtime/tmux.js

@@ -191,6 +191,39 @@ export function paneExists(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}']);
     return r.ok && r.stdout === pane;
 }
+/** Every live pane id on the server (`list-panes -a`), as a Set for membership
+ *  probes. Returns null when tmux is unreachable (no server / transient failure)
+ *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
+ *  never mass-delete, on a failed probe. One subprocess call total, so batch
+ *  liveness sweeps (e.g. the daemon's stale-focus GC) don't pay a per-pane
+ *  display-message each. */
+export function listLivePanes() {
+    const r = tmux(['list-panes', '-a', '-F', '#{pane_id}']);
+    if (!r.ok)
+        return null;
+    return new Set(r.stdout.split('\n').filter((p) => p !== ''));
+}
+/** The working directory of a pane (`display-message -p -t <pane>
+ *  '#{pane_current_path}'`). Used to preserve a view monitor's cwd across a
+ *  view-cycle respawn so project-scoped views still resolve. Null if tmux fails. */
+export function paneCurrentPath(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_current_path}']);
+    return r.ok && r.stdout !== '' ? r.stdout : null;
+}
+/** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
+ *  Used to tag a pane with the view id it currently hosts (`@crtr_view`) so the
+ *  view-nav cycle can read it back and switch to the next/prev view in place.
+ *  Best-effort; never throws. */
+export function setPaneOption(pane, name, value) {
+    return tmux(['set-option', '-p', '-t', pane, name, value]).ok;
+}
+/** Read a PANE-scoped tmux option value (`tmux show-options -p -t <pane> -q -v
+ *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
+ *  error so an unset option yields an empty string. undefined if tmux fails. */
+export function getPaneOption(pane, name) {
+    const r = tmux(['show-options', '-p', '-t', pane, '-q', '-v', name]);
+    return r.ok ? r.stdout : undefined;
+}
 /** Relocate a pane into another session as its own window WITHOUT killing the
  *  process in it — `break-pane -d` moves the pane out of its current window (the
  *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
@@ -375,12 +408,13 @@ export function installMenuBinding() {
         // a whole-canvas picker (incl. dormant nodes) and revives the choice via
         // `crtr node focus` — the only sync-safe open (routes through reviveNode).
         { name: 'resume node', key: 'r', cmd: `send-keys -t '#{pane_id}' '/resume-node' Enter` },
-        // `d` demotes the agent to TERMINAL in place: no finalize, no kill — it keeps
-        // running where it is, and because it is now terminal it is forced to push a
-        // final up the spine when it finishes. `D` ALSO detaches it to the background
-        // `crtr` session (frees the pane; the pi keeps generating). Neither ends it.
-        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' >/dev/null 2>&1"` },
-        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node lifecycle terminal --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
+        // `d` runs `node demote`: flip the agent to TERMINAL in place — no finalize,
+        // no kill — it keeps running where it is, and because it is now terminal it
+        // is forced to push a final up the spine when it finishes. `D` runs `node
+        // demote --detach`, which ALSO detaches it to the background `crtr` session
+        // (frees the pane; the pi keeps generating). Neither ends it.
+        { name: 'demote to terminal', key: 'd', cmd: `run-shell "crtr node demote --pane '#{pane_id}' >/dev/null 2>&1"` },
+        { name: 'detach to background', key: 'D', cmd: `run-shell "crtr node demote --pane '#{pane_id}' --detach >/dev/null 2>&1"` },
         // Close cascades down the subscribes_to spine (kills the subtree's windows,
         // marks them canceled); revivable. Output discarded — the keypress just acts.
         { name: 'close agent + subtree', key: 'x', cmd: `run-shell "crtr node close --pane '#{pane_id}' >/dev/null 2>&1"` },
@@ -455,3 +489,43 @@ export function installNavBindings() {
     ]).ok;
     return next && prev;
 }
+// ---------------------------------------------------------------------------
+// View-nav bindings — Alt+V then ] / [ cycle the view hosted in a MONITOR pane
+// to the next/prev available view, in place. A VIEW-PREFIXED CHORD, not a bare
+// Alt pair: Alt+V switches into a private one-shot `crtr-view` key table, then
+// ] (next) / [ (prev) fire the cycle — mirroring node cycle's bracket DIRECTION
+// grammar (Alt+] next / Alt+[ prev) while NAMESPACING the brackets so they can
+// never shadow root bindings. This is collision-proof: only ONE root key (M-v)
+// is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
+// and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
+// private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
+// dogs installNavBindings' Alt+[. Each key shells `crtr view cycle`, passing the
+// active pane; cycle reads the pane's @crtr_view tag and respawns it on the
+// next/prev view. Output discarded so the keypress never pops a results view.
+// Installed at root boot alongside the node nav + Alt+C menu.
+//
+// NOTE: `M-v` is a GLOBAL root binding — it intercepts Alt+V in every pane/app
+// (e.g. swallowed from the pi editor), the same tradeoff crtr already takes for
+// M-c / M-] / M-[. Intended: crtr owns a small set of Alt chords server-wide.
+// ---------------------------------------------------------------------------
+/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
+ *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
+ *  Best-effort; false if any of the three binds fail. Deliberately distinct from
+ *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
+ *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
+ *  view monitors. The bracket keys are bound in the private table, so they NEVER
+ *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
+export function installViewNavBindings() {
+    const enter = tmux([
+        'bind-key', '-n', 'M-v', 'switch-client', '-T', 'crtr-view',
+    ]).ok;
+    const next = tmux([
+        'bind-key', '-T', 'crtr-view', ']', 'run-shell',
+        `crtr view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    const prev = tmux([
+        'bind-key', '-T', 'crtr-view', '[', 'run-shell',
+        `crtr view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
+    ]).ok;
+    return enter && next && prev;
+}

package/dist/core/scope.d.ts

@@ -1,5 +1,7 @@
 import type { Scope } from '../types.js';
 export declare function builtinSkillsRoot(): string;
+export declare function builtinViewsRoot(): string;
+export declare function builtinMemoryRoot(): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
 export declare function projectScopeRoot(startDir?: string): string | null;
@@ -9,6 +11,15 @@ export declare function ensureProjectScopeRoot(startDir?: string): string;
 export declare function pluginsDir(scope: Scope): string | null;
 export declare function marketplacesDir(scope: Scope): string | null;
 export declare function scopeSkillsDir(scope: Scope): string | null;
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot, a sibling of
+ *  builtin-skills), NOT scopeRoot('builtin')/memory — mirroring viewsDir's
+ *  builtin handling. User and project memory live at scopeRoot(scope)/memory. */
+export declare function scopeMemoryDir(scope: Scope): string | null;
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+export declare function viewsDir(scope: Scope): string | null;
 export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
 export declare function listScopes(scopeArg: string | undefined): Scope[];
 export declare function resetScopeCache(): void;

package/dist/core/scope.js

@@ -12,6 +12,26 @@ export function builtinSkillsRoot() {
     const pkgDir = dirname(coreDir); // src/ or dist/
     return join(pkgDir, 'builtin-skills');
 }
+export function builtinViewsRoot() {
+    // Resolved relative to this file exactly like builtinSkillsRoot — sibling of
+    // builtin-skills: dist/core/scope.js → dist/builtin-views/ (src/ at dev time).
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-views');
+}
+export function builtinMemoryRoot() {
+    // The substrate's shipped built-in documents live in their OWN package dir,
+    // a sibling of builtin-skills — resolved relative to this file exactly like
+    // builtinSkillsRoot/builtinViewsRoot: dist/core/scope.js → dist/builtin-memory/
+    // (src/ at dev time). This is a HARD special case (design verdict m2): builtin
+    // memory is NOT scopeRoot('builtin')/memory, which would land under
+    // builtin-skills/ — builtin's scopeRoot is builtinSkillsRoot().
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-memory');
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
@@ -77,6 +97,25 @@ export function scopeSkillsDir(scope) {
     const root = scopeRoot(scope);
     return root ? join(root, 'skills') : null;
 }
+/** Where substrate memory documents live per scope. Builtin memory is the
+ *  special case — its own package dir (builtinMemoryRoot, a sibling of
+ *  builtin-skills), NOT scopeRoot('builtin')/memory — mirroring viewsDir's
+ *  builtin handling. User and project memory live at scopeRoot(scope)/memory. */
+export function scopeMemoryDir(scope) {
+    if (scope === 'builtin')
+        return builtinMemoryRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'memory') : null;
+}
+/** Where view definition dirs live per scope. Builtin views sit directly under
+ *  builtinViewsRoot() (no `views/` segment — they ARE the builtin views dir),
+ *  matching the loader's `<root>/<name>/view.mjs` resolution. */
+export function viewsDir(scope) {
+    if (scope === 'builtin')
+        return builtinViewsRoot();
+    const root = scope === 'user' ? userScopeRoot() : projectScopeRoot();
+    return root ? join(root, 'views') : null;
+}
 export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';

package/dist/core/spawn.d.ts

@@ -11,6 +11,11 @@ export declare function countPanesInCurrentWindow(): number;
  *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
  *  False outside tmux / on error. */
 export declare function paneAlive(pane: string): boolean;
+/** Resolve a tmux pane id to its `session:window_index` — the target form
+ *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
+ *  specify pane here"); only split-window -t takes a pane. null outside tmux /
+ *  on a bad pane id / on error / empty. */
+export declare function paneWindowTarget(pane: string): string | null;
 /** The active pane of the user's attached tmux client — where they are looking
  *  right now. `list-clients` first attached client, then its current pane. Used
  *  to surface a human prompt in the user's view when nothing in the asking

package/dist/core/spawn.js

@@ -41,6 +41,19 @@ export function paneAlive(pane) {
     });
     return r.status === 0 && r.stdout.trim() !== '';
 }
+/** Resolve a tmux pane id to its `session:window_index` — the target form
+ *  `new-window -t` accepts. tmux REJECTS a pane id for new-window ("can't
+ *  specify pane here"); only split-window -t takes a pane. null outside tmux /
+ *  on a bad pane id / on error / empty. */
+export function paneWindowTarget(pane) {
+    if (!isInTmux() || !/^%\d+$/.test(pane))
+        return null;
+    const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const t = r.stdout.trim();
+    return t !== '' ? t : null;
+}
 /** The active pane of the user's attached tmux client — where they are looking
  *  right now. `list-clients` first attached client, then its current pane. Used
  *  to surface a human prompt in the user's view when nothing in the asking
@@ -101,8 +114,13 @@ export function spawnAndDetach(opts) {
         if (opts.detached === true)
             splitArgs.push('-d'); // don't switch the client to it
         if (opts.targetPane !== undefined && opts.targetPane !== '') {
-            // -a = insert after target window; -t <pane> resolves to that pane's window.
-            splitArgs.push('-a', '-t', opts.targetPane);
+            // new-window -t REJECTS a pane id (tmux exits 1: "can't specify pane
+            // here") — only split-window -t accepts a pane. Resolve the target pane to
+            // its session:window first; -a then inserts the new window right after it.
+            // If the pane can't be resolved, fall back to no -t (tmux uses current).
+            const winTarget = paneWindowTarget(opts.targetPane);
+            if (winTarget !== null)
+                splitArgs.push('-a', '-t', winTarget);
         }
     }
     else {

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,7 @@
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, KIND_DEFAULT_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+export type { NodeConfigSubject } from './subject.js';
+export { gatePasses } from './gate.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -0,0 +1,18 @@
+// substrate/ — the unified document-substrate keystone: the frontmatter schema,
+// the 4-rung visibility ladder, the kind→default-rungs table, 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/§9 + plan-substrate.md §2.
+export { 
+// kinds
+KINDS, isDocKind, 
+// ladder
+RUNGS, rungRank, rungAtLeast, 
+// defaults
+KIND_DEFAULT_RUNGS, 
+// parse + render-shared helpers
+parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
+export { gatePasses } from './gate.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderOnReadDocs } from './on-read.js';

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,292 @@
+// 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). Two independent triggers decide
+// which docs surface (design §4/§6; plan-substrate.md track D1):
+//
+//   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
+//     ancestor's `.crouter/memory/` surfaces (a doc surfaces when a file
+//     beside/under its own scope dir is read). This mirrors nested-context's
+//     `.claude/rules` ancestor walk, but keyed on `.crouter/memory/`.
+//   • 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.
+//
+// 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 file="…">
+//   <doc kind="…" name="…" src="…" triggered-by="…">…body/preview…</doc>
+//   </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 { listAllMemoryDocs } from '../memory-resolver.js';
+import { assembleNodeSubject, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } 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 — nested-context /
+// frontmatter-rules — so the injected envelope matches their faithful 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 name = relative(memDir, file)
+            .replace(/\.md$/i, '')
+            .split(sep)
+            .join('/');
+        if (name === '')
+            return null;
+        const { data, body } = parseFrontmatterGeneric(readText(file));
+        const schema = parseSubstrateFrontmatter(data);
+        if (schema === null)
+            return null;
+        return { ...schema, name, scope, path: file, body };
+    }
+    catch {
+        return null;
+    }
+}
+function safeWalkMd(dir) {
+    try {
+        return walkFiles(dir, (n) => n.toLowerCase().endsWith('.md'));
+    }
+    catch {
+        return [];
+    }
+}
+/** POSITIONAL trigger: every substrate doc in an ancestor dir's
+ *  `.crouter/memory/`, walking from the read file up to $HOME (or the
+ *  filesystem root for a read outside $HOME), skipping junk ancestors. */
+function positionalCandidates(absReadFile) {
+    const out = [];
+    const seenDocPaths = new Set();
+    const home = homedir();
+    const fsRoot = parse(absReadFile).root;
+    let dir = dirname(absReadFile);
+    let depth = 0;
+    while (true) {
+        if (!isJunkAncestor(dir)) {
+            const memDir = join(dir, CRTR_DIR_NAME, 'memory');
+            if (pathExists(memDir)) {
+                const scope = dir === home ? 'user' : 'project';
+                for (const file of safeWalkMd(memDir)) {
+                    const real = realpathOrSelf(file);
+                    if (seenDocPaths.has(real))
+                        continue;
+                    seenDocPaths.add(real);
+                    const doc = loadPositionalDoc(file, memDir, scope);
+                    if (doc)
+                        out.push({ doc, realpath: real, order: depth });
+                }
+            }
+        }
+        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 });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Per-doc envelope render.
+// ---------------------------------------------------------------------------
+/** One doc as a `<doc …>` 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, absReadFile) {
+    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))}" triggered-by="${attr(disp(absReadFile))}"`;
+    return body === '' ? `<doc ${attrs} />` : `<doc ${attrs}>\n${body}\n</doc>`;
+}
+// ---------------------------------------------------------------------------
+// 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);
+        candidates = [...positional, ...byGlob];
+    }
+    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);
+    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
+            block = renderDocEnvelope(c.doc, absReadFile);
+        }
+        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 file="${attr(disp(absReadFile))}">\n${rendered.join('\n')}\n</auto-loaded-context>`;
+}

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

@@ -0,0 +1,25 @@
+/** The `## Skills` system-prompt section: every eligible `kind: skill` doc,
+ *  rendered at its `system-prompt-visibility`. `name`-rung skills collapse into
+ *  one compact catalog (group-collapsed, unioned with plugin/marketplace
+ *  skills); `preview`/`content`-rung skills each get a `###` sub-section.
+ *  Returns '' when nothing is eligible. */
+export declare function renderSkillsSection(nodeId: string): string;
+/** The `## Preferences` system-prompt section: every eligible `kind: preference`
+ *  doc as its own `###` sub-section, at its `system-prompt-visibility` (the
+ *  preference default rung is `preview` → the routing line). Returns '' when
+ *  nothing is eligible. */
+export declare function renderPreferencesSection(nodeId: string): string;
+/** The `## References` block embedded INSIDE the `<crtr-context>` session_start
+ *  message (the bearings caller pushes the returned string into the block, or
+ *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
+ *  `system-prompt-visibility` (reference boot default is `none`, so only
+ *  author-promoted references show) PLUS the node-local memory docs (any kind),
+ *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
+ *  nothing is eligible.
+ *
+ *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
+ *  doc drops only itself (with a loud stderr warning naming the offending path),
+ *  never silently swallowing the entire block (identity included).  Per the CTO
+ *  ruling, strictness lives at the COLLECTION layer (memory-resolver.ts); this
+ *  catch is error ISOLATION at the render layer, not a fallback parser. */
+export declare function renderReferencesBlock(nodeId: string): string;