@crouton-kit/crouter 0.3.20 → 0.3.22

package/dist/commands/human/queue.js

@@ -177,8 +177,8 @@ export const humanCancel = defineLeaf({
         return { canceled: true, job_id: jobId };
     },
     render: (r) => r['canceled'] === true
-        ? `<canceled job_id="${r['job_id']}"/>`
-        : `<cancel-noop job_id="${r['job_id']}">${r['reason'] ?? 'nothing to cancel'}</cancel-noop>`,
+        ? `Canceled human interaction ${r['job_id']} — its TUI pane is closed and subscribers were notified no answer is coming.`
+        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
 });
 // ---------------------------------------------------------------------------
 // _run (hidden worker; not listed in branch help)

package/dist/commands/memory/__tests__/lint-schema.test.js

@@ -0,0 +1,29 @@
+// Bug-regression: guards the hard cut that merged the substrate's `when`/`why`
+// frontmatter pair into the single `when-and-why-to-read` read-routing field.
+// The CTO ruling (taste/why-field-means-why-to-read) requires the migration be
+// a hard cut: an old-shape doc must FAIL at `crtr memory lint`, never be read at
+// runtime. `lintSubstrateSchema` is that enforcement seam — these lock it.
+//
+// Run: node --import tsx/esm --test src/commands/memory/__tests__/lint-schema.test.ts
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { lintSubstrateSchema } from '../lint.js';
+const ROUTING = 'When you are X, this reference should be read because Y';
+test('lint rejects a doc still carrying the retired `when` key', () => {
+    const err = lintSubstrateSchema({ kind: 'reference', when: 'when X' });
+    assert.ok(err !== null, 'old-shape `when` must produce a finding');
+    assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
+});
+test('lint rejects a doc still carrying the retired `why` key', () => {
+    const err = lintSubstrateSchema({ kind: 'reference', why: 'because Y' });
+    assert.ok(err !== null, 'old-shape `why` must produce a finding');
+    assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
+});
+test('lint rejects a substrate doc missing the merged routing field', () => {
+    const err = lintSubstrateSchema({ kind: 'reference' });
+    assert.ok(err !== null, 'a substrate doc must carry when-and-why-to-read');
+    assert.match(err, /when-and-why-to-read/);
+});
+test('lint accepts the merged new-shape frontmatter', () => {
+    assert.equal(lintSubstrateSchema({ kind: 'reference', 'when-and-why-to-read': ROUTING }), null);
+});

package/dist/commands/memory/find.js

