@north-light/crouter 0.3.154

package/dist/core/substrate/render-node.js

@@ -0,0 +1,29 @@
+// render-node.ts — the CANVAS-DB wrappers over the pure boot-render functions.
+// `renderPreferencesSection` and `renderKnowledgeBlock` take a node id, assemble
+// its subject from the canvas-db (assembleNodeSubject), then delegate to the
+// pure render fns in render.ts. Split out of render.ts so a CLI consumer that
+// only needs the pure `*ForSubject` fns imports render.js WITHOUT pulling
+// subject.js's canvas-db reach. Broker/daemon-side callers (bearings.ts,
+// canvas-doc-substrate.ts) import these — the canvas-db read is fine there.
+import { interpolateNodePaths } from '../canvas/paths.js';
+import { assembleNodeSubject } from './subject.js';
+import { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.js';
+/** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
+ *  the node's subject from the canvas-db, render the pure block, then swap the
+ *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
+ *  so agents don't paste it into the non-expanding Write tool (see
+ *  interpolateNodePaths). A null subject (unknown id) still renders the
+ *  always-present memory-usage guidance frame. */
+export function renderPreferencesSection(nodeId) {
+    const subject = assembleNodeSubject(nodeId);
+    return interpolateNodePaths(renderPreferencesForSubject(subject).block, nodeId);
+}
+/** The first-message `<memory kind="knowledge">` block for `nodeId`: assemble
+ *  the node's subject from the canvas-db and render the consultable catalog.
+ *  Returns '' for an unknown id or when nothing is eligible. */
+export function renderKnowledgeBlock(nodeId) {
+    const subject = assembleNodeSubject(nodeId);
+    if (subject === null)
+        return '';
+    return renderKnowledgeForSubject(subject, nodeId);
+}

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

@@ -0,0 +1,21 @@
+import { type SubstrateDoc } from './schema.js';
+import type { NodeConfigSubject } from './subject-fields.js';
+export declare function renderPreferencesForSubject(subject: NodeConfigSubject | null): {
+    block: string;
+    contentDocs: SubstrateDoc[];
+    tree: string;
+};
+/** The `<memory kind="knowledge">` block embedded in the session_start bearings
+ *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
+ *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
+ *  doc PLUS the node-local memory docs (any kind) — resolver docs win
+ *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
+ *  like the preference block: content prose first (general→specific,
+ *  node-local last), then the preview/name catalog tree. Node-local docs are
+ *  floored HERE — a rung-none node-local doc's effective rung is bumped to
+ *  `name` before grouping, so it still surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance
+ *  and factual references both live here as `knowledge`. Returns '' when
+ *  nothing is eligible. */
+export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string): string;

package/dist/core/substrate/render.js

