@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/core/personas/resolve.js

@@ -1,134 +1,376 @@
 /**
  * Persona resolver — composes base + orchestrator personas into a
  * ResolvedPersona ready for use when spawning a canvas node.
- *
- * Composition rules:
- *   mode==='base'
- *     → load <kind>/PERSONA.md; if missing fall back to general defaults.
- *
- *   mode==='orchestrator'
- *     → prefer <kind>/orchestrator.md (which must embed the kernel via
- *       @include orchestration-kernel.md — inlined by the loader).
- *       If no orchestrator.md exists for this kind, compose:
- *         <kind>/PERSONA.md body  +  '\n\n'  +  kernel body
- *       If even the PERSONA.md is missing, fall back to general defaults + kernel.
- *
- * Frontmatter from whichever file is the primary source (orchestrator.md >
- * PERSONA.md) supplies model/skills/extensions/tools. Lifecycle and spine position
- * are INPUTS (the caller decides them — root/child, terminal/resident), not
- * derived here; they select the lifecycle/spine protocol fragments spliced
- * ahead of the persona body.
  */
-import { loadPersona, loadKernel, loadRuntimeBase, loadSpineFragment, loadLifecycleFragment, loadWaitingFragment, subPersonasFor } from './loader.js';
+import { getNode } from '../canvas/index.js';
+import { renderKnowledgeBlock, renderPreferencesSection } from '../substrate/render.js';
+import { loadPersona, loadPersonaSource, loadKernelSource, loadRuntimeBaseSource, loadSpineFragmentSource, loadLifecycleFragmentSource, loadWaitingFragmentSource, loadScopedText, subPersonasFor, } from './loader.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function toStringArray(v) {
     if (!Array.isArray(v))
         return [];
-    // yaml.parse coerces scalars to native types; the persona prompt needs strings,
-    // so coerce each scalar element (dropping nested objects/arrays/null) — this
-    // mirrors the prior hand-rolled parser, which returned every scalar as a string.
     return v.filter((x) => x != null && typeof x !== 'object').map((x) => String(x));
 }
 function toOptionalString(v) {
     if (typeof v === 'string')
         return v;
-    // Preserve the legacy parser's string-typed contract for native scalars
-    // (e.g. `model: 4` must compose as "4", not be dropped as a non-string).
     if (typeof v === 'number' || typeof v === 'boolean')
         return String(v);
     return undefined;
 }
-/** The bare-minimum system prompt used when no persona file is found at all. */
 function fallbackBasePrompt(kind) {
     return `You are a ${kind} agent. Complete the task you have been given.`;
 }
