@north-light/crouter 0.3.208 → 0.3.209

package/dist/core/substrate/render.js

@@ -2,14 +2,14 @@
 //
 // Two boot targets, one shape per kind: each kind renders as ONE wrapped block —
 // intro prose → GROUPED content → an update directive. The render is grouped
-// by visibility rung, not interleaved: `content`-rung docs render FIRST as
+// by boot rung, not interleaved: `content`-rung docs render FIRST as
 // clean prose bodies (verbatim, no tree chrome, no name label — this is what
 // makes content-rung the persona-prose mechanism), in general→specific order;
-// then the `preview`+`name`(+hidden `none`) docs render as ONE catalog tree,
-// each at its own rung (preview → a `# read when:` routing line; name → a bare
-// entry); a `none`-rung doc leaks only into its dir's `[+N more]` count, never
-// a name — EXCEPT a node-local doc, whose contract is "node-local rides into
-// knowledge" unconditionally: renderKnowledgeBlock floors a rung-none
+// then the `preview`+`name` docs render as ONE catalog tree, each at its own
+// rung (preview → a `# read when:` routing line; name → a bare entry); a doc
+// with NO boot entry leaks only into its dir's `[+N more]` count, never a
+// name — EXCEPT a node-local doc, whose contract is "node-local rides into
+// knowledge" unconditionally: renderKnowledgeForSubject floors a bootless
 // node-local doc up to `name` so it still shows its bare name rather than
 // collapsing into a hidden count. Only gate evaluation removes a node-local
 // doc outright.
@@ -27,12 +27,13 @@
 //
 // The pipeline is explicitly TWO-STEP and must never run in the other order:
 //   1. SELECT WINNERS — MemoryDoc → parseSubstrateDoc → (null-filter
-//      non-substrate) → ceiling-capped effective rung → gatePasses →
-//      first-wins DEDUP by name over the resolver's precedence order (nearest
-//      project > user > builtin). Node-local docs follow the same gate rule,
-//      but the knowledge-block render floors a rung-none node-local doc's
-//      EFFECTIVE rung to `name` — the one rung-floor exemption, scoped to the
-//      node-local store only.
+//      non-substrate) → per-doc boot rung (`bootRung`, the max `at` over the
+//      doc's `on: boot` surfaces entries) → gatePasses → first-wins DEDUP by
+//      name over the resolver's precedence order (nearest project > user >
+//      builtin). Node-local docs follow the same gate rule, but the
+//      knowledge-block render floors a bootless node-local doc's rung to
+//      `name` — the one rung-floor exemption, scoped to the node-local store
+//      only.
 //   2. RENDER IN DISPLAY ORDER — split winners into content vs. the rest;
 //      order content general→specific (builtin, user, project outermost→
 //      nearest, node-local last) then by tree position then filename; place
@@ -43,29 +44,28 @@
 //   orderings and must not be conflated.
 //
 // Pure + defensive: reads the resolver, canvas-db (subject assembly), and the
-// node-local memory dir; performs no writes and no side effects. A single
-// malformed doc never throws the whole render — parsing is isolated upstream
-// (parseSubstrateDoc returns null for a non-substrate doc; per-file node-local
-// loads are wrapped), and tree construction is pure string work.
+// node-local memory dir; performs no writes and no side effects beyond the
+// caller-supplied `seen` delivery map (write-only seeding — boot docs render
+// every session and are never skipped). A single malformed doc never throws
+// the whole render — parsing is isolated upstream (parseSubstrateDoc returns
+// null for a non-substrate doc; per-file node-local loads are wrapped), and
+// tree construction is pure string work.
 import { relative, sep } from 'node:path';
 import { interpolateNodePaths } from '../canvas/paths.js';
 import { listAllMemoryDocs, resolveMemoryDoc } from '../memory-resolver.js';
 import { subKindsAvailableTo } from '../config.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { pathExists, readText, realpathOrSelf, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
 import { projectScopeRoots } from '../scope.js';
+import { gatePasses } from './gate.js';
 // De-barreled to LEAF modules on purpose: importing from './index.js' would
 // 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, effectiveSystemPromptRung, indexDirOf, isIndexName } from './ceiling.js';
