@crouton-kit/crouter 0.3.19 → 0.3.21

package/dist/core/render.js

@@ -1,14 +1,18 @@
 // Default stdout rendering: the result a leaf returns is written FOR the model
 // to act on, not as data to parse. Output is a continuation of the agent's
-// prompt — light XML fences around markdown, prose where prose belongs. The
-// raw JSON object is still available behind the `--json` global for tooling.
+// prompt — PLAIN MARKDOWN, no XML wrapper. Scalars list as `- name: value`
+// bullets in output-schema order, prose fields render as paragraphs, and arrays
+// become a count lead-in plus a markdown table (objects) or bullets (scalars).
+// The raw JSON object is still available behind the `--json` global for tooling.
 //
 // A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
-// output (see `node new`, `push`, `feed read`). Everything else falls through to
-// the schema-driven generic renderer here, so every command obeys the paradigm
-// without a hand-written renderer.
+// output that leads with the outcome (see `node new`, `push`, `feed read`).
+// Everything else falls through to the schema-driven generic renderer here, so
+// every command obeys the markdown paradigm without a hand-written renderer.
+// `renderError` is the one sanctioned exception: a failure is a different domain
+// from a result, so it keeps its `<error>` block.
 // Field names whose value is prose the agent reads, not a scalar it keys on —
