octwin-cli 0.5.1 → 0.6.1

package/dist/index.js

@@ -15,19 +15,19 @@
  *   octwin projects [--archived]    # the --project slugs this token can name
  *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
  *   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 status  [<packId>]       # 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)
- *   octwin media   generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
+ *   octwin media   generate "<prompt>" [--out <file.png>] [--json]  # AI-generate an image → MEDIA- handle (media:generate scope)
  *   octwin agents  [packId::agentId] [--prompt]   # effective model/memory + which layer won; --prompt = the resolved system prompt
  *   octwin orders  [reference_id]    # the orders a conversation produced — money breakdown + payment state (orders:read)
  *   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,20 @@ 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 { localhostFamilyHint } from './lib/net-hint.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.
@@ -157,7 +165,8 @@ async function fetchOrDie(url, init, what) {
         return await fetch(url, init);
     }
     catch (err) {
-        die(`${what} — platform unreachable at ${url} (${err?.message ?? err})`);
+        const hint = localhostFamilyHint(url, err);
+        die(`${what} — platform unreachable at ${url} (${err?.message ?? err})${hint ? `\n  ${hint}` : ''}`);
     }
 }
 /** One consistent explanation for auth failures on admin reads. A 401 can also
@@ -170,7 +179,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 +192,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 +226,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 +239,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 +252,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 +502,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 +540,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 +586,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 +615,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 +633,7 @@ function commandTouchesPlatform(command, flags) {
         case 'media':
         case 'pull':
         case 'records':
-        case 'cases':
+        case 'work':
         case 'logs':
         case 'whoami':
         case 'feedback':
@@ -602,9 +651,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 +690,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 +721,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, render.nested)));
         if (findings.length) {
             console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -680,14 +760,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 +776,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 +883,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.');
         }
@@ -723,10 +898,16 @@ async function cmdValidate(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
     console.log(`→ Validating against ${targetLabel(t)} @ ${url} …`);
+    // `--strict-primitives` (opt-in): the server additionally type-checks LITERAL
+    // `args:` values against each primitive's per-key input schema. Expression
+    // strings are always exempt — this judges only plain YAML scalars.
     const res = await fetchOrDie(`${url}/api/self/p/packs/validate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ files, blobs }),
+        body: JSON.stringify({
+            files, blobs,
+            ...(flags['strict-primitives'] === true ? { strict_primitives: true } : {}),
+        }),
     }, 'remote validate');
     const text = await res.text();
     let json;
@@ -838,6 +1019,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(/\/$/, '');
@@ -1066,13 +1265,13 @@ async function cmdSeed(flags) {
         const { terminal: final, stepErrors } = await readDeployProgress(res.body);
         if (!final || final.stage === 'error')
             die(`seed failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
-        console.log(`
+        console.log(`
 ✓ ${final.message ?? 'seed complete'}`);
         printSeedCounts(final.result?.seeded);
         if (stepErrors.length) {
             // A kind failed but the rest ran — the reconcile softens each step. Say which,
             // and exit non-zero so a scripted `seed && chat` doesn't read as clean.
-            console.error(`
+            console.error(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 console.error(`   • ${e}`);
@@ -1154,6 +1353,33 @@ async function cmdDeploy(flags) {
     }
     printDeploySuccess(id, version, t, json);
 }
+/**
+ * The QUALIFIED pack id (`<owner>.<name>`) for a manifest's bare name.
+ *
+ * A manifest declares a bare name and cannot legally declare anything else — the platform
+ * and this CLI both reject a `.` in it, because the owner segment is attached at publish
+ * time from the authenticated publisher. Every route that takes a pack id in its PATH
+ * requires the qualified form, so a command holding only a manifest has to ask who it is.
+ *
+ * `whoami`'s `tenant_slug` IS the owner segment. Without this, `octwin status` sent the bare
+ * name, `asPackId` rejected it, and the route's 404 was reported as "not installed" — so the
+ * command was structurally broken for every pack from the day ids gained owners
+ * (2026-08-01) until this was fixed, while the KB still taught it as step 4 of the loop.
+ */
+async function qualifiedPackId(t, bareName) {
+    if (bareName.includes('.'))
+        return bareName; // already qualified (explicit override)
+    const res = await fetchOrDie(`${t.url}/api/self/t/whoami`, { headers: authHeaders(t) }, 'workspace lookup');
+    if (!res.ok) {
+        printAuthHint(res.status, t.url);
+        die(`could not resolve your workspace to qualify the pack id (HTTP ${res.status}) — pass the full '<owner>.${bareName}' instead`);
+    }
+    const j = await res.json();
+    if (typeof j.tenant_slug !== 'string' || !j.tenant_slug) {
+        die(`the platform did not report a workspace slug — pass the full '<owner>.${bareName}' instead`);
+    }
+    return `${j.tenant_slug}.${bareName}`;
+}
 async function cmdStatus(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const t = resolveTarget(flags);
@@ -1164,8 +1390,11 @@ async function cmdStatus(flags) {
     const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
     if (typeof doc?.id !== 'string')
         die('manifest.yaml must declare a string `id`');
-    const id = doc.id;
+    const bare = doc.id;
     const localVersion = typeof doc?.version === 'string' ? doc.version : '?';
+    // An explicit `octwin status <packId>` wins, so an author who already knows the qualified
+    // id (from `octwin agents` / `octwin projects`) can skip the lookup.
+    const id = await qualifiedPackId(t, flags._[1] ?? bare);
     console.log(`→ Checking ${id}@${localVersion} on ${targetLabel(t)} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/p/packs/${id}/runtime`, {
         headers: authHeaders(t),
@@ -1179,8 +1408,16 @@ async function cmdStatus(flags) {
         json = text;
     }
     if (!res.ok) {
-        if (res.status === 404)
-            die(`'${id}' is not installed on ${targetLabel(t)} yet — run \`octwin deploy\` first`);
+        // A 404 here means one of four different things, and collapsing them into "not
+        // installed" sent one author chasing a deploy that had already succeeded. The route
+        // says which; relay it and only add the deploy hint to the case it fits.
+        if (res.status === 404) {
+            const why = typeof json === 'object' && json !== null && typeof json.error === 'string' ? json.error : text;
+            const notInstalled = /no active install|not installed/i.test(why);
+            die(notInstalled
+                ? `${why}\n  Run \`octwin deploy\` first.`
+                : `status check failed (HTTP 404) — ${why}`);
+        }
         console.error(`✗ status check failed (HTTP ${res.status})`);
         printAuthHint(res.status, url);
         console.error(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
@@ -1231,35 +1468,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 +1500,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 +1600,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 +1613,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 +1621,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 +1693,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 +1855,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)}`);
         }
@@ -1835,7 +2074,11 @@ async function cmdLogs(flags) {
         const { status, json } = await apiGet(`${base}/conversations?limit=50`, t);
         if (status !== 200)
             die(`could not read conversations (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
-        let convs = (json?.conversations ?? []);
+        // `rows` — the shared `makePage` envelope every other list command here reads. This one
+        // read `json.conversations`, a noun the route stopped emitting on 2026-08-09, so `convs`
+        // was ALWAYS empty and the command reported "No conversations yet" seconds after a chat
+        // that had plainly worked. Two pack authors filed it as a replica-lag bug; nothing lagged.
+        let convs = (json?.rows ?? []);
         if (asHandle)
             convs = convs.filter((c) => c.contact?.channel_contact_handle === asHandle);
         if (convs.length === 0) {
@@ -2233,29 +2476,32 @@ async function cmdChat(flags) {
     }
     console.log(`\n(same --as '${from}' continues this conversation — timeline: octwin logs --as ${from})`);
 }
-/** `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]`
+/** `octwin media generate "<prompt>" [--out <file.png>] [--json]`
  *  — AI-generate an image on the platform (needs a `media:generate`-scoped token),
  *  store it as a public asset, and return its `MEDIA-` handle + serve URL. `--out`
  *  downloads the bytes to a file (WhatsApp renders only `.png`/`.jpg`); the paired
- *  `octwin chat --media <file|id>` feeds it into a running media-collect flow. */
+ *  `octwin chat --media <file|id>` feeds it into a running media-collect flow.
+ *
+ *  A `--size` flag was accepted until 2026-08-10. The platform never forwarded it
+ *  to the provider, and stored resolution is decided at ingest regardless, so it
+ *  only ever changed the (fabricated) width/height the command printed back. */
 async function cmdMedia(flags) {
     const sub = flags._[0];
     if (sub !== 'generate')
-        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--json]');
     const t = resolveTarget(flags);
     const { url } = t;
     const prompt = flags._[1];
     if (!prompt)
-        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]');
+        die('usage: octwin media generate "<prompt>" [--out <file.png>] [--json]');
     const asJson = flags.json === true;
-    const size = typeof flags.size === 'string' ? flags.size : undefined;
     const out = typeof flags.out === 'string' ? flags.out : undefined;
     if (!asJson)
         console.log(`→ Generating an image on ${targetLabel(t)} @ ${url} …`);
     const res = await fetchOrDie(`${url}/api/self/p/media/generate`, {
         method: 'POST',
         headers: { 'content-type': 'application/json', ...authHeaders(t) },
-        body: JSON.stringify({ prompt, ...(size ? { size } : {}) }),
+        body: JSON.stringify({ prompt }),
     }, 'media generate');
     const text = await res.text();
     if (!res.ok) {
@@ -2284,80 +2530,96 @@ async function cmdMedia(flags) {
         }
     }
     if (asJson) {
-        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, width: r.width, height: r.height, bytes: r.bytes }));
+        console.log(JSON.stringify({ media_id: r.media_id, url: absUrl, mime: r.mime, bytes: r.bytes }));
         return;
     }
-    console.log(`✓ Generated ${r.media_ref} (${r.width}×${r.height}, ${r.mime}, ${r.bytes} bytes)`);
+    console.log(`✓ Generated ${r.media_ref} (${r.mime}, ${r.bytes} bytes)`);
     console.log(`  id:  ${r.media_id}`);
     console.log(`  url: ${absUrl}`);
     if (out)
         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.
  *
- * `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"
+ * `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 `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 +2631,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 +2673,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 +3157,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
@@ -3290,7 +3567,7 @@ async function cmdSchedulingWrite(flags) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        if (json?.has_scheduling === false) {
+        if (json?.has_data === false) {
             console.log('This pack declares no scheduling.');
             return;
         }
@@ -3365,7 +3642,7 @@ async function cmdSchedulingWrite(flags) {
     const { status, json } = await apiSend('POST', `${base}/availability/${path}`, body, t);
     if (status !== 201 && status !== 200)
         writeFail(`add the ${noun}`, status, json, url);
-    if (json?.has_scheduling === false)
+    if (json?.has_data === false)
         die('this pack declares no scheduling');
     const created = json?.rule ?? json?.exception ?? {};
     console.log(`✓ ${noun[0].toUpperCase()}${noun.slice(1)} added — ${created.id ?? '(no id returned)'}`);
@@ -3386,30 +3663,42 @@ async function cmdScheduling(flags) {
     if (flags.slots === true)
         die('usage: octwin scheduling --slots <resourceRecordId>   (the record id of a bookable resource)');
     if (resourceId) {
-        const q = new URLSearchParams({ include_booked: '1' }); // full occupancy, as the operator preview does
-        if (typeof flags.from === 'string')
-            q.set('from', flags.from);
-        if (typeof flags.days === 'string')
-            q.set('days', flags.days); // server-clamped to 1–31
+        // The range is `from`/`to`; `--days` is kept as the ergonomic flag and converted
+        // here, since a CLI user thinks in "the next 7 days".
+        const from = typeof flags.from === 'string' ? flags.from : new Date().toISOString().slice(0, 10);
+        const days = typeof flags.days === 'string' ? Math.max(Number(flags.days) || 1, 1) : 7;
+        const to = new Date(Date.parse(`${from}T00:00:00Z`) + (days - 1) * 86_400_000).toISOString().slice(0, 10);
+        const q = new URLSearchParams({ include_booked: '1', from, to }); // full occupancy, as the operator preview does
+        q.append('resource_id', resourceId);
         if (!asJson)
             console.log(`→ Computing slots for resource ${resourceId} in ${targetLabel(t)} …`);
-        const { status, json } = await apiGet(`${base}/resources/${encodeURIComponent(resourceId)}/slots?${q.toString()}`, t);
-        if (status === 404)
-            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        const { status, json } = await apiGet(`${base}/slots?${q.toString()}`, t);
         if (status === 400)
-            die(`that record isn't a bookable resource${errDetail(json)}`);
+            die(`could not compute slots${errDetail(json)}`);
         if (status !== 200)
             die(`could not compute slots (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         if (asJson) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        if (json?.has_scheduling === false) {
+        if (json?.has_data === false) {
             console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
             return;
         }
-        const slots = (json?.slots ?? []);
-        console.log(`Slots for ${resourceId} (timezone ${json?.timezone ?? '?'}): ${slots.length}`);
+        // A resource the server could not use comes back named, with a reason, rather
+        // than as an HTTP status — one call may carry several resources.
+        const bad = (json?.unresolved ?? []).find((u) => u.resource_id === resourceId);
+        if (bad?.reason === 'not_found') {
+            die(`resource '${resourceId}' not found (pass an XRM record id — \`octwin records <entity>\` lists them)`);
+        }
+        if (bad?.reason === 'not_bookable')
+            die(`that record isn't a bookable resource`);
+        const res = (json?.resources ?? [])[0];
+        const slots = (res?.slots ?? []);
+        console.log(`Slots for ${resourceId} (timezone ${res?.timezone ?? '?'} — from ${res?.timezone_source ?? '?'}): ${slots.length}`);
+        if (res?.timezone_source === 'pack_default' && json?.pack_timezone_declared === false) {
+            console.log('  ⚠ The pack declares no `timezone:`, so these are UTC — a clock nobody chose.');
+        }
         if (slots.length === 0)
             console.log('  (none — no availability rules cover this window; `octwin deploy --seed` seeds the demo rules)');
         for (const s of slots) {
@@ -3426,7 +3715,7 @@ async function cmdScheduling(flags) {
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    if (json?.has_scheduling === false) {
+    if (json?.has_data === false) {
         console.log('This pack declares no `scheduling.yaml` — nothing to schedule.');
         return;
     }
@@ -3438,254 +3727,274 @@ async function cmdScheduling(flags) {
     console.log('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
 }
 function help() {
-    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
-
-  octwin --version                                      # print the CLI version (+ any upgrade notice)
-  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
-  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
-  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
-  octwin projects [--archived] [--json]                  # the --project slugs this token can name
-  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-  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 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)
-  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
-  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
-  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 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 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
-  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-
-Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
-\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
-button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
-Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
-octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
-Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
+    console.log(`octwin ${VERSION} — Octwin external-pack developer CLI (by CEQUENS)
+
+  octwin --version                                      # print the CLI version (+ any upgrade notice)
+  octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
+  octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
+  octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  octwin status  [<packId>] [--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 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>] [--json]  # AI-generate an image → MEDIA- handle (needs media:generate scope)
+  octwin agents  [packId::agentId] [--prompt] [--json]   # effective model/memory + WHICH layer won; --prompt = the resolved system prompt
+  octwin orders  [reference_id] [--status s] [--payment p] [--json]  # the orders a conversation produced + money + payment state
+  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] [--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 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
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
+
+Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
+\`octwin chat --as <h>\` calls continue the same conversation; press a rendered
+button/row with \`--tap "<tap-id>"\` (chat prints every tap id).
+Get a deploy token: console → your workspace → Settings → API tokens → Generate (tick records:read to inspect data).
+octwin platform-kb pull → writes the platform capability reference into .octwin/platform-kb/ (for the octwin-pack skill).
+Config (deploy): flags > env (PACK_PLATFORM_URL/PACK_TENANT/PACK_PROJECT/PACK_TOKEN) > saved login (\`octwin login\` sets the default target).
 Per-command usage: octwin <command> --help`);
 }
 /** Per-subcommand usage — printed for `octwin <cmd> --help|-h` BEFORE any
  *  network/auth work (a --help that 401s is worse than no help at all). */
 const COMMAND_HELP = {
-    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
+    init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote] [--require-kb]
-  Offline structural check, plus two checks driven by the pulled capability
-  reference (render-intent fields, primitive arguments). Those two SKIP when the
-  reference is missing — the run says so, and --require-kb turns the skip into a
-  failure for CI. --remote additionally runs the platform's FULL manifest +
-  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.`,
-    login: `octwin login --url <platformUrl> --token oct_…
-  Save a deploy token (console → Settings → API tokens) for that platform url,
-  make that url the DEFAULT deploy target for every later command, and echo the
+    validate: `octwin validate [--dir .] [--remote] [--require-kb] [--strict-primitives]
+  Offline structural check, plus two checks driven by the pulled capability
+  reference (render-intent fields, primitive arguments). Those two SKIP when the
+  reference is missing — the run says so, and --require-kb turns the skip into a
+  failure for CI. --remote additionally runs the platform's FULL manifest +
+  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.
+  --strict-primitives (with --remote) additionally type-checks LITERAL args:
+  values against each primitive's declared input schema; expression strings
+  ('$found.id', '{$t(…)}') are always exempt.`,
+    login: `octwin login --url <platformUrl> --token oct_…
+  Save a deploy token (console → Settings → API tokens) for that platform url,
+  make that url the DEFAULT deploy target for every later command, and echo the
   workspace + project pin + scopes the token reaches.`,
-    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
+    whoami: `octwin whoami [--url <url>] [--tenant <slug>]
   Verify the resolved token authenticates against the tenant.`,
-    projects: `octwin projects [--archived] [--json]
-  List the workspace's projects — the slugs every --project flag takes, with the
-  plan's project cap. --archived includes archived ones. A pack:deploy token
-  reaches this (it names a project in every other command).
-
-octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
-  Create a project. The URL slug is derived from the name unless --slug pins one.
-  --pack installs an ALREADY-published pack; the usual next step is instead
-  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
-
-octwin projects rm <slug> [--yes]
-  HARD delete — the project and everything cascading from it (conversations,
-  contacts, records, installs). No undo, and not the same as archiving.
-  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
-  default. Together these make a disposable end-to-end environment:
-    octwin projects create "Scratch" && octwin deploy --project scratch --seed
-    octwin chat "hi" --project scratch
-    octwin projects rm scratch --yes
+    projects: `octwin projects [--archived] [--json]
+  List the workspace's projects — the slugs every --project flag takes, with the
+  plan's project cap. --archived includes archived ones. A pack:deploy token
+  reaches this (it names a project in every other command).
+
+octwin projects create "<name>" [--slug <slug>] [--pack <packId>]
+  Create a project. The URL slug is derived from the name unless --slug pins one.
+  --pack installs an ALREADY-published pack; the usual next step is instead
+  \`octwin deploy --project <slug>\`, which publishes this working tree and installs it.
+
+octwin projects rm <slug> [--yes]
+  HARD delete — the project and everything cascading from it (conversations,
+  contacts, records, installs). No undo, and not the same as archiving.
+  WITHOUT --yes it only previews what would be destroyed, so the dry run is the
+  default. Together these make a disposable end-to-end environment:
+    octwin projects create "Scratch" && octwin deploy --project scratch --seed
+    octwin chat "hi" --project scratch
+    octwin projects rm scratch --yes
   Both verbs need the \`projects:write\` scope — a pack:deploy token does NOT confer it.`,
-    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
-  Upload the pack bundle, validate server-side, install onto the project.
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+  Upload the pack bundle, validate server-side, install onto the project.
   --seed additionally applies the pack's demo seed (streams progress).`,
-    seed: `octwin seed [--pack <packId>]
-  Apply the pack's demo/reference data to the project it is installed on, without
-  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
-  and the demo operator topology. Reports what each kind produced.
-  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. --pack is only needed when a
+    seed: `octwin seed [--pack <packId>]
+  Apply the pack's demo/reference data to the project it is installed on, without
+  redeploying: xrm \`demo:\` records + scheduling availability, the commerce catalog,
+  and the demo operator topology. Reports what each kind produced.
+  Idempotent and safe to re-run — records upsert, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. --pack is only needed when a
   project somehow runs more than one.`,
-    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.
-
-  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>]
-    octwin records patch  <recordId> --entity <entity> --set field=value
-    octwin records stage  <recordId> --to <stage> [--note "..."]
-    octwin records note   <recordId> "the note text"
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
-  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
-  \`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
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack.
+  The pack id is read from manifest.yaml and QUALIFIED with your workspace slug
+  (a manifest declares a bare name; the owner is attached when you publish). Pass
+  <packId> explicitly to skip that lookup — \`octwin agents\` and \`octwin projects\`
+  both print the qualified form.`,
+    records: `octwin records [entity] [id] [--limit 50] [--offset n]
+  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>]
+    octwin records patch  <recordId> --entity <entity> --set field=value
+    octwin records stage  <recordId> --to <stage> [--note "..."]
+    octwin records note   <recordId> "the note text"
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
+  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
+  \`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.
-
-  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]
-
-  \`decide\` applies one of the case's declared dispositions — \`octwin cases <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\`).`,
-    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.
+    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 \`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 entity's declared operator actions — \`octwin work <id>\`
+  lists them with their params. --dry-run previews the customer-facing copy and the
+  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.
   --json = raw events (verbatim payloads).`,
-    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
-  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
-  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
-  runtime serves but nothing hands back, so its only source copy is the machine
-  that pushed it. Pull it, fix it, redeploy it.
-  Defaults to the version installed on the target project; --version overrides.
-  --dir defaults to ./<packId>; a non-empty dir needs --force.
-  The pulled dir redeploys where it came from — the target is your saved login.
+    pull: `octwin pull <packId> [--dir <out>] [--version <v>] [--force]
+  Write a DEPLOYED pack's source back to disk — the inverse of deploy.
+  A pack pushed with 'octwin deploy' lives on the platform as an artifact the
+  runtime serves but nothing hands back, so its only source copy is the machine
+  that pushed it. Pull it, fix it, redeploy it.
+  Defaults to the version installed on the target project; --version overrides.
+  --dir defaults to ./<packId>; a non-empty dir needs --force.
+  The pulled dir redeploys where it came from — the target is your saved login.
   You may pull a pack your tenant OWNS (deployed); an operator token pulls any.`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
-       octwin chat --script <file> [--as <handle>] [--json]
-  Drive ONE turn through the dev web channel and print every render with its
-  tap ids. Same --as handle = same conversation (multi-turn works).
-  --tap presses a rendered button/list row instead of sending text.
-  --media uploads a local file (or a media id from 'media generate --json') as
-  an image/document/audio inbound — any "message" rides as its caption; feeds a
-  running media-collect flow (e.g. activate-app).
-  --json dumps the raw SSE envelopes for the turn.
-
-  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
-  process over one connection — waiting for each turn to settle before sending
-  the next. Use this for any multi-step flow: chaining shell invocations races
-  the agent loop, because a turn ends on a quiet gap that can arrive while the
-  server is still working (the symptom is placeholder-filled fields or a second
-  workflow run). Blank lines and # comments are skipped:
-
-    # book an appointment end to end
-    احجز موعد
-    tap:t:invoke:book-appointment:doctor_id=D1
-    media:./licence.jpg | here is my licence
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--media <file|id>] [--json]
+       octwin chat --script <file> [--as <handle>] [--json]
+  Drive ONE turn through the dev web channel and print every render with its
+  tap ids. Same --as handle = same conversation (multi-turn works).
+  --tap presses a rendered button/list row instead of sending text.
+  --media uploads a local file (or a media id from 'media generate --json') as
+  an image/document/audio inbound — any "message" rides as its caption; feeds a
+  running media-collect flow (e.g. activate-app).
+  --json dumps the raw SSE envelopes for the turn.
+
+  --script drives a WHOLE conversation from a file, ONE TURN PER LINE, in one
+  process over one connection — waiting for each turn to settle before sending
+  the next. Use this for any multi-step flow: chaining shell invocations races
+  the agent loop, because a turn ends on a quiet gap that can arrive while the
+  server is still working (the symptom is placeholder-filled fields or a second
+  workflow run). Blank lines and # comments are skipped:
+
+    # book an appointment end to end
+    احجز موعد
+    tap:t:invoke:book-appointment:doctor_id=D1
+    media:./licence.jpg | here is my licence
     tap:t:resume:book-appointment:run_id=R1;_ctl_approved=true`,
-    media: `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]
-  AI-generate an image (needs a media:generate-scoped token), store it as a
-  public asset, and print its MEDIA- handle + serve URL. --out downloads the
-  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
-  width, height, bytes }. Pair with 'octwin chat --media' to drive media flows.`,
-    agents: `octwin agents [packId::agentId] [--prompt] [--json]
-  No args = the roster with each agent's EFFECTIVE model and which layer set it.
-  With an agent = every governed setting (model / memory.last_messages /
-  working_memory) plus the layer that won — an operator PLATFORM default can
-  override what your manifest declares, and this is where you see that.
-  --prompt = the exact system prompt the LLM sees for this project (pack
-  instructions + platform protocol + any project overlay). Needs agents:read.
-  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
-
-  WRITES (need \`agents:write\`):
-    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
-                            [--enable-tool <toolId>] [--disable-tool <toolId>]
-
-  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
-  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
+    media: `octwin media generate "<prompt>" [--out <file.png>] [--json]
+  AI-generate an image (needs a media:generate-scoped token), store it as a
+  public asset, and print its MEDIA- handle + serve URL. --out downloads the
+  bytes (WhatsApp renders only .png/.jpg); --json emits { media_id, url, mime,
+  bytes }. Pair with 'octwin chat --media' to drive media flows.`,
+    agents: `octwin agents [packId::agentId] [--prompt] [--json]
+  No args = the roster with each agent's EFFECTIVE model and which layer set it.
+  With an agent = every governed setting (model / memory.last_messages /
+  working_memory) plus the layer that won — an operator PLATFORM default can
+  override what your manifest declares, and this is where you see that.
+  --prompt = the exact system prompt the LLM sees for this project (pack
+  instructions + platform protocol + any project overlay). Needs agents:read.
+  The agent ref is the compound \`<packId>::<agentId>\` key or the override-row UUID.
+
+  WRITES (need \`agents:write\`):
+    octwin agents set <ref> [--model <m>] [--enabled true|false] [--overlay "..."|none]
+                            [--enable-tool <toolId>] [--disable-tool <toolId>]
+
+  Only what you pass is changed. Tool flags read-modify-write \`config_json.tools\`
+  so a sibling decision isn't dropped; absent = enabled. A workspace that hides model
   ids refuses --model with a 403 — the platform default governs there.`,
-    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
-  No args = the order list (#number, status/payment, total, contact). With a
-  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
-  payment_ref, and the allowed status transitions. Needs orders:read + the
-  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
-  so \`pending\` on a gateway-less workspace is expected, not a bug.
-
-  WRITES (need \`orders:write\`):
-    octwin orders transition <reference_id> --to <status>
-    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
-
-  Refund is irreversible and moves money, hence --force. The route answers 200 even
-  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
-  on a refusal rather than reporting a refund that never happened. Only a payment in
+    orders: `octwin orders [reference_id] [--status s] [--payment p] [--limit 50] [--json]
+  No args = the order list (#number, status/payment, total, contact). With a
+  reference_id = line items, the subtotal/tax/shipping/discount/total breakdown,
+  payment_ref, and the allowed status transitions. Needs orders:read + the
+  \`orders\` plan feature. Note: the forward payment lifecycle is webhook-owned,
+  so \`pending\` on a gateway-less workspace is expected, not a bug.
+
+  WRITES (need \`orders:write\`):
+    octwin orders transition <reference_id> --to <status>
+    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
+
+  Refund is irreversible and moves money, hence --force. The route answers 200 even
+  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
+  on a refusal rather than reporting a refund that never happened. Only a payment in
   \`captured\` state can be refunded; \`payment_status\` is never settable directly.`,
-    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
-  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
-  With an entity = stage-by-stage conversion (default --funnel) over the last 30
-  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
+    analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
+  No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
+  With an entity = stage-by-stage conversion (default --funnel) over the last 30
+  days. --stage <id> lists the records CURRENTLY at a stage (a live snapshot, not
   range-filtered). Needs records:read + a \`view\` grant on \`record.<entity>\`.`,
-    catalog: `octwin catalog [--readiness] [--json]
-  The commerce \`product\` records + price, availability, stock (null = not
-  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
-  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
-  catalog:read + the \`catalog\` plan feature.
-
-  WRITES (need \`catalog:write\`):
-    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
-    octwin catalog stock        <retailerId> [--set-on-hand <n>]
-
-  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
-  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
-  below the units already reserved for open carts is refused. Creating/deleting
+    catalog: `octwin catalog [--readiness] [--json]
+  The commerce \`product\` records + price, availability, stock (null = not
+  inventory-tracked) and the WhatsApp catalog binding. --readiness runs the Meta
+  Graph checklist (LIVE Graph calls; needs a bound access token). Needs
+  catalog:read + the \`catalog\` plan feature.
+
+  WRITES (need \`catalog:write\`):
+    octwin catalog availability <retailerId> --to "in stock"|"out of stock"|…
+    octwin catalog stock        <retailerId> [--set-on-hand <n>]
+
+  \`stock\` with no --set-on-hand READS it; \`null\` means the SKU is not
+  inventory-tracked (always sellable), which is different from 0. Lowering on_hand
+  below the units already reserved for open carts is refused. Creating/deleting
   products and the Meta catalog binding/sync stay in the console.`,
-    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
-  No args = the engine state (bookable resource types, upcoming slots, booked
-  seats). --slots <recordId> computes the slots for one bookable resource
-  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
-  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
-
-  RULES (list needs scheduling:read; add/rm need scheduling:write):
-    octwin scheduling rules --resource <resourceRecordId>
-    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
-                               [--slot-minutes 30] [--capacity 1]
-    octwin scheduling rule rm  <ruleId>
-    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
-                                    [--start 09:00 --end 13:00]
-    octwin scheduling exception rm  <exceptionId>
-
-  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
+    scheduling: `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]
+  No args = the engine state (bookable resource types, upcoming slots, booked
+  seats). --slots <recordId> computes the slots for one bookable resource
+  (occupancy included; --days is clamped to 1-31 server-side) — the way to verify
+  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
+
+  RULES (list needs scheduling:read; add/rm need scheduling:write):
+    octwin scheduling rules --resource <resourceRecordId>
+    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
+                               [--slot-minutes 30] [--capacity 1]
+    octwin scheduling rule rm  <ruleId>
+    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
+                                    [--start 09:00 --end 13:00]
+    octwin scheduling exception rm  <exceptionId>
+
+  --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>]
-  Pull the platform capability reference (markdown + JSON catalogs) into
-  .octwin/platform-kb/ for the octwin-pack authoring skill.`,
-    test: `octwin test [--dir .]
+    '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, 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 .]
-  Submit this pack's FEEDBACK.md to the platform team.
-  The octwin-pack skill writes that file in its last step — findings grouped by
-  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
-  you to paste it into a chat.
-  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
-  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
-  the last two to tell "the platform is wrong" from "that was already fixed" or
+    feedback: `octwin feedback [--dir .]
+  Submit this pack's FEEDBACK.md to the platform team.
+  The octwin-pack skill writes that file in its last step — findings grouped by
+  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
+  you to paste it into a chat.
+  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
+  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
+  the last two to tell "the platform is wrong" from "that was already fixed" or
   "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 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 +4031,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);