-import { gatePasses } from './gate.js';
-import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
+import { recordDelivery } from './injected-store.js';
+import { bootRung, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
 import { cachedSubstrateDocs } from './session-cache.js';
-// ---------------------------------------------------------------------------
-// Step 1 — winner selection (ceiling + gate + first-wins dedup).
-// ---------------------------------------------------------------------------
 /** First-wins dedup by (already-normalized) name, preserving the input's
  *  precedence order. The array's ORDER is the precedence signal — callers must
  *  pass docs already ordered highest-precedence-first; this function never
@@ -82,18 +82,14 @@ function dedupeFirstWins(docs) {
     return out;
 }
 /** STEP 1 — the resolver-provided WINNER docs of one `kind`, eligible at boot
- *  for `subject`: parsed (non-substrate docs null-filtered), ceiling-capped,
- *  gate-passed, then first-wins DEDUPED by name over the resolver's precedence
- *  order (nearest project > user > builtin) — at the EFFECTIVE system-prompt
- *  rung, INCLUDING `none`-rung docs (the tree counts them into `[+N more]`).
- *  This is winner selection ONLY; display ordering is a separate, later step
- *  (see renderGrouped) so a builtin doc can never mask a project/user override
- *  by virtue of sorting first. Uses the per-session cache so the full corpus
- *  is scanned + parsed at most once per session across the boot-render calls.
- *
- *  Ceilings are computed over the WHOLE corpus (cross-kind) BEFORE the kind
- *  filter, and the effective rung is written back into systemPromptVisibility —
- *  but each doc keeps its canonical logical identifier, such as `taste/INDEX`. */
+ *  for `subject`: parsed (non-substrate docs null-filtered), gate-passed, then
+ *  first-wins DEDUPED by name over the resolver's precedence order (nearest
+ *  project > user > builtin) — each at its own boot rung, INCLUDING docs with
+ *  NO boot entry (the tree counts them into `[+N more]`). This is winner
+ *  selection ONLY; display ordering is a separate, later step (see
+ *  renderGrouped) so a builtin doc can never mask a project/user override by
+ *  virtue of sorting first. Uses the per-session cache so the full corpus is
+ *  scanned + parsed at most once per session across the boot-render calls. */
 function selectWinners(subject, kind) {
     let docs;
     try {
@@ -102,17 +98,29 @@ function selectWinners(subject, kind) {
     catch {
         return [];
     }
-    const ceil = buildCeilingIndex(docs);
     const eligible = docs
-        .map((d) => {
-        const rung = effectiveSystemPromptRung(d, ceil);
-        return rung === d.systemPromptVisibility ? d : { ...d, systemPromptVisibility: rung };
-    })
         .filter((d) => d.kind === kind)
-        .filter((d) => gatePasses(d, subject));
+        .filter((d) => gatePasses(d, subject))
+        .map((d) => ({ ...d, bootRung: bootRung(d) }));
     return dedupeFirstWins(eligible);
 }
 // ---------------------------------------------------------------------------
+// Boot-delivery seeding — the injected-docs map grows at render time.
+// ---------------------------------------------------------------------------
+/** Record every VISIBLY rendered winner into the caller's transcript dedup map
+ *  at its displayed rung (write-only — boot renders every session and never
+ *  skips). Seeding is what lets a later listing line or on-read injection skip
+ *  a doc the boot catalog already discloses at that rank. */
+function seedBootDelivery(seen, docs) {
+    if (seen === undefined)
+        return;
+    for (const d of docs) {
+        if (!isVisible(d.bootRung))
+            continue;
+        recordDelivery(seen, realpathOrSelf(d.path), d.bootRung);
+    }
+}
+// ---------------------------------------------------------------------------
 // Step 2 — display ordering + grouped render.
 // ---------------------------------------------------------------------------
 /** Content-prose ordering rank: general → specific. builtin=0, user=1,
@@ -171,15 +179,15 @@ function compareTreePosition(a, b) {
 /** STEP 2 — split deduped `winners` by rung and render each group in its
  *  display order: `content` docs first, as clean prose (general→specific,
  *  then tree position, then filename — no tree chrome, no name label); every
- *  other winner (preview/name/hidden-none) folds into ONE catalog tree exactly
- *  as before. `nodeLocalSet` marks which winners came from the node-local
- *  store (ranked most-specific in content ordering); omit it for a pure
- *  resolver render. */
+ *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree
+ *  exactly as before. `nodeLocalSet` marks which winners came from the
+ *  node-local store (ranked most-specific in content ordering); omit it for a
+ *  pure resolver render. */
 function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
     const content = [];
     const rest = [];
     for (const d of winners) {
-        if (d.systemPromptVisibility === 'content')
+        if (d.bootRung === 'content')
             content.push(d);
         else
             rest.push(d);
@@ -204,10 +212,10 @@ function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
  *  Node-local docs follow the same GATE rule as every other store — gate
  *  evaluation is the only thing that removes a doc here. Rung is different:
  *  node-local's contract is "node-local rides into knowledge" unconditionally,
- *  so a `none`-rung node-local doc is retained AT its parsed rung by this
- *  function (never rewritten here) — it is the caller (renderKnowledgeBlock)
- *  that floors a rung-none node-local doc up to `name` so it still shows its
- *  bare name instead of collapsing into a `[+N more]` count. */
+ *  so a doc with no boot entry is retained by this function — it is the caller
+ *  (renderKnowledgeForSubject) that floors a bootless node-local doc up to
+ *  `name` so it still shows its bare name instead of collapsing into a
+ *  `[+N more]` count. */
 function nodeLocalDocs(nodeId, subject) {
     const dir = memoryDir(nodeId);
     if (!pathExists(dir))
@@ -246,7 +254,6 @@ function newDir(path) {
         path,
         children: new Map(),
         leaves: [],
-        index: null,
         hiddenHere: 0,
         renders: false,
         ownCount: 0,
@@ -281,9 +288,9 @@ function isVisible(rung) {
     return rungRank(rung) >= rungRank('name');
 }
 /** Bottom-up pass: decide which dirs render and where hidden counts land. A dir
- *  renders when it has ≥1 visible leaf, a visible INDEX, ≥1 rendering child dir,
- *  or it is top-level (a direct child of the root always renders so its subtree
- *  count is visible — the root itself always renders). `none`-rung docs in a
+ *  renders when it has ≥1 visible leaf, ≥1 rendering child dir, or it is
+ *  top-level (a direct child of the root always renders so its subtree count
+ *  is visible — the root itself always renders). Bootless docs in a
  *  NON-rendering dir bubble up to the nearest rendering ancestor's `[+N more]`;
  *  a rendering dir keeps its own subtree count. Returns the count to bubble up. */
 function resolveDir(dir, isTopLevel) {
@@ -292,10 +299,8 @@ function resolveDir(dir, isTopLevel) {
         totalHidden += resolveDir(child, dir.path === '');
     }
     const hasVisibleLeaf = dir.leaves.length > 0;
-    const hasVisibleIndex = dir.index !== null && isVisible(dir.index.systemPromptVisibility);
     const anyChildRenders = [...dir.children.values()].some((c) => c.renders);
-    dir.renders =
-        hasVisibleLeaf || hasVisibleIndex || anyChildRenders || isTopLevel || dir.path === '';
+    dir.renders = hasVisibleLeaf || anyChildRenders || isTopLevel || dir.path === '';
     dir.ownCount = dir.renders ? totalHidden : 0;
     return dir.renders ? 0 : totalHidden;
 }
@@ -306,9 +311,17 @@ function itemSortKey(item) {
         return leafSegment(item.doc.name);
     return '';
 }
-/** Render one canonical logical doc entry at its effective rung. */
+/** DISPLAY-ORDER PIN ONLY: a leaf whose last name segment is `INDEX` sorts
+ *  first among its directory's items. `INDEX` carries no mechanism anywhere in
+ *  the substrate anymore — these are ordinary docs — but the ex-router docs
+ *  keeping that name are each their dir's orientation entry, and localeCompare
+ *  would drop them mid-list. */
+function isIndexPinned(item) {
+    return item.kind === 'leaf' && leafSegment(item.doc.name) === 'INDEX';
+}
+/** Render one canonical logical doc entry at its boot rung. */
 function renderDocEntry(doc, label, entryPrefix, childPrefix, lines) {
-    switch (doc.systemPromptVisibility) {
+    switch (doc.bootRung) {
         case 'preview': {
             const pl = previewLine(doc);
             lines.push(pl === '' ? `${entryPrefix}${label}` : `${entryPrefix}${label}  # read when: ${pl}`);
@@ -329,23 +342,19 @@ function renderDocEntry(doc, label, entryPrefix, childPrefix, lines) {
     }
 }
 /** Render the children of a rendering dir, with `childPrefix` carrying the tree
- *  guides for this depth. Order: the dir's canonical INDEX identity first, then
- *  child dirs and leaves intermixed alphabetically, then the `[+N more]` count
- *  last. */
+ *  guides for this depth. Order: an `INDEX`-named leaf first (display pin),
+ *  then child dirs and leaves intermixed alphabetically, then the `[+N more]`
+ *  count last. */
 function renderChildren(dir, childPrefix, lines) {
-    const middle = [];
+    const ordered = [];
     for (const child of dir.children.values()) {
         if (child.renders)
-            middle.push({ kind: 'dir', node: child });
+            ordered.push({ kind: 'dir', node: child });
     }
     for (const leaf of dir.leaves)
-        middle.push({ kind: 'leaf', doc: leaf });
-    middle.sort((a, b) => itemSortKey(a).localeCompare(itemSortKey(b)));
-    const ordered = [];
-    if (dir.index !== null && isVisible(dir.index.systemPromptVisibility)) {
-        ordered.push({ kind: 'index', doc: dir.index });
-    }
-    ordered.push(...middle);
+        ordered.push({ kind: 'leaf', doc: leaf });
+    ordered.sort((a, b) => Number(isIndexPinned(b)) - Number(isIndexPinned(a)) ||
+        itemSortKey(a).localeCompare(itemSortKey(b)));
     if (dir.ownCount > 0)
         ordered.push({ kind: 'more', count: dir.ownCount });
     ordered.forEach((item, i) => {
@@ -360,7 +369,6 @@ function renderChildren(dir, childPrefix, lines) {
                 lines.push(`${entryPrefix}${item.node.segment}/`);
                 renderChildren(item.node, nextPrefix, lines);
                 break;
-            case 'index':
             case 'leaf':
                 renderDocEntry(item.doc, leafSegment(item.doc.name), entryPrefix, nextPrefix, lines);
                 break;
@@ -385,18 +393,11 @@ function buildTree(docs, rootLabel) {
         if (seen.has(d.name))
             continue; // first-wins cross-scope dedup
         seen.add(d.name);
-        if (isIndexName(d.name)) {
-            const dir = ensureDir(root, indexDirOf(d.name));
-            if (dir.index === null)
-                dir.index = d; // precedence-ordered → keep first (highest)
-        }
-        else {
-            const parent = ensureDir(root, parentDirOf(d.name));
-            if (isVisible(d.systemPromptVisibility))
-                parent.leaves.push(d);
-            else
-                parent.hiddenHere += 1;
-        }
+        const parent = ensureDir(root, parentDirOf(d.name));
+        if (isVisible(d.bootRung))
+            parent.leaves.push(d);
+        else
+            parent.hiddenHere += 1;
     }
     resolveDir(root, false);
     const lines = [rootLabel];
@@ -416,7 +417,9 @@ const KNOWLEDGE_INTRO = 'Knowledge documents are what you consult — playbooks
     'references on the user, projects, and this node. They are aggregated from your memory stores: ' +
     'user-global (`~/.crouter/memory/`), every ancestor project store (`<dir>/.crouter/memory/`) ' +
     "from the cwd upward, the selected profile's memory store (when one is selected), and node-local " +
-    "(this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
+    "(this node's `context/memory/`). To read one, run `crtr memory read <name>`; a directory " +
+    'name is a valid read target too — it answers with its listing, and walking directories is ' +
+    'the sanctioned way to browse. ' +
     'Each doc exists to prevent a specific mistake you would make without it, so when your task ' +
     'matches one — by its name or its `# read when:` line — read it before you act; consulting it ' +
     'only after the work is done forfeits the entire reason it exists. ' +
@@ -485,12 +488,13 @@ function buildSubPersonaMenu(kind) {
  *  preview/name catalog tree. ALWAYS returns a non-empty `<memory
  *  kind="preference">` block — the guidance frame is unconditional, so the
  *  system-prompt splice is never empty even when no preference is eligible. */
-function buildPreferencesBlock(subject) {
+function buildPreferencesBlock(subject, seen) {
     let body = MEMORY_USAGE_GUIDANCE;
     let contentDocs = [];
     let tree = '';
     if (subject !== null) {
         const winners = selectWinners(subject, 'preference');
+        seedBootDelivery(seen, winners);
         const grouped = renderGrouped(winners, 'preferences');
         contentDocs = grouped.contentDocs;
         tree = grouped.tree;
@@ -508,8 +512,8 @@ function buildPreferencesBlock(subject) {
     }
     return { block: `<memory kind="preference">\n${body}\n</memory>`, contentDocs, tree };
 }
-export function renderPreferencesForSubject(subject) {
-    return buildPreferencesBlock(subject);
+export function renderPreferencesForSubject(subject, seen) {
+    return buildPreferencesBlock(subject, seen);
 }
 // ---------------------------------------------------------------------------
 // 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
@@ -521,18 +525,22 @@ export function renderPreferencesForSubject(subject) {
  *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
  *  like the preference block: content prose first (general→specific,
  *  node-local last), then the preview/name catalog tree. Node-local docs are
- *  floored HERE — a rung-none node-local doc's effective rung is bumped to
- *  `name` before grouping, so it still surfaces as a bare-name tree entry
- *  rather than collapsing into a `[+N more]` count (its body still never
- *  renders: floored docs never reach the `content` rung). Procedural guidance
- *  and factual references both live here as `knowledge`. Returns '' when
- *  nothing is eligible. */
-export function renderKnowledgeForSubject(subject, nodeId) {
-    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => rungRank(d.systemPromptVisibility) >= rungRank('name') ? d : { ...d, systemPromptVisibility: 'name' });
+ *  floored HERE — a bootless node-local doc's rung is bumped to `name` before
+ *  grouping, so it still surfaces as a bare-name tree entry rather than
+ *  collapsing into a `[+N more]` count (its body still never renders: floored
+ *  docs never reach the `content` rung). Procedural guidance and factual
+ *  references both live here as `knowledge`. Returns '' when nothing is
+ *  eligible. */
+export function renderKnowledgeForSubject(subject, nodeId, seen) {
+    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => {
+        const r = bootRung(d);
+        return { ...d, bootRung: isVisible(r) ? r : 'name' };
+    });
     const nodeLocalSet = new Set(nodeLocal);
     // Resolver winners first: first-wins dedup keeps the resolver's copy over a
     // same-named node-local doc, matching the original precedence.
     const winners = dedupeFirstWins([...selectWinners(subject, 'knowledge'), ...nodeLocal]);
+    seedBootDelivery(seen, winners);
     const { contentProse, tree } = renderGrouped(winners, 'knowledge', nodeLocalSet);
     if (contentProse === '' && tree === '')
         return '';

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

@@ -7,10 +7,8 @@ export declare const RUNGS: readonly ["none", "name", "preview", "content"];
 export type Rung = (typeof RUNGS)[number];
 /** Ordinal of a rung on the ladder (none=0 … content=3). */
 export declare function rungRank(r: Rung): number;
-/** Does rung `r` disclose at least as much as `min`? — e.g.
- *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
+/** Does rung `r` disclose at least as much as `min`? */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
-export declare const FALLBACK_RUNG: Rung;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
  *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
  *  prefix) is unchanged. */
@@ -24,6 +22,32 @@ export declare function normalizeDocName(name: string): string;
  *  `name` field wins (trimmed + normalized), else `fallbackName` (the
  *  normalized path-derived name). */
 export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
+export declare const SURFACE_EVENTS: readonly ["boot", "workspace-open", "read", "memory-read", "command"];
+export type SurfaceEvent = (typeof SURFACE_EVENTS)[number];
+/** The rungs an entry may deliver at. There is no `none` — silence is the
+ *  absence of an entry. (`Rung`'s `none` survives only as the internal
+ *  ranking floor, e.g. `bootRung` of a doc with no boot entry.) */
+export declare const SURFACE_RUNGS: readonly ["name", "preview", "content"];
+export type SurfaceRung = (typeof SURFACE_RUNGS)[number];
+/** One routing entry: when event `on` exposes a subject that fits `match`
+ *  (and `matchFrontmatter`, `read` only), the doc delivers at rung `at`.
+ *  Constraints within one entry AND together (each present constraint must
+ *  fit; a `match` list is satisfied by any one glob); multiple entries per
+ *  event OR together. */
+export interface SurfaceEntry {
+    on: SurfaceEvent;
+    /** Globs vs the event's subject namespace. Required on read/memory-read/
+     *  command (a read entry may carry `matchFrontmatter` instead); meaningless
+     *  on boot/workspace-open (presence of the entry is the match). */
+    match?: string[];
+    /** Predicate over the read file's own YAML frontmatter — `read` event only.
+     *  Frontmatter key `match-frontmatter`. */
+    matchFrontmatter?: GatePredicate;
+    at: SurfaceRung;
+}
+/** A doc's boot rung: the highest `at` over its `boot` entries, `none` when
+ *  it carries no boot entry. The boot render's per-doc selection input. */
+export declare function bootRung(doc: Pick<SubstrateSchema, 'surfaces'>): Rung;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -46,25 +70,17 @@ export interface SubstrateSchema {
     /** Human-facing abbreviation for `crtr memory list`. NEVER loaded into an
      *  agent's context (design §3). Empty string when absent. */
     shortForm: string;
-    /** How much surfaces at boot (system prompt / autoloaded context). */
-    systemPromptVisibility: Rung;
-    /** How much surfaces on-read (when a related file is read). */
-    fileReadVisibility: Rung;
+    /** Suppress this doc from directory listings (default false). Suppression,
+     *  not a type — the doc is otherwise ordinary. */
+    unlisted: boolean;
+    /** Explicit event routing. Empty = no explicit routing (listings still
+     *  apply, unless `unlisted`). Invalid entries are dropped by the tolerant
+     *  runtime parser; lint enforces strictly. */
+    surfaces: SurfaceEntry[];
     /** Optional eligibility predicate over the node's own config. Absent ⇒ always
      *  eligible. An empty `{}` is carried as-is and is inert (never matches) — see
      *  `gatePasses`. */
     gate?: GatePredicate;
-    /** 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
-     *  vocabulary as `gate` (non-null non-array object carried; empty `{}` inert),
-     *  but evaluated by `evalCondition` against the read file's parsed YAML rather
-     *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
-     *  `read-when`. */
-    readWhen?: GatePredicate;
     /** Opt-in: this doc is invocable as a pi slash command (`/<name>`, `/` in a
      *  nested name rendered as `:`). Default `false` — most docs are consulted,
      *  not invoked. Frontmatter key `slash`. */

package/dist/core/substrate/schema.js

@@ -4,13 +4,9 @@
 // downstream track (CLI verbs, boot render, on-read render, migrator) builds
 // against — pure and side-effect free. See design-substrate.md §4 (schema).
 //
-// There is NO kind-based default for visibility: the right rung is a
-// case-by-case authoring call, so both rungs are required at authoring time
-// (enforced by `crtr memory write` on create and by `crtr memory lint`). The
-// runtime parser is tolerant by contract (it maps over many docs and must
-// never throw), so a doc missing/with an invalid rung falls back to the neutral
-// floor `none` — a malformed doc renders invisible rather than crashing, and
-// lint flags it. Valid docs never hit the fallback.
+// The runtime parser is tolerant by contract (it maps over many docs and must
+// never throw): invalid `surfaces` entries are dropped rather than crashing a
+// render, and `crtr memory lint` owns strict authoring-time enforcement.
 // ---------------------------------------------------------------------------
 // Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
 // playbooks + factual references merged) vs `preference` (behave — standing
@@ -31,19 +27,11 @@ export const RUNGS = ['none', 'name', 'preview', 'content'];
 export function rungRank(r) {
     return RUNGS.indexOf(r);
 }
-/** Does rung `r` disclose at least as much as `min`? — e.g.
- *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
+/** Does rung `r` disclose at least as much as `min`? */
 export function rungAtLeast(r, min) {
     return rungRank(r) >= rungRank(min);
 }
 // ---------------------------------------------------------------------------
-// The neutral fallback rung used only when a doc omits a visibility field or
-// carries an invalid one. NOT a default an author may lean on — authoring-time
-// enforcement requires explicit rungs; this is purely the runtime parser's
-// never-throw floor (a malformed doc renders invisible, and lint flags it).
-// ---------------------------------------------------------------------------
-export const FALLBACK_RUNG = 'none';
-// ---------------------------------------------------------------------------
 // Display-name normalization — the optional `NN-` ordering pin. A doc's
 // physical path may carry a two-digit numeric prefix on a file or directory
 // segment (`00-runtime-base.md`, `01-spine/`) purely to pin structural order
@@ -86,6 +74,31 @@ export function resolveDocName(fm, fallbackName) {
     return explicit !== '' ? explicit : fallbackName;
 }
 // ---------------------------------------------------------------------------
+// Surfaces — explicit event routing (design: surfaces-design.md). A doc
+// declares WHEN it delivers as (event, match, rung) entries; matches are
+// always globs, always absolute in the event's namespace, with `./` as the
+// one relative spelling (anchoring to the doc's own container). A doc with
+// no `surfaces` at all does exactly one thing: appears in its directory's
+// listing.
+// ---------------------------------------------------------------------------
+export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command'];
+/** The rungs an entry may deliver at. There is no `none` — silence is the
+ *  absence of an entry. (`Rung`'s `none` survives only as the internal
+ *  ranking floor, e.g. `bootRung` of a doc with no boot entry.) */
+export const SURFACE_RUNGS = ['name', 'preview', 'content'];
+/** A doc's boot rung: the highest `at` over its `boot` entries, `none` when
+ *  it carries no boot entry. The boot render's per-doc selection input. */
+export function bootRung(doc) {
+    let r = 'none';
+    for (const e of doc.surfaces) {
+        if (e.on !== 'boot')
+            continue;
+        if (rungRank(e.at) > rungRank(r))
+            r = e.at;
+    }
+    return r;
+}
+// ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
@@ -106,11 +119,9 @@ export function parseSubstrateFrontmatter(fm) {
         kind,
         whenAndWhyToRead: strField(fm['when-and-why-to-read']),
         shortForm: strField(fm['short-form']),
-        systemPromptVisibility: parseRung(fm['system-prompt-visibility'], FALLBACK_RUNG),
-        fileReadVisibility: parseRung(fm['file-read-visibility'], FALLBACK_RUNG),
+        unlisted: fm['unlisted'] === true,
+        surfaces: parseSurfaces(fm['surfaces']),
         gate: parseGate(fm.gate),
-        appliesTo: parseAppliesTo(fm['applies-to']),
-        readWhen: parseGate(fm['read-when']),
         slash: fm.slash === true,
         rationale: parseRationale(fm['rationale']),
     };
@@ -161,13 +172,6 @@ function strField(v) {
 function parseRationale(v) {
     return typeof v === 'string' && v.trim() !== '' ? v : undefined;
 }
-/** Resolve a visibility field to a ladder rung, falling back to the neutral
- *  floor when absent/invalid. */
-function parseRung(v, fallback) {
-    return typeof v === 'string' && RUNGS.includes(v)
-        ? v
-        : fallback;
-}
 /** A gate is engaged only when frontmatter carries a non-null, non-array object
  *  (the predicate vocabulary's field→matcher map). Anything else (absent, null,
  *  scalar, array) ⇒ no gate ⇒ always eligible — the safe default that never
@@ -177,14 +181,53 @@ function parseGate(v) {
         ? v
         : undefined;
 }
-/** 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) {
+/** Tolerant `surfaces` parse: a non-array yields `[]`; invalid entries are
+ *  dropped (bad `on`, bad `at`, a read/memory-read/command entry left with
+ *  neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
+ *  on a non-read event is dropped from the entry, which survives iff it still
+ *  carries a `match`. Lint owns strict enforcement; the runtime parser maps
+ *  over many docs and must never throw. */
+function parseSurfaces(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const raw of v) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const rec = raw;
+        const on = rec['on'];
+        if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on))
+            continue;
+        const at = rec['at'];
+        if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at))
+            continue;
+        const match = parseMatchGlobs(rec['match']);
+        const matchFrontmatter = on === 'read' ? parseGate(rec['match-frontmatter']) : undefined;
+        if ((on === 'read' || on === 'memory-read' || on === 'command') &&
+            match === undefined &&
+            matchFrontmatter === undefined) {
+            continue;
+        }
+        out.push({
+            on: on,
+            at: at,
+            ...(match !== undefined ? { match } : {}),
+            ...(matchFrontmatter !== undefined ? { matchFrontmatter } : {}),
+        });
+    }
+    return out;
+}
+/** Normalize an entry's `match` to a non-empty glob list, or undefined.
+ *  Accepts a string or an array of strings; blanks are dropped. */
+function parseMatchGlobs(v) {
     if (typeof v === 'string') {
-        return v.trim() === '' ? undefined : [v];
+        const t = v.trim();
+        return t === '' ? undefined : [t];
     }
     if (Array.isArray(v)) {
-        const globs = v.filter((g) => typeof g === 'string' && g.trim() !== '');
+        const globs = v
+            .filter((g) => typeof g === 'string' && g.trim() !== '')
+            .map((g) => g.trim());
         return globs.length > 0 ? globs : undefined;
     }
     return undefined;

package/dist/core/substrate/surface-match.d.ts

@@ -0,0 +1,32 @@
+import { type Rung, type SubstrateDoc, type SurfaceEntry } from './schema.js';
+/** The project directory owning a doc's store: the path segment stack above
+ *  the doc's `.crouter` dir. `null` when the doc's path carries no `.crouter`
+ *  segment (builtin docs). */
+export declare function owningRootOf(doc: Pick<SubstrateDoc, 'path'>): string | null;
+/** True when the (already-realpathed) file sits beneath the doc's store's
+ *  owning directory. Callers additionally guard on `doc.scope === 'project'`:
+ *  a profile store's path computes an owning root of `~`, and user/builtin/
+ *  node docs likewise have no project-owning dir, so a `./`-anchored glob
+ *  outside a project store must never match. */
+export declare function underOwningRoot(doc: Pick<SubstrateDoc, 'path'>, absFile: string): boolean;
+/** Does a `read` entry fit the read file? `absReadFile` must already be
+ *  realpathed. `readFrontmatter` is the read file's own parsed YAML (empty
+ *  for non-markdown files); an empty record never satisfies
+ *  `matchFrontmatter`. */
+export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<SubstrateDoc, 'path' | 'scope'>, absReadFile: string, readFrontmatter: Record<string, unknown>): boolean;
+/** Does a `memory-read` entry on the doc named `carrierName` fit a resolved
+ *  read of a doc known by `targetNames`? */
+export declare function matchesMemoryReadEntry(entry: SurfaceEntry, carrierName: string, targetNames: string[]): boolean;
+/** Does a `command` entry fit the executed command string? */
+export declare function matchesCommandEntry(entry: SurfaceEntry, command: string): boolean;
+/** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
+export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'path' | 'scope'>, absReadFile: string, readFrontmatter: Record<string, unknown>): Rung;
+/** The doc's workspace-open rung. Presence of an entry is the match; callers
+ *  scope the corpus to project stores mounted by the subject's cwd/profile. */
+export declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>): Rung;
+/** The doc's delivery rung for a `crtr memory read` that resolved a doc
+ *  known by `targetNames` (canonical name, plus the mount-stripped name for
+ *  plugin-mounted docs). The doc's own `name` anchors `./` globs. */
+export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'name'>, targetNames: string[]): Rung;
+/** The doc's delivery rung for an executed command string. */
+export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, command: string): Rung;