octwin-cli 0.5.1 → 0.6.0

package/dist/index.js

@@ -17,7 +17,7 @@
  *   octwin pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
  *   octwin status  [--dir .]        # did my deploy land? which version is live?
  *   octwin records [entity] [id]    # inspect the pack's XRM data (records:read token)
- *   octwin cases   [caseId] [--queues]     # inspect casework (support tickets) — list / one case + timeline
+ *   octwin work    [recordId] [--queues]   # inspect the work inbox (worked records) — list / one item + timeline
  *   octwin logs    [conversationId] [--as h] [--json]  # list conversations / show one's timeline
  *   octwin chat    "msg" [--as h] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn via the web channel (+ send media)
  *   octwin chat    --script <file> [--as h]   # drive a WHOLE conversation, one turn per line (the reliable way to test a flow)
@@ -27,7 +27,7 @@
  *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
  *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
  *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
- *   octwin platform-kb [pull] [--dir .]  # pull the platform capability reference for the authoring skill
+ *   octwin platform-kb [pull] [--if-stale|--check] [--dir .]  # the platform capability reference (no token needed)
  *   octwin test    [--dir .]        # = validate --remote (the full platform check)
  *
  * Multi-turn testing: the platform keeps ONE open conversation per `--as` handle,
@@ -58,12 +58,19 @@ import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
-import { validatePackBundle } from './lib/validate.js';
+import { validatePackBundle, describePackNameProblem, asPackName } from './lib/validate.js';
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
+import { yamlLineOf } from './lib/yaml-pos.js';
+import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from './lib/builtin-check.js';
+import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
+import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
+import { loadDeclarationSpecs, findDeclarationViolations, describeDeclarationFinding } from './lib/declaration-check.js';
 import { describeKbLookup, findPlatformKbDir } from './lib/kb-path.js';
 import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 import { readPage, morePageHint } from './lib/page.js';
+import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
+import { buildSymbols, linkExplainers, renderSymbolsMarkdown } from './lib/kb-symbols.js';
 // The in-package starter template ships alongside `dist/` and `src/` (both one
 // level under the package root), so `../templates/starter` resolves for the
 // built CLI and `tsx` dev alike.
@@ -170,7 +177,7 @@ function authFailureHint(status, url) {
 }
 /**
  * Write VERBS need a different scope than the read they share a command with —
- * `octwin cases` is `cases:read`, `octwin cases note` is `cases:write` — so the
+ * `octwin work` is `work:read`, `octwin work note` is `work:write` — so the
  * requirement is resolved by `<command> <verb>` first, then by command.
  *
  * Keyed on the verb rather than duplicating whole commands, because the hint's
@@ -183,13 +190,17 @@ const VERB_REQUIREMENTS = {
     'records note': { scope: 'records:write', feature: 'records' },
     'records tasks': { scope: 'records:read', feature: 'tasks' },
     'records task': { scope: 'records:write', feature: 'tasks' },
-    'cases assign': { scope: 'cases:write', feature: 'cases' },
-    'cases note': { scope: 'cases:write', feature: 'cases' },
-    'cases transition': { scope: 'cases:write', feature: 'cases' },
-    // `decide --dry-run` hits the PREVIEW route, which is `cases:read`. Naming the
+    'work assign': { scope: 'work:write', feature: 'work' },
+    'work note': { scope: 'work:write', feature: 'work' },
+    // The stage move rides the XRM records verb (`POST …/xrm/records/:id/stage`) —
+    // the work surface deliberately has no second transition spelling (P-02).
+    'work stage': { scope: 'records:write', feature: 'records' },
+    // `decide --dry-run` hits the PREVIEW route, which is `work:read`. Naming the
     // write scope is still the right hint: the committing form is the default.
-    'cases decide': { scope: 'cases:write', feature: 'cases' },
-    'orders transition': { scope: 'orders:write', feature: 'orders' },
+    'work decide': { scope: 'work:write', feature: 'work' },
+    // The stage move rides the XRM records verb (P-02), so the scope is records:write —
+    // the read that resolves the reference still needs orders:read.
+    'orders transition': { scope: 'records:write', feature: 'records' },
     'orders refund': { scope: 'orders:write', feature: 'orders' },
     'catalog availability': { scope: 'catalog:write', feature: 'catalog' },
     'catalog stock': { scope: 'catalog:write', feature: 'catalog' },
@@ -213,7 +224,12 @@ const COMMAND_REQUIREMENTS = {
     // same scope. Omitting it here meant a 403 on the one command that recovers a pack's
     // only source copy printed the generic hint WITHOUT naming the scope to grant.
     pull: { scope: 'pack:deploy' },
-    'platform-kb': { scope: 'pack:deploy' },
+    // `platform-kb` deliberately has NO requirement: the reference is platform stdlib,
+    // and the platform serves it anonymously at `/api/public/octwin-platform-kb` so a
+    // cold start needs no login. A token is still USED when present (the tenant-scoped
+    // route also works against platforms predating the public one) — but declaring a
+    // requirement here would print "needs pack:deploy" on a failure whose real cause is
+    // an unreachable instance.
     feedback: { scope: 'pack:deploy' },
     media: { scope: 'media:generate' },
     // The plan feature gates RECORD reads, not the entity list (`/xrm/entities` carries only
@@ -221,7 +237,7 @@ const COMMAND_REQUIREMENTS = {
     // plan for a 403 the plan did not cause.
     records: { scope: 'records:read', feature: 'records', featureAppliesTo: 'reading records (listing entities needs only the scope)' },
     analytics: { scope: 'records:read', feature: 'records' },
-    cases: { scope: 'cases:read', feature: 'cases' },
+    work: { scope: 'work:read', feature: 'work' },
     logs: { scope: 'conversations:read' },
     orders: { scope: 'orders:read', feature: 'orders' },
     catalog: { scope: 'catalog:read', feature: 'catalog' },
@@ -234,7 +250,7 @@ const COMMAND_REQUIREMENTS = {
 };
 /** The command currently running — set once in `main()` so any failure printer can
  *  name the scope that command needs without threading it through every call.
- *  Carries the write VERB too (`cases note`), since that is what decides the scope. */
+ *  Carries the write VERB too (`work note`), since that is what decides the scope. */
 let CURRENT_COMMAND;
 /** `→ needs the \`orders:read\` scope …` — the requirement line for the running
  *  command, or '' when the command has no declared requirement. */
@@ -484,6 +500,13 @@ async function notifyIfOutdated() {
     }
     catch { /* a version check must never break the CLI */ }
 }
