@crouton-kit/crouter 0.3.28 → 0.3.30

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/substrate/index.d.ts

@@ -5,5 +5,5 @@ 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

@@ -15,5 +15,5 @@ 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.js

@@ -11,9 +11,9 @@
 //
 // 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
-// launch paths that begin a FRESH transcript (reviveNode resume=false,
-// reviveInPlace, relaunchRootInPane — all in runtime/revive.ts) call
-// clearInjectedDocs(), so a new conversation starts with an empty set.
+// 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.

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

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

@@ -1,8 +1,8 @@
 import type { Scope } from '../../types.js';
 import type { MemoryDoc } from '../memory-resolver.js';
-export declare const KINDS: readonly ["skill", "reference", "preference"];
+export declare const KINDS: readonly ["knowledge", "preference"];
 export type DocKind = (typeof KINDS)[number];
-/** Is `v` one of the three valid document kinds? */
+/** Is `v` one of the two valid document kinds? */
 export declare function isDocKind(v: unknown): v is DocKind;
 export declare const RUNGS: readonly ["none", "name", "preview", "content"];
 export type Rung = (typeof RUNGS)[number];
@@ -21,7 +21,7 @@ export type GatePredicate = Record<string, unknown>;
  *  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. */
+    /** Which of the two semantic kinds (knowledge | preference). */
     kind: DocKind;
     /** 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
@@ -43,6 +43,13 @@ export interface SubstrateSchema {
     /** Optional glob list narrowing the on-read trigger to matching read files.
      *  Absent ⇒ positional trigger only. A single glob is normalized to a 1-list. */
     appliesTo?: string[];
+    /** Optional condition over the READ FILE's own frontmatter — the on-read
+     *  frontmatter trigger (Stream A native rules). Same coercion + predicate
+     *  vocabulary as `gate` (non-null non-array object carried; empty `{}` inert),
+     *  but evaluated by `evalCondition` against the read file's parsed YAML rather
+     *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
+     *  `read-when`. */
+    readWhen?: GatePredicate;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
  *  path-derived identity and body. This single object flows through the whole

package/dist/core/substrate/schema.js

@@ -12,10 +12,12 @@
 // floor `none` — a malformed doc renders invisible rather than crashing, and
 // lint flags it. Valid docs never hit the fallback.
 // ---------------------------------------------------------------------------
-// Kinds — the three semantic kinds (design §3). `kind` is data, not a fork.
+// Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
+// playbooks + factual references merged) vs `preference` (behave — standing
+// directives). `kind` is a load-bearing binary, not a content taxonomy.
 // ---------------------------------------------------------------------------
-export const KINDS = ['skill', 'reference', 'preference'];
-/** Is `v` one of the three valid document kinds? */
+export const KINDS = ['knowledge', 'preference'];
+/** Is `v` one of the two valid document kinds? */
 export function isDocKind(v) {
     return typeof v === 'string' && KINDS.includes(v);
 }
@@ -66,6 +68,7 @@ export function parseSubstrateFrontmatter(fm) {
         fileReadVisibility: parseRung(fm['file-read-visibility'], FALLBACK_RUNG),
         gate: parseGate(fm.gate),
         appliesTo: parseAppliesTo(fm['applies-to']),
+        readWhen: parseGate(fm['read-when']),
     };
 }
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the

package/dist/core/tui/host.d.ts

@@ -1,5 +1,5 @@
 import { type Draw, type Rect, type Size } from './draw.js';
-import type { ViewModule, ViewManifest, BannerLevel } from './contract.js';
+import type { ViewCore, TuiPresenter, TextPresenter, KeyHint, BannerLevel } from '../view/contract.js';
 export interface RunViewOptions {
     /** CLI flags forwarded verbatim to the view via host.options. */
     options?: Record<string, string>;
@@ -19,11 +19,19 @@ export interface Chrome {
     subtitle: string | null;
     mode: string | null;
 }
+/** The slice of a view's manifest that drawChrome reads (title + subtitle), plus
+ *  the footer hints lifted from the TuiPresenter's keymap bindings. */
+export interface ChromeManifest {
+    title: string;
+    subtitle?: string;
+    keymap?: KeyHint[];
+}
 /** Draw the host chrome into `draw` and return the content Rect for the view.
  *  Three zones: title row (state rail + title/subtitle + state chip + liveness),
  *  a hairline, and a footer (status left, keymap right) with a severity banner
  *  on the row above it when set. */
-declare function drawChrome(draw: Draw, size: Size, manifest: ViewManifest, c: Chrome, now?: number): Rect;
+declare function drawChrome(draw: Draw, size: Size, manifest: ChromeManifest, c: Chrome, now?: number): Rect;
 export { drawChrome };
-/** Host a view in the alt screen until it quits (or Ctrl-C). */
-export declare function runView<S>(view: ViewModule<S>, opts?: RunViewOptions): Promise<void>;
+/** Host a dual-target ViewCore + TuiPresenter in the alt screen until it quits
+ *  (or Ctrl-C). `text` is the optional text presenter for the piped path. */
+export declare function runCoreView<S>(core: ViewCore<S>, tui: TuiPresenter<S>, text: TextPresenter<S> | null, opts?: RunViewOptions): Promise<void>;