@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/skill-sync/snapshot.js

@@ -0,0 +1,120 @@
+/**
+ * Per-pair merge-base snapshot store + conflict-report helpers.
+ *
+ * All machine-local skill-sync I/O lives here. Nothing in this module is
+ * committed: everything is rooted under `~/.crouter/skill-sync/` (R-U9), which
+ * is the machine-local, uncommitted tier — never a scope's committed dirs.
+ *
+ *   snapshots/<pair-id>/body.md      merge base, frontmatter stripped (R-I3)
+ *   snapshots/<pair-id>/assets/…     byte-for-byte base of every non-SKILL.md
+ *                                    file, mirroring subdir structure (R-I3)
+ *   snapshots/<pair-id>/meta.json    { syncedAt, crtrFrontmatter, claudeFrontmatter }
+ *   conflicts/<pair-id>.md           current conflict report, if any (R-E6/OD-4)
+ *
+ * The snapshot is the SOLE change-detector (R-U4): the engine diffs body/assets
+ * against `body.md`/`assets/`, and each frontmatter value against the recorded
+ * `meta.json` value — no mtime, no fingerprint, no stamp file.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+import { userScopeRoot } from '../scope.js';
+// ── Path roots ───────────────────────────────────────────────────────────────
+/** `~/.crouter/skill-sync/` — the machine-local, uncommitted root (R-U9). */
+export function skillSyncRoot() {
+    return join(userScopeRoot(), 'skill-sync');
+}
+function snapshotsRoot() {
+    return join(skillSyncRoot(), 'snapshots');
+}
+function conflictsRoot() {
+    return join(skillSyncRoot(), 'conflicts');
+}
+/** `~/.crouter/skill-sync/snapshots/<id>/`. */
+export function snapshotDir(id) {
+    return join(snapshotsRoot(), id);
+}
+/** `~/.crouter/skill-sync/conflicts/<id>.md`. */
+export function conflictReportPath(id) {
+    return join(conflictsRoot(), `${id}.md`);
+}
+// ── Asset helpers ────────────────────────────────────────────────────────────
+/** Recursively read every file under `dir`, keyed by POSIX relpath. */
+function readAssetTree(dir) {
+    const out = new Map();
+    if (!existsSync(dir))
+        return out;
+    const walk = (cur) => {
+        for (const entry of readdirSync(cur, { withFileTypes: true })) {
+            const full = join(cur, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                const rel = relative(dir, full).split(sep).join('/');
+                out.set(rel, readFileSync(full));
+            }
+        }
+    };
+    walk(dir);
+    return out;
+}
+// ── Snapshot read / write ────────────────────────────────────────────────────
+/**
+ * Load the merge base for `id`, or `null` when the snapshot dir is absent
+ * (no prior sync — the engine seeds on first reconcile, R-S1/R-S3).
+ */
+export function readSnapshot(id) {
+    const dir = snapshotDir(id);
+    if (!existsSync(dir))
+        return null;
+    const bodyPath = join(dir, 'body.md');
+    const body = existsSync(bodyPath) ? readFileSync(bodyPath, 'utf8') : '';
+    const assets = readAssetTree(join(dir, 'assets'));
+    const metaPath = join(dir, 'meta.json');
+    const meta = existsSync(metaPath)
+        ? JSON.parse(readFileSync(metaPath, 'utf8'))
+        : { syncedAt: '', crtrFrontmatter: {}, claudeFrontmatter: {} };
+    return { body, assets, meta };
+}
+/**
+ * Write the merge base for `id` byte-for-byte. The snapshot dir is rebuilt
+ * from scratch so stale assets from a prior base never linger — the on-disk
+ * `assets/` always mirrors exactly the passed `assets` map (R-U5/R-I3).
+ */
+export function writeSnapshot(id, snapshot) {
+    const dir = snapshotDir(id);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'body.md'), snapshot.body, 'utf8');
+    const assetsDir = join(dir, 'assets');
+    mkdirSync(assetsDir, { recursive: true });
+    for (const [rel, buf] of snapshot.assets) {
+        const full = join(assetsDir, ...rel.split('/'));
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, buf);
+    }
+    writeFileSync(join(dir, 'meta.json'), `${JSON.stringify(snapshot.meta, null, 2)}\n`, 'utf8');
+}
+// ── Conflict-report helpers (R-E6 / OD-4) ────────────────────────────────────
+/**
+ * Write the current conflict report for `id` to `conflicts/<id>.md`. The engine
+ * calls this on any true conflict (overlapping body/asset merge or both-sides
+ * non-equivalent frontmatter) after deciding to write nothing for the pair.
+ */
+export function writeConflictReport(id, text) {
+    const path = conflictReportPath(id);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, 'utf8');
+}
+/**
+ * Delete a stale `conflicts/<id>.md` once the pair reconciles cleanly or
+ * becomes a no-op (OD-4). No-op if absent — never throws on a missing report.
+ */
+export function clearConflictReport(id) {
+    rmSync(conflictReportPath(id), { force: true });
+}
+/** True iff a conflict report currently exists for `id`. */
+export function hasConflictReport(id) {
+    const path = conflictReportPath(id);
+    return existsSync(path) && statSync(path).isFile();
+}

