@north-light/crouter 0.3.162 → 0.3.164

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

@@ -1,75 +1,38 @@
-// on-read.ts — the file-read-visibility render for the document substrate.
+// on-read.ts — file-context delivery 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):
+// A memory with file-read visibility participates only through an explicit
+// `applies-to` path glob (authoring lint requires one). Two events use that one
+// routing mechanism:
 //
-//   • 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.
+//   • A successful `read` tool call evaluates the read file against every
+//     visible substrate doc. Project stores encountered between that file and
+//     the filesystem root join the resolved cwd/profile corpus, so a nested
+//     workspace can contribute guidance exactly when a file beneath it is read.
+//   • Opening a workspace evaluates the reserved `applies-to: "."` target for
+//     every project store mounted by the cwd and selected profile. This happens
+//     while the first-message bearings are assembled, so workspace-wide context
+//     arrives before the task rather than waiting for an arbitrary first file.
 //
-// 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.
+// `read-when` remains an additional OR trigger over a read markdown file's own
+// frontmatter. It does not replace `applies-to`: every non-none file-read rung
+// still declares its path boundary explicitly.
 //
-// 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.
+// Every candidate renders at its own fileReadVisibility rung. Explicit routing
+// is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
+// concern and do not cap a deliberately matched document.
 import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, matchesGlob, parse, relative, sep } from 'node:path';
+import { basename, dirname, 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 { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
+import { getNode } from '../canvas/index.js';
 import { userScopeRoot } from '../scope.js';
-import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, } from './index.js';
+import { assembleNodeSubject, displayName, 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);
@@ -78,7 +41,6 @@ function realpathOrSelf(p) {
         return p;
     }
 }
-/** Escape a value for an XML-ish attribute in the injected envelope. */
 function attr(s) {
     return s
         .replace(/&/g, '&amp;')
@@ -86,12 +48,11 @@ function attr(s) {
         .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')))
+        if (pathExists(`${d}${sep}.git`))
             return d;
         if (d === root)
             return null;
@@ -101,7 +62,6 @@ function gitRootOf(p) {
         d = parent;
     }
 }
-/** Display a path relative to its nearest git repo root, else absolute. */
 function disp(p) {
     const root = gitRootOf(p);
     if (!root)
@@ -110,14 +70,18 @@ function disp(p) {
     return rel === '' ? '.' : rel;
 }
 function isJunkAncestor(dir) {
-    return dir.split(sep).some((seg) => JUNK_DIRS.has(seg));
+    return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
 }
-/** 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) {
+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 loadProjectDoc(file, memoryDir) {
     try {
-        const raw = relative(memDir, file)
+        const raw = relative(memoryDir, file)
             .replace(/\.md$/i, '')
             .split(sep)
             .join('/');
@@ -128,67 +92,47 @@ function loadPositionalDoc(file, memDir, scope) {
         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 };
+        return {
+            ...schema,
+            name: resolveDocName(data, fallbackName),
+            scope: 'project',
+            path: file,
+            body,
+        };
     }
     catch {
         return null;
     }
 }
-function safeWalkMd(dir) {
+function safeWalkMarkdown(dir) {
     try {
-        return walkFiles(dir, (n) => n.toLowerCase().endsWith('.md'));
+        return walkFiles(dir, (name) => name.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();
+/** Project docs from every workspace store enclosing the read file. This is a
+ * discovery walk only: each returned doc must still match an explicit trigger. */
+function enclosingProjectDocs(absReadFile) {
+    const docs = [];
+    const seen = 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 memoryDir = `${dir}${sep}${CRTR_DIR_NAME}${sep}memory`;
+            if (pathExists(memoryDir)) {
+                for (const file of safeWalkMarkdown(memoryDir)) {
                     const real = realpathOrSelf(file);
-                    if (seenDocPaths.has(real))
+                    if (seen.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 });
+                    seen.add(real);
+                    const doc = loadProjectDoc(file, memoryDir);
+                    if (doc !== null)
+                        docs.push(doc);
                 }
             }
         }
@@ -198,65 +142,42 @@ function positionalCandidates(absReadFile) {
         if (parent === dir)
             break;
         dir = parent;
-        depth += 1;
     }
-    return out;
+    return docs;
 }