@@ -2,9 +2,6 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/index.js';
-import { listAllSkills } from '../../core/resolver.js';
-import { parseFrontmatter } from '../../core/frontmatter.js';
-import { readText } from '../../core/fs-utils.js';
 import { MEMORY_KINDS } from './shared.js';
 function substrateUnit(d) {
     return {
@@ -12,42 +9,19 @@ function substrateUnit(d) {
         kind: d.kind,
         scope: d.scope,
         path: d.path,
-        when: d.when,
-        why: d.why,
+        routing: d.whenAndWhyToRead,
         shortForm: d.shortForm,
         loadBody: () => d.body,
     };
 }
-function skillUnit(s) {
-    const desc = s.frontmatter.description ?? '';
-    const keywords = s.frontmatter.keywords ? s.frontmatter.keywords.join(' ') : '';
-    return {
-        name: s.name,
-        kind: 'skill',
-        scope: s.scope,
-        path: s.path,
-        // A skill's description plays the when+why role; keywords ride along so the
-        // ranker weighs them too. short_form surfaces the description as the hook.
-        when: [desc, keywords].filter((x) => x).join(' '),
-        why: '',
-        shortForm: desc,
-        loadBody: () => parseFrontmatter(readText(s.path)).body,
-    };
-}
-/** The unioned candidate set: every substrate memory document + every skill,
- *  optionally narrowed to one kind. find searches EVERYTHING — it never applies
- *  gate or visibility-rung filtering (design §11#3). The skill half is wrapped
- *  defensively: the skill corpus is parsed by the resolver, which currently
- *  hard-throws on at least one shipped skill's frontmatter (a pre-existing
- *  regression in the yaml-parser swap, owned by the frontmatter/skill track). A
- *  broken skill corpus must degrade the union to substrate-docs-only, never
- *  crash `memory find`.
+/** The candidate set: every substrate memory document (native + plugin, supplied
+ *  by listAllMemoryDocs), optionally narrowed to one kind. find searches
+ *  EVERYTHING — it never applies gate or visibility-rung filtering (design
+ *  §11#3).
  *
- *  Dedup by (scope, name): the substrate and skill-plugin corpora overlap
- *  (builtin-memory/ contains migrated copies of builtin-skills/; a skill name
- *  can also appear in multiple installed plugins at the same scope). The FIRST
- *  unit encountered for a given identity wins — substrate docs before skill-plugin
- *  docs, which mirrors the memory resolver's own precedence. */
+ *  Dedup by (scope, name): native and plugin docs of the same scope can collide
+ *  on identity. The FIRST unit encountered for a given identity wins — native
+ *  before plugin, which mirrors the memory resolver's own precedence. */
 function candidates(kindFilter) {
     const seen = new Set(); // "scope/name" → first wins
     const add = (u) => {
@@ -66,26 +40,17 @@ function candidates(kindFilter) {
             continue;
         add(substrateUnit(sub));
     }
-    if (kindFilter === undefined || kindFilter === 'skill') {
-        try {
-            for (const skill of listAllSkills())
-                add(skillUnit(skill));
-        }
-        catch {
-            /* skill corpus unavailable — search substrate documents alone */
-        }
-    }
     return units;
 }
 export const findLeaf = defineLeaf({
     name: 'find',
     description: 'relevance search across memory documents',
-    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, when, why, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
+    whenToUse: 'you do not yet know which document applies and need to discover what is stored — ranks documents by relevance, weighted over name, the read-routing line, and short-form (add --body to also weigh body text). Searches the full scope set regardless of any visibility gate. Use --grep instead when you need an exact regex or literal-string match across document bodies rather than a ranked topic match.',
     help: {
         name: 'memory find',
-        summary: 'relevance search across memory documents, weighted over name/when/why/short-form (and body with --body)',
+        summary: 'relevance search across memory documents, weighted over name/routing-line/short-form (and body with --body)',
         params: [
-            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, when, why, and short-form (plus body with --body); documents matching more/stronger fields rank higher. With --grep: an ECMAScript regex applied to each document body line.' },
+            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. With --grep: an ECMAScript regex applied to each document body line.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
             { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body.' },
             { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies.' },
@@ -134,7 +99,7 @@ export const findLeaf = defineLeaf({
                 follow_up: 'Read a document in full with `crtr memory read <name>`. Drop --grep for a ranked topic search.',
             };
         }
-        // --- ranked mode: weighted relevance over name/when/why/short-form(+body) ---
+        // --- ranked mode: weighted relevance over name/routing-line/short-form(+body) ---
         const terms = query
             .toLowerCase()
             .split(/\s+/)
@@ -144,18 +109,15 @@ export const findLeaf = defineLeaf({
         const hits = [];
         for (const u of units) {
             const nameLc = u.name.toLowerCase();
-            const whenLc = u.when.toLowerCase();
-            const whyLc = u.why.toLowerCase();
+            const routingLc = u.routing.toLowerCase();
             const shortLc = u.shortForm.toLowerCase();
             const bodyLc = weighBody ? u.loadBody().toLowerCase() : null;
             let score = 0;
             for (const term of terms) {
                 if (nameLc.includes(term))
                     score += 10;
-                if (whenLc.includes(term))
+                if (routingLc.includes(term))
                     score += 5;
-                if (whyLc.includes(term))
-                    score += 4;
                 if (shortLc.includes(term))
                     score += 3;
                 if (bodyLc !== null && bodyLc.includes(term))

package/dist/commands/memory/lint.d.ts

@@ -1 +1,8 @@
+/** Schema checks for a doc living in a substrate memory dir: a memory store
+ *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
+ *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
+ *  values are checked RAW — the runtime parser silently falls back to kind
+ *  defaults / inert gates, which is exactly the silent tolerance this lint
+ *  exists to catch at authoring time. */
+export declare function lintSubstrateSchema(fm: Record<string, unknown> | null): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -1,20 +1,17 @@
 // `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
 // (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
 // so an invalid doc fails HERE instead of being silently isolated at runtime).
-// Bounded corpus = the substrate memory dirs (project/user/builtin) +
-// every installed plugin's skills tree + ~/.claude/skills. Never a
+// Bounded corpus = the substrate memory dirs (project/user/builtin). Never a
 // filesystem-wide scan.
-import { homedir } from 'node:os';
-import { basename, join, relative, sep } from 'node:path';
+import { basename, relative, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { general } from '../../core/errors.js';
 import { warn } from '../../core/output.js';
 import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { listAllPlugins } from '../../core/resolver.js';
-import { scopeMemoryDir } from '../../core/scope.js';
+import { listInstalledPlugins } from '../../core/resolver.js';
+import { pluginMemoryDir, scopeMemoryDir } from '../../core/scope.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
-import { SKILL_ENTRY_FILE, SKILLS_DIR } from '../../types.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
 const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
@@ -24,12 +21,21 @@ const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
  *  values are checked RAW — the runtime parser silently falls back to kind
  *  defaults / inert gates, which is exactly the silent tolerance this lint
  *  exists to catch at authoring time. */
-function lintSubstrateSchema(fm) {
+export function lintSubstrateSchema(fm) {
     if (fm === null)
         return 'missing frontmatter: a memory store doc requires `kind: skill|reference|preference`';
     if (!isDocKind(fm.kind)) {
         return `invalid kind: ${JSON.stringify(fm.kind)} (expected skill|reference|preference)`;
     }
+    // The retired `when`/`why` pair was merged into one read-routing field. The
+    // hard cut is enforced HERE: an old-shape doc must fail, never be silently
+    // read at runtime.
+    if ('when' in fm || 'why' in fm) {
+        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` line — "When <circumstance>, this <kind> should be read <because <payoff>>."';
+    }
+    if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
+        return 'missing `when-and-why-to-read`: one read-routing line — "When <circumstance>, this <kind> should be read <because <payoff>>."';
+    }
     for (const field of RUNG_FIELDS) {
         const v = fm[field];
         if (v !== undefined && (typeof v !== 'string' || !VALID_RUNGS.includes(v))) {
@@ -69,14 +75,14 @@ function lintFile(file, substrateStore, findings) {
 export const lintLeaf = defineLeaf({
     name: 'lint',
     description: 'validate frontmatter across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (memory stores, plugin skills, ~/.claude/skills) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation. Run it before shipping doc changes; CI-friendly (non-zero exit on any finding).',
     help: {
         name: 'memory lint',
         summary: 'strict-parse frontmatter across the bounded corpus; non-zero exit on any finding',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores, plugin_skills, claude_skills}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus file counts: {memory_stores}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
         ],
         outputKind: 'object',
@@ -85,40 +91,28 @@ export const lintLeaf = defineLeaf({
     run: async () => {
         const findings = [];
         let memoryCount = 0;
-        let pluginCount = 0;
-        let claudeCount = 0;
-        // 1. Substrate memory stores (project/user/builtin), schema-aware.
+        // Substrate memory stores (project/user/builtin), schema-aware. A scope's
+        // corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
+        // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
-        for (const scope of ['project', 'user', 'builtin']) {
-            const dir = scopeMemoryDir(scope);
+        const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
-                continue;
+                return;
             for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
                 if (!relative(dir, file).split(sep).join('/'))
                     continue;
                 memoryCount += 1;
                 lintFile(file, basename(file) !== 'MEMORY.md', findings);
             }
-        }
-        // 2. Every installed plugin's skills tree (builtin + plugin + marketplace).
-        for (const plugin of listAllPlugins()) {
-            const skillsRoot = join(plugin.root, SKILLS_DIR);
-            if (!pathExists(skillsRoot))
-                continue;
-            for (const file of walkFiles(skillsRoot, (n) => n === SKILL_ENTRY_FILE)) {
-                pluginCount += 1;
-                lintFile(file, false, findings);
-            }
-        }
-        // 3. ~/.claude/skills — read by the runtime, so it lints too.
-        const claudeSkills = join(homedir(), '.claude', SKILLS_DIR);
-        if (pathExists(claudeSkills)) {
-            for (const file of walkFiles(claudeSkills, (n) => n === SKILL_ENTRY_FILE)) {
-                claudeCount += 1;
-                lintFile(file, false, findings);
+        };
+        for (const scope of ['project', 'user', 'builtin']) {
+            lintDir(scopeMemoryDir(scope));
+            for (const plugin of listInstalledPlugins(scope)) {
+                if (plugin.enabled)
+                    lintDir(pluginMemoryDir(plugin));
             }
         }
-        const checked = memoryCount + pluginCount + claudeCount;
+        const checked = memoryCount;
         if (findings.length > 0) {
             // Human/agent path renders only the message — surface every offender as
             // a scoped stderr notice (the --json path carries them in details too).
@@ -132,7 +126,7 @@ export const lintLeaf = defineLeaf({
         }
         return {
             checked,
-            corpora: { memory_stores: memoryCount, plugin_skills: pluginCount, claude_skills: claudeCount },
+            corpora: { memory_stores: memoryCount },
             findings: [],
             follow_up: 'Corpus green — zero invalid frontmatter docs.',
         };

package/dist/commands/memory/list.js

@@ -1,7 +1,6 @@
 import { defineLeaf } from '../../core/command.js';
 import { listAllMemoryDocs } from '../../core/memory-resolver.js';
-import { parseSubstrateDoc } from '../../core/substrate/index.js';
-import { listAllSkills } from '../../core/resolver.js';
+import { parseSubstrateDoc, isIndexName, indexDirOf } from '../../core/substrate/index.js';
 import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
 export const listLeaf = defineLeaf({
     name: 'list',
@@ -15,7 +14,7 @@ export const listLeaf = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope}. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, is_dir}. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
         ],
         outputKind: 'object',
@@ -40,21 +39,11 @@ export const listLeaf = defineLeaf({
                 continue;
             if (kindFilter !== undefined && sub.kind !== kindFilter)
                 continue;
-            addItem({ name: sub.name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm });
-        }
-        // Skill-plugin corpus (scope-root skills + plugin/marketplace skills).
-        // Only include when the kindFilter is absent or explicitly 'skill'.
-        if (kindFilter === undefined || kindFilter === 'skill') {
-            try {
-                for (const skill of listAllSkills(scopeFilter)) {
-                    const raw = skill.frontmatter.description;
-                    const desc = typeof raw === 'string' ? raw : '';
-                    addItem({ name: skill.name, kind: 'skill', scope: skill.scope, shortForm: desc });
-                }
-            }
-            catch {
-                /* skill corpus unavailable — list substrate documents alone */
-            }
+            // A directory INDEX surfaces as a dir entry: its dir path with a trailing
+            // slash, flagged is_dir, so the inventory distinguishes it from a doc.
+            const isDir = isIndexName(sub.name);
+            const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
+            addItem({ name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm, isDir });
         }
         items.sort((a, b) => {
             const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -72,6 +61,7 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
+                is_dir: d.isDir,
             })),
             follow_up: 'Read one in full with `crtr memory read <name>`. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
         };

package/dist/commands/memory/read.js

@@ -2,8 +2,6 @@ import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
 import { resolveMemoryDoc } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/index.js';
-import { resolveSkill } from '../../core/resolver.js';
-import { parseFrontmatter } from '../../core/frontmatter.js';
 import { readText } from '../../core/fs-utils.js';
 import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
@@ -33,9 +31,9 @@ export const readLeaf = defineLeaf({
         const nameRaw = input['name'];
         const kindFilter = input['kind'];
         const includeFrontmatter = input['frontmatter'];
-        // 1) Primary: resolve a substrate/memory document (memory/ dirs across
-        //    project>user>builtin). A not_found here is not fatal — it falls through
-        //    to the skill resolver below (the D4 union).
+        // Resolve a substrate/memory document across scopes (project>user>builtin,
+        // with leaf-name fallback). The substrate corpus now includes plugin docs
+        // (mounted under <pluginName>/), so this resolves every name.
         let doc;
         try {
             doc = resolveMemoryDoc(nameRaw);
@@ -51,8 +49,7 @@ export const readLeaf = defineLeaf({
                 : typeof doc.frontmatter?.['kind'] === 'string'
                     ? doc.frontmatter['kind']
                     : 'reference';
-            // --kind asserts the resolved kind; a mismatch falls through to skills
-            // (which only satisfy --kind=skill).
+            // --kind asserts the resolved kind; a mismatch falls through to not-found.
             if (kindFilter === undefined || kind === kindFilter) {
                 const content = includeFrontmatter ? readText(doc.path) : doc.body;
                 return {
@@ -65,36 +62,6 @@ export const readLeaf = defineLeaf({
                 };
             }
         }
-        // 2) D4 union fallthrough: the name is not a memory document (or its kind
-        //    did not match --kind) — resolve it as a plugin/marketplace/scope skill
-        //    so skills are readable through `crtr memory read` too. Skills are kind
-        //    "skill", so honor --kind by skipping this path for other kinds.
-        if (kindFilter === undefined || kindFilter === 'skill') {
-            let skill;
-            try {
-                skill = resolveSkill(nameRaw);
-            }
-            catch (e) {
-                // not_found → fall through to the memory-not-found below. A genuine
-                // CrtrError (e.g. ambiguous) propagates. Any other throw means the skill
-                // corpus is currently unparseable (the yaml-parser regression owned by
-                // the frontmatter/skill track) — degrade to not-found rather than 500.
-                if (e instanceof CrtrError && e.code !== 'not_found')
-                    throw e;
-            }
-            if (skill !== undefined) {
-                const raw = readText(skill.path);
-                const content = includeFrontmatter ? raw : parseFrontmatter(raw).body;
-                return {
-                    name: skill.name,
-                    kind: 'skill',
-                    scope: skill.scope,
-                    path: skill.path,
-                    content,
-                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
-                };
-            }
-        }
         throw notFound(`memory document not found: ${nameRaw}`, {
             memory: nameRaw,
             next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',

package/dist/commands/memory/shared.js

@@ -91,8 +91,7 @@ export function coerceAppliesTo(raw) {
 // first in this order; any preserved-on-update extras append after.
 const FRONTMATTER_ORDER = [
     'kind',
-    'when',
-    'why',
+    'when-and-why-to-read',
     'short-form',
     'system-prompt-visibility',
     'file-read-visibility',

package/dist/commands/memory/write.js

@@ -13,8 +13,7 @@ export const writeLeaf = defineLeaf({
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
-            { kind: 'flag', name: 'when', type: 'string', required: false, constraint: 'Frontmatter whenText — a short string describing when this document should be read.' },
-            { kind: 'flag', name: 'why', type: 'string', required: false, constraint: 'Frontmatter whyText — a short string describing why this document matters.' },
+            { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'The read-routing line, authored as ONE sentence: "When <circumstance>, this <kind> should be read <because <payoff>>." It states WHEN to read this doc and WHY the read is worth it — read-routing, NEVER a justification of why the content should be obeyed. Rendered verbatim as the preview. Required when creating.' },
             { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
             { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
             { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk.' },
@@ -44,11 +43,10 @@ export const writeLeaf = defineLeaf({
         const { scope, memoryDir } = resolveWriteTarget(scopeArg);
         const path = memoryFilePath(memoryDir, name);
         const created = !pathExists(path);
-        // CREATE requires the two prose fields that compose the generated preview
-        // routing line — without them every preview renders the degenerate
-        // '", read this <kind>. ."'. UPDATE inherits them from the existing doc.
-        if (created && (input['when'] === undefined || input['why'] === undefined)) {
-            throw usage(`creating ${name} requires --when and --why (they compose the preview routing line "{when}, read this ${kind}. {why}.")`);
+        // CREATE requires the read-routing line that becomes the preview — without
+        // it every preview renders empty. UPDATE inherits it from the existing doc.
+        if (created && input['whenAndWhyToRead'] === undefined) {
+            throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read <because <payoff>>." (rendered verbatim as the preview).`);
         }
         // In-place update: start from the existing frontmatter (preserving fields
         // not passed this time), then overlay the provided ones. Create: start clean.
@@ -62,8 +60,7 @@ export const writeLeaf = defineLeaf({
             if (value !== undefined)
                 frontmatter[key] = value;
         };
-        setIf('when', input['when']);
-        setIf('why', input['why']);
+        setIf('when-and-why-to-read', input['whenAndWhyToRead']);
         setIf('short-form', input['shortForm']);
         setIf('system-prompt-visibility', input['systemPromptVisibility']);
         setIf('file-read-visibility', input['fileReadVisibility']);