@crouton-kit/crouter 0.3.23 → 0.3.25

package/dist/builtin-personas/orchestration-kernel.md

@@ -50,13 +50,13 @@ Larger artifacts — specs, plans, exploration findings, test recipes — live a
 
 Separate from the roadmap (your live plan and state) you have a persistent document substrate that outlasts any single roadmap: skills you adopt, preferences about how you work, references to external resources, and facts about the human and the project. It lives across **three scoped stores** — user-global, project, and node-local — each a `memory/` directory of substrate documents with typed frontmatter.
 
-**Reading.** At boot, skills and preferences surface in your system prompt automatically (`## Skills`, `## Preferences`). References surface in your `<crtr-context>` block (`## References`). To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
+**Reading.** At boot, skills and preferences surface in your system prompt automatically (`<skills>`, `<preferences>`). References surface in your `<crtr-context>` block (`<references>`). Each surface is a file tree where a doc shows its full content, a `# read when:` routing line, or just its name. To browse the full inventory: `crtr memory list`. To search by topic: `crtr memory find <query>`. To load a document by name: `crtr memory read <name>`.
 
 **Writing.** Use `crtr memory write` to create or update a document. Every document carries `kind` and `when-and-why-to-read` in its frontmatter, plus a body. `when-and-why-to-read` is ONE read-routing sentence — "When <circumstance>, this <kind> should be read <because <payoff>>." — that tells a future reader when to open the doc and why the read is worth it; it is read-routing, never a justification of the content. It becomes the preview line verbatim. The `kind` governs which section it surfaces in at boot and how it loads:
 