-/** 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;
+function resolvedDocs() {
     try {
-        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+        return cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
     }
     catch {
         return [];
     }
+}
+function dedupeByPhysicalPath(docs) {
+    const seen = new Set();
     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))
+        if (seen.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 });
+        seen.add(real);
+        out.push(doc);
     }
     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 globMatches(glob, absReadFile, owningRoot) {
+    const targets = [absReadFile, basename(absReadFile)];
+    if (owningRoot !== null)
+        targets.push(relative(owningRoot, absReadFile));
+    return targets.some((target) => {
+        try {
+            return matchesGlob(target, glob);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 function readFileFrontmatter(absReadFile) {
     if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
         return {};
@@ -267,41 +188,20 @@ function readFileFrontmatter(absReadFile) {
         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;
+function matchesReadEvent(doc, absReadFile, readFrontmatter) {
+    const pathMatch = doc.appliesTo?.some((glob) => globMatches(glob, absReadFile, owningRootOf(doc))) === true;
+    const frontmatterMatch = doc.readWhen !== undefined &&
+        Object.keys(readFrontmatter).length > 0 &&
+        evalCondition(doc.readWhen, readFrontmatter);
+    return pathMatch || frontmatterMatch;
+}
+function envelopeName(doc) {
+    const displayed = displayName(doc.name);
+    if (displayed !== '')
+        return displayed;
+    const root = owningRootOf(doc);
+    return root === null ? doc.name : basename(root);
 }
-// ---------------------------------------------------------------------------
-// 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')
@@ -311,26 +211,33 @@ function renderDocEnvelope(doc) {
         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))}"`;
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(envelopeName(doc))}" 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.
- */
+function renderCandidates(subject, docs, seen) {
+    const rendered = [];
+    for (const doc of docs) {
+        const real = realpathOrSelf(doc.path);
+        if (seen.has(real))
+            continue;
+        try {
+            if (!gatePasses(doc, subject))
+                continue;
+            const block = renderDocEnvelope(doc);
+            if (block === null)
+                continue;
+            seen.add(real);
+            rendered.push(block);
+        }
+        catch {
+            continue;
+        }
+    }
+    return rendered.length === 0
+        ? ''
+        : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
+}
+/** Surface docs matched by a successful read tool call. */
 export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     let subject;
     try {
@@ -342,63 +249,36 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     if (subject === null)
         return '';
     const absReadFile = realpathOrSelf(readFilePath);
-    let candidates;
+    const readFrontmatter = readFileFrontmatter(absReadFile);
+    const docs = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
+        .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
+        .filter((doc) => matchesReadEvent(doc, absReadFile, readFrontmatter));
+    return renderCandidates(subject, docs, seen);
+}
+/** Surface workspace-wide docs during first-message assembly. `.` is a reserved
+ * applies-to target meaning “when this project store is mounted by cwd/profile”. */
+export function renderWorkspaceOpenDocs(nodeId) {
+    let subject;
+    let docs;
     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];