-/** Compose the runtime protocol that precedes every persona body: the
- *  lifecycle-neutral base (identity/delegate/ask/promote), then the spine
- *  fragment (report-up vs. silent, keyed on whether the node has a manager),
- *  then the lifecycle fragment (finish-with-`push final` vs. dormant/wake). The
- *  kind×mode persona body follows after a rule. Empty fragments drop out. */
-/** Render the "sub-personas you may spawn" menu for a kind that has any
- *  available to it. Returns '' when none are. Data-driven: one line per
- *  sub-persona, its spawn string + its `whenToUse`. A sub-persona surfaces here
- *  for a kind when its `availableTo` includes that kind (default: its own
- *  top-level ancestor) or is the wildcard. */
+function approxTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function makeLayer(part) {
+    return {
+        ...part,
+        chars: part.text.length,
+        tokens: approxTokens(part.text),
+    };
+}
+function trimBlock(text) {
+    return text.trim();
+}
+function includeTargets(rawBody) {
+    const targets = [];
+    const re = /^@include\s+(\S+)\s*$/gm;
+    for (const match of rawBody.matchAll(re)) {
+        targets.push(match[1]);
+    }
+    return targets;
+}
+function addSource(list, seen, source) {
+    if (source === null)
+        return;
+    const key = `${source.scope}:${source.path}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    list.push(source);
+}
+function resolveSourceRef(path, label) {
+    const loaded = loadScopedText(path);
+    if (!loaded)
+        return null;
+    return { id: label, label, path: loaded.sourcePath, scope: loaded.scope };
+}
+function collectPersonaSources(primary, fallbackLabel) {
+    const sources = [];
+    const seen = new Set();
+    if (primary !== null) {
+        addSource(sources, seen, {
+            id: fallbackLabel,
+            label: fallbackLabel,
+            path: primary.sourcePath,
+            scope: primary.scope,
+        });
+        for (const target of includeTargets(primary.rawBody)) {
+            addSource(sources, seen, resolveSourceRef(target, `included: ${target}`));
+        }
+    }
+    return sources;
+}
+function basePersonaLayer(kind, mode) {
+    const source = loadPersonaSource(kind, mode);
+    if (source !== null) {
+        const label = mode === 'base' ? 'Persona body' : 'Orchestrator body';
+        return {
+            layer: makeLayer({
+                id: 'persona-body',
+                label,
+                group: 'persona',
+                source: source.source,
+                sourcePath: source.sourcePath,
+                scope: source.scope,
+                included: true,
+                condition: null,
+                text: source.body || fallbackBasePrompt(kind),
+            }),
+            sources: collectPersonaSources(source, label),
+        };
+    }
+    if (mode === 'orchestrator') {
+        const base = loadPersonaSource(kind, 'base');
+        const kernel = loadKernelSource();
+        const body = `${base?.body || fallbackBasePrompt(kind)}${kernel ? `\n\n${kernel.text}` : ''}`;
+        const layer = makeLayer({
+            id: 'persona-body',
+            label: 'Orchestrator body',
+            group: 'persona',
+            source: base?.sourcePath !== undefined ? base.source : 'generated: base persona + kernel',
+            sourcePath: base?.sourcePath ?? null,
+            scope: base?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: body,
+        });
+        const sources = [];
+        const seen = new Set();
+        if (base !== null) {
+            addSource(sources, seen, { id: 'persona-body', label: 'Persona body', path: base.sourcePath, scope: base.scope });
+            for (const target of includeTargets(base.rawBody)) {
+                addSource(sources, seen, resolveSourceRef(target, `included: ${target}`));
+            }
+        }
+        if (kernel !== null) {
+            addSource(sources, seen, { id: 'kernel', label: 'Kernel', path: kernel.sourcePath, scope: kernel.scope });
+        }
+        return { layer, sources };
+    }
+    const layer = makeLayer({
+        id: 'persona-body',
+        label: 'Persona body',
+        group: 'persona',
+        source: 'generated: fallback persona',
+        sourcePath: null,
+        scope: 'generated',
+        included: true,
+        condition: null,
+        text: fallbackBasePrompt(kind),
+    });
+    return { layer, sources: [] };
+}
+function protocolLayers(lifecycle, hasManager) {
+    const runtime = loadRuntimeBaseSource();
+    const wait = loadWaitingFragmentSource();
+    const spineHas = loadSpineFragmentSource(true);
+    const spineNo = loadSpineFragmentSource(false);
+    const lifecycleTerminal = loadLifecycleFragmentSource('terminal');
+    const lifecycleResident = loadLifecycleFragmentSource('resident');
+    return [
+        makeLayer({
+            id: 'runtime-base',
+            label: 'Runtime base',
+            group: 'protocol',
+            source: 'personas/runtime-base.md',
+            sourcePath: runtime?.sourcePath ?? null,
+            scope: runtime?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: trimBlock(runtime?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'spine-has-manager',
+            label: 'Has manager',
+            group: 'protocol',
+            source: 'personas/spine/has-manager.md',
+            sourcePath: spineHas?.sourcePath ?? null,
+            scope: spineHas?.scope ?? 'generated',
+            included: hasManager,
+            condition: hasManager ? null : 'hasManager == false',
+            text: trimBlock(spineHas?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'spine-no-manager',
+            label: 'No manager',
+            group: 'protocol',
+            source: 'personas/spine/no-manager.md',
+            sourcePath: spineNo?.sourcePath ?? null,
+            scope: spineNo?.scope ?? 'generated',
+            included: !hasManager,
+            condition: hasManager ? 'hasManager == true' : null,
+            text: trimBlock(spineNo?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'lifecycle-terminal',
+            label: 'Terminal lifecycle',
+            group: 'protocol',
+            source: 'personas/lifecycle/terminal.md',
+            sourcePath: lifecycleTerminal?.sourcePath ?? null,
+            scope: lifecycleTerminal?.scope ?? 'generated',
+            included: lifecycle === 'terminal',
+            condition: lifecycle === 'terminal' ? null : 'lifecycle == resident',
+            text: trimBlock(lifecycleTerminal?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'lifecycle-resident',
+            label: 'Resident lifecycle',
+            group: 'protocol',
+            source: 'personas/lifecycle/resident.md',
+            sourcePath: lifecycleResident?.sourcePath ?? null,
+            scope: lifecycleResident?.scope ?? 'generated',
+            included: lifecycle === 'resident',
+            condition: lifecycle === 'resident' ? null : 'lifecycle == terminal',
+            text: trimBlock(lifecycleResident?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'waiting',
+            label: 'Waiting',
+            group: 'protocol',
+            source: 'personas/waiting.md',
+            sourcePath: wait?.sourcePath ?? null,
+            scope: wait?.scope ?? 'generated',
+            included: true,
+            condition: null,
+            text: trimBlock(wait?.text ?? ''),
+        }),
+        makeLayer({
+            id: 'separator',
+            label: 'Separator',
+            group: 'protocol',
+            source: 'generated: separator',
+            sourcePath: null,
+            scope: 'generated',
+            included: true,
+            condition: null,
+            text: '---',
+        }),
+    ];
+}
 function renderSubPersonaMenu(kind) {
     const subs = subPersonasFor(kind);
     if (subs.length === 0)
-        return '';
-    const lines = subs.map((s) => `- \`${s.kind}\` — ${s.whenToUse}`);
-    return [
+        return { layer: null, sources: [] };
+    const lines = [
         '## Sub-personas you may spawn',
         '',
-        `These specialist sub-personas are available to the ${kind} kind. Spawn one with \`crtr node new --kind <sub> "<scope>"\`, giving it only its scope, never your suspicions: a reviewer handed a hint anchors on it instead of finding problems independently.`,
+        `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.`,
         '',
-        ...lines,
-    ].join('\n');
+    ];
+    const sources = [];
+    const seen = new Set();
+    for (const sub of subs) {
+        const src = loadPersonaSource(sub.kind, 'base');
+        if (src !== null) {
+            addSource(sources, seen, { id: sub.kind, label: sub.kind, path: src.sourcePath, scope: src.scope });
+            lines.push(`- \`${sub.kind}\` — ${sub.whenToUse} (${src.sourcePath})`);
+        }
+        else {
+            lines.push(`- \`${sub.kind}\` — ${sub.whenToUse}`);
+        }
+    }
+    return {
+        layer: makeLayer({
+            id: 'subpersona-menu',
+            label: 'Sub-persona menu',
+            group: 'generated',
+            source: 'generated: sub-persona menu',
+            sourcePath: null,
+            scope: 'generated',
+            included: true,
+            condition: null,
+            text: lines.join('\n'),
+        }),
+        sources,
+    };
 }