-- `skill` — a workflow or methodology to adopt. Surfaces by name in `## Skills`; load with `crtr memory read`.
-- `preference` — how you should work. Surfaces as a `###` routing line in `## Preferences` at boot (default `system-prompt-visibility: preview`).
-- `reference` — a fact, pointer, or constraint. Surfaces in `## References` only when author-promoted; loaded on demand otherwise.
+- `skill` — a workflow or methodology to adopt. Surfaces by name in `<skills>`; load with `crtr memory read`.
+- `preference` — how you should work. Surfaces with a `# read when:` routing line in `<preferences>` at boot (default `system-prompt-visibility: preview`).
+- `reference` — a fact, pointer, or constraint. Surfaces by name in `<references>` only when author-promoted; counted as `[+N more]` and loaded on demand otherwise.
 
 The scope decides which nodes see the document. `user` scope loads into every orchestrator everywhere. `project` scope loads into orchestrators working in this repo. `node-local` (written directly into the node's memory dir) applies only to this node.
 

package/dist/commands/skill/shared.d.ts

@@ -1,8 +1,3 @@
 import type { Scope } from '../../types.js';
 export declare function resolveWriteScope(scopeStr: string | undefined): Scope;
 export declare const VALID_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
-export type CatalogSource = {
-    plugin: string;
-    roots: string[];
-};
-export declare function renderCatalogSection(label: string, sources: CatalogSource[], descriptions: Map<string, string>, out: string[]): void;

package/dist/commands/skill/shared.js

@@ -17,84 +17,3 @@ export function resolveWriteScope(scopeStr) {
 // Valid skill types (used by author sub-branch)
 // ---------------------------------------------------------------------------
 export const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
-const CATALOG_T = 5;
-export function renderCatalogSection(label, sources, descriptions, out) {
-    if (sources.length === 0)
-        return;
-    const count = sources.reduce((n, s) => n + s.roots.length, 0);
-    out.push('');
-    out.push(`${label} (${count})`);
-    const named = [...sources].sort((a, b) => a.plugin.localeCompare(b.plugin));
-    if (named.length === 0)
-        return;
-    const classified = named.map((s) => {
-        const subcats = new Map();
-        const bare = [];
-        for (const n of s.roots) {
-            const slash = n.indexOf('/');
-            if (slash === -1) {
-                bare.push(n);
-            }
-            else {
-                const sub = n.slice(0, slash);
-                const rest = n.slice(slash + 1);
-                const arr = subcats.get(sub);
-                if (arr)
-                    arr.push(rest);
-                else
-                    subcats.set(sub, [rest]);
-            }
-        }
-        return { plugin: s.plugin, roots: s.roots, subcats, bare };
-    });
-    const descSuffix = (plugin) => {
-        const d = descriptions.get(plugin);
-        if (!d)
-            return '';
-        return ` — ${d.length > 80 ? d.slice(0, 77) + '…' : d}`;
-    };
-    // inlineW aligns the count column for collapsed + inline-enumerated plugins
-    // (nested plugins render their own header line, don't use this width)
-    const inlineW = classified
-        .filter((p) => {
-        const direct = p.subcats.size + p.bare.length;
-        return direct > CATALOG_T || p.subcats.size < 2;
-    })
-        .reduce((m, p) => Math.max(m, p.plugin.length + 1), 0);
-    for (const p of classified) {
-        // Bare native/builtin skills (no plugin namespace) carry sourceKey ''.
-        // Render them as flat lines, never under a stray '/' header.
-        if (p.plugin === '') {
-            for (const r of [...p.roots].sort())
-                out.push(`  ${r}`);
-            continue;
-        }
-        const direct = p.subcats.size + p.bare.length;
-        if (direct > CATALOG_T) {
-            out.push(`  ${(p.plugin + '/').padEnd(inlineW)}  ${p.roots.length} skills${descSuffix(p.plugin)}`);
-            continue;
-        }
-        if (p.subcats.size >= 2) {
-            out.push(`  ${p.plugin}/`);
-            if (p.bare.length > 0) {
-                out.push(`    ${[...p.bare].sort().join(', ')}`);
-            }
-            const subKeys = [...p.subcats.keys()].sort();
-            const subW = subKeys
-                .map((k) => `${k}/`)
-                .reduce((m, l) => (l.length > m ? l.length : m), 0);
-            for (const subKey of subKeys) {
-                const children = p.subcats.get(subKey).sort();
-                if (children.length > CATALOG_T) {
-                    out.push(`    ${(subKey + '/').padEnd(subW)}  ${children.length} skills`);
-                }
-                else {
-                    out.push(`    ${(subKey + '/').padEnd(subW)}  ${children.join(', ')}`);
-                }
-            }
-        }
-        else {
-            out.push(`  ${(p.plugin + '/').padEnd(inlineW)}  ${[...p.roots].sort().join(', ')}`);
-        }
-    }
-}

package/dist/core/__tests__/context-intro.test.js

@@ -1,6 +1,6 @@
 // Tests for the <crtr-context> bearings preamble:
-//   1. Worker and orchestrator bearings carry the `## References` block
-//      (substrate reference docs + node-local docs as `###` sub-sections).
+//   1. Worker and orchestrator bearings carry the `<references>` block
+//      (substrate reference docs + node-local docs as a file tree).
 //      Orchestrators add the across-cycles framing; promotion delivers that
 //      same orchestrator context-dir framing to a node that spawned base.
 //   2. canvas-context-intro injects the block as its own session message at
@@ -34,10 +34,10 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('worker bearings: base framing + ## References block, NO across-cycles framing', () => {
+test('worker bearings: base framing + <references> block, NO across-cycles framing', () => {
     // Bug-regression: review finding M1 — buildContextBearings renders the
-    // ## References block (renderReferencesBlock): ## References + ### <name>
-    // sub-sections. This test locks in that contract.
+    // <references> block (renderReferencesBlock): a kind-wrapped file tree of
+    // reference docs. This test locks in that contract.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     // Seed a node-local substrate doc so the ## References block is non-empty.
     const dir = memoryDir(meta.node_id);
@@ -46,21 +46,25 @@ test('worker bearings: base framing + ## References block, NO across-cycles fram
     const block = buildContextIntro(meta.node_id);
     assert.match(block, new RegExp(`<crtr-context dir="${contextDir(meta.node_id)}">`));
     assert.match(block, /shared document store, not a task tracker/, 'base = shared docs, not tasks');
-    // Reference content renders ONLY as ## References + ### sub-sections.
+    // Reference content renders ONLY as the <references> file-tree block.
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
     // Per-store stanza headers (label · dir) never appear.
     assert.doesNotMatch(block, /user-global · /, 'no user-global label·dir stanza');
     assert.doesNotMatch(block, /node-local · /, 'no node-local label·dir stanza');
     // No (empty) placeholder marker.
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) placeholder');
-    assert.match(block, /## References\n\n###/, '## References followed by ### sub-sections');
+    assert.match(block, /<references>/, '<references> block present');
+    assert.match(block, /\nreferences\n/, 'tree headed by the `references` root label');
+    // The node-local preview-rung doc renders as a tree entry with a `# read when:`
+    // routing line (verbatim previewLine output).
+    assert.match(block, /test-ref {2}# read when: When testing, this reference should be read because it is a regression fixture\./, 'node-local preview doc renders its routing line');
     // A terminal worker must NOT carry the orchestrator across-cycles framing.
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; a non-substrate .md file is never inlined', () => {
-    // Bug-regression: review finding M1 — buildContextBearings renders ## References.
-    // Node-local substrate docs render as ### sub-sections at their rung; a
+test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into <references>; a non-substrate .md file is never inlined', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders <references>.
+    // Node-local substrate docs render as tree entries at their rung; a
     // non-substrate .md file (no frontmatter `kind`) never surfaces.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode — the across-cycles gate
@@ -75,9 +79,8 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.match(block, /shared document store, not a task tracker/, 'still carries the base framing');
     assert.match(block, /refresh cycles/, 'orchestrator gets the across-cycles framing');
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
-    assert.match(block, /## References\n/, 'references block present');
-    assert.match(block, /### flaky-build\n/, 'node-local doc gets its ### sub-section');
-    assert.match(block, /When the build flakes, this reference should be read because the first run fails\./, 'preview rung renders the routing line');
+    assert.match(block, /<references>/, 'references block present');
+    assert.match(block, /flaky-build {2}# read when: When the build flakes, this reference should be read because the first run fails\./, 'node-local doc renders as a tree entry with its routing line');
     // The non-substrate file never renders: no header line, no pointer line, no path.
     assert.ok(!block.includes('# memory index'), 'the index header comment is NOT inlined');
     assert.ok(!block.includes('- [Flaky build](flaky-build.md)'), 'index pointer lines are NOT inlined');
@@ -85,12 +88,12 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.ok(!block.includes('node-local · '), 'no label·dir stanza header');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a ### title stub', () => {
-    // Bug-regression: review findings M1 + M6 — the ## References block carries no
+test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a bare-name tree entry', () => {
+    // Bug-regression: review findings M1 + M6 — the <references> block carries no
     // per-store `label · dir` stanzas or (empty) markers, and node-local docs are
     // NOT filtered on rung: a migrated node-local reference defaults
-    // system-prompt-visibility: none and must still ride into ## References as
-    // its bare title (never its body).
+    // system-prompt-visibility: none and must still ride into <references> as
+    // its bare name (floored to the `name` rung; never its body).
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode
     const dir = memoryDir(meta.node_id);
@@ -103,9 +106,9 @@ test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-non
     assert.ok(!block.includes('project · '), 'no project stanza header');
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) markers');
     assert.ok(!block.includes('MEMORY.md'), 'no MEMORY.md path in the block');
-    // M6: rung-none node-local doc surfaces as its title stub only.
-    assert.match(block, /### rung-none-fact\s*\n/, 'rung-none node-local doc surfaces as its title stub');
-    assert.ok(!block.includes('body that must not render'), 'none rung renders the title only, not the body');
+    // M6: rung-none node-local doc surfaces as a bare-name tree entry only.
+    assert.match(block, /─ rung-none-fact\n/, 'rung-none node-local doc surfaces as a bare-name tree entry');
+    assert.ok(!block.includes('body that must not render'), 'none rung renders the name only, not the body');
 });
 test('promotion guidance delivers the orchestrator context-dir framing', () => {
     // A node spawns as a base worker (no orchestrator bearings). On promotion the

package/dist/core/__tests__/memory-resolver.test.d.ts

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

package/dist/core/__tests__/memory-resolver.test.js

@@ -0,0 +1,108 @@
+// Regression test for the namespaced plugin-doc READ path in resolveMemoryDoc.
+//
+// Bug (substrate-unification cut f1b071b, fixed by 945d121): plugin memory docs
+// mount at a virtual `<pluginName>/` namespace and ARE enumerated by
+// listAllMemoryDocs, so `crtr memory list` advertises canonical names like
+// `claude-capture/capture`. But findMemoryMatches (the direct-path lookup inside
+// resolveMemoryDoc) only searched the NATIVE scopeMemoryDir, never each plugin's
+// pluginMemoryDir — so `crtr memory read <plugin>/<leaf>` returned not_found for
+// a name that `list` had just shown. Only the bare-leaf fallback (`read capture`)
+// resolved. The fix taught findMemoryMatches to resolve `<plugin>/<rest>` against
+// each enabled plugin's pluginMemoryDir, native-before-plugin precedence kept.
+//
+// Follow-up bug (same seat): the `<plugin>/<rest>` branch required a non-empty
+// rest (`if (slash <= 0) continue`), so a BARE plugin name never tried the
+// plugin-root INDEX.md — `read claude-godot-prompter` / `read ai` returned
+// not_found even though `<plugin>/INDEX` and `<plugin>/<child>` resolved. The
+// fix resolves a bare plugin name to `<plugin>/memory/INDEX.md`, mirroring the
+// native bare-dir-name -> INDEX.md contract, native-before-plugin kept.
+//
+// This test FAILS on the pre-fix code (the fully-qualified and bare-plugin-name
+// reads throw notFound) and PASSES on the current code.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/memory-resolver.test.ts
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveMemoryDoc } from '../memory-resolver.js';
+import { resetScopeCache } from '../scope.js';
+// Fixture: a temp PROJECT scope (a `.crouter/` dir discovered by walking up from
+// cwd) holding both a native memory/ tree and one enabled fixture plugin whose
+// memory/ tree mounts under the `fixplug/` namespace.
+let projectDir;
+let prevCwd;
+const PLUGIN = 'fixplug';
+function doc(name) {
+    return `---\nkind: skill\nwhen-and-why-to-read: fixture doc ${name}\n---\n\n# ${name}\n`;
+}
+before(() => {
+    prevCwd = process.cwd();
+    projectDir = mkdtempSync(join(tmpdir(), 'crtr-memres-'));
+    const scopeRoot = join(projectDir, '.crouter');
+    // Native scope docs. `fixplug/shared` is a native SHADOW of a plugin doc of
+    // the same canonical name — it must win (native-before-plugin precedence).
+    const memDir = join(scopeRoot, 'memory');
+    mkdirSync(join(memDir, PLUGIN), { recursive: true });
+    writeFileSync(join(memDir, PLUGIN, 'shared.md'), doc('native-shared'));
+    // Fixture plugin: enabled manifest + a flat substrate doc and a nested one.
+    const pluginRoot = join(scopeRoot, 'plugins', PLUGIN);
+    mkdirSync(join(pluginRoot, '.crouter-plugin'), { recursive: true });
+    writeFileSync(join(pluginRoot, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: PLUGIN, version: '0.0.0' }));
+    const pluginMem = join(pluginRoot, 'memory');
+    mkdirSync(join(pluginMem, 'area'), { recursive: true });
+    writeFileSync(join(pluginMem, 'widget.md'), doc('plugin-widget'));
+    writeFileSync(join(pluginMem, 'area', 'zone.md'), doc('plugin-zone'));
+    writeFileSync(join(pluginMem, 'shared.md'), doc('plugin-shared'));
+    // Plugin-root INDEX.md: a BARE plugin name must resolve this (mirrors the
+    // native bare-dir-name -> INDEX.md contract for the plugin mount root).
+    writeFileSync(join(pluginMem, 'INDEX.md'), doc('plugin-root-index'));
+    // Explicitly enable the plugin in config (default is enabled, but be robust).
+    writeFileSync(join(scopeRoot, 'config.json'), JSON.stringify({ plugins: { [PLUGIN]: { enabled: true } } }));
+    // Point the scope resolver at the fixture: project scope is found by walking
+    // up from cwd, so chdir into the temp dir and clear the cached project root.
+    process.chdir(projectDir);
+    resetScopeCache();
+});
+after(() => {
+    process.chdir(prevCwd);
+    resetScopeCache();
+    rmSync(projectDir, { recursive: true, force: true });
+});
+test('fully-qualified <plugin>/<leaf> resolves to the plugin substrate doc', () => {
+    // Pre-fix this threw notFound (findMemoryMatches never searched pluginMemoryDir).
+    const d = resolveMemoryDoc(`${PLUGIN}/widget`);
+    assert.equal(d.name, `${PLUGIN}/widget`);
+    assert.ok(d.path.endsWith(join('plugins', PLUGIN, 'memory', 'widget.md')));
+});
+test('fully-qualified multi-segment <plugin>/<a>/<b> resolves the nested doc', () => {
+    // Pre-fix this also threw notFound.
+    const d = resolveMemoryDoc(`${PLUGIN}/area/zone`);
+    assert.equal(d.name, `${PLUGIN}/area/zone`);
+    assert.ok(d.path.endsWith(join('plugins', PLUGIN, 'memory', 'area', 'zone.md')));
+});
+test('the bare leaf still resolves via last-segment fallback', () => {
+    // This worked even pre-fix (leaf fallback scans listAllMemoryDocs, which DID
+    // enumerate plugin docs) — the gap was the direct fully-qualified path only.
+    const d = resolveMemoryDoc('widget');
+    assert.equal(d.name, `${PLUGIN}/widget`);
+});
+test('bare plugin name resolves the plugin-root INDEX.md', () => {
+    // Regression: findMemoryMatches skipped the plugin branch for a bare name
+    // (`if (slash <= 0) continue`), so a bare plugin name never tried the
+    // plugin-root INDEX.md and returned not_found — even though `<plugin>/INDEX`
+    // resolved. The fix resolves the bare mount root to <plugin>/memory/INDEX.md.
+    const d = resolveMemoryDoc(PLUGIN);
+    assert.equal(d.name, PLUGIN);
+    assert.ok(d.path.endsWith(join('plugins', PLUGIN, 'memory', 'INDEX.md')));
+});
+test('native doc wins over a plugin doc of the same canonical name', () => {
+    // native-before-plugin precedence: findMemoryMatches checks scopeMemoryDir
+    // before pluginMemoryDir, so the native shadow at memory/fixplug/shared.md
+    // wins over the plugin's memory/shared.md.
+    const d = resolveMemoryDoc(`${PLUGIN}/shared`);
+    assert.equal(d.name, `${PLUGIN}/shared`);
+    assert.ok(d.path.endsWith(join('memory', PLUGIN, 'shared.md')));
+    assert.ok(!d.path.includes(join('plugins', PLUGIN)));
+});

package/dist/core/memory-resolver.js

@@ -97,17 +97,48 @@ export function listAllMemoryDocs(scope) {
 function findMemoryMatches(name, scope) {
     const matches = [];
     for (const s of scopesInPrecedence(scope)) {
+        // Native scope memory dir first (native-before-plugin precedence).
         const dir = scopeMemoryDir(s);
-        if (!dir)
-            continue;
-        const path = join(dir, ...name.split('/')) + '.md';
-        if (pathExists(path)) {
-            matches.push(loadMemoryDoc(name, s, path));
-            continue;
+        if (dir) {
+            const path = join(dir, ...name.split('/')) + '.md';
+            if (pathExists(path)) {
+                matches.push(loadMemoryDoc(name, s, path));
+                continue;
+            }
+            const indexPath = join(dir, ...name.split('/'), 'INDEX.md');
+            if (pathExists(indexPath)) {
+                matches.push(loadMemoryDoc(name, s, indexPath));
+                continue;
+            }
+        }
+        // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
+        // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
+        // enumerates — `read` must resolve what `list` shows). A BARE plugin name
+        // (no slash) resolves the plugin-root INDEX.md, mirroring the native
+        // bare-dir-name -> INDEX.md contract for the plugin mount root.
+        const slash = name.indexOf('/');
+        const pluginName = slash > 0 ? name.slice(0, slash) : name;
+        const rest = slash > 0 ? name.slice(slash + 1) : '';
+        for (const p of listInstalledPlugins(s)) {
+            if (!p.enabled || p.name !== pluginName)
+                continue;
+            const pdir = pluginMemoryDir(p);
+            if (rest) {
+                const ppath = join(pdir, ...rest.split('/')) + '.md';
+                if (pathExists(ppath)) {
+                    matches.push(loadMemoryDoc(name, s, ppath));
+                    break;
+                }
+            }
+            // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
+            const pindex = rest
+                ? join(pdir, ...rest.split('/'), 'INDEX.md')
+                : join(pdir, 'INDEX.md');
+            if (pathExists(pindex)) {
+                matches.push(loadMemoryDoc(name, s, pindex));
+                break;
+            }
         }
-        const indexPath = join(dir, ...name.split('/'), 'INDEX.md');
-        if (pathExists(indexPath))
-            matches.push(loadMemoryDoc(name, s, indexPath));
     }
     return matches;
 }

package/dist/core/runtime/bearings.d.ts

@@ -56,6 +56,6 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
  *  framing rides for EVERY node; the across-cycles context-dir note is added
  *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
- *  resumes from. The `## References` block carries the substrate reference docs
+ *  resumes from. The `<references>` block carries the substrate reference docs
  *  + node-local docs. */
 export declare function buildContextBearings(nodeId: string): string;

package/dist/core/runtime/bearings.js

@@ -19,7 +19,7 @@
 // one place other nodes on the canvas can read from, so it is for documents
 // worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
 // you" stash (a terminal worker has no future cycle — that framing only makes
-// sense once a node is a resident orchestrator). The `## References` block
+// sense once a node is a resident orchestrator). The `<references>` block
 // (substrate reference docs + node-local docs) rides into the context message.
 //
 // Orchestrator addendum (gated on orchestrator MODE): the dir ALSO survives
@@ -145,7 +145,7 @@ export function buildWakeBearings(origin) {
  *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
  *  framing rides for EVERY node; the across-cycles context-dir note is added
  *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
- *  resumes from. The `## References` block carries the substrate reference docs
+ *  resumes from. The `<references>` block carries the substrate reference docs
  *  + node-local docs. */
 export function buildContextBearings(nodeId) {
     const identity = buildIdentityAssertion(nodeId);

package/dist/core/runtime/launch.d.ts

@@ -15,8 +15,8 @@ export declare const CANVAS_VIEW_PATH: string;
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
  *  message, once per brand-new chat), doc-substrate (the unified document
- *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
- *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  substrate's two hooks: <skills> + <preferences> + <memory-guidance> at boot,
+ *  on-read context injection), commands (the /promote slash-command), resume (the /resume-node
  *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
  *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it

package/dist/core/runtime/launch.js

@@ -42,8 +42,8 @@ export const CANVAS_VIEW_PATH = resolveExtension('canvas-view');
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
  *  message, once per brand-new chat), doc-substrate (the unified document
- *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
- *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  substrate's two hooks: <skills> + <preferences> + <memory-guidance> at boot,
+ *  on-read context injection), commands (the /promote slash-command), resume (the /resume-node
  *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
  *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it

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

@@ -19,10 +19,3 @@ export declare function buildCeilingIndex(docs: SubstrateDoc[]): Map<string, Sub
  *  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

@@ -69,19 +69,3 @@ export function effectiveRung(doc, ceil, 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,7 +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 { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
 export type { Surface } from './ceiling.js';
-export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -14,6 +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 { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

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

@@ -1,23 +1,22 @@
-/** The `## Skills` system-prompt section: every eligible `kind: skill` doc,
- *  rendered at its `system-prompt-visibility`. `name`-rung skills collapse into
- *  one compact, plugin-grouped catalog; `preview`/`content`-rung skills each get
- *  a `###` sub-section. Returns '' when nothing is eligible. */
+/** The `<skills>` system-prompt block: every eligible `kind: skill` doc placed
+ *  in one tree at its effective rung. Plugin skills (`<plugin>/…` names) fall out
+ *  naturally as dirs. Returns '' when nothing is eligible. */
 export declare function renderSkillsSection(nodeId: string): string;
-/** The `## Preferences` system-prompt section: every eligible `kind: preference`
- *  doc as its own `###` sub-section, at its `system-prompt-visibility` (the
- *  preference default rung is `preview` → the routing line). Returns '' when
- *  nothing is eligible. */
+/** The `<preferences>` system-prompt block: every eligible `kind: preference`
+ *  doc in one tree at its effective rung (the preference default rung is
+ *  `preview` → the routing line). Returns '' when nothing is eligible. */
 export declare function renderPreferencesSection(nodeId: string): string;
-/** The `## References` block embedded INSIDE the `<crtr-context>` session_start
- *  message (the bearings caller pushes the returned string into the block, or
- *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
- *  `system-prompt-visibility` (reference boot default is `none`, so only
- *  author-promoted references show) PLUS the node-local memory docs (any kind),
- *  each a `###` sub-section. Returns '' when nothing is eligible.
- *
- *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
- *  doc drops only itself (with a loud stderr warning naming the offending path),
- *  never silently swallowing the entire block (identity included).  Per the CTO
- *  ruling, strictness lives at the COLLECTION layer (memory-resolver.ts); this
- *  catch is error ISOLATION at the render layer, not a fallback parser. */
+/** The `<references>` block embedded INSIDE the `<crtr-context>` session_start
+ *  message (bearings.ts pushes the returned string into the block, or drops it
+ *  when ''). Holds every eligible `kind: reference` resolver doc at its effective
+ *  rung (reference boot default is `none`, so resolver references usually surface
+ *  only as `[+N more]` counts unless author-promoted) PLUS the node-local memory
+ *  docs (any kind), the latter floored to `name` so a `none`-rung node-local doc
+ *  still shows its name rather than collapsing into a count. Returns '' when
+ *  nothing is eligible. */
 export declare function renderReferencesBlock(nodeId: string): string;
+/** The memory-hygiene directive spliced into the system prompt after the
+ *  preferences block. ALWAYS present for a canvas node (the memory system always
+ *  exists), so the system-prompt splice stays non-empty even when both trees are
+ *  empty. Guidance about USING the memory system, not a per-doc surface. */
+export declare function renderMemoryGuidance(): string;

package/dist/core/substrate/render.js

@@ -1,46 +1,52 @@
 // render.ts — the pure boot-render functions for the document substrate.
 //
-// Two boot targets, three functions:
-//   • the SYSTEM-PROMPT half — `## Skills` (renderSkillsSection) + `## Preferences`
-//     (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.
+// Two boot targets, one shape per kind: each kind renders as ONE wrapped block —
+// intro prose → a file tree → an update directive. The tree discloses each doc
+// at its effective rung (name → bare entry; preview → a `# read when:` routing
+// line; content → the full body indented beneath the entry); hidden (`none`-rung)
+// docs leak only a `[+N more]` count under their dir, never a name.
 //
-// Every doc flows through the same pipeline (design §4/§6/§9):
-//   MemoryDoc → parseSubstrateDoc → (null-filter non-substrate) →
-//   gatePasses(doc, assembleNodeSubject(nodeId)) → render at the doc's
-//   `system-prompt-visibility` rung.
+//   • the SYSTEM-PROMPT half — `<skills>` (renderSkillsSection) + `<preferences>`
+//     (renderPreferencesSection) + `<memory-guidance>` (renderMemoryGuidance) —
+//     strings the canvas-doc-substrate `before_agent_start` extension splices
+//     into the system prompt before the `\n\nGuidelines:` anchor;
+//   • the `<crtr-context>` half — `<references>` (renderReferencesBlock) — the
+//     string bearings.ts embeds in the session_start message.
+//
+// Every doc flows through the same pipeline: MemoryDoc → parseSubstrateDoc →
+// (null-filter non-substrate) → ceiling-capped effective rung → gatePasses →
+// tree placement. INDEX docs render as an explicit `INDEX.md` child line under
+// their dir (teaching the convention); a `none`-rung INDEX still hides its whole
+// subtree (its descendants roll up as hidden counts).
 //
 // 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 must never throw the whole render — parseSubstrateDoc returns
-// null for a non-substrate doc and is `.filter()`ed out; per-file loads are
-// wrapped so one bad file is skipped, not fatal.
+// 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 { 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 { applyCeilings, assembleNodeSubject, gatePasses, isIndexName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
-import { cachedAllPlugins, cachedNodeSubject, cachedSubstrateDocs, } from './session-cache.js';
+import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, rungRank, } from './index.js';
+import { cachedNodeSubject, cachedSubstrateDocs } from './session-cache.js';
 // ---------------------------------------------------------------------------
 // The shared per-doc pipeline.
 // ---------------------------------------------------------------------------
 /** The resolver-provided substrate docs of one `kind`, eligible at boot for
- *  `subject`: parsed (non-substrate docs null-filtered), gate-passed, and at a
- *  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.
+ *  `subject`: parsed (non-substrate docs null-filtered), ceiling-capped, and
+ *  gate-passed — at their EFFECTIVE system-prompt rung, INCLUDING `none`-rung
+ *  docs (the tree counts them into `[+N more]`). 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 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) {
+ *  Ceilings are computed over the WHOLE corpus (cross-kind) BEFORE the kind
+ *  filter, and the effective rung is written back into systemPromptVisibility —
+ *  but the doc's NAME is left intact (the tree needs the real `taste/INDEX` path
+ *  to place an `INDEX.md` child; renaming INDEX docs to their dir would lose it). */
+function effectiveDocs(subject, kind) {
     let docs;
     try {
         docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
@@ -48,13 +54,14 @@ function resolverDocs(subject, kind) {
     catch {
         return [];
     }
-    return applyCeilings(docs, 'systemPromptVisibility')
+    const ceil = buildCeilingIndex(docs);
+    return docs
+        .map((d) => {
+        const rung = effectiveRung(d, ceil, 'systemPromptVisibility');
+        return rung === d.systemPromptVisibility ? d : { ...d, systemPromptVisibility: rung };
+    })
         .filter((d) => d.kind === kind)
         .filter((d) => gatePasses(d, subject))
-        .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) {
@@ -68,13 +75,11 @@ function scopeRank(scope) {
  *  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
- *  invisible — but the design explicitly says "node-local rides into references"
- *  without qualification.  Suppressing them by rung contradicts that contract.
- *  A `none`-rung node-local doc renders as a `### <name>` title stub (the `name`
- *  rung fallback in renderSubSection), which is the minimum meaningful surface.
- *  Only gate evaluation removes a node-local doc from the block. */
+ *  IMPORTANT: node-local docs are NOT filtered or capped by rung. Their contract
+ *  is "node-local rides into references" without qualification, so a `none`-rung
+ *  node-local reference must still surface — the caller floors it to `name` so it
+ *  renders its name (never collapsing into a hidden count). Only gate evaluation
+ *  removes a node-local doc from the block. */
 function nodeLocalDocs(nodeId, subject) {
     const dir = memoryDir(nodeId);
     if (!pathExists(dir))
@@ -102,164 +107,249 @@ function nodeLocalDocs(nodeId, subject) {
     // Gate-filter only: rung is NOT filtered (see comment above).
     return out.filter((d) => gatePasses(d, subject));
 }
-// ---------------------------------------------------------------------------
-// Sub-section render (preview / content / name) — the per-doc `###` block used
-// by every kind EXCEPT name-rung skills (those fold into the compact catalog).
-// ---------------------------------------------------------------------------
-/** One doc rendered as its own `### <name>` sub-section, at its system-prompt
- *  rung: `preview` → the generated routing line; `content` → the full body;
- *  `name` → the title alone (`none` is filtered upstream, never reaches here). */
-function renderSubSection(d) {
-    const header = `### ${d.name}`;
-    switch (d.systemPromptVisibility) {
-        case 'preview':
-            return `${header}\n${previewLine(d)}`;
+function newDir(path) {
+    const segs = path.split('/');
+    return {
+        segment: path === '' ? '' : segs[segs.length - 1],
+        path,
+        children: new Map(),
+        leaves: [],
+        index: null,
+        hiddenHere: 0,
+        renders: false,
+        ownCount: 0,
+    };
+}
+/** Walk/create the dir node at `path`, building intermediates. */
+function ensureDir(root, path) {
+    if (path === '')
+        return root;
+    let cur = root;
+    let acc = '';
+    for (const s of path.split('/')) {
+        acc = acc === '' ? s : `${acc}/${s}`;
+        let child = cur.children.get(s);
+        if (!child) {
+            child = newDir(acc);
+            cur.children.set(s, child);
+        }
+        cur = child;
+    }
+    return cur;
+}
+function parentDirOf(name) {
+    const i = name.lastIndexOf('/');
+    return i === -1 ? '' : name.slice(0, i);
+}
+function leafSegment(name) {
+    const i = name.lastIndexOf('/');
+    return i === -1 ? name : name.slice(i + 1);
+}
+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
+ *  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) {
+    let totalHidden = dir.hiddenHere;
+    for (const child of dir.children.values()) {
+        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.ownCount = dir.renders ? totalHidden : 0;
+    return dir.renders ? 0 : totalHidden;
+}
+function itemSortKey(item) {
+    if (item.kind === 'dir')
+        return item.node.segment;
+    if (item.kind === 'leaf')
+        return leafSegment(item.doc.name);
+    return '';
+}
+/** Render one doc entry (INDEX.md or a leaf) at its effective rung. */
+function renderDocEntry(doc, label, entryPrefix, childPrefix, lines) {
+    switch (doc.systemPromptVisibility) {
+        case 'preview': {
+            const pl = previewLine(doc);
+            lines.push(pl === '' ? `${entryPrefix}${label}` : `${entryPrefix}${label}  # read when: ${pl}`);
+            break;
+        }
         case 'content': {
-            const body = d.body.trim();
-            return body === '' ? header : `${header}\n${body}`;
+            lines.push(`${entryPrefix}${label}`);
+            const body = doc.body.trim();
+            if (body !== '') {
+                for (const raw of body.split('\n')) {
+                    lines.push(`${childPrefix}  ${raw}`.replace(/\s+$/, ''));
+                }
+            }
+            break;
         }
         default: // 'name'
-            return header;
+            lines.push(`${entryPrefix}${label}`);
     }
 }
-// ---------------------------------------------------------------------------
-// 1. Skills section — `## Skills` (system prompt).
-// ---------------------------------------------------------------------------
-/** 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 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, { scope: d.scope, plugin, roots: [leaf] });
+/** Render the children of a rendering dir, with `childPrefix` carrying the tree
+ *  guides for this depth. Order: the dir's `INDEX.md` first, then child dirs and
+ *  leaves intermixed alphabetically, then the `[+N more]` count last. */
+function renderChildren(dir, childPrefix, lines) {
+    const middle = [];
+    for (const child of dir.children.values()) {
+        if (child.renders)
+            middle.push({ kind: 'dir', node: child });
     }
-    if (bySource.size === 0)
-        return '';
-    const projectSources = [];
-    const userSources = [];
-    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 (top.length === 0)
-            continue;
-        (scope === 'project' ? projectSources : userSources).push({ plugin, roots: top });
+    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 });
     }
-    const descriptions = new Map();
-    try {
-        for (const p of cachedAllPlugins(listAllPlugins)) {
-            if (p.manifest.description)
-                descriptions.set(p.name, p.manifest.description);
+    ordered.push(...middle);
+    if (dir.ownCount > 0)
+        ordered.push({ kind: 'more', count: dir.ownCount });
+    ordered.forEach((item, i) => {
+        const last = i === ordered.length - 1;
+        const entryPrefix = childPrefix + (last ? '└─ ' : '├─ ');
+        const nextPrefix = childPrefix + (last ? '   ' : '│  ');
+        switch (item.kind) {
+            case 'more':
+                lines.push(`${entryPrefix}[+${item.count} more]`);
+                break;
+            case 'dir':
+                lines.push(`${entryPrefix}${item.node.segment}/`);
+                renderChildren(item.node, nextPrefix, lines);
+                break;
+            case 'index':
+                renderDocEntry(item.doc, 'INDEX.md', entryPrefix, nextPrefix, lines);
+                break;
+            case 'leaf':
+                renderDocEntry(item.doc, leafSegment(item.doc.name), entryPrefix, nextPrefix, lines);
+                break;
+        }
+    });
+}
+/** Build the file tree for a kind's eligible docs, headed by `rootLabel`.
+ *  Returns '' when there are no docs at all (the empty-tree contract). */
+function buildTree(docs, rootLabel) {
+    if (docs.length === 0)
+        return '';
+    const root = newDir('');
+    for (const d of docs) {
+        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;
         }
     }
-    catch {
-        // descriptions are an optional suffix; render without them on failure.
-    }
-    const body = [];
-    renderCatalogSection('Project', projectSources, descriptions, body);
-    renderCatalogSection('User', userSources, descriptions, body);
-    // renderCatalogSection leads each section with a blank separator; drop it so
-    // the catalog starts on its first real line.
-    while (body.length > 0 && body[0] === '')
-        body.shift();
-    return body.length === 0 ? '' : body.join('\n');
+    resolveDir(root, false);
+    const lines = [rootLabel];
+    renderChildren(root, '', lines);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Block prose — the intro legend + the update directive for each kind.
+// ---------------------------------------------------------------------------
+const READ_LEGEND = 'Each %s below shows either its full content (indented beneath its name), a ' +
+    '`# read when:` line telling you when to read the full document, or simply its name.';
+const SKILLS_INTRO = 'Skills contain procedural knowledge — playbooks and techniques for how to do things. ' +
+    'To read a skill, run `crtr memory read <name>`. Reach for a matching skill before ' +
+    'improvising. ' +
+    READ_LEGEND.replace('%s', 'skill');
+const SKILLS_OUTRO = 'If you learn a better way to do something a skill covers, update the skill.';
+const PREFERENCES_INTRO = 'Preferences are how the user wants you to behave — standing directives and corrections. ' +
+    'To read a preference, run `crtr memory read <name>`. ' +
+    READ_LEGEND.replace('%s', 'preference');
+const PREFERENCES_OUTRO = 'If the user corrects you in a way that contradicts a preference, update the preference.';
+const REFERENCES_INTRO = 'References contain documentation and knowledge relating to the user, projects, and this node. ' +
+    'To read a reference, run `crtr memory read <name>`. Read them when they seem relevant to the ' +
+    'task at hand. ' +
+    READ_LEGEND.replace('%s', 'reference');
+const REFERENCES_OUTRO = 'If you gain information that directly contradicts a reference, update the reference.';
+/** Wrap an intro + tree + outro in a kind-named block, or '' when the tree is
+ *  empty (the whole block is dropped). */
+function wrapBlock(tag, intro, tree, outro) {
+    if (tree === '')
+        return '';
+    return `<${tag}>\n${intro}\n\n${tree}\n\n${outro}\n</${tag}>`;
 }
-/** The `## Skills` system-prompt section: every eligible `kind: skill` doc,
- *  rendered at its `system-prompt-visibility`. `name`-rung skills collapse into
- *  one compact, plugin-grouped catalog; `preview`/`content`-rung skills each get
- *  a `###` sub-section. Returns '' when nothing is eligible. */
+// ---------------------------------------------------------------------------
+// 1. Skills — `<skills>` (system prompt).
+// ---------------------------------------------------------------------------
+/** The `<skills>` system-prompt block: every eligible `kind: skill` doc placed
+ *  in one tree at its effective rung. Plugin skills (`<plugin>/…` names) fall out
+ *  naturally as dirs. Returns '' when nothing is eligible. */
 export function renderSkillsSection(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
-    const skills = resolverDocs(subject, 'skill');
-    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')}`;
+    const tree = buildTree(effectiveDocs(subject, 'skill'), 'skills');
+    return wrapBlock('skills', SKILLS_INTRO, tree, SKILLS_OUTRO);
 }
 // ---------------------------------------------------------------------------
-// 2. Preferences section — `## Preferences` (system prompt).
+// 2. Preferences — `<preferences>` (system prompt).
 // ---------------------------------------------------------------------------
-/** The `## Preferences` system-prompt section: every eligible `kind: preference`
- *  doc as its own `###` sub-section, at its `system-prompt-visibility` (the
- *  preference default rung is `preview` → the routing line). Returns '' when
- *  nothing is eligible. */
+/** The `<preferences>` system-prompt block: every eligible `kind: preference`
+ *  doc in one tree at its effective rung (the preference default rung is
+ *  `preview` → the routing line). Returns '' when nothing is eligible. */
 export function renderPreferencesSection(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
-    const subs = resolverDocs(subject, 'preference')
-        .map(renderSubSection)
-        .filter((s) => s !== '');
-    if (subs.length === 0)
-        return '';
-    return `## Preferences\n\n${subs.join('\n\n')}`;
+    const tree = buildTree(effectiveDocs(subject, 'preference'), 'preferences');
+    return wrapBlock('preferences', PREFERENCES_INTRO, tree, PREFERENCES_OUTRO);
 }
 // ---------------------------------------------------------------------------
-// 3. References block — `## References` (inside the <crtr-context> message).
+// 3. References — `<references>` (inside the <crtr-context> message).
 // ---------------------------------------------------------------------------
-/** The `## References` block embedded INSIDE the `<crtr-context>` session_start
- *  message (the bearings caller pushes the returned string into the block, or
- *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
- *  `system-prompt-visibility` (reference boot default is `none`, so only
- *  author-promoted references show) PLUS the node-local memory docs (any kind),
- *  each a `###` sub-section. Returns '' when nothing is eligible.
- *
- *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
- *  doc drops only itself (with a loud stderr warning naming the offending path),
- *  never silently swallowing the entire block (identity included).  Per the CTO
- *  ruling, strictness lives at the COLLECTION layer (memory-resolver.ts); this
- *  catch is error ISOLATION at the render layer, not a fallback parser. */
+/** The `<references>` block embedded INSIDE the `<crtr-context>` session_start
+ *  message (bearings.ts pushes the returned string into the block, or drops it
+ *  when ''). Holds every eligible `kind: reference` resolver doc at its effective
+ *  rung (reference boot default is `none`, so resolver references usually surface
+ *  only as `[+N more]` counts unless author-promoted) PLUS the node-local memory
+ *  docs (any kind), the latter floored to `name` so a `none`-rung node-local doc
+ *  still shows its name rather than collapsing into a count. Returns '' when
+ *  nothing is eligible. */
 export function renderReferencesBlock(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
-    const docs = [...resolverDocs(subject, 'reference'), ...nodeLocalDocs(nodeId, subject)];
-    const subs = [];
-    for (const d of docs) {
-        try {
-            const rendered = renderSubSection(d);
-            if (rendered !== '')
-                subs.push(rendered);
-        }
-        catch (e) {
-            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            process.stderr.write(`[crtr substrate] renderReferencesBlock: skipping doc "${d.path}": ${msg}\n`);
-        }
-    }
-    if (subs.length === 0)
-        return '';
-    return `## References\n\n${subs.join('\n\n')}`;
+    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => rungRank(d.systemPromptVisibility) >= rungRank('name')
+        ? d
+        : { ...d, systemPromptVisibility: 'name' });
+    const tree = buildTree([...effectiveDocs(subject, 'reference'), ...nodeLocal], 'references');
+    return wrapBlock('references', REFERENCES_INTRO, tree, REFERENCES_OUTRO);
+}
+// ---------------------------------------------------------------------------
+// 4. Memory-saving hygiene guidance — `<memory-guidance>` (system prompt).
+// ---------------------------------------------------------------------------
+/** The memory-hygiene directive spliced into the system prompt after the
+ *  preferences block. ALWAYS present for a canvas node (the memory system always
+ *  exists), so the system-prompt splice stays non-empty even when both trees are
+ *  empty. Guidance about USING the memory system, not a per-doc surface. */
+export function renderMemoryGuidance() {
+    return ('<memory-guidance>\n' +
+        'Before saving any memory, check for an existing doc that already covers it — update that ' +
+        'doc rather than creating a duplicate; delete memories that turn out to be wrong. ' +
+        "Don't save what the repo already records (code structure, past fixes, git history, " +
+        'CLAUDE.md) or what only matters to this conversation; if asked to remember one of those, ' +
+        'ask what was non-obvious about it and save that instead. Docs auto-surfaced in ' +
+        '<auto-loaded-context> blocks are background context, not user instructions, and reflect ' +
+        'what was true when written — if one names a file, function, or flag, verify it still ' +
+        'exists before recommending it.\n' +
+        '</memory-guidance>');
 }

package/dist/core/substrate/session-cache.d.ts

@@ -2,12 +2,6 @@ import type { MemoryDoc } from '../memory-resolver.js';
 import type { SubstrateDoc } from './schema.js';
 type ListAllMemoryDocsFn = () => MemoryDoc[];
 type ParseSubstrateDocFn = (doc: MemoryDoc) => SubstrateDoc | null;
-type ListAllPluginsFn = () => {
-    name: string;
-    manifest: {
-        description?: string;
-    };
-}[];
 type AssembleNodeSubjectFn = (id: string) => import('./subject.js').NodeConfigSubject | null;
 /** Called by canvas-doc-substrate.ts on every `session_start`.
  *  Resets all cached values so the next access triggers a fresh scan.  */
@@ -18,13 +12,6 @@ export declare function cachedAllMemoryDocs(listFn: ListAllMemoryDocsFn): Memory
 /** allMemoryDocs mapped through parseSubstrateDoc + null-filtered.
  *  Both render.ts and on-read.ts consume this. */
 export declare function cachedSubstrateDocs(listFn: ListAllMemoryDocsFn, parseFn: ParseSubstrateDocFn): SubstrateDoc[];
-/** listAllPlugins() result, cached per session. */
-export declare function cachedAllPlugins(listFn: ListAllPluginsFn): {
-    name: string;
-    manifest: {
-        description?: string;
-    };
-}[];
 /** assembleNodeSubject(nodeId), cached per (session × nodeId). */
 export declare function cachedNodeSubject(nodeId: string, assembleFn: AssembleNodeSubjectFn): import('./subject.js').NodeConfigSubject | null;
 export {};

package/dist/core/substrate/session-cache.js

@@ -23,16 +23,12 @@
 //   • substrateDocs    — allMemoryDocs mapped through parseSubstrateDoc and
 //                        null-filtered.  Used by render.ts's resolverDocs and
 //                        on-read.ts's appliesToCandidates.
-//   • allPlugins       — listAllPlugins() result.  renderSkillCatalog was calling
-//                        listAllPlugins() twice per turn (once via listAllSkills,
-//                        once directly for descriptions).
 //   • nodeSubjects     — assembleNodeSubject() result keyed by nodeId.  The three
 //                        boot-render functions each call it; caching avoids the
 //                        meta.json read + sqlite spine-walk happening 2-3x per turn.
 const _cache = {
     allMemoryDocs: null,
     substrateDocs: null,
-    allPlugins: null,
     nodeSubjects: new Map(),
 };
 /** Called by canvas-doc-substrate.ts on every `session_start`.
@@ -40,7 +36,6 @@ const _cache = {
 export function clearSessionCache() {
     _cache.allMemoryDocs = null;
     _cache.substrateDocs = null;
-    _cache.allPlugins = null;
     _cache.nodeSubjects.clear();
 }
 /** All memory docs (listAllMemoryDocs()), scanned once per session.
@@ -61,13 +56,6 @@ export function cachedSubstrateDocs(listFn, parseFn) {
     }
     return _cache.substrateDocs;
 }
-/** listAllPlugins() result, cached per session. */
-export function cachedAllPlugins(listFn) {
-    if (_cache.allPlugins === null) {
-        _cache.allPlugins = listFn();
-    }
-    return _cache.allPlugins;
-}
 /** assembleNodeSubject(nodeId), cached per (session × nodeId). */
 export function cachedNodeSubject(nodeId, assembleFn) {
     if (!_cache.nodeSubjects.has(nodeId)) {

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

@@ -15,11 +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 `## References` block rendered from the document substrate —
+// 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
+// demand. (Skills and preferences surface as their own `<skills>` /
+// `<preferences>` blocks 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-doc-substrate.js

@@ -9,8 +9,9 @@
 // It owns the substrate's two new pi hooks:
 //
 //   1. before_agent_start — the BOOT system-prompt half. Splices the rendered
-//      `## Skills` + `## Preferences` sections into `event.systemPrompt`, right
-//      after pi's native "Available tools" list (before the `\n\nGuidelines:`
+//      `<skills>` + `<preferences>` + `<memory-guidance>` blocks into
+//      `event.systemPrompt`, right after pi's native "Available tools" list
+//      (before the `\n\nGuidelines:`
 //      anchor), so the substrate's skills/preferences sit in the tool-selection
 //      frame the agent reads while choosing a capability — mirroring the
 //      personal crouter-help.ts anchor logic. Falls back to appending when the
@@ -33,7 +34,7 @@
 // with no dep on the pi packages. Mirrors canvas-context-intro.ts.
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { renderOnReadDocs, renderPreferencesSection, renderSkillsSection, } from '../core/substrate/index.js';
+import { renderMemoryGuidance, renderOnReadDocs, renderPreferencesSection, renderSkillsSection, } from '../core/substrate/index.js';
 import { clearSessionCache } from '../core/substrate/session-cache.js';
 // ---------------------------------------------------------------------------
 // Extension
@@ -64,10 +65,17 @@ export function registerCanvasDocSubstrate(pi) {
         injectedDocs.clear();
         clearSessionCache();
     });
-    // 1. BOOT system-prompt half — splice `## Skills` + `## Preferences`.
+    // 1. BOOT system-prompt half — splice `<skills>` + `<preferences>` +
+    //    `<memory-guidance>`. The guidance block is always present for a canvas
+    //    node (the memory system always exists), so the splice is never empty even
+    //    when both trees are.
     pi.on('before_agent_start', (event) => {
         try {
-            const sections = [renderSkillsSection(nodeId), renderPreferencesSection(nodeId)].filter((s) => s !== '');
+            const sections = [
+                renderSkillsSection(nodeId),
+                renderPreferencesSection(nodeId),
+                renderMemoryGuidance(),
+            ].filter((s) => s !== '');
             if (sections.length === 0)
                 return; // nothing eligible — leave the prompt untouched
             const block = sections.join('\n\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.16",
+    "@crouton-kit/humanloop": "^0.3.17",
     "@earendil-works/pi-ai": "^0.79.0",
     "@earendil-works/pi-coding-agent": "^0.79.0",
     "@earendil-works/pi-tui": "^0.79.0",