+        subject = assembleNodeSubject(nodeId);
+        const node = getNode(nodeId);
+        if (subject === null || node === null)
+            return '';
+        docs = listProjectMemoryDocs(node.cwd, node.profile_id ?? null)
+            .map(parseSubstrateDoc)
+            .filter((doc) => doc !== null);
     }
     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>`;
+    docs = dedupeByPhysicalPath(docs)
+        .filter((doc) => doc.appliesTo?.some((glob) => glob.trim() === '.') === true)
+        .sort((a, b) => {
+        const aRoot = owningRootOf(a) ?? '';
+        const bRoot = owningRootOf(b) ?? '';
+        const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
+        return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
+    });
+    return renderCandidates(subject, docs, new Set());
 }

package/dist/core/substrate/render.js

@@ -59,7 +59,7 @@ import { projectScopeRoots } from '../scope.js';
 // pull subject.js (canvas-db) transitively, re-tainting every CLI consumer of
 // the pure render fns. The canvas-db wrappers (renderPreferencesSection /
 // renderKnowledgeBlock) live in render-node.js instead.
-import { buildCeilingIndex, effectiveRung, indexDirOf, isIndexName } from './ceiling.js';
+import { buildCeilingIndex, effectiveSystemPromptRung, indexDirOf, isIndexName } from './ceiling.js';
 import { gatePasses } from './gate.js';
 import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
 import { cachedSubstrateDocs } from './session-cache.js';
@@ -105,7 +105,7 @@ function selectWinners(subject, kind) {
     const ceil = buildCeilingIndex(docs);
     const eligible = docs
         .map((d) => {
-        const rung = effectiveRung(d, ceil, 'systemPromptVisibility');
+        const rung = effectiveSystemPromptRung(d, ceil);
         return rung === d.systemPromptVisibility ? d : { ...d, systemPromptVisibility: rung };
     })
         .filter((d) => d.kind === kind)
@@ -224,8 +224,8 @@ function nodeLocalDocs(nodeId, subject) {
             if (schema === null)
                 continue;
             // ONE substrate-identity rule (schema.ts's resolveDocName), shared with
-            // the resolver and the on-read positional loader: explicit frontmatter
-            // `name` wins over the physical-path-derived fallback.
+            // the resolver and explicit file-context loader: frontmatter `name` wins
+            // over the physical-path-derived fallback.
             const name = resolveDocName(data, fallbackName);
             // node-local is NOT a resolver scope; `scope` is a placeholder never read
             // by gate eval (keyed off the NODE subject, not the doc) nor by the

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

@@ -54,8 +54,9 @@ export interface SubstrateSchema {
      *  eligible. An empty `{}` is carried as-is and is inert (never matches) — see
      *  `gatePasses`. */
     gate?: GatePredicate;
-    /** Optional glob list narrowing the on-read trigger to matching read files.
-     *  Absent ⇒ positional trigger only. A single glob is normalized to a 1-list. */
+    /** Explicit file-context routes. `.` is the project workspace-open target;
+     *  every other value is a glob matched after an actual file read. A single
+     *  value is normalized to a 1-list. */
     appliesTo?: string[];
     /** Optional condition over the READ FILE's own frontmatter — the on-read
      *  frontmatter trigger (Stream A native rules). Same coercion + predicate

package/dist/core/substrate/schema.js

@@ -73,9 +73,9 @@ export function normalizeDocName(name) {
 // Substrate identity — the ONE explicit-name-then-path-fallback rule. A doc's
 // resolver identity is its explicit frontmatter `name` when present (normalized),
 // otherwise the caller-supplied path-derived fallback. Every loader that turns a
-// physical .md file into a named doc (the resolver's `listMemoryDocsInDir`, the
-// on-read positional loader) calls this ONE helper, so a doc's identity never
-// depends on which path loaded it.
+// physical .md file into a named doc (the resolver's `listMemoryDocsInDir` and
+// the explicit file-context loader) calls this ONE helper, so a doc's identity
+// never depends on which path loaded it.
 // ---------------------------------------------------------------------------
 /** Resolve a doc's identity from its raw frontmatter record: an explicit
  *  `name` field wins (trimmed + normalized), else `fallbackName` (the
@@ -177,8 +177,8 @@ function parseGate(v) {
         ? v
         : undefined;
 }
-/** Normalize `applies-to` to a non-empty glob list, or undefined (positional
- *  trigger only). Accepts a single string or an array of strings. */
+/** Normalize `applies-to` to a non-empty route list, or undefined when no
+ *  file-context event is declared. Accepts a string or an array of strings. */
 function parseAppliesTo(v) {
     if (typeof v === 'string') {
         return v.trim() === '' ? undefined : [v];

package/dist/pi-extensions/__tests__/canvas-tool-guide.test.d.ts

@@ -0,0 +1 @@
+export {};