-function composeProtocol(personaPrompt, kind, lifecycle, hasManager) {
+function coreLayers(kind, mode, opts) {
+    const protocol = protocolLayers(opts.lifecycle, opts.hasManager);
+    const body = basePersonaLayer(kind, mode);
     const menu = renderSubPersonaMenu(kind);
-    const body = menu ? `${personaPrompt}\n\n${menu}` : personaPrompt;
-    const protocol = [
-        loadRuntimeBase(),
-        loadSpineFragment(hasManager),
-        loadLifecycleFragment(lifecycle),
-        loadWaitingFragment(),
-    ]
-        .filter((s) => s.length > 0)
-        .join('\n\n');
-    return protocol ? `${protocol}\n\n---\n\n${body}` : body;
+    const layers = [...protocol, body.layer];
+    if (menu.layer !== null)
+        layers.push(menu.layer);
+    const sources = [];
+    const seen = new Set();
+    for (const layer of protocol) {
+        if (layer.sourcePath === null)
+            continue;
+        addSource(sources, seen, { id: layer.id, label: layer.label, path: layer.sourcePath, scope: layer.scope });
+    }
+    for (const source of body.sources)
+        addSource(sources, seen, source);
+    for (const source of menu.sources)
+        addSource(sources, seen, source);
+    return { layers, sources };
 }
-export function resolve(kind, mode, opts) {
-    if (mode === 'base') {
-        const persona = loadPersona(kind, 'base');
-        if (!persona) {
-            // No persona file for this kind — use minimal defaults.
-            return {
-                systemPrompt: composeProtocol(fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-                extensions: [],
-                skills: [],
-                lifecycle: opts.lifecycle,
-            };
-        }
-        const fm = persona.frontmatter ?? {};
-        return {
-            systemPrompt: composeProtocol(persona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-            extensions: toStringArray(fm['extensions']),
-            skills: toStringArray(fm['skills']),
-            model: toOptionalString(fm['model']),
-            lifecycle: opts.lifecycle,
-            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
-        };
+function joinIncluded(layers) {
+    return layers.filter((layer) => layer.included && layer.text.length > 0).map((layer) => layer.text).join('\n\n');
+}
+function spliceRuntimeSubstrate(systemPrompt, nodeId) {
+    const pref = renderPreferencesSection(nodeId).trim();
+    const blocks = [];
+    const layers = [];
+    if (pref !== '') {
+        const text = pref;
+        blocks.push(text);
+        layers.push(makeLayer({
+            id: 'memory-preference',
+            label: 'Memory — usage guidance + preferences',
+            group: 'substrate',
+            source: 'runtime-spliced',
+            sourcePath: null,
+            scope: 'runtime',
+            included: true,
+            condition: null,
+            text,
+        }));
     }
-    // mode === 'orchestrator'
-    const orchestratorPersona = loadPersona(kind, 'orchestrator');
-    if (orchestratorPersona) {
-        // Orchestrator file exists; @include was already inlined by the loader.
-        const fm = orchestratorPersona.frontmatter ?? {};
-        return {
-            systemPrompt: composeProtocol(orchestratorPersona.body || fallbackBasePrompt(kind), kind, opts.lifecycle, opts.hasManager),
-            extensions: toStringArray(fm['extensions']),
-            skills: toStringArray(fm['skills']),
-            model: toOptionalString(fm['model']),
-            lifecycle: opts.lifecycle,
-            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
-        };
+    const knowledge = renderKnowledgeBlock(nodeId).trim();
+    if (knowledge !== '') {
+        layers.push(makeLayer({
+            id: 'memory-knowledge',
+            label: 'Memory (knowledge) — context message, not system prompt',
+            group: 'substrate',
+            source: 'runtime-spliced',
+            sourcePath: null,
+            scope: 'runtime',
+            included: false,
+            condition: 'session_start context message, not the system prompt',
+            text: knowledge,
+        }));
     }
-    // No orchestrator.md for this kind — compose base + bare kernel.
-    const kernel = loadKernel();
-    const basePersona = loadPersona(kind, 'base');
-    const baseBody = basePersona?.body || fallbackBasePrompt(kind);
-    const fm = basePersona?.frontmatter ?? {};
-    // Append the kernel to the base body (with separator if kernel is non-empty).
-    const systemPrompt = kernel ? `${baseBody}\n\n${kernel}` : baseBody;
+    if (blocks.length === 0)
+        return { prompt: systemPrompt, layers };
+    const insert = blocks.join('\n\n');
+    const anchor = '\n\nGuidelines:';
+    const idx = systemPrompt.indexOf(anchor);
+    if (idx === -1)
+        return { prompt: `${systemPrompt}\n\n${insert}`, layers };
+    return { prompt: `${systemPrompt.slice(0, idx)}\n\n${insert}${systemPrompt.slice(idx)}`, layers };
+}
+function collectLayers(kind, mode, opts, nodeId) {
+    const core = coreLayers(kind, mode, opts);
+    const assembledCore = joinIncluded(core.layers);
+    const node = nodeId !== undefined ? getNode(nodeId) : null;
+    const config = {
+        kind,
+        mode,
+        lifecycle: opts.lifecycle,
+        hasManager: opts.hasManager,
+        node: node !== null ? node.node_id : null,
+    };
+    const substrate = node !== null ? spliceRuntimeSubstrate(assembledCore, node.node_id) : { prompt: assembledCore, layers: [] };
+    const layers = [...core.layers, ...substrate.layers];
+    const sources = [];
+    const seen = new Set();
+    for (const source of core.sources)
+        addSource(sources, seen, source);
+    const included = layers.filter((layer) => layer.included).reduce((acc, layer) => ({ tokens: acc.tokens + layer.tokens, chars: acc.chars + layer.chars }), { tokens: 0, chars: 0 });
+    return {
+        config,
+        layers,
+        assembled: substrate.prompt,
+        total: included,
+        sources,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ */
+export function resolve(kind, mode, opts) {
+    const persona = mode === 'base' ? loadPersona(kind, 'base') : loadPersona(kind, 'orchestrator') ?? loadPersona(kind, 'base');
+    const fm = persona?.frontmatter ?? {};
+    const systemPrompt = joinIncluded(coreLayers(kind, mode, opts).layers);
     return {
-        systemPrompt: composeProtocol(systemPrompt, kind, opts.lifecycle, opts.hasManager),
+        systemPrompt,
         extensions: toStringArray(fm['extensions']),
-        skills: toStringArray(fm['skills']),
         model: toOptionalString(fm['model']),
         lifecycle: opts.lifecycle,
         tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
     };
 }
+export function resolveLayers(kind, mode, opts) {
+    return coreLayers(kind, mode, opts).layers;
+}
+export function resolvePromptReview(kind, mode, opts, nodeId) {
+    return collectLayers(kind, mode, opts, nodeId);
+}

package/dist/core/runtime/auth-reload.d.ts

@@ -0,0 +1,7 @@
+/** Reload a LIVE node's credentials over its view.sock. Connects as an OBSERVER
+ *  (hello only — NO request_control, so an attached human keeps control through
+ *  the fan; the broker's reload_auth handler is open to any client), sends
+ *  `reload_auth`, and resolves on its ack. Rejects on the broker's `error` frame,
+ *  connect failure, a premature close, or timeout — the caller (the daemon fan)
+ *  isolates each broker so one failure never aborts the rest. */
+export declare function reloadAuthLive(nodeId: string): Promise<void>;

package/dist/core/runtime/auth-reload.js

@@ -0,0 +1,69 @@
+// auth-reload.ts — fan a live credential reload to a node's broker over its
+// view.sock, the headless sibling of the viewer's own `reload_auth` frame.
+//
+// Every broker reads the SAME shared `~/.pi/agent/auth.json`. When the user
+// `/login`s (anywhere), the broker that performed it self-reloads — but every
+// OTHER live broker keeps its stale in-memory credentials until told. The
+// daemon watches auth.json's mtime and fans this RPC to each live broker so the
+// whole canvas follows one account switch with no per-broker re-login.
+//
+// connect → hello → reload_auth → await ack. NO request_control: the broker's
+// reload_auth handler is open to any client (it's an idempotent local re-read
+// that doesn't steer the conversation), so the fan must NOT claim controller —
+// request_control ALWAYS preempts, which would silently demote any human
+// attached-and-driving a node every time /login fans canvas-wide.
+import { randomUUID } from 'node:crypto';
+import { ViewSocketClient } from './view-socket-client.js';
+/** How long to wait for the broker's `reload_auth` ack before giving up. The
+ *  reload is an instant local file read + registry refresh, and the daemon's
+ *  supervision loop awaits this on a real change — so the timeout is kept tight
+ *  to cap the worst-case stall if a broker connects but never acks. */
+const ACK_TIMEOUT_MS = 3_000;
+/** Reload a LIVE node's credentials over its view.sock. Connects as an OBSERVER
+ *  (hello only — NO request_control, so an attached human keeps control through
+ *  the fan; the broker's reload_auth handler is open to any client), sends
+ *  `reload_auth`, and resolves on its ack. Rejects on the broker's `error` frame,
+ *  connect failure, a premature close, or timeout — the caller (the daemon fan)
+ *  isolates each broker so one failure never aborts the rest. */
+export function reloadAuthLive(nodeId) {
+    return new Promise((resolve, reject) => {
+        const client = new ViewSocketClient(nodeId);
+        const clientId = randomUUID();
+        let settled = false;
+        const timer = setTimeout(() => finish(() => reject(new Error(`timed out after ${ACK_TIMEOUT_MS}ms waiting for the broker to ack the auth reload`))), ACK_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        function finish(act) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                client.close();
+            }
+            catch {
+                /* best-effort */
+            }
+            act();
+        }
+        client.on('error', (err) => finish(() => reject(err)));
+        client.on('close', () => finish(() => reject(new Error('broker connection closed before it acked the auth reload'))));
+        client.on('connect', () => {
+            // Hello as OBSERVER — reload_auth is open to any client, and an observer
+            // hello never touches controllerId, so a human driving this broker keeps
+            // control through the fan. (A `controller` hello also only takes control
+            // when none is held, which is safe; observer is the more honest signal.)
+            client.send({ type: 'hello', role: 'observer', client_id: clientId });
+            client.send({ type: 'reload_auth' });
+        });
+        client.on('frame', (frame) => {
+            if (frame.type === 'ack' && frame.for === 'reload_auth' && frame.ok) {
+                finish(() => resolve());
+            }
+            else if (frame.type === 'error') {
+                finish(() => reject(new Error(frame.message)));
+            }
+        });
+        client.connect();
+    });
+}

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

@@ -1,23 +1,36 @@
 import { type WakeKind, type Wakeup } from '../canvas/index.js';
-/** Base framing — present for every node. No path baked in: the caller carries
- *  the dir in the `<crtr-context dir="…">` attribute. */
-export declare const BASE_CONTEXT_NOTE: string;
+/** The `<project_context>` block for the files discovered from `cwd`, plus the
+ *  cwd/git environment snapshot that now rides at the end of the wrapper.
+ *  Always emits the wrapper because the environment snapshot is always present
+ *  even when no project instructions exist. Exported for testing. */
+export declare function buildProjectContextBlock(cwd: string): string;
+/** The context-directory note — names the path INLINE (no XML attribute, so it
+ *  never scopes a sibling block) and frames the dir as durable, shared scratch.
+ *  Present for every node, rendered as the `## Your context directory`
+ *  subsection of <crtr-bearings>. */
+export declare function contextDirNote(nodeId: string): string;
 /** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
  *  so its context dir is also where a future cycle of itself resumes the work.
  *  Used inside the bearings block AND in the promotion guidance dump, so a
  *  promoted node gets the same note a born-orchestrator gets. */
 export declare function orchestratorContextNote(nodeId: string): string;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). Exported for testing. */
+export declare function buildGraphMap(nodeId: string): string;
 /** The IDENTITY assertion that opens every boot intro — the load-bearing fix
  *  for the `--fork-from` impersonation bug. A fork copies the SOURCE node's
  *  entire first-person conversation into its own session, so without an explicit
  *  re-assertion the forked agent reads that copied narrative as its own and
  *  impersonates the source (it kept "monitoring itself" as a phantom child).
- *  This block names the node unambiguously. ONLY when the node IS a fork does it
- *  additionally name the source AND disown the copied first-person narrative as
- *  inherited reference material — a non-fork node's bearings are its first session
- *  entry, so there is no earlier narrative to disown (emitting a disown line there
- *  is dead weight that reads as a contradiction with no referent). Always the FIRST
- *  thing the node reads. Exported for testing. */
+ *  These lines name the node unambiguously and lead the <crtr-bearings> block
+ *  (no wrapper of their own — identity is the first prose the model reads). ONLY
+ *  when the node IS a fork do they additionally name the source AND disown the
+ *  copied first-person narrative as inherited reference material — a non-fork
+ *  node's bearings are its first session entry, so there is no earlier narrative
+ *  to disown (emitting a disown line there is dead weight that reads as a
+ *  contradiction with no referent). Also prepended to a fork's kickoff prompt in
+ *  spawn.ts. Exported for testing. */
 export declare function buildIdentityAssertion(nodeId: string): string;
 /** Why a node woke or was born, as carried from the fired wakeup row to the
  *  injection seam. `ownerName` is the armer's resolved display name when it
@@ -52,10 +65,17 @@ export declare function wakeOriginFrom(w: Wakeup): WakeOrigin;
  *  agent cannot cheaply turn into an elapsed delta). Rendered for 'spawn' and
  *  'bare'; other kinds self-mark elsewhere. */
 export declare function buildWakeBearings(origin: WakeOrigin): string;
-/** The full boot intro: the IDENTITY assertion (always first, so it overrides
- *  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 `<knowledge>` block carries the substrate knowledge docs
- *  + node-local docs. */
+/** The full boot intro, three top-level sections:
+ *
+ *   1. `<crtr-bearings>` — the orienting facts about THIS node: the identity
+ *      assertion (always first, so it overrides any copied-in persona), then a
+ *      `## Your place in the canvas` graph map and a `## Your context directory`
+ *      note. The across-cycles context-dir framing is added ONLY for an
+ *      orchestrator (by mode) — the one node whose dir a future cycle resumes
+ *      from.
+ *   2. `<memory kind="knowledge">` — the consultable catalog, a SIBLING of the
+ *      bearings (never nested under the context dir). Dropped when empty.
+ *   3. `<project_context>` — the AGENTS.md/CLAUDE.md instructions + the cwd/git
+ *      environment snapshot, moved OUT of the system prompt (pi's copy is
+ *      suppressed via noContextFiles in broker.ts) so it rides this message. */
 export declare function buildContextBearings(nodeId: string): string;