@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/core/scope.js

@@ -5,16 +5,9 @@ import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
 import { usage } from './errors.js';
 let cachedProjectRoot;
-export function builtinSkillsRoot() {
-    // Resolve relative to this file: src/core/scope.ts → src/builtin-skills/ OR dist/core/scope.js → dist/builtin-skills/
-    const thisFile = fileURLToPath(import.meta.url);
-    const coreDir = dirname(thisFile);
-    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).
+    // Resolved relative to this file: 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/
@@ -22,11 +15,10 @@ export function builtinViewsRoot() {
 }
 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/
+    // resolved relative to this file: 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().
+    // memory is the only content the builtin scope carries — the scope has no
+    // scopeRoot (scopeRoot('builtin') is null).
     const thisFile = fileURLToPath(import.meta.url);
     const coreDir = dirname(thisFile);
     const pkgDir = dirname(coreDir); // src/ or dist/
@@ -65,8 +57,10 @@ export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
 export function scopeRoot(scope) {
+    // The builtin scope has no scope-root dir: its only content is memory
+    // (builtinMemoryRoot) and views (builtinViewsRoot), both hard special cases.
     if (scope === 'builtin')
-        return builtinSkillsRoot();
+        return null;
     return scope === 'user' ? userScopeRoot() : projectScopeRoot();
 }
 export function requireScopeRoot(scope) {
@@ -98,15 +92,20 @@ export function scopeSkillsDir(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. */
+ *  special case — its own package dir (builtinMemoryRoot), since the builtin
+ *  scope has no scopeRoot — 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 a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export function pluginMemoryDir(plugin) {
+    return join(plugin.root, 'memory');
+}
 /** 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. */

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

@@ -0,0 +1,28 @@
+import { type Rung, type SubstrateDoc } from './schema.js';
+/** The reserved basename (no extension) that marks a directory's index doc. */
+export declare const INDEX_NAME = "INDEX";
+/** Does this path-derived name denote a directory INDEX (`taste/INDEX`, or a
+ *  top-level `INDEX`)? */
+export declare function isIndexName(name: string): boolean;
+/** The directory an INDEX doc represents: `taste/INDEX` → `taste`, `INDEX` → ''. */
+export declare function indexDirOf(name: string): string;
+/** The name a doc renders under in agent-facing surfaces: an INDEX doc renders
+ *  under its directory name (the dir entry); every other doc keeps its name. */
+export declare function displayName(name: string): string;
+/** The two visibility surfaces an INDEX can cap. */
+export type Surface = 'systemPromptVisibility' | 'fileReadVisibility';
+/** Build the dir → governing-INDEX map. Precedence is first-occurrence-wins, so
+ *  callers MUST pass docs precedence-ordered (project > user > builtin) — the
+ *  highest-precedence INDEX governs a dir, mirroring the memory resolver. */
+export declare function buildCeilingIndex(docs: SubstrateDoc[]): Map<string, SubstrateDoc>;
+/** A doc's effective rung on `surface` after applying every ancestor INDEX
+ *  ceiling: min(own rung, each ancestor INDEX's rung). A `none` ancestor INDEX
+ *  hides the whole subtree (min with none = none). */
+export declare function effectiveRung(doc: SubstrateDoc, ceil: Map<string, SubstrateDoc>, surface: Surface): Rung;
+/** Apply ceilings to a doc list for a surface: each doc gets its effective rung
+ *  on `surface` written back into that field, and INDEX docs are renamed to
+ *  their dir entry. Returns NEW objects only where something changed (cheap,
+ *  preserves identity for untouched docs). Does NOT drop `none`-rung docs — the
+ *  caller filters per surface (boot drops them; node-local intentionally keeps
+ *  them). */
+export declare function applyCeilings(docs: SubstrateDoc[], surface: Surface): SubstrateDoc[];

package/dist/core/substrate/ceiling.js

@@ -0,0 +1,87 @@
+// ceiling.ts — INDEX.md dir-level entries and the subtree rung ceiling.
+//
+// A directory under a memory store may carry an `INDEX.md` with the SAME
+// substrate frontmatter as any doc. That file makes the directory a first-class
+// substrate entry: it renders as ONE entry at dir level (headed by the dir
+// name, not `…/INDEX`), and its rung is a CEILING for everything in its subtree.
+//
+//   effective rung of a descendant = min(own rung, every ancestor INDEX's rung)
+//
+// So a dir's INDEX at `preview` lets its files surface at most at `preview`; an
+// INDEX at `none` hides the whole subtree. This is the single, explicit
+// mechanism for collapsing a directory in agent-facing surfaces (boot render +
+// on-read) — there is no parallel auto-hiding heuristic. See design taste:
+// `crtr memory read taste/document-substrate`.
+import { rungRank } from './schema.js';
+/** The reserved basename (no extension) that marks a directory's index doc. */
+export const INDEX_NAME = 'INDEX';
+/** Does this path-derived name denote a directory INDEX (`taste/INDEX`, or a
+ *  top-level `INDEX`)? */
+export function isIndexName(name) {
+    return name === INDEX_NAME || name.endsWith('/' + INDEX_NAME);
+}
+/** The directory an INDEX doc represents: `taste/INDEX` → `taste`, `INDEX` → ''. */
+export function indexDirOf(name) {
+    return name === INDEX_NAME ? '' : name.slice(0, name.length - INDEX_NAME.length - 1);
+}
+/** The name a doc renders under in agent-facing surfaces: an INDEX doc renders
+ *  under its directory name (the dir entry); every other doc keeps its name. */
+export function displayName(name) {
+    return isIndexName(name) ? indexDirOf(name) : name;
+}
+/** Build the dir → governing-INDEX map. Precedence is first-occurrence-wins, so
+ *  callers MUST pass docs precedence-ordered (project > user > builtin) — the
+ *  highest-precedence INDEX governs a dir, mirroring the memory resolver. */
+export function buildCeilingIndex(docs) {
+    const m = new Map();
+    for (const d of docs) {
+        if (!isIndexName(d.name))
+            continue;
+        const dir = indexDirOf(d.name);
+        if (!m.has(dir))
+            m.set(dir, d);
+    }
+    return m;
+}
+function minRung(a, b) {
+    return rungRank(a) <= rungRank(b) ? a : b;
+}
+/** Ancestor directory names of a doc, nearest-last: `a/b/c` → [`a/b`, `a`];
+ *  `a` → []. An INDEX doc's OWN dir is included (a self-cap is a no-op), so a
+ *  nested INDEX still inherits its parents' ceilings. */
+function ancestorDirs(name) {
+    const parts = name.split('/');
+    parts.pop(); // drop the leaf
+    const out = [];
+    for (let i = parts.length; i > 0; i--)
+        out.push(parts.slice(0, i).join('/'));
+    return out;
+}
+/** A doc's effective rung on `surface` after applying every ancestor INDEX
+ *  ceiling: min(own rung, each ancestor INDEX's rung). A `none` ancestor INDEX
+ *  hides the whole subtree (min with none = none). */
+export function effectiveRung(doc, ceil, surface) {
+    let rung = doc[surface];
+    for (const dir of ancestorDirs(doc.name)) {
+        const idx = ceil.get(dir);
+        if (idx)
+            rung = minRung(rung, idx[surface]);
+    }
+    return rung;
+}
+/** Apply ceilings to a doc list for a surface: each doc gets its effective rung
+ *  on `surface` written back into that field, and INDEX docs are renamed to
+ *  their dir entry. Returns NEW objects only where something changed (cheap,
+ *  preserves identity for untouched docs). Does NOT drop `none`-rung docs — the
+ *  caller filters per surface (boot drops them; node-local intentionally keeps
+ *  them). */
+export function applyCeilings(docs, surface) {
+    const ceil = buildCeilingIndex(docs);
+    return docs.map((d) => {
+        const rung = effectiveRung(d, ceil, surface);
+        const name = displayName(d.name);
+        if (rung === d[surface] && name === d.name)
+            return d;
+        return { ...d, [surface]: rung, name };
+    });
+}

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

@@ -3,5 +3,7 @@ export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';
 export { gatePasses } from './gate.js';
+export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, applyCeilings, } from './ceiling.js';
+export type { Surface } from './ceiling.js';
 export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -14,5 +14,6 @@ KIND_DEFAULT_RUNGS,
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
+export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, applyCeilings, } from './ceiling.js';
 export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

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