+// ── platform-KB drift check (observe the pulled reference, fail-silent) ──
+//
+// `KbIndexEntry` / `KbEntriesDescriptor` mirror the platform's own types and live
+// in `lib/kb-index.js` beside the renderers that consume them. `entries` (list
+// catalogs only) describes how to enumerate a catalog so we can EXPLODE it into
+// one file per entry; the PLATFORM supplies it rather than this CLI hardcoding
+// per-catalog knowledge, so a platform that adds a catalog needs no CLI release.
 /** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
  *  (content hash + per-entry index), or null if nothing has been pulled yet. */
 function readLocalKb(packDir) {
@@ -515,15 +538,44 @@ function diffKbIndex(prev, next) {
     const removed = prev.filter(e => !nextKeys.has(e.key)).map(e => e.key);
     return { added, removed, changed };
 }
+/**
+ * Fetch the platform's KB identity (`?meta=1`) — the cheap poll behind both the
+ * drift nudge and `--if-stale`. Returns null on anything that is not a clean
+ * answer; the caller decides whether that is worth a word.
+ *
+ * `notAuthorized` is reported separately because it is the one failure with a
+ * fix the author can act on.
+ */
+async function fetchKbMeta(t, timeoutMs = 2_000) {
+    const ep = kbEndpoint(t);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${ep.url}?meta=1`, { headers: ep.headers, signal: ctrl.signal });
+        if (!res.ok)
+            return { ok: false, notAuthorized: res.status === 401 || res.status === 403 };
+        return { ok: true, meta: await res.json() };
+    }
+    catch {
+        return { ok: false, notAuthorized: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Nudge (to stderr) when the platform's capability KB has changed since the last
  *  `octwin platform-kb pull`. The sibling of `notifyIfOutdated`, for the KB instead
  *  of the CLI: run only after commands that already hit the platform, so this adds
  *  a single tiny `?meta=1` GET on top of work that was networked anyway. Never
  *  throws — observing must never break a command. No-op until the author has pulled
- *  once (nothing to compare) or if the target/token can't be resolved. */
+ *  once (nothing to compare) or if the target can't be resolved.
+ *
+ *  NOT TTY-gated, deliberately. It was, on the reasoning that a nudge is for a
+ *  human watching a terminal — but the primary reader of this CLI is now an
+ *  authoring agent whose output is piped, and gating on `isTTY` meant the one
+ *  reader that CANNOT notice a stale reference on its own was the only one never
+ *  told. It is a single line on stderr, so piped stdout stays clean either way. */
 async function notifyIfKbStale(flags) {
-    if (!process.stdout.isTTY)
-        return;
     try {
         const packDir = resolve(flags.dir ?? '.');
         const local = readLocalKb(packDir);
@@ -532,25 +584,20 @@ async function notifyIfKbStale(flags) {
         const t = resolveTargetOrNull(flags);
         if (!t)
             return;
-        const ctrl = new AbortController();
-        const timer = setTimeout(() => ctrl.abort(), 2_000);
-        const res = await fetch(`${t.url}/api/self/t/octwin-platform-kb?meta=1`, {
-            headers: authHeaders(t), signal: ctrl.signal,
-        });
-        clearTimeout(timer);
-        if (!res.ok) {
-            // The meta poll needs `pack:deploy`, but this nudge rides on every networked
-            // command — so an author inspecting data with a narrow (`records:read`-only) token
-            // got NO drift signal at all, silently, and a stale reference is exactly what makes
-            // an author invent a primitive from memory. Say so once; stay silent for every other
-            // failure (offline, timeout, a platform without the route).
-            if (res.status === 401 || res.status === 403) {
-                console.error('\nⓘ can\'t check whether the platform capability reference drifted — that needs a `pack:deploy` token.');
-                console.error('  Refresh it directly with a deploy token: octwin platform-kb --token oct_…');
+        const polled = await fetchKbMeta(t);
+        if (!polled.ok) {
+            // The tenant-scoped meta poll needs `pack:deploy`, but this nudge rides on every
+            // networked command — so an author inspecting data with a narrow (`records:read`-only)
+            // token got NO drift signal at all, silently, and a stale reference is exactly what
+            // makes an author invent a primitive from memory. Say so once; stay silent for every
+            // other failure (offline, timeout, a platform without the route).
+            if (polled.notAuthorized) {
+                console.error('\nⓘ can\'t check whether the platform capability reference drifted — that token lacks `pack:deploy`.');
+                console.error('  Check it without a token: octwin platform-kb --check   (or refresh: octwin platform-kb --token oct_…)');
             }
             return;
         }
-        const meta = await res.json();
+        const meta = polled.meta;
         if (meta.content_hash && meta.content_hash !== local.content_hash) {
             // Per-entry summary (now that the index carries per-entry hashes) — the
             // exact list of what changed is one `octwin platform-kb` away.
@@ -566,7 +613,7 @@ async function notifyIfKbStale(flags) {
                     summary = ` (${parts.join(' · ')})`;
             }
             console.error(`\n⬆ the platform capability reference changed since you last pulled it${summary}.`);
-            console.error('  Refresh it: octwin platform-kb');
+            console.error('  Refresh it: octwin platform-kb --if-stale');
         }
     }
     catch { /* a KB check must never break the CLI */ }
@@ -584,7 +631,7 @@ function commandTouchesPlatform(command, flags) {
         case 'media':
         case 'pull':
         case 'records':
-        case 'cases':
+        case 'work':
         case 'logs':
         case 'whoami':
         case 'feedback':
@@ -602,9 +649,14 @@ function commandTouchesPlatform(command, flags) {
 function cmdInit(flags) {
     const target = flags._[0] ?? die('usage: octwin init <dir> [--id my-pack]');
     const dir = resolve(target);
+    // A BARE name, and it stays bare: the platform prefixes the workspace slug at publish,
+    // which is why `init` can stay offline (it has no idea which workspace this will deploy
+    // to, and no longer needs one) and why the same scaffold deploys into two workspaces as
+    // two packs with nothing to edit in between.
     const id = flags.id ?? target.replace(/[/\\]/g, '').replace(/[^a-z0-9-]/gi, '-').toLowerCase();
-    if (!/^[a-z][a-z0-9-]*$/.test(id))
-        die(`pack id '${id}' must be lowercase ASCII with hyphens — pass --id`);
+    const idProblem = describePackNameProblem(id);
+    if (idProblem)
+        die(`${idProblem}\n  → pass --id <pack-name>`);
     if (existsSync(dir) && readdirSync(dir).length > 0)
         die(`target '${dir}' is not empty`);
     if (!existsSync(TEMPLATE_DIR))
@@ -636,7 +688,14 @@ function cmdInit(flags) {
 }
 function localValidate(packDir) {
     const { files, blobs } = collectBundleFiles(packDir);
-    const { id, version } = readManifestIdVersion(files);
+    const { id: rawId, version } = readManifestIdVersion(files);
+    // The manifest declares a BARE name; the platform prefixes your workspace at publish.
+    // Minted here so an unusable one is reported with the rest of the bundle's errors.
+    const id = asPackName(rawId);
+    if (!id) {
+        console.error(`  ✗ ${describePackNameProblem(rawId)}`);
+        die('bundle validation failed (1 error)');
+    }
     const r = validatePackBundle(id, files, blobs);
     if (!r.ok) {
         for (const e of r.errors)
@@ -660,17 +719,36 @@ async function cmdValidate(flags) {
             return [];
         }
     });
-    // Checks that need the pulled KB. Both DEGRADE when it is absent — the KB is a
-    // gitignored cache wiped by every pull, and `platform-kb pull` needs a
-    // `pack:deploy` scope a CI job may not have, so failing hard would break a fresh
-    // clone before the author could act. But a skip is now ANNOUNCED, and remembered:
+    // Checks that need the pulled KB. All of them DEGRADE when it is absent — the KB
+    // is a gitignored cache wiped by every pull, so failing hard would break a fresh
+    // clone before the author could act. But a skip is ANNOUNCED, and remembered:
     // the ✓ used to print above these blocks unconditionally while the per-check ✓s
     // lived inside the `if`s, so a KB-less run read as "one check, passed". An entire
     // backlog batch reached production that way. The defect is the silence, not the skip.
+    //
+    // Reasons are COLLECTED rather than printed inline. When the KB is missing, every
+    // check skips for the identical reason, and six copies of one sentence is how a
+    // reader learns to scroll past the ⚠ block — which is the same failure as not
+    // printing it. One line, naming all six.
     const skipped = [];
+    const skipReasons = new Map();
+    const noteSkip = (label, lookup) => {
+        skipped.push(label);
+        // Group by the lookup's IDENTITY, then let `describeKbLookup` phrase the one
+        // line at print time — so the wording stays in the module that owns it and
+        // cannot drift into a doubled "SKIPPED — SKIPPED —".
+        const key = lookup.state === 'ok' ? 'ok'
+            : `${lookup.state}|${'dir' in lookup ? lookup.dir : ''}|${'reason' in lookup ? lookup.reason : ''}`;
+        const bucket = skipReasons.get(key) ?? { lookup, labels: [] };
+        bucket.labels.push(label);
+        skipReasons.set(key, bucket);
+    };
+    /** Stamp each finding with its source line — the walkers carry the node
+     *  path; `files` holds the raw text the locator needs (E-08). */
+    const withLines = (fs) => fs.map(f => ({ ...f, line: files[f.file] ? yamlLineOf(files[f.file], f.path) : null }));
     const render = loadAllowedRenderKeys(packDir);
     if (render.keys) {
-        const findings = yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys));
+        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys)));
         if (findings.length) {
             console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -680,14 +758,13 @@ async function cmdValidate(flags) {
         console.log('✓ render intents use only fields the platform renders');
     }
     else {
-        console.log(`⚠ ${describeKbLookup(render.lookup, 'render-intent fields')}`);
-        skipped.push('render-intent fields');
+        noteSkip('render-intent fields', render.lookup);
     }
     // Primitive `args:` keys, same source and same contract. Cannot see inside a
     // `use:` template body (expansion is the platform's job); `--remote` covers that.
     const args = loadPrimitiveArgSpecs(packDir);
     if (args.specs) {
-        const findings = yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs));
+        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
         if (findings.length) {
             console.error(`✗ ${findings.length} primitive-argument error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -697,8 +774,104 @@ async function cmdValidate(flags) {
         console.log('✓ primitive arguments match their declared inputs');
     }
     else {
-        console.log(`⚠ ${describeKbLookup(args.lookup, 'primitive arguments')}`);
-        skipped.push('primitive arguments');
+        noteSkip('primitive arguments', args.lookup);
+    }
+    // Expression builtins — the function set is CLOSED and generated from the
+    // runtime, so an invented `$fn(` is checkable here and nowhere else offline.
+    const builtins = loadBuiltinNames(packDir);
+    if (builtins.names) {
+        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findBuiltinViolations(doc, p, builtins.names)));
+        if (findings.length) {
+            console.error(`✗ ${findings.length} unknown expression function${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeBuiltinFinding(f)}`);
+            die('fix these before deploying — the evaluator cannot resolve them, and it fails mid-conversation');
+        }
+        console.log('✓ every $function() in an expression exists');
+    }
+    else {
+        noteSkip('expression functions', builtins.lookup);
+    }
+    // `use:` templates. A pack's OWN templates shadow the platform's, so they are
+    // named here and skipped — this check has no schema for them.
+    const templates = loadTemplateSpecs(packDir);
+    if (templates.specs) {
+        // A pack template is `templates/<name>.template.yaml` — the `.template`
+        // segment is part of the convention the expander scans for, NOT part of the
+        // name a `use:` writes. Capturing it would leave every pack that shadows a
+        // platform template (kaiian shadows `field_prompt_render`) reported as using
+        // one that does not exist.
+        const packTemplates = new Set(Object.keys(files)
+            .map(p => /^templates\/(.+)\.template\.ya?ml$/i.exec(p.replace(/\\/g, '/'))?.[1])
+            .filter((n) => !!n));
+        const findings = yamlDocs().flatMap(([p, doc]) => findTemplateViolations(doc, p, templates.specs, packTemplates));
+        if (findings.length) {
+            console.error(`✗ ${findings.length} template error${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeTemplateFinding(f)}`);
+            die('fix these before deploying — a template param that does not exist arrives as undefined, and renders as a blank');
+        }
+        console.log('✓ `use:` templates and their params exist');
+    }
+    else {
+        noteSkip('`use:` templates', templates.lookup);
+    }
+    // Reserved XRM entity keys — a boot error, which means the pack deploys clean
+    // and then fails to load on the first inbound message.
+    const system = loadSystemEntities(packDir);
+    if (system.entities) {
+        const findings = yamlDocs()
+            .filter(([p]) => /(^|[/\\])xrm\.ya?ml$/i.test(p))
+            .flatMap(([p, doc]) => findEntityViolations(doc, p, system.entities, system.rules));
+        if (findings.length) {
+            console.error(`✗ ${findings.length} reserved-entity error${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeEntityFinding(f)}`);
+            die('fix these before deploying — these fail at BOOT, after a deploy that reported success');
+        }
+        // Name the narrower promise when the catalog-level rules are absent (a KB
+        // pulled before they were published) — a ✓ that reads wider than what ran is
+        // the failure this file's skip contract exists to prevent.
+        console.log(system.rules
+            ? '✓ no entity collides with a reserved platform key, and no extension overrides a platform-owned one'
+            : '✓ no entity collides with a reserved platform key (re-pull for the `contact`/extension-override rules)');
+    }
+    else {
+        noteSkip('reserved entity keys', system.lookup);
+    }
+    // The declaration files themselves, against the published JSON Schemas.
+    // Deliberately narrow (see declaration-check.ts) — it walks away from anything
+    // it cannot read rather than guessing.
+    const decls = loadDeclarationSpecs(packDir);
+    if (decls.specs) {
+        const findings = yamlDocs().flatMap(([p, doc]) => {
+            const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
+            const spec = decls.specs.get(base);
+            // Only a file at the PACK ROOT is a declaration — `flows/tools/xrm.yaml`
+            // would be a flow that happens to share a name.
+            if (!spec || p.replace(/\\/g, '/').includes('/'))
+                return [];
+            return findDeclarationViolations(doc, spec).map(f => ({ ...f, file: p }));
+        });
+        if (findings.length) {
+            console.error(`✗ ${findings.length} declaration error${findings.length === 1 ? '' : 's'}:`);
+            for (const f of findings)
+                console.error(`  ✗ ${describeDeclarationFinding(f)}`);
+            die('fix these before deploying — a declaration file is parsed strictly, and an unknown key is rejected');
+        }
+        // Deliberately narrow wording. Most of `xrm.yaml`'s field shapes are a Zod
+        // union, which renders as `anyOf` and which this check walks away from by
+        // design — so "matches its schema" would be a promise it does not keep, and
+        // an over-claimed ✓ is how an author stops reading `--remote` output.
+        console.log('✓ declaration files carry no unknown or missing keys (unions are left to --remote)');
+    }
+    else {
+        noteSkip('declaration schemas', decls.lookup);
+    }
+    // One ⚠ per distinct reason, naming every check it cost.
+    for (const { lookup, labels } of skipReasons.values()) {
+        const what = labels.length === 1 ? labels[0] : `${labels.length} checks (${labels.join(', ')})`;
+        console.log(`⚠ ${describeKbLookup(lookup, what)}`);
     }
     // `--require-kb` is for CI, where a skip nobody reads is worse than a red build.
     if (skipped.length && flags['require-kb'] === true) {
@@ -708,7 +881,7 @@ async function cmdValidate(flags) {
         // The LAST line carries the skip. A reader who sees a ✓ and stops there is the
         // failure mode; a caveat printed ABOVE the ✓ does not fix it.
         if (skipped.length) {
-            console.log(`\n⚠ ${id}@${version} passed the checks that RAN — ${skipped.join(' and ')} ${skipped.length === 1 ? 'was' : 'were'} skipped.`);
+            console.log(`\n⚠ ${id}@${version} passed the checks that RAN — ${skipped.length} skipped: ${skipped.join(', ')}.`);
             console.log('  Run `octwin platform-kb pull` (once, at your repo root — it covers every pack under it),');
             console.log('  or `octwin validate --remote` to have the platform run everything server-side.');
         }
@@ -838,6 +1011,24 @@ function resolveTargetOrNull(flags) {
     const t = readTarget(flags);
     return t.url && t.token ? t : null;
 }
+/**
+ * Where to read the platform capability reference from, and how.
+ *
+ * The KB is tenant-independent platform stdlib, and the platform now serves it
+ * anonymously at `/api/public/octwin-platform-kb` precisely so a COLD START does
+ * not need a login: `.octwin/` is gitignored, so a fresh clone — or a fresh
+ * Claude Code session — has no reference at all, and an authoring agent's first
+ * useful question came after a credential round-trip it had no way to satisfy.
+ *
+ * A token still WINS when one is available: the tenant-scoped route is the one
+ * that has always existed, it works against platforms that predate the public
+ * rung, and using it keeps the author's own instance the source of truth.
+ */
+function kbEndpoint(t) {
+    return t.token
+        ? { url: `${t.url}/api/self/t/octwin-platform-kb`, headers: authHeaders(t), anonymous: false }
+        : { url: `${t.url}/api/public/octwin-platform-kb`, headers: {}, anonymous: true };
+}
 /** The raw resolution both wrappers share — may return empty url/token. */
 function readTarget(flags) {
     const url = (flags.url ?? process.env.PACK_PLATFORM_URL ?? savedDefaultUrl()).replace(/\/$/, '');
@@ -1231,35 +1422,10 @@ async function cmdStatus(flags) {
 function kbEntryFileName(name) {
     return name.replace(/[^A-Za-z0-9._-]/g, '_');
 }
-/** First sentence (or a hard clamp) of a possibly-long `describe` — INDEX.md needs
- *  one scannable line per entry, not the whole contract.
- *
- *  Sentence detection ignores punctuation nested in brackets: primitive `describe`
- *  text routinely inlines an envelope shape (`… { rows, total, …, refs? } …`) whose
- *  `?` would otherwise cut the summary off mid-brace. */
-function kbOneLiner(text, max = 160) {
-    if (typeof text !== 'string' || !text.trim())
-        return '';
-    const flat = text.replace(/\s+/g, ' ').trim();
-    let depth = 0;
-    let end = -1;
-    for (let i = 0; i < flat.length; i++) {
-        const ch = flat[i];
-        if (ch === '{' || ch === '(' || ch === '[')
-            depth++;
-        else if (ch === '}' || ch === ')' || ch === ']')
-            depth = Math.max(0, depth - 1);
-        else if (depth === 0 && (ch === '.' || ch === '!' || ch === '?')) {
-            const next = flat[i + 1];
-            if (next === undefined || next === ' ') {
-                end = i + 1;
-                break;
-            }
-        }
-    }
-    const line = end >= 40 ? flat.slice(0, end) : flat;
-    return line.length > max ? line.slice(0, max - 1).trimEnd() + '…' : line;
-}
+/** Envelope keys that are bookkeeping, not catalog-level content — never worth a
+ *  `_catalog.json` of their own. Anything else in the envelope is a real rule that
+ *  would otherwise be dropped by the explode. */
+const CATALOG_ENVELOPE_NOISE = new Set(['version', 'description', 'source']);
 /** Enumerate a catalog's entries per the platform-supplied descriptor. Handles both
  *  collection shapes in use: an ARRAY of named objects (`primitives`, keyed by
  *  `name`) and an OBJECT MAP keyed by entry name (`declarations`, `system-entities`).
@@ -1288,73 +1454,56 @@ function enumerateKbEntries(catalog, d) {
     }
     return [];
 }
-/**
- * Build `INDEX.md` — the map an authoring agent reads FIRST.
- *
- * The KB is ~800 KB across three dozen files; reading it whole costs more context
- * than the pack being authored. This index is one ~7k-token read that names every
- * doc and every catalog entry with a one-line summary and its exact path, so the
- * agent can jump straight to the ~600-token file it actually needs.
- */
-function buildKbIndexMarkdown(bundle, exploded) {
-    const index = bundle.index ?? [];
-    const docs = index.filter(e => e.kind === 'doc');
-    const catalogs = index.filter(e => e.kind === 'catalog');
-    const L = [];
-    L.push('# Octwin platform capability reference — INDEX');
-    L.push('');
-    L.push(`Reference version ${bundle.version ?? '?'} · content_hash \`${bundle.content_hash ?? '?'}\` · pulled ${bundle.generated_at ?? '?'}`);
-    L.push('');
-    L.push('**This is the map. Read it, then open only the specific file you need — never a whole catalog.**');
-    L.push('Everything the platform supports is here; if a step, function, field, or render intent is NOT in');
-    L.push('this index, it does not exist for a pure-YAML pack. Do not fill a gap from memory.');
-    L.push('');
-    L.push('## Start here');
-    L.push('');
-    L.push('1. `craft-capabilities.md` — how this reference fits together.');
-    L.push('2. `craft-ux.md` — what a *good* pack looks like (home hub, rich cards, confirm-before-commit).');
-    L.push('3. `craft-flows.md` — the flow DSL in practice.');
-    L.push('4. Then the tables below, on demand.');
-    L.push('');
-    L.push('## Guides & reference docs');
-    L.push('');
-    L.push('| Doc | Read it for | File |');
-    L.push('|---|---|---|');
-    for (const d of docs)
-        L.push(`| ${d.title ?? d.key} | ${kbOneLiner(d.summary)} | \`${d.key}.md\` |`);
-    L.push('');
-    L.push('## Catalogs — exact machine-readable schemas');
-    L.push('');
-    for (const c of catalogs) {
-        const entries = exploded.get(c.key);
-        L.push(`### ${c.title ?? c.key}`);
-        L.push('');
-        L.push(kbOneLiner(c.summary, 400));
-        L.push('');
-        if (!entries || entries.length === 0) {
-            L.push(`Single document: \`${c.key}.json\``);
-            L.push('');
-            continue;
-        }
-        L.push(`${entries.length} entries in \`${c.key}/\` — one file each.`);
-        L.push('');
-        L.push('| Entry | What it does | File |');
-        L.push('|---|---|---|');
-        for (const e of entries) {
-            L.push(`| \`${e.name}\` | ${e.summary.replace(/\|/g, '\\|')} | \`${c.key}/${kbEntryFileName(e.name)}.json\` |`);
-        }
-        L.push('');
-    }
-    return L.join('\n') + '\n';
-}
 async function cmdPlatformKb(flags) {
     const packDir = resolve(flags.dir ?? '.');
-    const t = resolveTarget(flags);
+    const t = readTarget(flags);
+    if (!t.url)
+        die('no platform url — pass --url <url>, set PACK_PLATFORM_URL, or run `octwin login`');
     const { url } = t;
-    console.log(`→ Pulling the platform capability reference from ${url} …`);
-    const res = await fetchOrDie(`${url}/api/self/t/octwin-platform-kb`, {
-        headers: authHeaders(t),
-    }, 'platform-kb pull');
+    const ep = kbEndpoint(t);
+    // ── --check: report staleness as an EXIT CODE, write nothing ──────────
+    //
+    // For a loop that wants to branch on "is my reference current?" without
+    // parsing prose. 0 = current · 2 = stale (or never pulled) · 1 = could not
+    // tell. Three codes, not two: an agent that treats "unreachable" as "stale"
+    // re-pulls forever against an instance that is down.
+    if (flags.check === true) {
+        const local = readLocalKb(packDir);
+        const polled = await fetchKbMeta(t, 10_000);
+        if (!polled.ok) {
+            console.error(polled.notAuthorized
+                ? '✗ cannot check — the platform refused the token, and this instance serves no anonymous reference.'
+                : `✗ cannot check — ${url} did not answer.`);
+            process.exit(1);
+        }
+        const remote = polled.meta.content_hash;
+        if (!local?.content_hash) {
+            console.log(`⬆ no reference pulled yet (platform is at ${remote ?? '?'}) — run \`octwin platform-kb pull\`.`);
+            process.exit(2);
+        }
+        if (remote && remote !== local.content_hash) {
+            console.log(`⬆ stale: local ${local.content_hash} → platform ${remote}. Run \`octwin platform-kb pull\`.`);
+            process.exit(2);
+        }
+        console.log(`✓ current (${local.content_hash}).`);
+        return;
+    }
+    // ── --if-stale: make "pull at the start of every session" free ────────
+    //
+    // One small `?meta=1` GET instead of ~1 MB, and it is what lets the skill say
+    // "pull every session" without that costing a megabyte per session. An
+    // unreachable platform is NOT treated as current: it falls through to the real
+    // pull, which fails loudly with the actual error.
+    if (flags['if-stale'] === true) {
+        const local = readLocalKb(packDir);
+        const polled = await fetchKbMeta(t, 10_000);
+        if (polled.ok && local?.content_hash && polled.meta.content_hash === local.content_hash) {
+            console.log(`✓ capability reference already current (${local.content_hash}) — nothing to pull.`);
+            return;
+        }
+    }
+    console.log(`→ Pulling the platform capability reference from ${url}${ep.anonymous ? ' (anonymous — no token needed for the reference)' : ''} …`);
+    const res = await fetchOrDie(ep.url, { headers: ep.headers }, 'platform-kb pull');
     const text = await res.text();
     if (!res.ok) {
         let j;
@@ -1405,6 +1554,9 @@ async function cmdPlatformKb(flags) {
     // (or an unexpected payload shape) fall back to the flat file.
     const byKey = new Map((bundle.index ?? []).map(e => [e.key, e]));
     const exploded = new Map();
+    /** Catalogs written as ONE file — the flow schema is the only one today, and the
+     *  symbol router still mines it for node op-keys. */
+    const flatCatalogs = {};
     let catalogCount = 0;
     let entryCount = 0;
     for (const [key, val] of Object.entries(bundle.sources ?? {})) {
@@ -1415,6 +1567,7 @@ async function cmdPlatformKb(flags) {
         const entries = descriptor ? enumerateKbEntries(val, descriptor) : [];
         if (entries.length === 0) {
             writeFileSync(join(outDir, `${key}.json`), JSON.stringify(val, null, 2) + '\n', 'utf8');
+            flatCatalogs[key] = val;
             continue;
         }
         const dir = join(outDir, key);
@@ -1422,17 +1575,57 @@ async function cmdPlatformKb(flags) {
         for (const entry of entries) {
             writeFileSync(join(dir, `${kbEntryFileName(entry.name)}.json`), JSON.stringify(entry.value, null, 2) + '\n', 'utf8');
         }
+        // The ENVELOPE, when it carries anything beyond the collection.
+        //
+        // Exploding a catalog drops everything that is not an entry — which was fine
+        // while the envelope held only `version`/`description`/`source`, and silently
+        // wrong the moment a catalog published a rule that belongs to the whole set
+        // rather than to one member. `system-entities` does exactly that: the reserved
+        // entity keys, the reserved prefix, and the keys an `extends: system` entity
+        // may not override are properties of the CATALOG. Written as `_catalog.json`
+        // so the offline checks can read them.
+        //
+        // The `_` prefix is load-bearing: every loader that reads one of these
+        // directories iterates `*.json`, so a sibling that is not an entry must be
+        // skippable by name. See the `isEntryFile` guard the checks share.
+        const envelope = Object.fromEntries(Object.entries(val)
+            .filter(([k]) => k !== descriptor.at && !CATALOG_ENVELOPE_NOISE.has(k)));
+        if (Object.keys(envelope).length > 0) {
+            writeFileSync(join(dir, '_catalog.json'), JSON.stringify(envelope, null, 2) + '\n', 'utf8');
+        }
         exploded.set(key, entries);
         entryCount += entries.length;
     }
-    // The map the authoring skill reads first.
-    writeFileSync(join(outDir, 'INDEX.md'), buildKbIndexMarkdown(bundle, exploded), 'utf8');
+    // ── the three maps ────────────────────────────────────────────────────
+    //
+    // Three, not one, because an author arrives with three different things in
+    // hand: a QUESTION (INDEX), a NAME (SYMBOLS), or a doc too heavy to read whole
+    // (OUTLINE). One file answering all three is the file nobody can afford to
+    // read — which is what INDEX.md had become at ~30 KB, most of it entry rows
+    // that belong in a grep target.
+    writeFileSync(join(outDir, 'INDEX.md'), buildKbIndexMarkdown(bundle, new Map([...exploded].map(([k, v]) => [k, v.length]))), 'utf8');
+    // SYMBOLS.md — every addressable name → the file that defines it. Derived from
+    // the catalogs just written, so it needs nothing extra over the wire.
+    const symbols = buildSymbols(exploded, (catalogKey, entryName) => `${catalogKey}/${kbEntryFileName(entryName)}.json`, flatCatalogs);
+    linkExplainers(symbols, new Map((bundle.index ?? [])
+        .filter(e => e.kind === 'doc' && e.sections?.length)
+        .map(e => [e.key, e.sections])));
+    writeFileSync(join(outDir, 'SYMBOLS.md'), renderSymbolsMarkdown(symbols, bundle.content_hash), 'utf8');
+    // OUTLINE.md — only when the platform published section data. An empty outline
+    // would read as "these docs have no sections", which is worse than its absence.
+    const outline = buildKbOutlineMarkdown(bundle);
+    if (outline)
+        writeFileSync(join(outDir, 'OUTLINE.md'), outline, 'utf8');
     // Persist `content_hash` too — the staleness observer (`notifyIfKbStale`) reads
     // it back and compares against the platform's current hash to nudge a re-pull.
     writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, content_hash: bundle.content_hash, generated_at: bundle.generated_at, index: bundle.index }, null, 2) + '\n', 'utf8');
     console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
     console.log(`  ${mdCount} markdown docs + ${catalogCount} catalogs (${entryCount} entries, one file each) — reference version ${bundle.version ?? '?'}`);
-    console.log('  Start at INDEX.md — it maps every doc and every catalog entry to its file.');
+    console.log(`  Three maps: INDEX.md (the corpus) · SYMBOLS.md (${symbols.length} names → their file, grep it)`
+        + `${outline ? ' · OUTLINE.md (every heading, with line numbers)' : ''}`);
+    if (!outline) {
+        console.log('  (no OUTLINE.md — this platform publishes no doc section data; upgrade it for line-addressable docs.)');
+    }
     console.log('  Every pack UNDER this directory finds it — `octwin validate` walks up to locate it,');
     console.log('  so one pull at a repo root covers a whole monorepo of packs.');
     // Changelog since the last pull — per-entry hashes tell us WHICH docs/catalogs
@@ -1454,7 +1647,7 @@ async function cmdPlatformKb(flags) {
     }
     console.log('  The octwin-pack authoring skill reads these as the source of truth for what the platform supports.');
 }
-// ── records / cases / logs / chat — headless inspect + test with the deploy token ────
+// ── records / work / logs / chat — headless inspect + test with the deploy token ────
 /** GET an admin endpoint with the deploy token; returns `{ status, json }`.
  *  Dies (with the URL) on a network failure; auth failures return so the
  *  caller can add command-specific context on top of `authFailureHint`. */
@@ -1616,9 +1809,9 @@ async function cmdRecords(flags) {
         const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&${pagingQs(flags)}`, t);
         if (status !== 200) {
             // Always show the server's reason (it names the unknown entity). Cases are
-            // casework (worklist), not pack-declared XRM — point at the right command.
+            // worked records (worklist), not pack-declared XRM — point at the right command.
             if (entity === 'case' || entity === 'cases') {
-                console.error(`  '${entity}' is casework (worklist), not a pack-declared XRM entity — inspect tickets with: octwin cases`);
+                console.error(`  '${entity}' is a worked record (worklist), not a pack-declared XRM entity — inspect it with: octwin work`);
             }
             die(`could not read records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         }
@@ -2294,70 +2487,86 @@ async function cmdMedia(flags) {
         console.log(`  saved → ${out}`);
     console.log(`  Send it into a chat: octwin chat "here you go" --media ${out ?? r.media_id} --as <handle>`);
 }
-/** Reserved leading words on `octwin cases` — see `RECORD_VERBS` for the rule. */
-const CASE_VERBS = new Set(['assign', 'note', 'transition', 'decide']);
+/** Reserved leading words on `octwin work` — see `RECORD_VERBS` for the rule. */
+const WORK_VERBS = new Set(['assign', 'note', 'stage', 'decide']);
+/** A localized label bag (or legacy bare string) → one printable string.
+ *  The work routes ship labels as full bags so each consumer picks; the CLI
+ *  prefers English and falls back to whatever the bag has. */
+function pickLabel(v) {
+    if (typeof v === 'string')
+        return v;
+    if (v && typeof v === 'object') {
+        const bag = v;
+        return bag.en ?? Object.values(bag)[0] ?? null;
+    }
+    return null;
+}
 /**
- * The write half of `octwin cases` — assign / note / transition / decide.
+ * The write half of `octwin work` — assign / note / stage / decide.
+ *
+ * `stage` is deliberately the XRM records verb (`POST …/xrm/records/:id/stage`):
+ * the work surface carries no second transition spelling — a stage move has one
+ * verb platform-wide (consolidation P-02).
  *
- * `decide --dry-run` routes to the PREVIEW endpoint, which sits behind `cases:read`
- * rather than `cases:write`: it renders the customer-facing copy and the resulting
- * status without committing. That makes "show me what this disposition would do"
+ * `decide --dry-run` routes to the PREVIEW endpoint, which sits behind `work:read`
+ * rather than `work:write`: it renders the customer-facing copy and the resulting
+ * stage without committing. That makes "show me what this disposition would do"
  * safe to run with a read-only token, which is exactly when an author wants it.
  */
-async function cmdCasesWrite(flags) {
+async function cmdWorkWrite(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
     const verb = flags._[0];
-    const id = flags._[1] ?? die(`usage: octwin cases ${verb} <caseId> …`);
-    const readBack = () => console.log(`\nRead it back:  octwin cases ${id}`);
+    const id = flags._[1] ?? die(`usage: octwin work ${verb} <recordId> …`);
+    const readBack = () => console.log(`\nRead it back:  octwin work ${id}`);
     if (verb === 'assign') {
         // `--to none` unassigns (the route takes null); anything else must carry the
         // principal kind, because a bare uuid cannot say user-or-team.
         const to = typeof flags.to === 'string' ? flags.to
-            : die('usage: octwin cases assign <caseId> --to user:<uuid>|team:<uuid>|none');
+            : die('usage: octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none');
         const assignee = to === 'none' ? null : to;
         if (assignee !== null && !/^(user|team):/.test(assignee)) {
             die(`--to must be 'user:<uuid>', 'team:<uuid>' or 'none' (got '${to}')`);
         }
-        console.log(`→ ${assignee === null ? 'Unassigning' : `Assigning to ${assignee}`} case ${id} …`);
-        const { status, json } = await apiSend('PATCH', `${base}/cases/${encodeURIComponent(id)}/assign`, { assignee }, t);
+        console.log(`→ ${assignee === null ? 'Unassigning' : `Assigning to ${assignee}`} work item ${id} …`);
+        const { status, json } = await apiSend('PATCH', `${base}/work/${encodeURIComponent(id)}/assign`, { assignee }, t);
         if (status !== 200)
-            writeFail(`assign case ${id}`, status, json, url, true);
+            writeFail(`assign work item ${id}`, status, json, url, true);
         console.log(assignee === null ? '✓ Unassigned.' : `✓ Assigned to ${json?.assignee ?? assignee}.`);
         return;
     }
     if (verb === 'note') {
-        const note = flags._[2] ?? die('usage: octwin cases note <caseId> "the note text"');
-        console.log(`→ Adding a note to case ${id} …`);
-        const { status, json } = await apiSend('POST', `${base}/cases/${encodeURIComponent(id)}/note`, { note }, t);
+        const note = flags._[2] ?? die('usage: octwin work note <recordId> "the note text"');
+        console.log(`→ Adding a note to work item ${id} …`);
+        const { status, json } = await apiSend('POST', `${base}/work/${encodeURIComponent(id)}/note`, { note }, t);
         if (status !== 200)
-            writeFail(`note case ${id}`, status, json, url, true);
-        console.log('✓ Note added to the case timeline.');
+            writeFail(`note work item ${id}`, status, json, url, true);
+        console.log('✓ Note added to the record timeline.');
         readBack();
         return;
     }
-    if (verb === 'transition') {
+    if (verb === 'stage') {
         const to = typeof flags.to === 'string' ? flags.to
-            : die('usage: octwin cases transition <caseId> --to <status> [--note "..."]');
-        const body = { to_status: to };
+            : die('usage: octwin work stage <recordId> --to <stage> [--note "..."]');
+        const body = { to_stage: to };
         if (typeof flags.note === 'string')
             body.note = flags.note;
-        console.log(`→ Moving case ${id} to '${to}' …`);
-        const { status, json } = await apiSend('POST', `${base}/cases/${encodeURIComponent(id)}/transition`, body, t);
+        console.log(`→ Moving record ${id} to '${to}' …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/records/${encodeURIComponent(id)}/stage`, body, t);
         if (status !== 200) {
-            // The case detail read carries the legal targets; point at it rather than
+            // The work detail read carries the legal targets; point at it rather than
             // leaving the author to guess the vocabulary.
             if (status === 400)
-                console.error(`  → legal targets for this case: octwin cases ${id}  (see its workflow)`);
-            writeFail(`move case ${id} to '${to}'`, status, json, url, true);
+                console.error(`  → legal targets for this record: octwin work ${id}  (see its workflow)`);
+            writeFail(`move record ${id} to '${to}'`, status, json, url, true);
         }
-        console.log(`✓ Case is now '${json?.case?.status ?? to}'.`);
+        console.log(`✓ Record is now '${json?.stage ?? to}'.`);
         return;
     }
-    // decide
+    // decide — apply one of the entity's declared operator actions
     const action = typeof flags.action === 'string' ? flags.action
-        : die('usage: octwin cases decide <caseId> --action <action> [--param k=v] [--note "..."] [--dry-run]');
+        : die('usage: octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]');
     const params = {};
     for (const pair of flagList(flags, 'param')) {
         const eq = pair.indexOf('=');
@@ -2369,39 +2578,41 @@ async function cmdCasesWrite(flags) {
     const body = { action, ...(Object.keys(params).length ? { params } : {}) };
     if (!dryRun && typeof flags.note === 'string')
         body.internal_note = flags.note;
-    console.log(`→ ${dryRun ? 'Previewing' : 'Applying'} '${action}' on case ${id} …`);
-    const endpoint = `${base}/cases/${encodeURIComponent(id)}/decision${dryRun ? '/preview' : ''}`;
+    console.log(`→ ${dryRun ? 'Previewing' : 'Applying'} '${action}' on work item ${id} …`);
+    const endpoint = `${base}/work/${encodeURIComponent(id)}/action${dryRun ? '/preview' : ''}`;
     const { status, json } = await apiSend('POST', endpoint, body, t);
     if (status === 404)
-        die(`case '${id}' not found`);
+        die(`work item '${id}' not found`);
     if (status !== 200) {
-        console.error(`  → the case's applicable actions are listed by: octwin cases ${id}`);
-        writeFail(`${dryRun ? 'preview' : 'apply'} '${action}' on case ${id}`, status, json, url, true);
+        console.error(`  → the item's applicable actions are listed by: octwin work ${id}`);
+        writeFail(`${dryRun ? 'preview' : 'apply'} '${action}' on work item ${id}`, status, json, url, true);
     }
     if (dryRun) {
         console.log('Preview (nothing was committed):');
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    console.log(`✓ Applied '${action}' — case is now '${json?.case?.status ?? '?'}'.`);
-    // `notified` is the customer-facing half; silence here usually means the
-    // disposition had no message template, which is easy to mistake for a failure.
-    console.log(json?.notified ? '  ✓ the customer was notified.' : '  ⓘ no customer notification was sent by this action.');
+    console.log(`✓ Applied '${action}'${json?.to_stage ? ` — record is now '${json.to_stage}'` : ''}.`);
+    // `relayed`/`notified` are the customer-facing half; silence here usually means
+    // the action had no message template, which is easy to mistake for a failure.
+    const reached = json?.relayed || json?.notified;
+    console.log(reached ? '  ✓ the customer was notified.' : '  ⓘ no customer notification was sent by this action.');
     readBack();
 }
-/** `octwin cases [caseId] [--queues]` — inspect casework (support tickets):
- *  the aggregate inbox, one case + its timeline, or the queue list. */
-async function cmdCases(flags) {
-    if (typeof flags._[0] === 'string' && CASE_VERBS.has(flags._[0]))
-        return cmdCasesWrite(flags);
+/** `octwin work [recordId] [--queues]` — inspect the work inbox (every entity the
+ *  pack declares worked): the aggregate inbox, one item + its timeline, or the
+ *  queue list. */
+async function cmdWork(flags) {
+    if (typeof flags._[0] === 'string' && WORK_VERBS.has(flags._[0]))
+        return cmdWorkWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
-    const caseId = flags._[0];
+    const recordId = flags._[0];
     const asJson = flags.json === true;
     if (!asJson)
-        console.log(`→ Reading ${flags.queues === true ? 'case queues' : caseId ? `case ${caseId}` : 'the case inbox'} from ${targetLabel(t)} …`);
-    const caseFail = (what, status, json) => {
+        console.log(`→ Reading ${flags.queues === true ? 'work queues' : recordId ? `work item ${recordId}` : 'the work inbox'} from ${targetLabel(t)} …`);
+    const workFail = (what, status, json) => {
         // A 403 here can also be an RBAC gap the scope hint can't see — a role whose
         // grants don't reach the queue passes the scope gate and still gets nothing.
         if (status === 403)
@@ -2409,72 +2620,74 @@ async function cmdCases(flags) {
         die(`could not read ${what} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     };
     if (flags.queues === true) {
-        const { status, json } = await apiGet(`${base}/case-queues`, t);
+        const { status, json } = await apiGet(`${base}/work/queues`, t);
         if (status !== 200)
-            caseFail('case queues', status, json);
+            workFail('work queues', status, json);
         if (asJson) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
         const queues = (json?.queues ?? []);
-        console.log(`Case queues in ${targetLabel(t)}:`);
-        for (const q of queues)
-            console.log(`  ${q.key}${q.name ? `  (${q.name})` : ''}  ${q.open_count} open`);
+        console.log(`Work queues in ${targetLabel(t)}:`);
+        for (const q of queues) {
+            const name = pickLabel(q.name);
+            console.log(`  ${q.key}${name ? `  (${name})` : ''}  ${q.open_count} open`);
+        }
         if (json?.unrouted_open_count)
             console.log(`  (unrouted: ${json.unrouted_open_count} open)`);
         return;
     }
-    if (!caseId) {
-        const { status, json } = await apiGet(`${base}/cases?${pagingQs(flags)}`, t);
+    if (!recordId) {
+        const { status, json } = await apiGet(`${base}/work?${pagingQs(flags)}`, t);
         if (status !== 200)
-            caseFail('cases', status, json);
+            workFail('the work inbox', status, json);
         if (asJson) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
         const page = readPage(json);
-        console.log(`Cases in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
+        console.log(`Work items in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
         if (page.rows.length === 0)
             console.log('  (none)');
-        for (const c of page.rows) {
-            const sla = c.sla_due_at ? `  sla:${c.sla_due_at}` : '';
-            console.log(`  #${c.case_number ?? '?'}  ${c.type}  [${c.status}]  ${c.priority}${c.queue_key ? `  q:${c.queue_key}` : ''}${sla}  ${c.id}`);
+        for (const w of page.rows) {
+            const sla = w.sla_due_at ? `  sla:${w.sla_due_at}` : '';
+            console.log(`  #${w.record_number ?? '?'}  ${w.entity}${w.type ? `/${w.type}` : ''}  [${w.stage ?? '?'}]  ${w.priority}${w.queue_key ? `  q:${w.queue_key}` : ''}${sla}  ${w.record_id}`);
         }
-        const more = morePageHint(page, 'octwin cases');
+        const more = morePageHint(page, 'octwin work');
         if (more)
             console.log(more);
-        console.log('\nOne case + timeline:  octwin cases <caseId>    queues:  octwin cases --queues');
+        console.log('\nOne item + timeline:  octwin work <recordId>    queues:  octwin work --queues');
         return;
     }
-    const { status, json } = await apiGet(`${base}/cases/${encodeURIComponent(caseId)}`, t);
+    const { status, json } = await apiGet(`${base}/work/${encodeURIComponent(recordId)}`, t);
     if (status === 404)
-        die(`case '${caseId}' not found`);
+        die(`work item '${recordId}' not found`);
     if (status !== 200)
-        caseFail('case', status, json);
+        workFail('work item', status, json);
     if (asJson) {
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    const c = json?.case ?? {};
-    console.log(`Case #${c.case_number ?? '?'}  ${c.type}  [${c.status}]  ${c.priority}`);
-    console.log(`  id: ${c.id}   queue: ${c.queue_key ?? '(unrouted)'}   assignee: ${c.assignee_principal ?? '(none)'}`);
+    const w = json?.item ?? {};
+    console.log(`${pickLabel(json?.entity_label) ?? w.entity} #${w.record_number ?? '?'}${w.type ? `  ${w.type}` : ''}  [${w.stage ?? '?'}]  ${w.priority}`);
+    console.log(`  id: ${w.record_id}   queue: ${w.queue_key ?? '(unrouted)'}   assignee: ${w.assignee_principal ?? '(none)'}`);
     if (json?.contact)
         console.log(`  contact: ${json.contact.display_name ?? json.contact.channel_contact_handle ?? json.contact.id}`);
-    if (c.conversation_id)
-        console.log(`  conversation: ${c.conversation_id}   (octwin logs ${c.conversation_id})`);
-    if (c.sla_due_at)
-        console.log(`  sla due: ${c.sla_due_at}`);
-    if (c.fields && Object.keys(c.fields).length > 0)
-        console.log(`  fields: ${JSON.stringify(c.fields)}`);
-    const events = (json?.events ?? []);
+    if (w.conversation_id)
+        console.log(`  conversation: ${w.conversation_id}   (octwin logs ${w.conversation_id})`);
+    if (w.sla_due_at)
+        console.log(`  sla due: ${w.sla_due_at}`);
+    if (w.fields && Object.keys(w.fields).length > 0)
+        console.log(`  fields: ${JSON.stringify(w.fields)}`);
+    const events = (json?.timeline ?? []);
     console.log(`  Timeline (${events.length}):`);
     for (const e of events) {
         const payload = e.payload && Object.keys(e.payload).length > 0 ? `  ${JSON.stringify(e.payload)}` : '';
         console.log(`    ${e.ts ?? ''}  ${e.kind}${e.actor ? ` (${e.actor})` : ''}${payload}`);
     }
-    const dispositions = (json?.dispositions ?? []);
-    if (dispositions.length > 0) {
-        console.log(`  Decisions: ${dispositions.map((d) => `${d.action}${d.next_status ? `→${d.next_status}` : ''}`).join(', ')}`);
+    const actions = (json?.actions ?? []);
+    if (actions.length > 0) {
+        console.log(`  Actions: ${actions.map((a) => `${a.action}${a.to_stage ? `→${a.to_stage}` : ''}`).join(', ')}`);
     }
 }
 // ── money formatting (orders / catalog) ─────────────────────────────────────
@@ -2891,21 +3104,32 @@ async function cmdOrdersWrite(flags) {
     if (verb === 'transition') {
         const to = typeof flags.to === 'string' ? flags.to
             : die('usage: octwin orders transition <reference_id> --to <status>');
+        // A stage move has ONE verb platform-wide — `POST …/xrm/records/:id/stage`
+        // (`POST …/orders/:ref/transition` was retired, consolidation P-02). The order
+        // detail read resolves the opaque reference to the record id and carries the
+        // legal targets for the failure hint.
         console.log(`→ Moving order ${ref} to '${to}' …`);
-        const { status, json } = await apiSend('POST', `${base}/${encodeURIComponent(ref)}/transition`, { to_status: to }, t);
-        if (status === 404)
+        const detail = await apiGet(`${base}/${encodeURIComponent(ref)}`, t);
+        if (detail.status === 404)
             die(`order '${ref}' not found (pass the opaque reference_id, not the #number)`);
-        if (status === 409) {
+        if (detail.status !== 200)
+            writeFail(`read order ${ref}`, detail.status, detail.json, url);
+        const recordId = detail.json?.order?.id;
+        if (!recordId)
+            die(`order '${ref}' carries no record id — cannot move its stage`);
+        const { status, json } = await apiSend('POST', `${url}/api/self/p/xrm/records/${encodeURIComponent(recordId)}/stage`, { to_stage: to }, t);
+        if (status === 400 || status === 409) {
             console.error(`✗ '${to}' is not a legal move for this order.`);
-            if (Array.isArray(json?.transitions))
-                console.error(`  → allowed: ${json.transitions.join(', ') || '(none)'}`);
+            const allowed = (detail.json?.transitions ?? []);
+            if (allowed.length > 0)
+                console.error(`  → allowed: ${allowed.join(', ')}`);
             else
                 console.error(`  → see the allowed set: octwin orders ${ref}`);
             process.exit(1);
         }
         if (status !== 200)
             writeFail(`move order ${ref} to '${to}'`, status, json, url);
-        console.log(`✓ Order is now '${json?.order?.status ?? to}'.`);
+        console.log(`✓ Order is now '${json?.stage ?? to}'.`);
         return;
     }
     // refund — irreversible, and money. `--force` rather than a prompt: the CLI is
@@ -3450,7 +3674,7 @@ function help() {
   octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
   octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
   octwin records [entity] [id]                           # inspect the pack's XRM data (needs a records:read token)
-  octwin cases   [caseId] [--queues] [--json]            # inspect casework (support tickets) + timelines
+  octwin work    [recordId] [--queues] [--json]          # inspect the work inbox (worked records) + timelines
   octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
   octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]  # drive a turn (+ send media) + print every render
   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
@@ -3459,15 +3683,15 @@ function help() {
   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
   octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
   octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
   octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
 
 Writes — exercise the state your pack creates (each needs the matching :write scope):
   octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
   octwin records tasks | task complete <taskId> [--outcome done|cancelled]
-  octwin cases   assign <id> --to user:<uuid>|none | note <id> "…" | transition <id> --to <status>
-  octwin cases   decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin work    assign <id> --to user:<uuid>|none | note <id> "…" | stage <id> --to <stage>
+  octwin work    decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
   octwin orders  transition <ref> --to <status> | refund <ref> --force
   octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
   octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
@@ -3530,8 +3754,8 @@ octwin projects rm <slug> [--yes]
     status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
   Show installed vs live version + the flow list for this pack.`,
     records: `octwin records [entity] [id] [--limit 50] [--offset n]
-  Inspect the pack's XRM data. No args = list entities. Cases/tickets are
-  casework, not XRM — use \`octwin cases\` for those.
+  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
+  tickets, anything routed to a queue) read best through \`octwin work\`.
 
   WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
     octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
@@ -3546,19 +3770,21 @@ octwin projects rm <slug> [--yes]
   \`patch\` needs --entity even though it has an id: the route resolves the field
   validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
   VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    cases: `octwin cases [caseId] [--queues] [--limit 50] [--offset n] [--json]
-  Inspect casework (support tickets): the inbox, one case + its timeline
-  (+ applicable decisions), or --queues for queue keys + open counts.
+    work: `octwin work [recordId] [--queues] [--limit 50] [--offset n] [--json]
+  Inspect the work inbox — every entity the pack declares worked (cases, orders
+  needing review, applications, …): the inbox, one item + its timeline
+  (+ applicable actions), or --queues for queue keys + open counts.
 
-  WRITES (need \`cases:write\`):
-    octwin cases assign     <caseId> --to user:<uuid>|team:<uuid>|none
-    octwin cases note       <caseId> "the note text"
-    octwin cases transition <caseId> --to <status> [--note "..."]
-    octwin cases decide     <caseId> --action <action> [--param k=v] [--note "..."] [--dry-run]
+  WRITES (need \`work:write\`; \`stage\` needs \`records:write\`):
+    octwin work assign <recordId> --to user:<uuid>|team:<uuid>|none
+    octwin work note   <recordId> "the note text"
+    octwin work stage  <recordId> --to <stage> [--note "..."]
+    octwin work decide <recordId> --action <action> [--param k=v] [--note "..."] [--dry-run]
 
-  \`decide\` applies one of the case's declared dispositions — \`octwin cases <id>\`
+  \`decide\` applies one of the entity's declared operator actions — \`octwin work <id>\`
   lists them with their params. --dry-run previews the customer-facing copy and the
-  resulting status WITHOUT committing (that route needs only \`cases:read\`).`,
+  resulting stage WITHOUT committing (that route needs only \`work:read\`).
+  \`stage\` is the XRM records verb (one transition spelling platform-wide).`,
     logs: `octwin logs [conversationId] [--as <handle>] [--json]
   No id = recent conversations (handle, status, last activity; --as filters).
   With id = the full event timeline including what each turn rendered.
@@ -3666,9 +3892,20 @@ octwin projects rm <slug> [--yes]
 
   --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
   \`--slots\` is how you check what a rule actually produces.`,
-    'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
+    'platform-kb': `octwin platform-kb [pull] [--if-stale] [--check] [--dir .] [--url <url>] [--token <t>]
   Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill.`,
+  .octwin/platform-kb/ for the octwin-pack authoring skill, plus three maps:
+  INDEX.md (the corpus) · SYMBOLS.md (every name -> its file; grep this) ·
+  OUTLINE.md (every heading with its line number).
+
+  NO TOKEN NEEDED — the reference is platform stdlib and is served anonymously.
+  A token is used when you have one (it also works against older platforms).
+
+  --if-stale   poll the platform's content_hash first and skip the download when
+               nothing changed. Cheap enough to run at the start of every session.
+  --check      report only, write nothing. Exit 0 = current, 2 = stale or never
+               pulled, 1 = could not tell (offline / refused). For scripts and
+               agent loops that want to branch without parsing prose.`,
     test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
     feedback: `octwin feedback [--dir .]
@@ -3685,7 +3922,7 @@ async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
     // So an auth failure can name the scope THIS invocation needs. A leading write
-    // verb changes the answer (`cases` reads, `cases note` writes), so it rides along
+    // verb changes the answer (`work` reads, `work note` writes), so it rides along
     // when the first positional is one — `VERB_REQUIREMENTS` is keyed that way.
     const leadingVerb = flags._[0];
     CURRENT_COMMAND = (typeof leadingVerb === 'string' && command && `${command} ${leadingVerb}` in VERB_REQUIREMENTS)
@@ -3722,8 +3959,8 @@ async function main() {
         case 'records':
             await cmdRecords(flags);
             break;
-        case 'cases':
-            await cmdCases(flags);
+        case 'work':
+            await cmdWork(flags);
             break;
         case 'logs':
             await cmdLogs(flags);