-// these always render as their own fenced block, never as a tag attribute.
+// these always render as their own paragraph, never as a `- name: value` bullet.
 const PROSE_FIELDS = new Set([
     'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
     'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
@@ -37,20 +41,17 @@ function isProse(name, v) {
         return true;
     return v.includes('\n') || v.length > 80;
 }
-/** Short, space-free scalars ride as attributes on the open tag (ids, statuses,
- *  counts); everything else that isn't prose lists as a markdown bullet. */
-function isAttr(v) {
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return true;
-    return typeof v === 'string' && v.length <= 40 && !v.includes(' ') && !v.includes('\n');
-}
-/** Root element name = the command path with spaces hyphenated. */
-function rootTag(help) {
-    return help.name.trim().split(/\s+/).join('-').replace(/[^a-zA-Z0-9_-]/g, '') || 'result';
+/** Keep a value safe inside a markdown table cell: pipes would split columns,
+ *  newlines would break the row. */
+function cellEsc(v) {
+    return scalarStr(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
 }
+/** An array renders as a count lead-in followed by the collection: a markdown
+ *  table when every element is an object, plain bullets otherwise. */
 function renderArray(name, arr) {
     if (arr.length === 0)
-        return `<${name} count="0"></${name}>`;
+        return `0 ${name}.`;
+    const lead = `${arr.length} ${name}:`;
     const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
     if (allObjects) {
         const rows = arr;
@@ -61,55 +62,51 @@ function renderArray(name, arr) {
                     cols.push(k);
         const head = `| ${cols.join(' | ')} |`;
         const sep = `| ${cols.map(() => '---').join(' | ')} |`;
-        const body = rows.map((r) => `| ${cols.map((c) => scalarStr(r[c])).join(' | ')} |`).join('\n');
-        return `<${name} count="${arr.length}">\n${head}\n${sep}\n${body}\n</${name}>`;
+        const body = rows.map((r) => `| ${cols.map((c) => cellEsc(r[c])).join(' | ')} |`).join('\n');
+        return `${lead}\n\n${head}\n${sep}\n${body}`;
     }
     const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
-    return `<${name} count="${arr.length}">\n${items}\n</${name}>`;
+    return `${lead}\n${items}`;
 }
-/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
  *  Field order follows the leaf's declared output schema; any extra keys append
- *  after. Scalars become attributes or a bullet list, prose and collections
- *  become their own fenced blocks. */
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
 export function renderResult(result, help) {
     const order = help.output.map((f) => f.name);
     for (const k of Object.keys(result))
         if (!order.includes(k))
             order.push(k);
-    const attrs = [];
     const bullets = [];
-    const blocks = [];
+    const proseFields = [];
+    const arrays = [];
     for (const name of order) {
         const v = result[name];
         if (v === undefined || v === null)
             continue;
         if (Array.isArray(v)) {
-            blocks.push(renderArray(name, v));
-            continue;
-        }
-        if (typeof v === 'object') {
-            blocks.push(`<${name}>\n${JSON.stringify(v, null, 2)}\n</${name}>`);
+            arrays.push(renderArray(name, v));
             continue;
         }
         if (isProse(name, v)) {
-            blocks.push(`<${name}>\n${v}\n</${name}>`);
-            continue;
-        }
-        if (isAttr(v)) {
-            attrs.push(`${name}="${attrEsc(v)}"`);
+            proseFields.push({ name, text: v });
             continue;
         }
+        // Scalars and nested objects alike list as a bullet (objects via compact JSON).
         bullets.push(`- ${name}: ${scalarStr(v)}`);
     }
-    const tag = rootTag(help);
-    const open = attrs.length > 0 ? `<${tag} ${attrs.join(' ')}>` : `<${tag}>`;
     const parts = [];
     if (bullets.length > 0)
         parts.push(bullets.join('\n'));
-    if (blocks.length > 0)
-        parts.push(blocks.join('\n\n'));
-    const inner = parts.join('\n\n');
-    return inner !== '' ? `${open}\n${inner}\n</${tag}>` : `${open}</${tag}>`;
+    // Label prose only when more than one block would otherwise blur together.
+    const labelProse = proseFields.length > 1;
+    for (const { name, text } of proseFields) {
+        parts.push(labelProse ? `**${name}:** ${text}` : text);
+    }
+    for (const block of arrays)
+        parts.push(block);
+    return parts.join('\n\n');
 }
 /** Render a structured failure as an instruction-shaped block: what broke, what
  *  was received, and the recovery road sign — the same recovery info the JSON

package/dist/core/resolver.js

@@ -403,7 +403,7 @@ function formatNotFoundMessage(rawName, skillName, pluginQualifier) {
         lines.push(`       did you mean: ${formatted.join(', ')}`);
     }
     else {
-        lines.push('       run `crtr skill find list` or `crtr skill find search <query>` to discover skills');
+        lines.push('       run `crtr memory list` or `crtr memory find "<query>"` to discover skills');
     }
     return lines.join('\n');
 }

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 (substrate reference docs +
- *  node-local docs) replaces the old `<memory>` block. */
+ *  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

@@ -145,8 +145,8 @@ 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 (substrate reference docs +
- *  node-local docs) replaces the old `<memory>` block. */
+ *  resumes from. The `## References` block carries the substrate reference docs
+ *  + node-local docs. */
 export function buildContextBearings(nodeId) {
     const identity = buildIdentityAssertion(nodeId);
     const dir = contextDir(nodeId);

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

@@ -22,8 +22,14 @@ export declare const CANVAS_VIEW_PATH: string;
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];
-/** Bare model aliases resolve to the anthropic provider under pi (avoids the
- *  bedrock default). Anything with a `/` or an unknown name passes through. */
+/** The named capability tiers a caller picks with `--model`, in descending
+ *  strength. Each maps to a concrete pi model spec. `strong`/`medium`/`light`
+ *  resolve to the latest opus/sonnet/haiku; `ultra` to the frontier model. */
+export declare const MODEL_TIERS: Record<string, string>;
+/** Resolve a model token to the spec pi gets via `--model`. A named tier
+ *  (ultra/strong/medium/light) maps to its concrete spec; a bare alias
+ *  (sonnet/opus/haiku) resolves to the anthropic provider under pi (avoids the
+ *  bedrock default); anything with a `/` or an unknown name passes through. */
 export declare function normalizeModel(model: string): string;
 /** Compose a node's full pi launch recipe from its persona. The system prompt
  *  is composed from FOUR inputs: kind×mode (the persona body) plus lifecycle
@@ -36,6 +42,7 @@ export declare function buildLaunchSpec(kind: string, mode: Mode, opts: {
     lifecycle: Lifecycle;
     hasManager: boolean;
     extraEnv?: Record<string, string>;
+    model?: string;
 }): {
     launch: LaunchSpec;
     lifecycle: 'terminal' | 'resident';

package/dist/core/runtime/launch.js

@@ -60,9 +60,22 @@ export const CANVAS_EXTENSIONS = [
     CANVAS_RESUME_PATH,
     CANVAS_VIEW_PATH,
 ];
-/** Bare model aliases resolve to the anthropic provider under pi (avoids the
- *  bedrock default). Anything with a `/` or an unknown name passes through. */
+/** The named capability tiers a caller picks with `--model`, in descending
+ *  strength. Each maps to a concrete pi model spec. `strong`/`medium`/`light`
+ *  resolve to the latest opus/sonnet/haiku; `ultra` to the frontier model. */
+export const MODEL_TIERS = {
+    ultra: 'anthropic/claude-fable-5',
+    strong: 'anthropic/opus',
+    medium: 'anthropic/sonnet',
+    light: 'anthropic/haiku',
+};
+/** Resolve a model token to the spec pi gets via `--model`. A named tier
+ *  (ultra/strong/medium/light) maps to its concrete spec; a bare alias
+ *  (sonnet/opus/haiku) resolves to the anthropic provider under pi (avoids the
+ *  bedrock default); anything with a `/` or an unknown name passes through. */
 export function normalizeModel(model) {
+    if (model in MODEL_TIERS)
+        return MODEL_TIERS[model];
     const bare = new Set(['sonnet', 'opus', 'haiku']);
     if (bare.has(model))
         return `anthropic/${model}`;
@@ -80,8 +93,12 @@ export function normalizeModel(model) {
  *  declared extensions follow. */
 export function buildLaunchSpec(kind, mode, opts) {
     const p = resolvePersona(kind, mode, { lifecycle: opts.lifecycle, hasManager: opts.hasManager });
+    // A caller-supplied override (durable on `meta.model_override`, re-passed on
+    // every polymorph) wins over the persona's declared default; absent both, the
+    // model is left unset and the node inherits pi's default.
+    const chosenModel = opts.model ?? p.model;
     const launch = {
-        model: p.model !== undefined ? normalizeModel(p.model) : undefined,
+        model: chosenModel !== undefined ? normalizeModel(chosenModel) : undefined,
         tools: p.tools,
         extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
         systemPrompt: p.systemPrompt,

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

@@ -98,6 +98,10 @@ export interface SpawnNodeOpts {
     passiveDefault?: boolean;
     /** Resolved pi launch recipe (from resolve(kind,mode)). */
     launch?: LaunchSpec;
+    /** Caller-pinned model tier (ultra/strong/medium/light) that overrides the
+     *  persona default. Persisted to `meta.model_override` so polymorphs preserve
+     *  it. Omit to use the persona default. */
+    modelOverride?: string | null;
     /** Override the generated id (e.g. when a caller pre-allocates one). */
     nodeId?: string;
 }

package/dist/core/runtime/nodes.js

@@ -179,6 +179,7 @@ export function spawnNode(opts) {
         parent,
         spawned_by: spawnedBy,
         fork_from: opts.forkFrom,
+        model_override: opts.modelOverride ?? null,
         passive_default: opts.passiveDefault ?? false,
         intent: null,
         pi_session_id: null,

package/dist/core/runtime/promote.js

@@ -46,6 +46,9 @@ export function promote(nodeId, opts = {}) {
     const { launch } = buildLaunchSpec(targetKind, 'orchestrator', {
         lifecycle: opts.resident === true ? 'resident' : node.lifecycle,
         hasManager: node.parent !== null,
+        // Preserve a caller-pinned model tier across the polymorph (the persona
+        // default is recomputed fresh for targetKind).
+        model: node.model_override ?? undefined,
     });
     // Seed a barebones roadmap scaffold if absent so the file exists for a
     // refresh. Pre-fill its Goal from the node's goal doc when present (set at

package/dist/core/runtime/reset.js

@@ -112,7 +112,7 @@ export function resetRoot(nodeId, newSessionId, newSessionFile) {
     //    Re-seed persona_ack to the fresh persona so the pristine `/new`
     //    conversation never gets a spurious mode/lifecycle transition steer (the
     //    persona injector compares against this ack).
-    const { launch } = buildLaunchSpec(meta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    const { launch } = buildLaunchSpec(meta.kind, 'base', { lifecycle: 'resident', hasManager: false, model: meta.model_override ?? undefined });
     updateNode(nodeId, {
         mode: 'base',
         lifecycle: 'resident',
@@ -180,7 +180,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
         window: oldMeta.window ?? null,
     };
     const newId = newNodeId();
-    const { launch } = buildLaunchSpec(oldMeta.kind, 'base', { lifecycle: 'resident', hasManager: false });
+    const { launch } = buildLaunchSpec(oldMeta.kind, 'base', { lifecycle: 'resident', hasManager: false, model: oldMeta.model_override ?? undefined });
     // Park-old + mint-new is the single most fragile spot in the runtime, so it is
     // ONE atomic unit: every ROW write below runs inside a sqlite transaction. A
     // failure anywhere — including the respawn DISPATCH — rolls the whole thing
@@ -206,6 +206,7 @@ export function relaunchRoot(oldId, pane, deps = {}) {
             parent: null,
             spawnedBy: oldId, // audit-only successor link; does NOT touch the spine
             nodeId: newId,
+            modelOverride: oldMeta.model_override,
             launch,
         });
         transition(newId, 'yield'); // active (from spawn) + intent=refresh safety net

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

@@ -39,6 +39,10 @@ export interface SpawnChildOpts {
      *  headless broker. Persisted as `host_kind` at birth (resolved from
      *  `--headless` / the `headless` config default by the caller). */
     hostKind?: 'tmux' | 'broker';
+    /** Pin the node to a model TIER (ultra/strong/medium/light), overriding the
+     *  persona's declared default. Persisted to `meta.model_override` so it
+     *  survives polymorphs. Omit to use the persona default. */
+    model?: string;
 }
 /** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
  *  A live node id resolves to its captured session FILE (absolute, cwd-immune),

package/dist/core/runtime/spawn.js

@@ -161,7 +161,7 @@ export function spawnChild(opts) {
     // Spine: a managed child reports up to its spawner (has a manager); an
     // independent root sits top-of-spine with nobody to push to. Mirrors the
     // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
-    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root });
+    const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
     // Name the worker from its task now, so its first editor label carries it.
     const meta = spawnNode({
         kind: opts.kind,
@@ -180,6 +180,7 @@ export function spawnChild(opts) {
         // identity over the source's copied-in conversation.
         forkFrom: opts.forkFrom,
         hostKind: opts.hostKind,
+        modelOverride: opts.model,
         launch,
     });
     // Persist the task as the child's goal for a fresh revive to re-read.

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

@@ -14,8 +14,7 @@ export declare function renderPreferencesSection(nodeId: string): string;
  *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
  *  `system-prompt-visibility` (reference boot default is `none`, so only
  *  author-promoted references show) PLUS the node-local memory docs (any kind),
- *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
- *  nothing is eligible.
+ *  each a `###` sub-section. Returns '' when nothing is eligible.
  *
  *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
  *  doc drops only itself (with a loud stderr warning naming the offending path),

package/dist/core/substrate/render.js

@@ -5,8 +5,7 @@
 //     (renderPreferencesSection) — strings the D2 `before_agent_start` extension
 //     splices into the system prompt (built by a sibling AFTER this module);
 //   • the `<crtr-context>` half — `## References` (renderReferencesBlock) — the
-//     string wired into bearings.ts's session_start message, REPLACING the old
-//     `<memory>` block.
+//     string wired into bearings.ts's session_start message.
 //
 // Every doc flows through the same pipeline (design §4/§6/§9):
 //   MemoryDoc → parseSubstrateDoc → (null-filter non-substrate) →
@@ -54,10 +53,9 @@ function resolverDocs(subject, kind) {
  *  canvas home (`nodes/<id>/context/memory/`) and is OUTSIDE the scope resolver,
  *  so it is loaded directly here, its raw frontmatter run through
  *  parseSubstrateFrontmatter (mirroring the resolver pipeline), then gate-passed.
- *  Old-format / non-substrate files (incl. the MEMORY.md index, which has no
- *  `kind`) parse to null and drop out. Returned across ALL kinds — node-local is
- *  the catch-all this-node store and rides into the references block as the
- *  replacement for the old node-local `<memory>` stanza.
+ *  Non-substrate files (those with no `kind`) parse to null and drop out.
+ *  Returned across ALL kinds — node-local is the catch-all this-node store and
+ *  rides into the references block.
  *
  *  IMPORTANT: node-local docs are NOT filtered by `systemPromptVisibility` rung.
  *  A migrated node-local reference defaults to rung `none`, which would make it
@@ -122,8 +120,8 @@ function renderSubSection(d) {
  *  resolver-provided, NOT migrated — named-plugin skills at user/project scope;
  *  the SCOPE_SKILL_PLUGIN sentinel and builtin scope are EXCLUDED because they
  *  become substrate docs). Reuses skill/shared.ts's renderCatalogSection
- *  group-collapse so the boot catalog matches today's `<skills count=N>` shape.
- *  Returns '' when nothing is in the catalog. */
+ *  group-collapse for a compact, source-grouped catalog. Returns '' when nothing
+ *  is in the catalog. */
 function renderSkillCatalog(nameRungSkillDocs) {
     let pluginSkills;
     try {
@@ -138,8 +136,8 @@ function renderSkillCatalog(nameRungSkillDocs) {
     ];
     if (entries.length === 0)
         return '';
-    // Group by scope+plugin → forest-root names (drop nested children), mirroring
-    // buildSkillCatalog's source construction.
+    // Group by scope+plugin → forest-root names (drop nested children) so each
+    // source contributes only its top-level skills.
     const bySource = new Map();
     for (const e of entries) {
         const key = `${e.scope}\t${e.plugin}`;
@@ -225,8 +223,7 @@ export function renderPreferencesSection(nodeId) {
  *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
  *  `system-prompt-visibility` (reference boot default is `none`, so only
  *  author-promoted references show) PLUS the node-local memory docs (any kind),
- *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
- *  nothing is eligible.
+ *  each a `###` sub-section. Returns '' when nothing is eligible.
  *
  *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
  *  doc drops only itself (with a loud stderr warning naming the offending path),

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

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

package/dist/core/substrate/schema.js

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",