@@ -36,7 +36,7 @@ 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 { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, 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
@@ -264,6 +264,18 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
     // 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.
@@ -276,7 +288,11 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
         try {
             if (!gatePasses(c.doc, subject))
                 continue; // gated out for this node
-            block = renderDocEnvelope(c.doc, absReadFile);
+            const rung = 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, absReadFile);
         }
         catch {
             continue; // a single bad doc never breaks the read

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

@@ -1,8 +1,7 @@
 /** 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. */
+ *  one compact, plugin-grouped catalog; `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
@@ -14,8 +13,7 @@ export declare function renderPreferencesSection(nodeId: string): string;
  *  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.
+ *  each a `###` sub-section. 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),

package/dist/core/substrate/render.js

@@ -5,8 +5,7 @@
 //     (renderPreferencesSection) — strings the D2 `before_agent_start` extension
 //     splices into the system prompt (built by a sibling AFTER this module);
 //   • the `<crtr-context>` half — `## References` (renderReferencesBlock) — the
-//     string wired into bearings.ts's session_start message, REPLACING the old
-//     `<memory>` block.
+//     string wired into bearings.ts's session_start message.
 //
 // Every doc flows through the same pipeline (design §4/§6/§9):
 //   MemoryDoc → parseSubstrateDoc → (null-filter non-substrate) →
@@ -19,14 +18,13 @@
 // null for a non-substrate doc and is `.filter()`ed out; per-file loads are
 // wrapped so one bad file is skipped, not fatal.
 import { relative, sep } from 'node:path';
-import { SCOPE_SKILL_PLUGIN } from '../../types.js';
-import { listAllPlugins, listAllSkills } from '../resolver.js';
+import { listAllPlugins } from '../resolver.js';
 import { renderCatalogSection } from '../../commands/skill/shared.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
-import { assembleNodeSubject, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
+import { applyCeilings, assembleNodeSubject, gatePasses, isIndexName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
 import { cachedAllPlugins, cachedNodeSubject, cachedSubstrateDocs, } from './session-cache.js';
 // ---------------------------------------------------------------------------
 // The shared per-doc pipeline.
@@ -36,7 +34,12 @@ import { cachedAllPlugins, cachedNodeSubject, cachedSubstrateDocs, } from './ses
  *  system-prompt rung above `none`. Resolver = user + project + builtin scopes
  *  (precedence-ordered); node-local is loaded separately (see nodeLocalDocs).
  *  Uses the per-session cache so the full corpus is scanned+parsed at most once
- *  per session across the three boot-render calls. */
+ *  per session across the three boot-render calls.
+ *
+ *  Ceilings are applied over the WHOLE corpus (cross-kind) BEFORE the kind
+ *  filter: an INDEX.md renders as its dir entry (`taste`, not `taste/INDEX`) at
+ *  its own rung, and every descendant's rung is capped by its ancestor INDEX
+ *  rungs — a `none` dir hides its whole subtree. */
 function resolverDocs(subject, kind) {
     let docs;
     try {
@@ -45,19 +48,25 @@ function resolverDocs(subject, kind) {
     catch {
         return [];
     }
-    return docs
+    return applyCeilings(docs, 'systemPromptVisibility')
         .filter((d) => d.kind === kind)
         .filter((d) => gatePasses(d, subject))
-        .filter((d) => d.systemPromptVisibility !== 'none');
+        .filter((d) => d.systemPromptVisibility !== 'none')
+        // Re-sort after the INDEX rename (taste/INDEX → taste) so a dir entry sorts
+        // immediately BEFORE its children, keeping scope precedence (project > user
+        // > builtin) intact.
+        .sort((a, b) => scopeRank(a.scope) - scopeRank(b.scope) || a.name.localeCompare(b.name));
+}
+function scopeRank(scope) {
+    return scope === 'project' ? 0 : scope === 'user' ? 1 : 2;
 }
 /** The node-local memory docs eligible at boot. Node-local memory lives in the
  *  canvas home (`nodes/<id>/context/memory/`) and is OUTSIDE the scope resolver,
  *  so it is loaded directly here, its raw frontmatter run through
  *  parseSubstrateFrontmatter (mirroring the resolver pipeline), then gate-passed.
- *  Old-format / non-substrate files (incl. the MEMORY.md index, which has no
- *  `kind`) parse to null and drop out. Returned across ALL kinds — node-local is
- *  the catch-all this-node store and rides into the references block as the
- *  replacement for the old node-local `<memory>` stanza.
+ *  Non-substrate files (those with no `kind`) parse to null and drop out.
+ *  Returned across ALL kinds — node-local is the catch-all this-node store and
+ *  rides into the references block.
  *
  *  IMPORTANT: node-local docs are NOT filtered by `systemPromptVisibility` rung.
  *  A migrated node-local reference defaults to rung `none`, which would make it
@@ -116,50 +125,49 @@ function renderSubSection(d) {
 // ---------------------------------------------------------------------------
 // 1. Skills section — `## Skills` (system prompt).
 // ---------------------------------------------------------------------------
-/** The compact, group-collapsed `name`-rung catalog: the UNION of name-rung
- *  substrate `skill` docs (the migrated scope-local + builtin skills, rendered
- *  as scope-local `_` entries) WITH plugin/marketplace skills (which stay
- *  resolver-provided, NOT migrated — named-plugin skills at user/project scope;
- *  the SCOPE_SKILL_PLUGIN sentinel and builtin scope are EXCLUDED because they
- *  become substrate docs). Reuses skill/shared.ts's renderCatalogSection
- *  group-collapse so the boot catalog matches today's `<skills count=N>` shape.
- *  Returns '' when nothing is in the catalog. */
-function renderSkillCatalog(nameRungSkillDocs) {
-    let pluginSkills;
-    try {
-        pluginSkills = listAllSkills().filter((s) => s.enabled && s.plugin !== SCOPE_SKILL_PLUGIN && s.scope !== 'builtin');
-    }
-    catch {
-        pluginSkills = [];
-    }
-    const entries = [
-        ...pluginSkills.map((s) => ({ scope: s.scope, plugin: s.plugin, name: s.name })),
-        ...nameRungSkillDocs.map((d) => ({ scope: d.scope, plugin: SCOPE_SKILL_PLUGIN, name: d.name })),
-    ];
-    if (entries.length === 0)
-        return '';
-    // Group by scope+plugin → forest-root names (drop nested children), mirroring
-    // buildSkillCatalog's source construction.
+/** The compact, group-collapsed `name`-rung catalog of substrate `skill` docs.
+ *  Every leaf is a migrated/generated substrate doc (native, builtin, or a
+ *  plugin's `<pluginName>/` subtree) — there is no second, resolver-provided
+ *  skill corpus. Each doc self-groups by its top-dir segment: a name with a
+ *  slash sources to its top segment (the plugin name); a bare name sources to
+ *  '' (a scope-local native/builtin skill). A plugin whose INDEX is elevated to
+ *  preview/content renders as its own `### <plugin>` subsection, so its catalog
+ *  group is dropped here (via `elevatedSources`) to avoid a double render.
+ *  Reuses skill/shared.ts's renderCatalogSection group-collapse. Returns ''
+ *  when nothing is in the catalog. */
+function renderSkillCatalog(nameRungSkillDocs, elevatedSources) {
     const bySource = new Map();
-    for (const e of entries) {
-        const key = `${e.scope}\t${e.plugin}`;
-        const arr = bySource.get(key);
-        if (arr)
-            arr.push(e);
+    for (const d of nameRungSkillDocs) {
+        // INDEX docs are structural ceilings (already renamed to their dir entry by
+        // applyCeilings), never catalog leaves — drop defensively.
+        if (isIndexName(d.name))
+            continue;
+        const slash = d.name.indexOf('/');
+        const plugin = slash === -1 ? '' : d.name.slice(0, slash);
+        const leaf = slash === -1 ? d.name : d.name.slice(slash + 1);
+        // A plugin represented by its own elevated ### subsection is dropped from the
+        // catalog so it is not rendered twice.
+        if (plugin !== '' && elevatedSources.has(plugin))
+            continue;
+        const key = `${d.scope}\t${plugin}`;
+        const src = bySource.get(key);
+        if (src)
+            src.roots.push(leaf);
         else
-            bySource.set(key, [e]);
+            bySource.set(key, { scope: d.scope, plugin, roots: [leaf] });
     }
+    if (bySource.size === 0)
+        return '';
     const projectSources = [];
     const userSources = [];
-    for (const [key, group] of bySource) {
-        const [scope, plugin] = key.split('\t');
-        const names = group.map((g) => g.name);
-        const roots = names
-            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
+    for (const { scope, plugin, roots } of bySource.values()) {
+        // Drop nested children so each source contributes only its top-level skills.
+        const top = roots
+            .filter((n) => !roots.some((m) => m !== n && n.startsWith(m + '/')))
             .sort();
-        if (roots.length === 0)
+        if (top.length === 0)
             continue;
-        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
+        (scope === 'project' ? projectSources : userSources).push({ plugin, roots: top });
     }
     const descriptions = new Map();
     try {
@@ -182,19 +190,21 @@ function renderSkillCatalog(nameRungSkillDocs) {
 }
 /** 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. */
+ *  one compact, plugin-grouped catalog; `preview`/`content`-rung skills each get
+ *  a `###` sub-section. Returns '' when nothing is eligible. */
 export function renderSkillsSection(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
     const skills = resolverDocs(subject, 'skill');
-    const catalog = renderSkillCatalog(skills.filter((d) => d.systemPromptVisibility === 'name'));
-    const elevated = skills
-        .filter((d) => d.systemPromptVisibility !== 'name')
-        .map(renderSubSection);
-    const blocks = [catalog, ...elevated].filter((s) => s !== '');
+    const elevated = skills.filter((d) => d.systemPromptVisibility !== 'name');
+    // A plugin whose INDEX is elevated surfaces as its own `### <plugin>`
+    // subsection (its display name is the plugin/dir name after ceiling rename);
+    // the catalog drops that plugin's group so it is not rendered twice.
+    const elevatedSources = new Set(elevated.map((d) => d.name));
+    const catalog = renderSkillCatalog(skills.filter((d) => d.systemPromptVisibility === 'name'), elevatedSources);
+    const elevatedBlocks = elevated.map(renderSubSection);
+    const blocks = [catalog, ...elevatedBlocks].filter((s) => s !== '');
     if (blocks.length === 0)
         return '';
     return `## Skills\n\n${blocks.join('\n\n')}`;
@@ -225,8 +235,7 @@ export function renderPreferencesSection(nodeId) {
  *  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.
+ *  each a `###` sub-section. 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),

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

@@ -21,15 +21,17 @@ export declare const KIND_DEFAULT_RUNGS: Record<DocKind, {
  *  `all`/`any`/`not` combinators (design §4). */
 export type GatePredicate = Record<string, unknown>;
 /** The frontmatter-derived schema of a substrate document, with kind-aware
- *  defaults applied. Required fields (`kind`/`when`/`why`) and optionals all
- *  resolved to concrete typed values. */
+ *  defaults applied. Required fields (`kind`/`when-and-why-to-read`) and
+ *  optionals all resolved to concrete typed values. */
 export interface SubstrateSchema {
     /** Which of the three semantic kinds. */
     kind: DocKind;
-    /** Routing condition — "When you are in a situation like X…" (design §4). */
-    when: string;
-    /** Payoff — "…because Z." Half of the generated preview line. */
-    why: string;
+    /** The read-routing line — a single sentence answering WHEN to read this doc
+     *  and WHY it is worth the read: "When <circumstance>, this <kind> should be
+     *  read <because <payoff>>." (design §4). This is read-routing — why an agent
+     *  should spend the read — NEVER justification of why the content should be
+     *  obeyed. It IS the preview verbatim. Frontmatter key `when-and-why-to-read`. */
+    whenAndWhyToRead: string;
     /** Human-facing abbreviation for `crtr memory list`. NEVER loaded into an
      *  agent's context (design §3). Empty string when absent. */
     shortForm: string;
@@ -62,15 +64,18 @@ export interface SubstrateDoc extends SubstrateSchema {
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
  *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
- *  the kind default), so a renderer mapping over many docs never throws. */
+ *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
+ *  falls back to the kind default), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
 export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
  *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc
  *  (no valid `kind`), so callers can `docs.map(parseSubstrateDoc).filter(...)`. */
 export declare function parseSubstrateDoc(doc: MemoryDoc): SubstrateDoc | null;
-/** The generated `preview`-rung routing line (design §4), composed from the two
- *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
- *  Both boot and on-read render render this identical line, so it lives once
- *  here to prevent drift. Light cleanup avoids doubled punctuation. */
-export declare function previewLine(doc: Pick<SubstrateSchema, 'kind' | 'when' | 'why'>): string;
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
+export declare function previewLine(doc: Pick<SubstrateSchema, 'whenAndWhyToRead'>): string;

package/dist/core/substrate/schema.js

@@ -50,8 +50,9 @@ export const KIND_DEFAULT_RUNGS = {
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
  *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
- *  the kind default), so a renderer mapping over many docs never throws. */
+ *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
+ *  falls back to the kind default), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
 export function parseSubstrateFrontmatter(fm) {
     if (fm === null)
         return null;
@@ -61,8 +62,7 @@ export function parseSubstrateFrontmatter(fm) {
     const defaults = KIND_DEFAULT_RUNGS[kind];
     return {
         kind,
-        when: strField(fm.when),
-        why: strField(fm.why),
+        whenAndWhyToRead: strField(fm['when-and-why-to-read']),
         shortForm: strField(fm['short-form']),
         systemPromptVisibility: parseRung(fm['system-prompt-visibility'], defaults.systemPrompt),
         fileReadVisibility: parseRung(fm['file-read-visibility'], defaults.fileRead),
@@ -79,14 +79,15 @@ export function parseSubstrateDoc(doc) {
         return null;
     return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body };
 }
-/** The generated `preview`-rung routing line (design §4), composed from the two
- *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
- *  Both boot and on-read render render this identical line, so it lives once
- *  here to prevent drift. Light cleanup avoids doubled punctuation. */
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
 export function previewLine(doc) {
-    const when = doc.when.trim().replace(/[.,]+$/, '');
-    const why = doc.why.trim().replace(/\.+$/, '');
-    return `${when}, read this ${doc.kind}. ${why}.`;
+    const line = doc.whenAndWhyToRead.trim().replace(/\.+$/, '');
+    return line === '' ? '' : `${line}.`;
 }
 // ---------------------------------------------------------------------------
 // Field coercion helpers (private).

package/dist/pi-extensions/canvas-context-intro.js

@@ -15,9 +15,11 @@
 //
 // The block carries: the path to the node's own context dir and the framing for
 // what belongs there (a shared document store for the other nodes). EVERY node
-// also gets a <memory> block merging the indexes of its three scoped memory
-// stores (user-global, project, node-local), each labeled with its dir — one
-// consistent surface, since every node is born with all three stores. An
+// also gets a `## References` block rendered from the document substrate —
+// eligible `reference` docs at their system-prompt visibility rung, plus the
+// node's own node-local substrate docs — so the bearings name what to read on
+// demand. (Skills and preferences surface as their own `## Skills` /
+// `## Preferences` sections of the system prompt, not in this block.) An
 // orchestrator additionally gets the across-refresh-cycles framing (the one
 // thing a terminal worker's bearings drop). The prose lives in
 // core/runtime/bearings.ts (shared with the promotion guidance dump).

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -43,8 +43,24 @@ import { getNode } from '../core/canvas/index.js';
 // one watcher is live. Pattern copied verbatim from agent-inbox-watcher.ts.
 // ---------------------------------------------------------------------------
 let liveTimer;
-const TICK_MS = 800; // polling cadence
-const DEBOUNCE_MS = 1000; // flush once the burst has been quiet for this long
+const DEFAULT_TICK_MS = 800; // polling cadence
+const DEFAULT_DEBOUNCE_MS = 1000; // flush once the burst has been quiet for this long
+// Testability seam: a test can inject a much shorter cadence so it doesn't have
+// to sleep against the real ~800ms/1000ms wall-clock timing. Read per-registration
+// (not as an import-time module const) so each registerCanvasInboxWatcher() call
+// picks up the env current at that moment. Unset → production defaults.
+function resolveCadence() {
+    const parse = (raw, fallback) => {
+        if (raw === undefined)
+            return fallback;
+        const n = Number(raw);
+        return Number.isFinite(n) && n > 0 ? n : fallback;
+    };
+    return {
+        tickMs: parse(process.env['CRTR_WATCHER_TICK_MS'], DEFAULT_TICK_MS),
+        debounceMs: parse(process.env['CRTR_WATCHER_DEBOUNCE_MS'], DEFAULT_DEBOUNCE_MS),
+    };
+}
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
@@ -56,6 +72,7 @@ const DEBOUNCE_MS = 1000; // flush once the burst has been quiet for this long
  * the module-level liveTimer guard is the actual stacking prevention.
  */
 export function registerCanvasInboxWatcher(pi) {
+    const { tickMs: TICK_MS, debounceMs: DEBOUNCE_MS } = resolveCadence();
     // Capture the latest event context so isIdle() is readable inside the timer
     // callback, which has no ctx of its own.
     let lastCtx;