@@ -0,0 +1,547 @@
+// render.ts — the pure boot-render functions for the document substrate.
+//
+// Two boot targets, one shape per kind: each kind renders as ONE wrapped block —
+// intro prose → GROUPED content → an update directive. The render is grouped
+// by visibility rung, not interleaved: `content`-rung docs render FIRST as
+// clean prose bodies (verbatim, no tree chrome, no name label — this is what
+// makes content-rung the persona-prose mechanism), in general→specific order;
+// then the `preview`+`name`(+hidden `none`) docs render as ONE catalog tree,
+// each at its own rung (preview → a `# read when:` routing line; name → a bare
+// entry); a `none`-rung doc leaks only into its dir's `[+N more]` count, never
+// a name — EXCEPT a node-local doc, whose contract is "node-local rides into
+// knowledge" unconditionally: renderKnowledgeBlock floors a rung-none
+// node-local doc up to `name` so it still shows its bare name rather than
+// collapsing into a hidden count. Only gate evaluation removes a node-local
+// doc outright.
+//
+//   • the SYSTEM-PROMPT half — `<memory kind="preference">`
+//     (renderPreferencesSection) — the always-present memory-usage guidance plus
+//     the eligible preference docs, which the canvas-doc-substrate
+//     `before_agent_start` extension splices into the system prompt before the
+//     `\n\nGuidelines:` anchor;
+//   • the first-message half — `<memory kind="knowledge">`
+//     (renderKnowledgeBlock) — the consultable catalog (every `kind: knowledge`
+//     doc ∪ node-local) the string bearings.ts embeds in the session_start
+//     message as a SIBLING of `<crtr-bearings>` (never nested under the context
+//     dir — the catalog spans all scopes and belongs to no one directory).
+//
+// The pipeline is explicitly TWO-STEP and must never run in the other order:
+//   1. SELECT WINNERS — MemoryDoc → parseSubstrateDoc → (null-filter
+//      non-substrate) → ceiling-capped effective rung → gatePasses →
+//      first-wins DEDUP by name over the resolver's precedence order (nearest
+//      project > user > builtin). Node-local docs follow the same gate rule,
+//      but the knowledge-block render floors a rung-none node-local doc's
+//      EFFECTIVE rung to `name` — the one rung-floor exemption, scoped to the
+//      node-local store only.
+//   2. RENDER IN DISPLAY ORDER — split winners into content vs. the rest;
+//      order content general→specific (builtin, user, project outermost→
+//      nearest, node-local last) then by tree position then filename; place
+//      the rest into the catalog tree (position-ordered, as before).
+//   Sorting into display order BEFORE step 1's dedup would let a
+//   later-in-display-order builtin doc's array position mask a project/user
+//   override — dedup precedence and display order are deliberately different
+//   orderings and must not be conflated.
+//
+// Pure + defensive: reads the resolver, canvas-db (subject assembly), and the
+// node-local memory dir; performs no writes and no side effects. A single
+// malformed doc never throws the whole render — parsing is isolated upstream
+// (parseSubstrateDoc returns null for a non-substrate doc; per-file node-local
+// loads are wrapped), and tree construction is pure string work.
+import { relative, sep } from 'node:path';
+import { interpolateNodePaths } from '../canvas/paths.js';
+import { listAllMemoryDocs, resolveMemoryDoc } from '../memory-resolver.js';
+import { subKindsAvailableTo } from '../config.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { pathExists, readText, walkFiles } from '../fs-utils.js';
+import { memoryDir } from '../runtime/memory.js';
+import { projectScopeRoots } from '../scope.js';
+// De-barreled to LEAF modules on purpose: importing from './index.js' would
+// pull subject.js (canvas-db) transitively, re-tainting every CLI consumer of
+// the pure render fns. The canvas-db wrappers (renderPreferencesSection /
+// renderKnowledgeBlock) live in render-node.js instead.
+import { buildCeilingIndex, effectiveRung, indexDirOf, isIndexName } from './ceiling.js';
+import { gatePasses } from './gate.js';
+import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './schema.js';
+import { cachedSubstrateDocs } from './session-cache.js';
+// ---------------------------------------------------------------------------
+// Step 1 — winner selection (ceiling + gate + first-wins dedup).
+// ---------------------------------------------------------------------------
+/** First-wins dedup by (already-normalized) name, preserving the input's
+ *  precedence order. The array's ORDER is the precedence signal — callers must
+ *  pass docs already ordered highest-precedence-first; this function never
+ *  reorders, only drops later duplicates. */
+function dedupeFirstWins(docs) {
+    const seen = new Set();
+    const out = [];
+    for (const d of docs) {
+        if (seen.has(d.name))
+            continue;
+        seen.add(d.name);
+        out.push(d);
+    }
+    return out;
+}
+/** STEP 1 — the resolver-provided WINNER docs of one `kind`, eligible at boot
+ *  for `subject`: parsed (non-substrate docs null-filtered), ceiling-capped,
+ *  gate-passed, then first-wins DEDUPED by name over the resolver's precedence
+ *  order (nearest project > user > builtin) — at the EFFECTIVE system-prompt
+ *  rung, INCLUDING `none`-rung docs (the tree counts them into `[+N more]`).
+ *  This is winner selection ONLY; display ordering is a separate, later step
+ *  (see renderGrouped) so a builtin doc can never mask a project/user override
+ *  by virtue of sorting first. Uses the per-session cache so the full corpus
+ *  is scanned + parsed at most once per session across the boot-render calls.
+ *
+ *  Ceilings are computed over the WHOLE corpus (cross-kind) BEFORE the kind
+ *  filter, and the effective rung is written back into systemPromptVisibility —
+ *  but each doc keeps its canonical logical identifier, such as `taste/INDEX`. */
+function selectWinners(subject, kind) {
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    const ceil = buildCeilingIndex(docs);
+    const eligible = 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));
+    return dedupeFirstWins(eligible);
+}
+// ---------------------------------------------------------------------------
+// Step 2 — display ordering + grouped render.
+// ---------------------------------------------------------------------------
+/** Content-prose ordering rank: general → specific. builtin=0, user=1,
+ *  profile=2, project ranks start at 3 and climb by root nearness — the
+ *  OUTERMOST ancestor `.crouter/` root ranks lowest (renders first), the
+ *  NEAREST root ranks highest (renders last) — the mirror of the resolver's
+ *  nearest-first dedup precedence. `isNodeLocal` docs rank last of all (the
+ *  most specific, this-node-only store). This is display order ONLY — the
+ *  resolver's REPLACEMENT precedence (first-wins dedup, step 1) is the
+ *  opposite direction for project/profile: project stack > profile > user >
+ *  builtin, nearest project strongest; the two orderings are deliberately
+ *  different (see the module comment). */
+function scopeGeneralityRank(doc, isNodeLocal) {
+    if (isNodeLocal)
+        return 1000;
+    if (doc.scope === 'builtin')
+        return 0;
+    if (doc.scope === 'user')
+        return 1;
+    if (doc.scope === 'profile')
+        return 2;
+    const roots = projectScopeRoots(); // nearest-first
+    if (roots.length === 0)
+        return 3;
+    const nearFirstIdx = roots.findIndex((root) => doc.path.startsWith(root + sep));
+    const idx = nearFirstIdx === -1 ? 0 : nearFirstIdx;
+    return 3 + (roots.length - 1 - idx); // outermost (largest idx) -> smallest rank
+}
+/** The doc's RAW physical path segments (numeric prefix intact), recovered
+ *  from its absolute `path` using its (already-normalized) `name`'s segment
+ *  COUNT — normalization strips a prefix from a segment but never merges or
+ *  drops a segment, so the last N components of `path` are always the doc's
+ *  physical segments. This is what lets `tree position` sort respect an
+ *  author's `NN-` ordering pin even though the pin is invisible in `name`. */
+function physicalSegments(doc) {
+    const n = doc.name.split('/').length;
+    const raw = doc.path.split(sep).slice(-n);
+    if (raw.length > 0)
+        raw[raw.length - 1] = raw[raw.length - 1].replace(/\.md$/i, '');
+    return raw;
+}
+/** "Tree position" comparator for content-prose ordering within a store:
+ *  compares two docs' RAW physical segments element-by-element (a shallower
+ *  path sorts before a path nested under it at the first differing segment). */
+function compareTreePosition(a, b) {
+    const as = physicalSegments(a);
+    const bs = physicalSegments(b);
+    const len = Math.min(as.length, bs.length);
+    for (let i = 0; i < len; i++) {
+        const c = as[i].localeCompare(bs[i]);
+        if (c !== 0)
+            return c;
+    }
+    return as.length - bs.length;
+}
+/** STEP 2 — split deduped `winners` by rung and render each group in its
+ *  display order: `content` docs first, as clean prose (general→specific,
+ *  then tree position, then filename — no tree chrome, no name label); every
+ *  other winner (preview/name/hidden-none) folds into ONE catalog tree exactly
+ *  as before. `nodeLocalSet` marks which winners came from the node-local
+ *  store (ranked most-specific in content ordering); omit it for a pure
+ *  resolver render. */
+function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
+    const content = [];
+    const rest = [];
+    for (const d of winners) {
+        if (d.systemPromptVisibility === 'content')
+            content.push(d);
+        else
+            rest.push(d);
+    }
+    content.sort((a, b) => scopeGeneralityRank(a, nodeLocalSet.has(a)) - scopeGeneralityRank(b, nodeLocalSet.has(b)) ||
+        compareTreePosition(a, b) ||
+        a.name.localeCompare(b.name));
+    const contentProse = content
+        .map((d) => d.body.trim())
+        .filter((b) => b !== '')
+        .join('\n\n');
+    return { contentProse, tree: buildTree(rest, rootLabel), contentDocs: content };
+}
+/** 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.
+ *  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 knowledge block.
+ *
+ *  Node-local docs follow the same GATE rule as every other store — gate
+ *  evaluation is the only thing that removes a doc here. Rung is different:
+ *  node-local's contract is "node-local rides into knowledge" unconditionally,
+ *  so a `none`-rung node-local doc is retained AT its parsed rung by this
+ *  function (never rewritten here) — it is the caller (renderKnowledgeBlock)
+ *  that floors a rung-none node-local doc up to `name` so it still shows its
+ *  bare name instead of collapsing into a `[+N more]` count. */
+function nodeLocalDocs(nodeId, subject) {
+    const dir = memoryDir(nodeId);
+    if (!pathExists(dir))
+        return [];
+    const out = [];
+    for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
+        const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
+        const fallbackName = normalizeDocName(raw);
+        if (!fallbackName)
+            continue;
+        try {
+            const { data, body } = parseFrontmatterGeneric(readText(file));
+            const schema = parseSubstrateFrontmatter(data);
+            if (schema === null)
+                continue;
+            // ONE substrate-identity rule (schema.ts's resolveDocName), shared with
+            // the resolver and the on-read positional loader: explicit frontmatter
+            // `name` wins over the physical-path-derived fallback.
+            const name = resolveDocName(data, fallbackName);
+            // node-local is NOT a resolver scope; `scope` is a placeholder never read
+            // by gate eval (keyed off the NODE subject, not the doc) nor by the
+            // renderers (keyed off name / body / rung).
+            out.push({ ...schema, name, scope: 'user', path: file, body });
+        }
+        catch {
+            // A single malformed file is skipped, never fatal to the render.
+            continue;
+        }
+    }
+    return out.filter((d) => gatePasses(d, subject));
+}
+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 canonical logical doc entry 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': {
+            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'
+            lines.push(`${entryPrefix}${label}`);
+    }
+}
+/** Render the children of a rendering dir, with `childPrefix` carrying the tree
+ *  guides for this depth. Order: the dir's canonical INDEX identity first, then
+ *  child dirs and leaves intermixed alphabetically, then the `[+N more]` count
+ *  last. */
+function renderChildren(dir, childPrefix, lines) {
+    const middle = [];
+    for (const child of dir.children.values()) {
+        if (child.renders)
+            middle.push({ kind: 'dir', node: child });
+    }
+    for (const leaf of dir.leaves)
+        middle.push({ kind: 'leaf', doc: leaf });
+    middle.sort((a, b) => itemSortKey(a).localeCompare(itemSortKey(b)));
+    const ordered = [];
+    if (dir.index !== null && isVisible(dir.index.systemPromptVisibility)) {
+        ordered.push({ kind: 'index', doc: dir.index });
+    }
+    ordered.push(...middle);
+    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':
+            case 'leaf':
+                renderDocEntry(item.doc, leafSegment(item.doc.name), entryPrefix, nextPrefix, lines);
+                break;
+        }
+    });
+}
+/** Build the catalog tree for a set of already-deduped, non-content winners,
+ *  headed by `rootLabel`. Returns '' when there are no docs at all (the
+ *  empty-tree contract).
+ *
+ *  Callers (renderGrouped) pass docs that are ALREADY first-wins deduped by
+ *  Step 1 (selectWinners); the `seen` set below is a defensive no-op guard
+ *  against a residual duplicate name (e.g. the resolver-winners ∪ node-local
+ *  merge), never the primary dedup mechanism — sorting into display order
+ *  happens upstream of this call, never before dedup. */
+function buildTree(docs, rootLabel) {
+    if (docs.length === 0)
+        return '';
+    const root = newDir('');
+    const seen = new Set();
+    for (const d of docs) {
+        if (seen.has(d.name))
+            continue; // first-wins cross-scope dedup
+        seen.add(d.name);
+        if (isIndexName(d.name)) {
+            const dir = ensureDir(root, indexDirOf(d.name));
+            if (dir.index === null)
+                dir.index = d; // precedence-ordered → keep first (highest)
+        }
+        else {
+            const parent = ensureDir(root, parentDirOf(d.name));
+            if (isVisible(d.systemPromptVisibility))
+                parent.leaves.push(d);
+            else
+                parent.hiddenHere += 1;
+        }
+    }
+    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 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 KNOWLEDGE_INTRO = 'Knowledge documents are what you consult — playbooks and techniques for how to do things, and ' +
+    'references on the user, projects, and this node. They are aggregated from your memory stores: ' +
+    'user-global (`~/.crouter/memory/`), every ancestor project store (`<dir>/.crouter/memory/`) ' +
+    "from the cwd upward, the selected profile's memory store (when one is selected), and node-local " +
+    "(this node's `context/memory/`). To read one, run `crtr memory read <name>`. " +
+    'Each doc exists to prevent a specific mistake you would make without it, so when your task ' +
+    'matches one — by its name or its `# read when:` line — read it before you act; consulting it ' +
+    'only after the work is done forfeits the entire reason it exists. ' +
+    READ_LEGEND.replace('%s', 'document');
+const KNOWLEDGE_OUTRO = 'If you learn a better way to do something a document covers, or gain information that ' +
+    'contradicts one, update that document.';
+/** The memory-usage guidance — how to consult and save memory. ALWAYS present
+ *  (the memory system always exists), folded in as the lead frame of the
+ *  system-prompt `<memory kind="preference">` block rather than carrying its own
+ *  XML section (guidance ABOUT a section is not itself a section). The
+ *  read-before-you-act stress is intentionally repeated here AND in
+ *  KNOWLEDGE_INTRO — agents forget to consult memory, so it earns the echo. */
+const MEMORY_USAGE_GUIDANCE = 'When your task matches a knowledge doc or preference — by its name or its `# read when:` ' +
+    'line — read it before you act, not after: each doc exists only to shore up a mistake you ' +
+    "will make without it, so doing the relevant work without consulting it defeats the doc's " +
+    'whole purpose. ' +
+    'Before saving any memory, check for an existing doc that already covers it — update that ' +
+    'doc rather than creating a duplicate, rewriting it as if for the first time instead of ' +
+    'appending the new truth beneath the old; 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.';
+/** Try to resolve a sub-kind's builtin memory doc body citation, or '' if none
+ *  resolves. Mirrors `runtime/persona.ts`'s `loadMemoryBody` try/catch pattern —
+ *  a sub-kind registered without a matching doc simply gets no citation clause,
+ *  never a thrown render. */
+function subKindDocCitation(subKind) {
+    try {
+        resolveMemoryDoc(`kinds/${subKind}`);
+        return ` (\`crtr memory read kinds/${subKind}\`)`;
+    }
+    catch {
+        return '';
+    }
+}
+/** The computed "sub-personas you may spawn" menu for a subject's kind — the
+ *  live restoration of the old `personas/resolve.ts` static menu, now derived
+ *  at render time from the merged kind registry (`subKindsAvailableTo`) so it
+ *  can never drift from `sys prompt-review --list`'s `subPersonas` metadata.
+ *  Returns '' when the kind has zero available sub-kinds (no dangling empty
+ *  header). Emitted for BOTH base and orchestrator modes per the CTO's ruling —
+ *  mode is irrelevant to which sub-kinds are spawnable. */
+function buildSubPersonaMenu(kind) {
+    const subKinds = subKindsAvailableTo(kind);
+    if (subKinds.length === 0)
+        return '';
+    const lines = subKinds.map((sub) => {
+        const citation = subKindDocCitation(sub.kind);
+        return `- \`${sub.kind}\` — ${sub.whenToUse}${citation}`;
+    });
+    return (`## Sub-personas you may spawn\n\n` +
+        `These specialist sub-personas are available to the ${kind} kind. Spawn one with ` +
+        '`crtr node new --kind <sub> "<scope>"`, and treat it as its own scope instead of ' +
+        'dragging unrelated context into it.\n\n' +
+        lines.join('\n'));
+}
+// ---------------------------------------------------------------------------
+// 1. Preferences — `<memory kind="preference">` (system prompt).
+// ---------------------------------------------------------------------------
+/** The system-prompt memory block: the always-present memory-usage guidance,
+ *  then (when any are eligible) the `kind: preference` docs GROUPED by rung —
+ *  content-rung docs first as clean prose (general→specific), then the
+ *  preview/name catalog tree. ALWAYS returns a non-empty `<memory
+ *  kind="preference">` block — the guidance frame is unconditional, so the
+ *  system-prompt splice is never empty even when no preference is eligible. */
+function buildPreferencesBlock(subject) {
+    let body = MEMORY_USAGE_GUIDANCE;
+    let contentDocs = [];
+    let tree = '';
+    if (subject !== null) {
+        const winners = selectWinners(subject, 'preference');
+        const grouped = renderGrouped(winners, 'preferences');
+        contentDocs = grouped.contentDocs;
+        tree = grouped.tree;
+        const subPersonaMenu = buildSubPersonaMenu(subject.kind);
+        if (grouped.contentProse !== '' || grouped.tree !== '' || subPersonaMenu !== '') {
+            body += `\n\n${PREFERENCES_INTRO}`;
+            if (grouped.contentProse !== '')
+                body += `\n\n${grouped.contentProse}`;
+            if (subPersonaMenu !== '')
+                body += `\n\n${subPersonaMenu}`;
+            if (grouped.tree !== '')
+                body += `\n\n${grouped.tree}`;
+            body += `\n\n${PREFERENCES_OUTRO}`;
+        }
+    }
+    return { block: `<memory kind="preference">\n${body}\n</memory>`, contentDocs, tree };
+}
+export function renderPreferencesForSubject(subject) {
+    return buildPreferencesBlock(subject);
+}
+// ---------------------------------------------------------------------------
+// 2. Knowledge — `<memory kind="knowledge">` (the first-message bearings).
+// ---------------------------------------------------------------------------
+/** The `<memory kind="knowledge">` block embedded in the session_start bearings
+ *  message (bearings.ts pushes it as a SIBLING of `<crtr-bearings>`, or drops it
+ *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
+ *  doc PLUS the node-local memory docs (any kind) — resolver docs win
+ *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
+ *  like the preference block: content prose first (general→specific,
+ *  node-local last), then the preview/name catalog tree. Node-local docs are
+ *  floored HERE — a rung-none node-local doc's effective rung is bumped to
+ *  `name` before grouping, so it still surfaces as a bare-name tree entry
+ *  rather than collapsing into a `[+N more]` count (its body still never
+ *  renders: floored docs never reach the `content` rung). Procedural guidance
+ *  and factual references both live here as `knowledge`. Returns '' when
+ *  nothing is eligible. */
+export function renderKnowledgeForSubject(subject, nodeId) {
+    const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => rungRank(d.systemPromptVisibility) >= rungRank('name') ? d : { ...d, systemPromptVisibility: 'name' });
+    const nodeLocalSet = new Set(nodeLocal);
+    // Resolver winners first: first-wins dedup keeps the resolver's copy over a
+    // same-named node-local doc, matching the original precedence.
+    const winners = dedupeFirstWins([...selectWinners(subject, 'knowledge'), ...nodeLocal]);
+    const { contentProse, tree } = renderGrouped(winners, 'knowledge', nodeLocalSet);
+    if (contentProse === '' && tree === '')
+        return '';
+    let out = KNOWLEDGE_INTRO;
+    if (contentProse !== '')
+        out += `\n\n${contentProse}`;
+    if (tree !== '')
+        out += `\n\n${tree}`;
+    out += `\n\n${KNOWLEDGE_OUTRO}`;
+    // Surfaced INTO this node: swap literal `$CRTR_CONTEXT_DIR` for the real path.
+    return interpolateNodePaths(`<memory kind="knowledge">\n${out}\n</memory>`, nodeId);
+}