package/dist/core/spawn.d.ts

@@ -1,4 +1,18 @@
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export declare function isInTmux(): boolean;
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export declare function tmuxServerReachable(): boolean;
 export declare function shellQuote(s: string): string;
 /** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
  *  counts the window THAT pane lives in (the placement decision must reflect the

package/dist/core/spawn.js

@@ -3,13 +3,30 @@
 // A small set of tmux primitives used by the `human` command tree to put the
 // humanloop TUI in a detached pane: spawnAndDetach (open a pane running a given
 // command), countPanesInCurrentWindow (placement decision), plus shellQuote and
-// isInTmux. The canvas runtime has its own one-window-per-node machinery in
-// core/runtime/tmux.ts; this module is only the pane-split path the human TUI
-// needs.
+// tmuxServerReachable. The canvas runtime has its own one-window-per-node
+// machinery in core/runtime/tmux.ts; this module is only the pane-split path the
+// human TUI needs.
 import { spawnSync } from 'node:child_process';
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export function isInTmux() {
     return Boolean(process.env.TMUX);
 }
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export function tmuxServerReachable() {
+    const r = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' });
+    return r.status === 0;
+}
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
@@ -34,7 +51,7 @@ export function countPanesInCurrentWindow() {
  *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
  *  False outside tmux / on error. */
 export function paneAlive(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return false;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
         encoding: 'utf8',
@@ -46,7 +63,7 @@ export function paneAlive(pane) {
  *  specify pane here"); only split-window -t takes a pane. null outside tmux /
  *  on a bad pane id / on error / empty. */
 export function paneWindowTarget(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return null;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
     if (r.status !== 0)
@@ -59,8 +76,6 @@ export function paneWindowTarget(pane) {
  *  to surface a human prompt in the user's view when nothing in the asking
  *  node's graph is focused. null outside tmux / no client / on error. */
 export function attachedClientPane() {
-    if (!isInTmux())
-        return null;
     const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
         encoding: 'utf8',
     });
@@ -102,10 +117,15 @@ export function scheduleKillCurrentPane(delaySeconds) {
  * as soon as the new pane is up; does NOT wait for the command to finish.
  */
 export function spawnAndDetach(opts) {
-    if (!isInTmux()) {
+    // Gate on the CANVAS tmux server's reachability, NOT the caller's $TMUX. A
+    // headless-broker child strips its own $TMUX (broker.ts) but the canvas server
+    // is on the default socket, so `split-window -t <pane>` against a resolved
+    // target pane (resolveHumanTarget) works fine from it. Only a genuine
+    // no-server case degrades to the inbox-drain follow-up.
+    if (!tmuxServerReachable()) {
         return {
             status: 'not-in-tmux',
-            message: 'handoff requires tmux (TMUX env var not set)',
+            message: 'handoff requires a reachable tmux server',
         };
     }
     const splitArgs = [];

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

@@ -1,9 +1,9 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, KIND_DEFAULT_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
 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, } from './ceiling.js';
 export type { Surface } from './ceiling.js';
-export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -1,19 +1,19 @@
 // substrate/ — the unified document-substrate keystone: the frontmatter schema,
-// the 4-rung visibility ladder, the kind→default-rungs table, the node-config
-// subject assembly, and gate evaluation. Pure + well-typed; the shared base the
-// CLI verbs, boot render, on-read render, and migrator all build on. See
-// design-substrate.md §4/§9 + plan-substrate.md §2.
+// the 4-rung visibility ladder, the node-config subject assembly, and gate
+// evaluation. Pure + well-typed; the shared base the CLI verbs, boot render,
+// on-read render, and migrator all build on. See design-substrate.md §4 +
+// plan-substrate.md §2.
 export { 
 // kinds
 KINDS, isDocKind, 
 // ladder
 RUNGS, rungRank, rungAtLeast, 
-// defaults
-KIND_DEFAULT_RUNGS, 
+// fallback floor
+FALLBACK_RUNG, 
 // parse + render-shared helpers
 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, } from './ceiling.js';
-export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
+export { renderPreferencesSection, renderKnowledgeBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/injected-store.d.ts

@@ -0,0 +1,10 @@
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export declare function loadInjectedDocs(nodeId: string): Set<string>;
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export declare function saveInjectedDocs(nodeId: string, seen: Set<string>): void;
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export declare function clearInjectedDocs(nodeId: string): void;

package/dist/core/substrate/injected-store.js

@@ -0,0 +1,55 @@
+// injected-store.ts — durable per-node dedup set for on-read doc injection.
+//
+// The on-read substrate hook (canvas-doc-substrate.ts → renderOnReadDocs) dedups
+// so a given doc surfaces at most once per conversation. That set USED to live
+// only in the pi process heap, cleared on session_start. But a node's logical
+// session — the .jsonl transcript — spans MULTIPLE pi processes: a dormancy →
+// revive(resume) cycle exits the old process and launches a fresh `pi --session`
+// that REUSES the same transcript. The fresh process started with an empty set,
+// so any doc already injected before dormancy got injected AGAIN on the next
+// read — the "fires a second time per session" bug.
+//
+// This module persists the set to `nodes/<id>/injected-docs.json` so the resumed
+// process rehydrates it and skips docs already present in the transcript. The
+// one launch path that begins a FRESH transcript (reviveNode with resume=false,
+// in runtime/revive.ts) calls clearInjectedDocs(), so a new conversation starts
+// with an empty set.
+//
+// All ops are best-effort: a failed read/write degrades to a possible re-inject,
+// never a crash — a dedup miss must never break a read or a revive.
+import { readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { injectedDocsPath } from '../canvas/paths.js';
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export function loadInjectedDocs(nodeId) {
+    try {
+        const arr = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
+        if (!Array.isArray(arr))
+            return new Set();
+        return new Set(arr.filter((x) => typeof x === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export function saveInjectedDocs(nodeId, seen) {
+    try {
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...seen]));
+    }
+    catch {
+        // best-effort — a failed persist only risks a re-inject, never a crash
+    }
+}
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export function clearInjectedDocs(nodeId) {
+    try {
+        rmSync(injectedDocsPath(nodeId), { force: true });
+    }
+    catch {
+        // ignore — absence is the desired state anyway
+    }
+}

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

@@ -3,16 +3,25 @@
 // When a `read` tool call returns, the canvas-doc-substrate pi extension calls
 // renderOnReadDocs() to surface the substrate docs that should appear ALONGSIDE
 // the file just read — each at its FILE-READ-VISIBILITY rung (NOT the
-// system-prompt rung the boot render uses). Two independent triggers decide
-// which docs surface (design §4/§6; plan-substrate.md track D1):
+// system-prompt rung the boot render uses). Three triggers decide which docs
+// surface (design §4/§6; Stream A native rules):
 //
 //   • POSITIONAL — walk the read file's ancestor dirs; any doc living in an
 //     ancestor's `.crouter/memory/` surfaces (a doc surfaces when a file
-//     beside/under its own scope dir is read). This mirrors nested-context's
-//     `.claude/rules` ancestor walk, but keyed on `.crouter/memory/`.
+//     beside/under its own scope dir is read), UNLESS it carries an explicit
+//     read-trigger (see D5 below). This mirrors nested-context's `.claude/rules`
+//     ancestor walk, but keyed on `.crouter/memory/`.
 //   • applies-to GLOB — any RESOLVED substrate doc (user/project/builtin scope)
 //     whose `appliesTo` glob matches the read file path surfaces, regardless of
 //     where the read file sits relative to the doc.
+//   • read-when FRONTMATTER (Stream A) — any RESOLVED doc whose `readWhen`
+//     condition matches the READ FILE's own parsed frontmatter (markdown only),
+//     via `evalCondition` against that YAML rather than the node subject.
+//
+// D5 — an EXPLICIT read-trigger (applies-to OR read-when) SUPPRESSES the
+// positional default for that doc: an author who declared a trigger meant it, so
+// the doc fires only on its trigger, never positionally on every read under its
+// scope. The two explicit triggers compose by OR.
 //
 // Each candidate runs the substrate pipeline at its fileReadVisibility rung:
 //   parse → gatePasses(doc, assembleNodeSubject(nodeId)) → render
@@ -35,6 +44,7 @@ import { basename, dirname, join, matchesGlob, parse, relative, sep } from 'node
 import { CRTR_DIR_NAME } from '../../types.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs } from '../memory-resolver.js';
 import { assembleNodeSubject, buildCeilingIndex, displayName, effectiveRung, gatePasses, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, } from './index.js';
 import { cachedSubstrateDocs } from './session-cache.js';
@@ -117,6 +127,12 @@ function safeWalkMd(dir) {
         return [];
     }
 }
+/** Does the doc declare an EXPLICIT read-trigger? (applies-to glob OR read-when
+ *  frontmatter condition). D5: an explicit trigger SUPPRESSES the positional
+ *  default — such a doc fires only on its declared trigger, never positionally. */
+function hasExplicitTrigger(doc) {
+    return (doc.appliesTo !== undefined && doc.appliesTo.length > 0) || doc.readWhen !== undefined;
+}
 /** POSITIONAL trigger: every substrate doc in an ancestor dir's
  *  `.crouter/memory/`, walking from the read file up to $HOME (or the
  *  filesystem root for a read outside $HOME), skipping junk ancestors. */
@@ -138,7 +154,9 @@ function positionalCandidates(absReadFile) {
                         continue;
                     seenDocPaths.add(real);
                     const doc = loadPositionalDoc(file, memDir, scope);
-                    if (doc)
+                    // D5: a doc with an explicit read-trigger (applies-to/read-when) does
+                    // NOT fire positionally — it surfaces only via that trigger.
+                    if (doc && !hasExplicitTrigger(doc))
                         out.push({ doc, realpath: real, order: depth });
                 }
             }
@@ -204,6 +222,49 @@ function appliesToCandidates(absReadFile, taken) {
     }
     return out;
 }
+/** Parse the READ FILE's own YAML frontmatter once (markdown only), the subject
+ *  a `read-when` condition is evaluated against. Non-markdown reads (and any
+ *  unreadable / frontmatter-less file) yield `{}` — no `read-when` rule can then
+ *  match (mirrors pi's frontmatter-rules, which only consider .md/.mdx/.markdown). */
+function readFileFrontmatter(absReadFile) {
+    if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
+        return {};
+    try {
+        return parseFrontmatterGeneric(readText(absReadFile)).data ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** read-when FRONTMATTER trigger (Stream A): every RESOLVED substrate doc whose
+ *  `readWhen` condition matches the read file's own frontmatter. `taken` carries
+ *  the realpaths already claimed by earlier passes so a doc is not double-counted.
+ *  Uses the per-session cache (same corpus the glob pass walks). Returns [] when
+ *  the read file has no frontmatter — no condition can match an empty subject. */
+function readWhenCandidates(readFileFm, taken) {
+    if (Object.keys(readFileFm).length === 0)
+        return [];
+    let docs;
+    try {
+        docs = cachedSubstrateDocs(listAllMemoryDocs, parseSubstrateDoc);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const doc of docs) {
+        if (doc.readWhen === undefined)
+            continue;
+        const real = realpathOrSelf(doc.path);
+        if (taken.has(real))
+            continue;
+        if (!evalCondition(doc.readWhen, readFileFm))
+            continue;
+        taken.add(real);
+        out.push({ doc, realpath: real, order: -1 });
+    }
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Per-doc envelope render.
 // ---------------------------------------------------------------------------
@@ -256,7 +317,8 @@ export function renderOnReadDocs(nodeId, readFilePath, seen = new Set()) {
         const positional = positionalCandidates(absReadFile);
         const taken = new Set(positional.map((c) => c.realpath));
         const byGlob = appliesToCandidates(absReadFile, taken);
-        candidates = [...positional, ...byGlob];
+        const byReadWhen = readWhenCandidates(readFileFrontmatter(absReadFile), taken);
+        candidates = [...positional, ...byGlob, ...byReadWhen];
     }
     catch {
         return '';

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

@@ -1,20 +1,17 @@
-/** 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 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
+/** The `<knowledge>` 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
+ *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
+ *  doc at its effective rung (most 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. Procedural skills and factual references both
+ *  live here now — they merged into the one `knowledge` kind. Returns '' when
  *  nothing is eligible. */
-export declare function renderReferencesBlock(nodeId: string): string;
+export declare function renderKnowledgeBlock(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

package/dist/core/substrate/render.js

@@ -6,12 +6,13 @@
 // 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.
 //
-//   • 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.
+//   • the SYSTEM-PROMPT half — `<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 — `<knowledge>` (renderKnowledgeBlock) — the
+//     consultable catalog (every `kind: knowledge` doc ∪ node-local) 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 →
@@ -73,11 +74,11 @@ function scopeRank(scope) {
  *  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 references block.
+ *  rides into the knowledge 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
+ *  is "node-local rides into knowledge" without qualification, so a `none`-rung
+ *  node-local doc 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) {
@@ -276,20 +277,17 @@ function buildTree(docs, rootLabel) {
 // ---------------------------------------------------------------------------
 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 ' +
+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. To read one, run `crtr memory read <name>`. ' +
+    'Reach for a matching document before improvising, and read one when it seems 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.';
+    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.';
 /** 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) {
@@ -298,20 +296,7 @@ function wrapBlock(tag, intro, tree, outro) {
     return `<${tag}>\n${intro}\n\n${tree}\n\n${outro}\n</${tag}>`;
 }
 // ---------------------------------------------------------------------------
-// 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 tree = buildTree(effectiveDocs(subject, 'skill'), 'skills');
-    return wrapBlock('skills', SKILLS_INTRO, tree, SKILLS_OUTRO);
-}
-// ---------------------------------------------------------------------------
-// 2. Preferences — `<preferences>` (system prompt).
+// 1. Preferences — `<preferences>` (system prompt).
 // ---------------------------------------------------------------------------
 /** The `<preferences>` system-prompt block: every eligible `kind: preference`
  *  doc in one tree at its effective rung (the preference default rung is
@@ -324,28 +309,29 @@ export function renderPreferencesSection(nodeId) {
     return wrapBlock('preferences', PREFERENCES_INTRO, tree, PREFERENCES_OUTRO);
 }
 // ---------------------------------------------------------------------------
-// 3. References — `<references>` (inside the <crtr-context> message).
+// 2. Knowledge — `<knowledge>` (inside the <crtr-context> message).
 // ---------------------------------------------------------------------------
-/** The `<references>` block embedded INSIDE the `<crtr-context>` session_start
+/** The `<knowledge>` 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
+ *  when ''). The consultable catalog: every eligible `kind: knowledge` resolver
+ *  doc at its effective rung (most 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. Procedural skills and factual references both
+ *  live here now — they merged into the one `knowledge` kind. Returns '' when
  *  nothing is eligible. */
-export function renderReferencesBlock(nodeId) {
+export function renderKnowledgeBlock(nodeId) {
     const subject = cachedNodeSubject(nodeId, assembleNodeSubject);
     if (subject === null)
         return '';
     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);
+    const tree = buildTree([...effectiveDocs(subject, 'knowledge'), ...nodeLocal], 'knowledge');
+    return wrapBlock('knowledge', KNOWLEDGE_INTRO, tree, KNOWLEDGE_OUTRO);
 }
 // ---------------------------------------------------------------------------
-// 4. Memory-saving hygiene guidance — `<memory-guidance>` (system prompt).
+// 3. 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