octwin-cli 0.8.15 → 0.8.17

package/dist/cli.js

@@ -13,7 +13,7 @@
  *   octwin login   --url <platformUrl> [--token oct_…]   # no token → approve in a browser
  *   octwin whoami  [--url <url>] [--tenant <slug>]
  *   octwin projects [--archived]    # the --project slugs this token can name
- *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
+ *   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed] [--force]
  *                  [--request-listing | --withdraw-listing]   # marketplace listing — opt-in, see `deploy` help
  *   octwin pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
  *   octwin status  [<packId>]       # did my deploy land? which version is live?
@@ -64,6 +64,8 @@ import { homedir, hostname, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import { applyRenames } from './lib/rename.js';
+import { packIdFromDir } from './lib/init-id.js';
+import { recipeModules, recipeStarters, planRecipe, recipeNeeds } from './lib/recipe.js';
 import { validatePackBundle, describePackNameProblem, asPackName } from './lib/validate.js';
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding, findArgWarnings, describeArgWarning, } from './lib/args-check.js';
@@ -76,9 +78,12 @@ import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from
 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 { collectJourneyIds, findJourneyViolations, describeJourneyFinding, isFlowFile } from './lib/journey-check.js';
 import { findPlatformKbDir } from './lib/kb-path.js';
 import { reportChecks } from './lib/outcome.js';
 import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
+import { BASE_FILE, deployBaseOf, hashBundle, planPull, readBase, writeBase } from './lib/base.js';
+import { formatChecksRefusal } from './lib/refusal.js';
 import { readPage, morePageHint } from './lib/page.js';
 import { chatLabel, answersTheTurn } from './lib/chat-line.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
@@ -291,6 +296,9 @@ const COMMAND_REQUIREMENTS = {
     // derived from record + journey data, and the route is gated accordingly, so the
     // Read-only token preset already reaches this.
     performance: { scope: 'records:read' },
+    charts: { scope: 'records:read', feature: 'records' },
+    handoff: { scope: 'work:read', feature: 'live_chat' },
+    surveys: { scope: 'records:read', feature: 'records' },
     // `usage` is deliberately absent: its route is `requireTenantAccess` only, so any
     // valid token reaches it. Declaring a requirement would print "needs the X scope"
     // on a failure whose real cause is an unreachable instance — the same reasoning as
@@ -914,6 +922,9 @@ function commandTouchesPlatform(command, flags) {
         case 'journeys':
         case 'performance':
         case 'usage':
+        case 'charts':
+        case 'surveys':
+        case 'handoff':
         case 'projects':
         case 'seed': return true;
         default: return false;
@@ -927,7 +938,7 @@ function cmdInit(flags) {
     // 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();
+    const id = flags.id ?? packIdFromDir(target);
     const idProblem = describePackNameProblem(id);
     if (idProblem)
         die(`${idProblem}\n  → pass --id <pack-name>`);
@@ -948,17 +959,127 @@ function cmdInit(flags) {
     // the token carries its own tenant + optional project pin.
     writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.pack-bundles/\n.octwin/\n', 'utf8');
     if (!existsSync(join(dir, 'README.md'))) {
-        writeFileSync(join(dir, 'README.md'), `# ${id}\n\nA pure-YAML pack for the Octwin platform.\n\n- \`flows/tools/home.flow.yaml\` — the menu hub (your front door); add a row + tool per journey\n- Edit \`manifest.yaml\`, \`prompts/identity.md\`\n- \`octwin validate --remote\` — full platform check before deploy\n- \`octwin deploy\` — deploy + install onto your tenant\n`, 'utf8');
+        writeFileSync(join(dir, 'README.md'), [
+            `# ${id}`, '',
+            'A pure-YAML pack for the Octwin platform, in Arabic and English.', '',
+            '- `flows/tools/home.flow.yaml` — the menu (your front door); add a row per journey',
+            '- `flows/tools/request.flow.yaml` + `xrm.yaml` — a visit request, saved as a record; replace it with your own',
+            '- `journeys/request.journey.yaml` — the funnel the owner reads on the Performance page',
+            '- `octwin platform-kb pull` — the authoring guides and recipes; start with `.octwin/platform-kb/INDEX.md`',
+            '- `octwin recipe` — list the recipes; `octwin recipe <module>` adds one to this pack',
+            '- `octwin validate` — the platform\'s full check, before every deploy',
+            '- `octwin deploy --seed` — deploy, install, and add the demo rows',
+            '',
+        ].join('\n'), 'utf8');
     }
     out.print(`✓ Scaffolded pure-YAML pack '${id}' at ${dir}`);
     out.print('\nNext:');
     out.print(`  cd ${target}`);
     out.print('  git init && git add -A && git commit -m "init pack"');
-    out.print('  # edit manifest.yaml / flows / prompts, then:');
-    out.print('  octwin validate');
-    out.print('  # point the CLI at your platform (the token carries the tenant):');
-    out.print('  octwin login --url <platformUrl> --token <deploy-token>');
-    out.print('  octwin deploy');
+    out.print('  octwin platform-kb pull      # the authoring guides + recipes — read .octwin/platform-kb/INDEX.md first');
+    out.print('  octwin recipe                # the recipes you can add; `octwin recipe <module>` writes one in');
+    out.print('  octwin validate              # the platform\'s FULL check — no login needed');
+    out.print('  # point the CLI at your platform (the token carries the tenant), then deploy with the demo rows:');
+    out.print('  octwin login --url <platformUrl>');
+    out.print('  octwin deploy --seed');
+}
+/**
+ * `octwin recipe [<module>] [--dir .] [--dry-run]` — a KB recipe's starter files into this pack.
+ *
+ * Read from the PULLED guide (`lib/recipe.ts`), so a recipe has one copy — the one the platform holds
+ * to its full deploy check together with every other recipe, on the `init` starter. Nothing is
+ * overwritten: a file the pack already has is named, and a declaration it already has (an `xrm.yaml`
+ * holding the author's own entities) gets the recipe's part printed to merge. With no module it lists
+ * the recipes the pulled KB carries.
+ */
+function cmdRecipe(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const kbDir = findPlatformKbDir(packDir)
+        ?? die('no pulled KB here or above — run `octwin platform-kb pull` first (a recipe is read from it)');
+    let index = [];
+    try {
+        index = JSON.parse(readFileSync(join(kbDir, 'index.json'), 'utf8')).index ?? [];
+    }
+    catch {
+        die(`${join(kbDir, 'index.json')} could not be read — re-run \`octwin platform-kb pull\``);
+    }
+    const modules = recipeModules(index);
+    const module = flags._[0]?.toLowerCase();
+    if (!module) {
+        if (modules.size === 0)
+            die('the pulled KB names no recipe — re-run `octwin platform-kb pull` (an older platform published none)');
+        out.print('Recipes in the pulled KB — `octwin recipe <module>` writes one into this pack:');
+        for (const [m, key] of modules)
+            out.print(`  ${m.padEnd(14)} guide:${key}#${m}-recipe`);
+        return;
+    }
+    const key = modules.get(module) ?? die(`no recipe '${module}' in the pulled KB — known: ${[...modules.keys()].join(', ')}`);
+    const starters = recipeStarters(readFileSync(join(kbDir, `${key}.md`), 'utf8'), module)
+        ?? die(`${key}.md has no '## ${module} recipe' section — re-run \`octwin platform-kb pull\``);
+    const manifestPath = join(packDir, 'manifest.yaml');
+    if (!existsSync(manifestPath))
+        die(`no manifest.yaml in ${packDir} — run this inside a pack, or pass --dir`);
+    const manifest = parseYaml(readFileSync(manifestPath, 'utf8'));
+    const { actions, flows } = planRecipe(starters, p => existsSync(join(packDir, p)), String(manifest.id ?? ''));
+    const dry = flags['dry-run'] === true;
+    out.print(`${dry ? 'Would apply' : 'Applying'} the ${module} recipe (guide:${key}#${module}-recipe) to ${packDir}`);
+    for (const a of actions) {
+        if (a.act === 'write') {
+            if (!dry) {
+                mkdirSync(dirname(join(packDir, a.path)), { recursive: true });
+                writeFileSync(join(packDir, a.path), a.body, 'utf8');
+            }
+            out.print(`  ✓ ${dry ? 'would write' : 'wrote'} ${a.path}`);
+        }
+        else if (a.act === 'exists') {
+            out.print(`  • ${a.path} already exists — left as it is (compare it with guide:${key}#${module}-starter)`);
+        }
+    }
+    for (const a of actions) {
+        if (a.act === 'merge') {
+            out.print(`\n${a.path} already exists — merge this part into it${a.note ? ` (${a.note})` : ''}:`);
+            out.print(a.body.trimEnd());
+        }
+        else if (a.act === 'manifest') {
+            out.print('\nAdd to manifest.yaml:');
+            out.print(a.body.trimEnd());
+        }
+    }
+    const listed = (v) => (Array.isArray(v) ? v.map(String) : []);
+    const newFlows = flows.filter(f => !listed(manifest.flows).includes(f));
+    const newTools = flows.filter(f => !listed(manifest.agents?.[0]?.tools).includes(f));
+    if (newFlows.length || newTools.length) {
+        out.print('\nList the new flows in manifest.yaml:');
+        if (newFlows.length)
+            out.print(`  flows:            ${newFlows.map(f => `- ${f}`).join('   ')}`);
+        if (newTools.length)
+            out.print(`  agents[0].tools:  ${newTools.map(f => `- ${f}`).join('   ')}`);
+    }
+    // What this recipe's buttons and `track:` ids need that the pack does not ship yet — other recipes,
+    // derived from their files (`recipeNeeds`). Said now, so the author does not meet the chain as one
+    // validate error after another.
+    const all = new Map();
+    for (const [m, k] of modules) {
+        const s = existsSync(join(kbDir, `${k}.md`)) ? recipeStarters(readFileSync(join(kbDir, `${k}.md`), 'utf8'), m) : null;
+        if (s)
+            all.set(m, s);
+    }
+    const journeyDir = join(packDir, 'journeys');
+    const journeys = existsSync(journeyDir)
+        ? readdirSync(journeyDir).filter(f => f.endsWith('.journey.yaml'))
+            .map(f => [`journeys/${f}`, parseYaml(readFileSync(join(journeyDir, f), 'utf8'))])
+        : [];
+    const { needs, unresolved } = recipeNeeds(module, all, {
+        flows: new Set([...listed(manifest.flows), ...flows]), journeys,
+    });
+    if (needs.length) {
+        out.print(`\nThis recipe also needs ${needs.length === 1 ? 'another recipe' : `${needs.length} other recipes`} — its buttons and \`track:\` ids name what they ship:`);
+        for (const n of needs)
+            out.print(`  octwin recipe ${n}`);
+    }
+    for (const u of unresolved)
+        out.print(`  ! ${u}`);
+    out.print(`\nThen read guide:${key}#${module}-ingredients and #${module}-rules, add the home row it names, and run \`octwin validate\`.`);
 }
 function localValidate(packDir) {
     const { files, blobs } = collectBundleFiles(packDir);
@@ -1194,6 +1315,25 @@ async function cmdValidate(flags) {
                     : { kind: 'passed', line: 'declaration files carry no unknown or missing keys (unions are left to --remote)' };
             },
         },
+        {
+            // Journey ids named by `track:` / `do: track_event`, against the pack's OWN `journeys/`.
+            // Needs no KB — the declared set is in the bundle — so it never skips. Last, because a
+            // malformed journey file is the declaration check's finding, not a wall of these.
+            label: 'journey ids',
+            run: () => {
+                const ids = collectJourneyIds(yamlDocs());
+                const findings = withLines(yamlDocs()
+                    .filter(([p]) => isFlowFile(p))
+                    .flatMap(([p, doc]) => findJourneyViolations(doc, p, ids)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'undeclared journey id',
+                        lines: findings.map(describeJourneyFinding),
+                        hint: 'fix these before deploying — the platform refuses them too, and at runtime a `track:` throws mid-conversation while `track_event` takes its `failed` port',
+                    }
+                    : { kind: 'passed', line: 'every literal journey id in `track:` / `track_event` is declared in journeys/' };
+            },
+        },
     ];
     const skipped = reportChecks(checks, {
         log: (l) => out.print(l),
@@ -1639,16 +1779,20 @@ async function cmdWhoami(flags) {
  * You may pull a pack YOUR tenant owns (an operator token may pull any). A pack
  * you merely installed from the marketplace is not yours to read.
  *
- * Writes into `<out>/` and refuses a non-empty directory unless `--force`, so it
- * can't quietly clobber local edits. The pulled directory is immediately
- * `octwin deploy`-able back to where it came from — the target is the saved
- * login, so nothing machine-specific needs to land in the pack dir.
+ * Writes into the pack folder you are standing in when it IS this pack (its
+ * `.octwin-base.json` or its manifest says so), else into `./<packId>` — `--dir`
+ * overrides. It replaces only files that still match the folder's base: a file you
+ * changed since your last pull or deploy stops it (`planPull`), unless `--force`. It
+ * then writes the new base, so the next `octwin deploy` is judged against what you
+ * pulled. The pulled directory is immediately `octwin deploy`-able back to where it
+ * came from — the target is the saved login, so nothing machine-specific needs to
+ * land in the pack dir.
  */
 async function cmdPull(flags) {
     const packId = flags._[0] ?? '';
     if (!packId)
         die('usage: octwin pull <packId> [--dir <out>] [--version <v>] [--force]');
-    const outDir = resolve(flags.dir ?? packId);
+    const outDir = pullTarget(flags, packId);
     const t = resolveTarget(flags);
     const { url } = t;
     const qs = typeof flags.version === 'string' ? `?version=${encodeURIComponent(flags.version)}` : '';
@@ -1676,8 +1820,23 @@ async function cmdPull(flags) {
     const total = Object.keys(files).length + Object.keys(blobs).length;
     if (total === 0)
         die(`${packId}@${json.version} has no files — nothing to write`);
-    if (existsSync(outDir) && readdirSync(outDir).length > 0 && flags.force !== true) {
-        die(`${outDir} is not empty — pass --force to overwrite it`);
+    // Replace only what still matches the base — never the author's own edits (`planPull`).
+    const incoming = hashBundle(files, blobs);
+    const prior = readBase(outDir);
+    const base = prior?.pack_id === json.pack_id ? prior : null;
+    const here = existsSync(outDir) ? collectBundleFiles(outDir) : { files: {}, blobs: {} };
+    const { atRisk, remove } = planPull({ local: hashBundle(here.files, here.blobs), incoming, base });
+    if (atRisk.length > 0 && flags.force !== true) {
+        out.err(`✗ ${outDir} has changes the live ${json.version} does not — pulling would overwrite them:`);
+        for (const rel of atRisk.slice(0, 15))
+            out.err(`   • ${rel}`);
+        if (atRisk.length > 15)
+            out.err(`   … and ${atRisk.length - 15} more`);
+        out.err(base
+            ? '  Save them first (git commit, or copy the folder), then pull with --force and apply them again.'
+            : `  This folder has no ${BASE_FILE} (the record of its last pull or deploy), so your edits cannot be told `
+                + 'apart from an old version. Save them first (git commit, or copy the folder), then pull with --force.');
+        exitNow(1);
     }
     for (const [rel, body] of Object.entries(files)) {
         const p = join(outDir, rel);
@@ -1689,9 +1848,35 @@ async function cmdPull(flags) {
         mkdirSync(dirname(p), { recursive: true });
         writeFileSync(p, Buffer.from(b64, 'base64'));
     }
+    // The live version no longer has these — left behind, the next deploy would bring them back.
+    for (const rel of remove)
+        rmSync(join(outDir, rel), { force: true });
+    writeBase(outDir, { pack_id: json.pack_id, version: json.version, content_sha: json.content_sha, files: incoming });
     out.print(`✓ Pulled ${json.pack_id}@${json.version} → ${outDir}`);
-    out.print(`  ${Object.keys(files).length} file(s)${Object.keys(blobs).length ? `, ${Object.keys(blobs).length} blob(s)` : ''}   content_sha ${String(json.content_sha).slice(0, 12)}…`);
-    out.print(`\nFix it, then: octwin deploy --dir ${outDir}`);
+    out.print(`  ${Object.keys(files).length} file(s)${Object.keys(blobs).length ? `, ${Object.keys(blobs).length} blob(s)` : ''}`
+        + `${remove.length ? `, ${remove.length} removed` : ''}   content_sha ${String(json.content_sha).slice(0, 12)}…`);
+    out.print(`\nFix it, then: octwin deploy${outDir === resolve('.') ? '' : ` --dir ${outDir}`}`);
+}
+/**
+ * Where `pull` writes: `--dir`, else the folder you are in when it is this pack (its base names it, or
+ * its manifest declares the pack's name — the folder a refused deploy was run from), else `./<packId>`.
+ */
+function pullTarget(flags, packId) {
+    if (typeof flags.dir === 'string')
+        return resolve(flags.dir);
+    const here = resolve('.');
+    if (readBase(here)?.pack_id === packId)
+        return here;
+    const manifest = join(here, 'manifest.yaml');
+    if (existsSync(manifest)) {
+        try {
+            const id = parseYaml(readFileSync(manifest, 'utf8'))?.id;
+            if (typeof id === 'string' && id === packId.slice(packId.indexOf('.') + 1))
+                return here;
+        }
+        catch { /* not a manifest we can read — not this pack */ }
+    }
+    return resolve(packId);
 }
 /**
  * Read the deploy SSE stream, printing each progress frame's message live, and
@@ -1849,6 +2034,9 @@ function printDeploySuccess(id, version, t, r, listing, problems = 0) {
     out.print(problems > 0
         ? `⚠ Deployed ${id}@${version} onto ${targetLabel(t)} WITH ${problems} failure(s) — data may be incomplete`
         : `✓ Deployed ${id}@${version} and installed onto ${targetLabel(t)}`);
+    if (r?.forced_over) {
+        out.print(`  ⚠ --force replaced ${r.forced_over === 'downgrade' ? 'a higher live version' : 'a version someone else published after your copy'}.`);
+    }
     if (r?.warning)
         out.print(`  ⚠ ${r.warning}`);
     // This read `r.summary.records` / `.rules` / `.failed` and had been DEAD: the deploy route's
@@ -1908,7 +2096,7 @@ async function cmdSeed(flags) {
         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.
-            out.err(`
+            out.err(`
 ⚠ ${stepErrors.length} step${stepErrors.length === 1 ? '' : 's'} failed — data may be incomplete:`);
             for (const e of stepErrors)
                 out.err(`   • ${e}`);
@@ -1954,7 +2142,12 @@ async function cmdDeploy(flags) {
     const endpoint = `${url}/api/self/p/packs/deploy`;
     const seed = flags.seed === true;
     const listing = resolveListingFlags(flags);
-    const extras = [seed ? 'with demo seed' : null, listing ? LISTING_LABEL[listing] : null].filter(Boolean);
+    // What this copy was made from: the platform refuses when someone published since (`live_moved`).
+    const base = deployBaseOf(readBase(packDir));
+    const force = flags.force === true;
+    const extras = [
+        seed ? 'with demo seed' : null, listing ? LISTING_LABEL[listing] : null, force ? 'forced over any newer live version' : null,
+    ].filter(Boolean);
     out.print(`→ Deploying ${id}@${version} (${Object.keys(files).length} files) to ${targetLabel(t)}${extras.length ? ` — ${extras.join(', ')}` : ''} …`);
     const res = await fetchOrDie(endpoint, {
         method: 'POST',
@@ -1963,7 +2156,9 @@ async function cmdDeploy(flags) {
         headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...authHeaders(t) },
         // `listing` is omitted entirely unless asked for: an ordinary deploy says NOTHING about the
         // marketplace, which is what keeps a test loop out of the operator review queue.
-        body: JSON.stringify({ files, blobs, seed, ...(listing ? { listing } : {}) }),
+        body: JSON.stringify({
+            files, blobs, seed, ...(listing ? { listing } : {}), ...(base ? { base } : {}), ...(force ? { force: true } : {}),
+        }),
     }, 'deploy');
     // Streaming path — live install + seed progress (image generation can take a
     // while, so `--seed` prints per-record / per-image lines as they happen).
@@ -1971,6 +2166,7 @@ async function cmdDeploy(flags) {
         const { terminal: final, stepErrors } = await readDeployProgress(res.body);
         if (!final || final.stage === 'error')
             die(`deploy failed${final?.message ? `: ${final.message}` : ' (stream ended early)'}`);
+        rememberDeploy(packDir, final, files, blobs);
         // The count goes IN, so the headline itself carries the verdict. It used to be
         // printed underneath a `✓ Deployed` line, which is what a reporting author read.
         printDeploySuccess(id, version, t, final, { intent: listing, packDir }, stepErrors.length);
@@ -1996,11 +2192,28 @@ async function cmdDeploy(flags) {
         json = text;
     }
     if (!res.ok) {
+        // Someone published since this copy was made, or it is an older version: nothing changed on the
+        // platform. The message says what happened and the way out (pull, or --force) — print it as words.
+        if (res.status === 409 && (json?.code === 'live_moved' || json?.code === 'downgrade')) {
+            out.err(`✗ ${json.error}`);
+            if (json.code === 'live_moved' && typeof flags.dir === 'string') {
+                out.err(`  This copy is in ${flags.dir} — add \`--dir ${flags.dir}\` to the pull.`);
+            }
+            exitNow(1);
+        }
+        // The checks refused it: say what keeps running, then what to fix (`formatChecksRefusal`).
+        const refusal = res.status === 400 ? formatChecksRefusal(json) : null;
+        if (refusal) {
+            for (const line of refusal)
+                out.err(line);
+            exitNow(1);
+        }
         out.err(`✗ deploy failed (HTTP ${res.status})`);
         printAuthHint(res.status, url);
         out.err(typeof json === 'string' ? json : JSON.stringify(json, null, 2));
         exitNow(1);
     }
+    rememberDeploy(packDir, json, files, blobs);
     // This path had NO step-error check at all. With no SSE frames to read, the only
     // evidence a seed kind threw is `seed_failed` in the body — so a broken seed printed
     // a clean `✓ Deployed` here even after the streaming path was fixed in 0.1.14.
@@ -2013,6 +2226,15 @@ async function cmdDeploy(flags) {
         exitNow(1);
     }
 }
+/**
+ * After a deploy: this folder's new base is what the project now runs. Written even when a seed step
+ * failed — the pack itself IS installed. A platform too old to report `content_sha` leaves the base alone.
+ */
+function rememberDeploy(packDir, r, files, blobs) {
+    if (typeof r?.content_sha !== 'string' || typeof r?.pack_id !== 'string' || typeof r?.version !== 'string')
+        return;
+    writeBase(packDir, { pack_id: r.pack_id, version: r.version, content_sha: r.content_sha, files: hashBundle(files, blobs) });
+}
 /**
  * The QUALIFIED pack id (`<owner>.<name>`) for a manifest's bare name.
  *
@@ -2092,6 +2314,13 @@ async function cmdStatus(flags) {
     const shortSha = (s) => (typeof s === 'string' && s ? s.slice(0, 12) + '…' : '(none)');
     out.print(`  live on instance  : registered=${json.registered}  loaded=${shortSha(json.loaded_content_sha)}`);
     out.print(`  catalog artifact  : ${shortSha(json.catalog_content_sha)}${json.origin ? `  origin=${json.origin}` : ''}`);
+    // The copy on disk against what runs: the question a deploy is about to be judged on (`live_moved`).
+    const base = readBase(packDir);
+    out.print(`  your copy         : ${!base || base.pack_id !== id
+        ? `no ${BASE_FILE} — run \`octwin pull ${id}\` once, so a deploy can tell when someone else published`
+        : base.content_sha === json.catalog_content_sha
+            ? `from ${base.version} (${shortSha(base.content_sha)}) — the live content`
+            : `from ${base.version} (${shortSha(base.content_sha)}) — the live content MOVED since; run \`octwin pull ${id}\` before you deploy`}`);
     out.print(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
     // Every line above is process-global — `registered` is true for a pack ANY
     // project on this instance loaded. `dispatches` is the project-scoped answer to
@@ -2322,9 +2551,10 @@ async function cmdPlatformKb(flags) {
         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');
+    writeFileSync(join(outDir, 'index.json'), JSON.stringify({ version: bundle.version, content_hash: bundle.content_hash, generated_at: bundle.generated_at, platform_version: bundle.platform_version, index: bundle.index }, null, 2) + '\n', 'utf8');
     out.print(`✓ Pulled the Octwin platform KB → ${outDir}`);
-    out.print(`  ${mdCount} markdown docs + ${catalogCount} catalogs (${entryCount} entries, one file each) — reference version ${bundle.version ?? '?'}`);
+    out.print(`  ${mdCount} markdown docs + ${catalogCount} catalogs (${entryCount} entries, one file each) — reference version ${bundle.version ?? '?'}`
+        + `, published by platform ${bundle.platform_version ?? 'unknown'}`);
     out.print(`  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) {
@@ -4092,12 +4322,15 @@ async function cmdAgents(flags) {
  *  docs/BACKLOG.md → "Headless payment settle" (a `--settle` flag lands here once
  *  the platform grows a manual-driver-only reconcile endpoint). */
 function printPaymentNote(paymentStatus) {
-    if (paymentStatus !== 'pending' && paymentStatus !== 'none')
-        return;
-    out.print(`  → payment_status '${paymentStatus}' is expected without a live gateway: the forward payment`);
-    out.print('    lifecycle is WEBHOOK-owned (not patchable), and the default `manual` driver has no hosted');
-    out.print('    checkout — so `payment_request` takes its `empty` port and the flow should offer');
-    out.print('    pay-on-delivery. Refund is the one operator-driven move.');
+    if (paymentStatus === 'none') {
+        out.print("  → payment_status 'none': no payment was opened. Without a hosted-checkout gateway");
+        out.print('    `payment_request` takes its `empty` port and leaves the order alone — the flow should offer');
+        out.print('    pay-on-delivery. Refund is the one operator-driven move.');
+    }
+    else if (paymentStatus === 'pending') {
+        out.print("  → payment_status 'pending': a checkout was opened and the gateway's webhook has not");
+        out.print('    confirmed it yet. The forward payment lifecycle is WEBHOOK-owned (not patchable).');
+    }
 }
 /** `octwin orders [referenceId] [--status s] [--payment p] [--limit n] [--json]` —
  *  the orders a conversation created: money breakdown, payment state, allowed
@@ -4108,8 +4341,8 @@ const ORDER_VERBS = new Set(['transition', 'refund']);
  * The write half of `octwin orders` — fulfilment transitions and refunds.
  *
  * `payment_status` is deliberately NOT settable: the forward payment lifecycle is
- * webhook-owned, which is why `pending` on a gateway-less workspace is expected
- * rather than a bug (`printPaymentNote`).
+ * webhook-owned: `none` is an order no payment was opened for (no gateway), `pending` one whose
+ * checkout the gateway has not confirmed yet (`printPaymentNote`).
  */
 async function cmdOrdersWrite(flags) {
     const t = resolveTarget(flags);
@@ -4700,7 +4933,7 @@ async function cmdScheduling(flags) {
  *
  * `pause` / `resume` rather than a literal `status active|paused`: the route body
  * takes the status, but the RBAC layer it calls checks the ACTION
- * (`assertCan(…, action: 'pause' | 'resume')`), and `VERB_REQUIREMENTS` is keyed
+ * (`assertMay(…, action: 'pause' | 'resume')`), and `VERB_REQUIREMENTS` is keyed
  * per verb — so one verb per intent makes both the permission hint and the 403
  * say the right thing.
  */
@@ -4800,11 +5033,26 @@ async function cmdAutomationWrite(flags) {
         return;
     }
     const r = json?.result ?? {};
-    out.print(`✓ campaign '${typed}': matched ${r.matched ?? 0}, enqueued ${r.enqueued ?? 0}`);
-    if ((r.enqueued ?? 0) < (r.matched ?? 0))
-        out.print('  partial: some matched contacts were not enqueued (cooldown, or no reachable channel)');
+    const already = Number(r.already_queued ?? 0);
+    out.print(`✓ campaign '${typed}': matched ${r.matched ?? 0}, enqueued ${r.enqueued ?? 0}${already ? `, ${already} already had it` : ''}  [${r.stage ?? '?'}]`);
+    // A campaign that stopped half-way is FINISHED by the same command: it queues only the contacts
+    // with no delivery yet, so `already` is the earlier send's work, not a skip.
+    if (already)
+        out.print('  finished an earlier send — each contact gets this campaign once');
+    if ((r.enqueued ?? 0) + already < (r.matched ?? 0))
+        out.print('  partial: some matched records were not enqueued (records sharing a contact, or a record with none)');
     out.print('  enqueued ≠ delivered — watch the sends land with `octwin logs`');
 }
+/**
+ * A campaign's delivery progress — the per-status counts of the reminders it queued. Not sent yet
+ * (a draft) is all zeros, and reads as a dash rather than "sent 0".
+ */
+function campaignProgressLine(p) {
+    const n = (k) => Number(p?.[k] ?? 0);
+    if (n('sent') + n('failed') + n('pending') + n('cancelled') === 0)
+        return '—'.padEnd(28);
+    return `sent ${n('sent')} · failed ${n('failed')} · pending ${n('pending')}${n('cancelled') ? ` · cancelled ${n('cancelled')}` : ''}`.padEnd(28);
+}
 /**
  * `octwin automation [--campaigns] [--json]` — the jobs a pack's declarations
  * produced, with their last result, plus the health counts.
@@ -4838,15 +5086,17 @@ async function cmdAutomation(flags) {
         const page = readPage(json);
         out.print(`Campaigns in ${targetLabel(t)}: ${page.total ?? page.rows.length}`);
         if (page.rows.length === 0)
-            out.print('  (none — a campaign comes from a `campaigns:` block in the pack\'s automation declaration)');
+            out.print('  (none — a flow drafts one with the `campaign_create` step)');
+        // What the route returns, field for field: `{ id, record_number, name, entity, stage, progress }`.
+        // It read `label` / `key` / `audience_size` / `matched` until 2026-10-11 — none of which a campaign
+        // row carries — so every row printed its uuid twice and "—".
         for (const c of page.rows) {
-            const label = pickLabel(c.label) ?? c.key ?? c.id;
-            out.print(`  ${String(label).padEnd(28)} ${String(c.audience_size ?? c.matched ?? '—').padStart(6)} contact(s)  ${c.key ?? c.id}`);
+            out.print(`  ${`#${c.record_number ?? '?'}`.padEnd(6)} ${String(c.name ?? '(no name)').padEnd(28)} ${String(c.stage ?? '—').padEnd(9)} ${campaignProgressLine(c.progress)}  ${c.id}`);
         }
         const more = morePageHint(page, 'octwin automation campaigns');
         if (more)
             out.print(more);
-        out.print('\nSend one:  octwin automation send <campaignId>   (needs automation:write)');
+        out.print('\nSend a draft, or finish one stuck at `sending`:  octwin automation send <campaignId>   (needs automation:write; each contact gets it once)');
         return;
     }
     if (!asJson)
@@ -4864,7 +5114,7 @@ async function cmdAutomation(flags) {
     const page = readPage(jobs.json);
     const h = health.status === 200 ? (health.json ?? {}) : {};
     out.print(`Automation in ${targetLabel(t)}: ${h.total ?? page.rows.length} job(s)`
-        + `  —  ${h.active ?? '?'} active, ${h.paused ?? '?'} paused, ${h.failing ?? '?'} failing, ${h.never_ran ?? '?'} never ran`);
+        + `  —  ${h.active ?? '?'} active, ${h.paused ?? '?'} paused, ${h.failing ?? '?'} failing, ${h.never_checked ?? '?'} never checked`);
     if (page.rows.length === 0) {
         out.print('  (none — jobs are DERIVED from the pack\'s automation declaration, not created here.');
         out.print('   No `automation.yaml` block → no jobs. `octwin deploy` installs them.)');
@@ -4872,7 +5122,9 @@ async function cmdAutomation(flags) {
     }
     for (const j of page.rows) {
         const r = j.last_result ?? {};
-        const ran = j.last_run_at ? `last ${j.last_run_at}` : 'never ran';
+        // A job runs only when its look finds work, so "not run yet" is normal; "never checked" is the dead one.
+        const ran = (j.last_run_at ? `last run ${j.last_run_at}` : 'not run yet')
+            + (j.last_checked_at ? `, checked ${j.last_checked_at}` : ', never checked');
         const result = j.last_result
             ? `  matched ${r.matched ?? 0}/acted ${r.acted ?? 0}${(r.errors ?? 0) > 0 ? `/ERRORS ${r.errors}` : ''}`
             : '';
@@ -5334,8 +5586,214 @@ async function cmdJourneys(flags) {
 }
 // ── performance: the project's business indicators ──────────────────────────
 /**
- * `octwin performance [--detail] [--json]` — the indicators the project's own
- * declarations produce: value, conversion, duration, per journey.
+ * `octwin charts [<key>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--json]` — the pack's own `charts:`
+ * (xrm.yaml), as the owner's dashboard draws them: the list, or one chart's figure, parts or points.
+ * Needs `records:read`; a `view` grant on each chart's entity decides which ones the token sees.
+ */
+async function cmdCharts(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/xrm/charts`;
+    const key = flags._[0];
+    const asJson = flags.json === true;
+    if (!key) {
+        if (!asJson)
+            out.print(`→ Reading the pack's charts from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}`, t);
+        if (status !== 200)
+            die(`could not read charts (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            out.result(json);
+            return;
+        }
+        const charts = (json?.charts ?? []);
+        if (charts.length === 0) {
+            out.print('No charts — a pack declares them under `charts:` in xrm.yaml (craft-measure, "Your own charts"), or this token may not view their entities.');
+            return;
+        }
+        for (const c of charts)
+            out.print(`  ${c.key.padEnd(24)} ${(pickLabel(c.label) ?? c.key).padEnd(32)} ${c.show} · ${c.entity}`);
+        out.print('\n`octwin charts <key>` draws one.');
+        return;
+    }
+    const q = new URLSearchParams();
+    if (typeof flags.from === 'string')
+        q.set('from', flags.from);
+    if (typeof flags.to === 'string')
+        q.set('to', flags.to);
+    const qs = q.toString() ? `?${q}` : '';
+    if (!asJson)
+        out.print(`→ Reading chart '${key}' from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(key)}${qs}`, t);
+    if (status !== 200)
+        die(`could not read chart '${key}' (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        out.result(json);
+        return;
+    }
+    if (json?.has_data !== true) {
+        out.print(`No figure for '${key}' — its entity has no records in this window, or this token may not view it.`);
+        return;
+    }
+    const c = json.chart;
+    out.print(`${pickLabel(c.label) ?? c.key}   ${json.range?.from ?? '?'} → ${json.range?.to ?? '?'}`);
+    if (c.value !== undefined)
+        out.print(`  ${c.value ?? '—'}${c.ratio ? `   (${c.ratio.of ?? '—'} ÷ ${c.ratio.per ?? '—'})` : ''}`);
+    for (const p of c.parts ?? [])
+        out.print(`  ${String(pickLabel(p.label) ?? p.key).padEnd(28)} ${String(p.value ?? '—').padStart(10)}   n=${p.count}`);
+    if (c.cut)
+        out.print(`  … top ${c.cut.kept} of ${c.cut.groups}${c.cut.other ? `; the rest: ${c.cut.other.value ?? '—'} (n=${c.cut.other.count})` : ''}`);
+    for (const p of c.points ?? [])
+        out.print(`  ${String(p.bucket).padEnd(12)} ${String(p.value ?? '—').padStart(10)}   n=${p.count}`);
+}
+/**
+ * `octwin handoff [<id>] [--bucket waiting|mine|all|ended] [--limit n] [--offset n] [--json]` — the
+ * Live chat desk, READ-ONLY: the handoffs in a bucket, or one with its transcript (who said what —
+ * customer, AI Agent, operator, platform). Needs `work:read` and the `live_chat` plan feature.
+ *
+ * Accepting, answering and returning a handoff stay in the console: those routes need a signed-in
+ * PERSON to hold the conversation (`accepting needs a signed-in person`), and a token is not one.
+ */
+async function cmdHandoff(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/handoff`;
+    const id = flags._[0];
+    const asJson = flags.json === true;
+    if (!id) {
+        const q = new URLSearchParams();
+        if (typeof flags.bucket === 'string')
+            q.set('bucket', flags.bucket);
+        if (flags.limit !== undefined)
+            q.set('limit', String(flags.limit));
+        if (flags.offset !== undefined)
+            q.set('offset', String(flags.offset));
+        const qs = q.toString() ? `?${q}` : '';
+        if (!asJson)
+            out.print(`→ Reading the Live chat desk from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}${qs}`, t);
+        if (status !== 200)
+            die(`could not read the Live chat desk (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            out.result(json);
+            return;
+        }
+        if (json?.has_data === false) {
+            out.print(`No Live chat on this project — ${json?.reason ?? 'the pack works no handoff'} (craft-escalation, the Handoff recipe).`);
+            return;
+        }
+        const rows = (json?.rows ?? []);
+        if (rows.length === 0) {
+            out.print('No handoffs in this view (--bucket waiting|mine|all|ended).');
+            return;
+        }
+        for (const r of rows) {
+            const who = r.contact?.display_name ?? r.contact?.channel_contact_handle ?? '—';
+            out.print(`  #${String(r.handoff_number).padEnd(5)} ${r.stage.padEnd(10)} ${String(r.channel ?? '—').padEnd(9)} ${(pickLabel(r.queue?.name) ?? r.queue_key ?? '—').padEnd(18)} ${who}   ${r.id}`);
+        }
+        out.print('\n`octwin handoff <id>` shows one with its transcript.');
+        return;
+    }
+    if (!asJson)
+        out.print(`→ Reading handoff ${id} from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(id)}`, t);
+    if (status !== 200)
+        die(`could not read handoff ${id} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        out.result(json);
+        return;
+    }
+    const h = json?.handoff ?? {};
+    out.print(`Handoff #${h.handoff_number ?? '?'} — ${h.stage ?? '?'}${h.queue_key ? ` · queue ${h.queue_key}` : ''}${h.reason ? ` · ${h.reason}` : ''}`);
+    if (h.summary)
+        out.print(`  ${h.summary}`);
+    for (const line of (json?.transcript ?? [])) {
+        out.print(`  ${String(line.ts).slice(11, 16)}  ${line.role === 'operator' && line.author ? `operator: ${line.author}` : line.role}  ${line.body}`);
+    }
+    if (json?.has_more)
+        out.print('  … earlier lines in the console (Live chat).');
+}
+/**
+ * `octwin surveys [<key>] [--limit n] [--offset n] [--json]` — the declared surveys with their
+ * standing (responses, the headline score under its model), or one survey: its questions, the
+ * rollup and the recent responses. The same reads as the console's Surveys page. Needs `records:read`.
+ */
+async function cmdSurveys(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/surveys`;
+    const key = flags._[0];
+    const asJson = flags.json === true;
+    const score = (s) => s?.value == null ? '—' : `${s.value}${s.unit === 'pct' ? '%' : ''} (${s.model})`;
+    if (!key) {
+        if (!asJson)
+            out.print(`→ Reading surveys from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}`, t);
+        if (status !== 200)
+            die(`could not read surveys (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+        if (asJson) {
+            out.result(json);
+            return;
+        }
+        const rows = (json?.rows ?? []);
+        if (rows.length === 0) {
+            out.print('No surveys — a pack declares them in surveys.yaml (craft-surveys).');
+            return;
+        }
+        for (const r of rows)
+            out.print(`  ${r.key.padEnd(22)} ${(pickLabel(r.label) ?? r.key).padEnd(30)} responses ${String(r.responses ?? '—').padStart(5)}   score ${score(r.score)}`);
+        out.print('\n`octwin surveys <key>` shows one — its questions, rollup and recent answers.');
+        return;
+    }
+    const q = new URLSearchParams();
+    if (flags.limit !== undefined)
+        q.set('limit', String(flags.limit));
+    if (flags.offset !== undefined)
+        q.set('offset', String(flags.offset));
+    const qs = q.toString() ? `?${q}` : '';
+    if (!asJson)
+        out.print(`→ Reading survey '${key}' from ${targetLabel(t)} …`);
+    const { status, json } = await apiGet(`${base}/${encodeURIComponent(key)}${qs}`, t);
+    if (status !== 200)
+        die(`could not read survey '${key}' (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        out.result(json);
+        return;
+    }
+    const sv = json?.survey ?? {};
+    const a = json?.analytics;
+    out.print(`${pickLabel(sv.label) ?? key}${sv.subject ? `   about: ${sv.subject}` : ''}`);
+    for (const qq of sv.questions ?? [])
+        out.print(`  • ${qq.key} (${qq.type}${qq.required ? ', required' : ''})`);
+    out.print(a ? `  responses ${a.responses} · scored ${a.scored} · score ${score(a.score)}` : '  rollup unavailable — the pack has not loaded on this project');
+    const rows = (json?.responses?.rows ?? []);
+    for (const r of rows)
+        out.print(`  ${String(r.created_at).slice(0, 16)}  score ${r.score ?? '—'}  ${JSON.stringify(r.answers)}`);
+}
+/**
+ * `--range <days>` and `--channel <whatsapp|web>` as the route's own `?range=` / `?channel=` — the
+ * console's two controls. Until 2026-10-11 the CLI read only `--detail`, so `--channel web` printed
+ * the all-channel band as if it were the web's (an unknown flag was ignored then, not refused).
+ */
+function performanceQuery(flags) {
+    const p = new URLSearchParams();
+    if (flags.range !== undefined) {
+        const days = Number(flags.range);
+        if (!Number.isInteger(days) || days <= 0)
+            die('--range takes a whole number of days, e.g. --range 30');
+        p.set('range', String(days));
+    }
+    if (flags.channel !== undefined) {
+        if (typeof flags.channel !== 'string')
+            die('--channel takes a channel name, e.g. --channel whatsapp');
+        p.set('channel', flags.channel);
+    }
+    const s = p.toString();
+    return s ? `?${s}` : '';
+}
+/**
+ * `octwin performance [--detail] [--range <days>] [--channel <ch>] [--json]` — the indicators the
+ * project's own declarations produce: value, conversion, duration, per journey.
  *
  * Needs `records:read` — **not** a `performance:*` scope, which does not exist.
  * That means the Read-only token preset already reaches this.
@@ -5351,9 +5809,10 @@ async function cmdPerformance(flags) {
     // Two explicit calls rather than `apiGet(detail ? … : base)`: the route guard's
     // extractor only reads a template literal in the FIRST argument position, so a
     // ternary hides both URLs from it.
+    const qs = performanceQuery(flags);
     const { status, json } = detail
-        ? await apiGet(`${base}/detail`, t)
-        : await apiGet(`${base}`, t);
+        ? await apiGet(`${base}/detail${qs}`, t)
+        : await apiGet(`${base}${qs}`, t);
     if (status !== 200)
         die(`could not read performance (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     if (asJson) {
@@ -5373,14 +5832,24 @@ async function cmdPerformance(flags) {
         out.print('  (none)');
     for (const i of inds) {
         const unit = i.unit === 'pct' ? '%' : '';
-        // `delta_pct` is signed and against the PREVIOUS window — sign it explicitly so
-        // a fall is never read as a rise.
-        const delta = i.delta_pct == null ? '' : `  ${i.delta_pct >= 0 ? '+' : ''}${i.delta_pct}% vs prev`;
+        // `change` is the band's ONE change rule, already derived by the platform: a relative % for
+        // a count, money or duration, POINTS for a rate, score or NPS (a % of a % misleads), and
+        // signed the way the number moved — sign it explicitly so a fall is never read as a rise.
+        const c = i.change ?? { kind: 'none' };
+        const sign = (n) => `${n > 0 ? '+' : ''}${n}`;
+        const delta = c.kind === 'relative' ? `  ${sign(c.pct)}% vs prev`
+            : c.kind === 'points' ? `  ${sign(c.delta)}${i.unit === 'pct' ? ' pts' : ''} vs prev`
+                : c.kind === 'from_zero' ? '  new vs prev'
+                    : c.kind === 'flat' ? '  no change vs prev'
+                        : '';
         const frac = i.numerator != null && i.denominator != null
             ? `  (${i.numerator}/${i.denominator}${i.denominator_of ? ` ${i.denominator_of}` : ''})`
             : '';
+        // A band narrowed to one channel says so per figure: one that cannot be narrowed (capacity) is
+        // the all-channel figure, and the line says it rather than letting it pass as the channel's.
+        const scope = i.channel?.kind === 'not_narrowable' ? '  (all channels)' : '';
         out.print(`  ${String(pickLabel(i.heading) ?? i.kind).padEnd(16)} ${String(pickLabel(i.label) ?? '').padEnd(20)}`
-            + ` ${String(i.value ?? '—').padStart(9)}${unit}${delta}${frac}`);
+            + ` ${String(i.value ?? '—').padStart(9)}${unit}${delta}${frac}${scope}`);
         if (i.why)
             out.print(`      why: ${i.why}`);
         if (i.biggest_dropoff)
@@ -5456,427 +5925,461 @@ async function cmdUsage(flags) {
     out.print('\nThis is MODEL spend. WhatsApp/Meta message billing is operator-only — not reachable by an API token.');
 }
 function help() {
-    out.print(`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 | --offline] [--require-kb]   # the platform's FULL check by default — no login needed
-  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
-  octwin login   --url <platformUrl> --token oct_…      # or paste 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]
-                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
-  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] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
-                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
-  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
-  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--press <label>] [--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 automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
-  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
-  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
-  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
-  octwin performance [--detail] [--json]                 # the project's business indicators (value/conversion/duration)
-  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
-  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
-  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
-
-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> "…", archive|restore <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]
-  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
-  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
-  octwin integrations retry|cancel|send-now <deliveryId>
-  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
-
-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), or by its label with
-\`--press "<label>"\` — the way through a form or checkout, whose ids change.
-Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
-scopes instead, mint a 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).
+    out.print(`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 recipe  [<module>] [--dir .] [--dry-run]       # a KB recipe's starter files into this pack (no module = the list)
+  octwin validate [--dir .] [--remote | --offline] [--require-kb] [--strict-primitives]   # the platform's FULL check by default — no login needed
+  octwin login   --url <platformUrl>                    # approve in a browser; the CLI collects the token
+  octwin login   --url <platformUrl> --token oct_…      # or paste 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 projects create "<name>" [--slug s] [--pack p] | rm <slug> [--yes]   # a disposable project (needs projects:write)
+  octwin seed    [--reset] [--pack <packId>]             # apply the pack's demo data without redeploying
+  octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed] [--force]
+                 [--request-listing | --withdraw-listing]   # public marketplace — opt-in, see: octwin help deploy
+  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] [--unrouted] [--json]  # inspect the work inbox (worked records) + timelines
+                 #   --queues: per-queue open counts + an UNROUTED warning · --unrouted: only the items in no queue
+  octwin logs    [conversationId] [--as <handle>] [--json]  # list conversations / show one's event timeline
+  octwin chat    "message" [--as <handle>] [--tap <tap-id>] [--press <label>] [--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 automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
+  octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
+  octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
+  octwin performance [--detail] [--range <days>] [--channel <ch>] [--json]   # the project's business indicators (value/conversion/duration)
+  octwin usage   [--json]                                # model calls, tokens and cost (project if pinned, else workspace)
+  octwin charts  [<key>] [--from d] [--to d] [--json]    # the pack's own charts: — the list, or one chart's figure
+  octwin handoff [<id>] [--bucket waiting|mine|all|ended] [--limit n] [--offset n] [--json]   # the Live chat desk, read-only
+  octwin surveys [<key>] [--limit n] [--offset n] [--json]   # surveys with their score; one survey's questions, rollup, answers
+  octwin platform-kb [pull] [--if-stale|--check] [--dir .] [--url <url>]  # no token needed
+  octwin test    [--dir .] [--require-kb] [--strict-primitives]   # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+  octwin memos   [--all] [--json]                        # read the platform's replies + notices (a reply to your feedback lands here)
+
+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> "…", archive|restore <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]
+  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin integrations test <key>                         # a LIVE call to the connection's health: operation
+  octwin integrations retry|cancel|send-now <deliveryId>
+  (octwin integrations preflight <key> needs only integrations:read — it makes no call)
+
+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), or by its label with
+\`--press "<label>"\` — the way through a form or checkout, whose ids change.
+Signing in: \`octwin login --url <u>\` prints a link + code to approve in a browser. To pick your own
+scopes instead, mint a 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 | --offline] [--require-kb] [--strict-primitives]
-  First the fast OFFLINE checks (structure, YAML, and the checks driven by the
-  pulled capability reference — those SKIP when the reference is missing, and
-  --require-kb turns the skip into a failure for CI). Then, BY DEFAULT, the
-  platform's FULL validation — the same check deploy runs, all errors at once.
-
-  The full check needs NO login: without a token + --project it goes to the
-  platform's public validate route. With a token AND --project (or PACK_PROJECT)
-  it goes through your workspace, which also confirms that project exists.
-
-  When the platform cannot be reached (no url, offline, rate-limited) the run
-  ends with "only the OFFLINE check ran — a PARTIAL check" and exits 0.
-  --remote REQUIRES the full check: not reaching it is an error. --offline runs
-  only the partial subset. --strict-primitives additionally type-checks LITERAL
-  args: values against each primitive's declared input schema; expression
+    validate: `octwin validate [--dir .] [--remote | --offline] [--require-kb] [--strict-primitives]
+  First the fast OFFLINE checks (structure, YAML, and the checks driven by the
+  pulled capability reference — those SKIP when the reference is missing, and
+  --require-kb turns the skip into a failure for CI). Then, BY DEFAULT, the
+  platform's FULL validation — the same check deploy runs, all errors at once.
+
+  The full check needs NO login: without a token + --project it goes to the
+  platform's public validate route. With a token AND --project (or PACK_PROJECT)
+  it goes through your workspace, which also confirms that project exists.
+
+  When the platform cannot be reached (no url, offline, rate-limited) the run
+  ends with "only the OFFLINE check ran — a PARTIAL check" and exits 0.
+  --remote REQUIRES the full check: not reaching it is an error. --offline runs
+  only the partial subset. --strict-primitives 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_…] [--wait <seconds>] [--json]
-  Sign in to a platform and make that url the DEFAULT deploy target for every
-  later command.
-
-  WITH --token: saves a token you minted yourself (console → Settings → API
-  tokens). Unchanged, and still the right answer for CI — there, skip login and
-  set PACK_PLATFORM_URL + PACK_TOKEN instead.
-
-  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
-  it, checks which machine is asking, and clicks Approve; the CLI then collects a
-  30-day token by itself, so no token is ever pasted between people. The code is
-  printed too — it is what the page shows, so you can tell it is your own request.
-  Approve only a link you opened because YOU ran this command: a link someone
-  sends you would connect THEIR machine to your workspace.
-
-  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
-  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
+    login: `octwin login --url <platformUrl> [--token oct_…] [--wait <seconds>] [--json]
+  Sign in to a platform and make that url the DEFAULT deploy target for every
+  later command.
+
+  WITH --token: saves a token you minted yourself (console → Settings → API
+  tokens). Unchanged, and still the right answer for CI — there, skip login and
+  set PACK_PLATFORM_URL + PACK_TOKEN instead.
+
+  WITHOUT --token: prints a link to approve in a browser. A workspace admin opens
+  it, checks which machine is asking, and clicks Approve; the CLI then collects a
+  30-day token by itself, so no token is ever pasted between people. The code is
+  printed too — it is what the page shows, so you can tell it is your own request.
+  Approve only a link you opened because YOU ran this command: a link someone
+  sends you would connect THEIR machine to your workspace.
+
+  The wait is bounded (90s by default) and RESUMABLE: if nobody has approved yet
+  it exits 75 and keeps the request, so running \`octwin login\` again picks up the
   same code. --wait 0 prints the code and returns at once.`,
-    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]
-                [--request-listing | --withdraw-listing]
-  Upload the pack bundle, validate server-side, install onto the project.
-  --seed additionally applies the pack's demo seed (streams progress).
-
-  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
-  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
-
-  --request-listing    ask an operator to review this pack for the public marketplace
-                       (the pre-signup storefront at /packs). Requires 'public: true'
-                       under 'listing:' in manifest.yaml — the manifest states that the
-                       pack is a product, the flag is you choosing to ask.
-  --withdraw-listing   retract the request, including an approved listing.
-
-  An approval covers the CONTENT it was made against, so a later deploy that changes the
+    deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed] [--force]
+                [--request-listing | --withdraw-listing]
+  Upload the pack bundle, validate server-side, install onto the project.
+  --seed additionally applies the pack's demo seed (streams progress).
+
+  A deploy sends what this copy was made from (${BASE_FILE}, written by every pull and
+  deploy). When someone published since — Tavi in the console, another deploy, a repo
+  import — it is refused and NOTHING changes: run 'octwin pull <packId>', which updates
+  this folder (it stops if you changed a file since, so you can save your edit first),
+  then deploy again. A version lower than the live one is refused the same way.
+  --force              deploy anyway, replacing the newer or higher live version.
+
+  A plain deploy says NOTHING about the public marketplace — it is a test loop, so it
+  neither asks for a listing nor gives one up. The marketplace flags are opt-in:
+
+  --request-listing    ask an operator to review this pack for the public marketplace
+                       (the pre-signup storefront at /packs). Requires 'public: true'
+                       under 'listing:' in manifest.yaml — the manifest states that the
+                       pack is a product, the flag is you choosing to ask.
+  --withdraw-listing   retract the request, including an approved listing.
+
+  An approval covers the CONTENT it was made against, so a later deploy that changes the
   pack returns it to the review queue on its own — no flag needed, and the CLI says so.`,
-    seed: `octwin seed [--pack <packId>] [--reset]
-  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 — each demo row is found again by its handle (its
-  \`as:\`, natural key or title) and updated, and existing media is REUSED rather
-  than regenerated, so a second pass costs nothing. Demo rows are DATA: no \`on:\`
-  reaction fires, and a row takes its \`stage:\` as written.
-  --reset   archive every row the pack's demo loaded, then load it again. Needed once
-            for demo rows seeded before 2026-10-05 (the seed says so), and a clean
-            slate whenever you want one. Records your customers made are not touched.
+    seed: `octwin seed [--pack <packId>] [--reset]
+  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 — each demo row is found again by its handle (its
+  \`as:\`, natural key or title) and updated, and existing media is REUSED rather
+  than regenerated, so a second pass costs nothing. Demo rows are DATA: no \`on:\`
+  reaction fires, and a row takes its \`stage:\` as written.
+  --reset   archive every row the pack's demo loaded, then load it again. Needed once
+            for demo rows seeded before 2026-10-05 (the seed says so), and a clean
+            slate whenever you want one. Records your customers made are not touched.
   --pack is only needed when a project somehow runs more than one.`,
-    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\`
+    status: `octwin status [<packId>] [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
+  Show installed vs live version + the flow list for this pack, and whether your copy
+  (${BASE_FILE}) is still the live content — if not, pull before you deploy.
+  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] [--json]
-  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
-  tickets, anything routed to a queue) read best through \`octwin work\`.
-
-  SEARCH:
-    octwin records <entity> --search "<words>"   # ranked, best match first, each row with its score (0–1)
-  Works for an entity that declares \`search:\` in xrm.yaml (fuzzy, plus semantic when declared) —
-  the same search the console's search box runs. Any other entity answers "not searchable".
-
-  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 archive <recordId>          # out of every list and count (test data too)
-    octwin records restore <recordId>          # undo an archive
-    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
-    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
-
-  There is NO delete — on the platform or here. \`archive\` is how a record leaves use:
-  it fires the entity's \`on.archived\` reactions, exactly like the console's Archive,
-  and \`restore\` brings it back.
-
-  --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/archive/restore/tasks/task\` is
+    records: `octwin records [entity] [id] [--limit 50] [--offset n] [--json]
+  Inspect the pack's XRM data. No args = list entities. Worked records (cases,
+  tickets, anything routed to a queue) read best through \`octwin work\`.
+
+  SEARCH:
+    octwin records <entity> --search "<words>"   # ranked, best match first, each row with its score (0–1)
+  Works for an entity that declares \`search:\` in xrm.yaml (fuzzy, plus semantic when declared) —
+  the same search the console's search box runs. Any other entity answers "not searchable".
+
+  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 archive <recordId>          # out of every list and count (test data too)
+    octwin records restore <recordId>          # undo an archive
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  There is NO delete — on the platform or here. \`archive\` is how a record leaves use:
+  it fires the entity's \`on.archived\` reactions, exactly like the console's Archive,
+  and \`restore\` brings it back.
+
+  --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/archive/restore/tasks/task\` is
   read as a VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
-    work: `octwin work [recordId] [--queues] [--unrouted] [--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\`).
+    work: `octwin work [recordId] [--queues] [--unrouted] [--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.
+    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.
-  You may pull a pack your tenant OWNS (deployed); an operator token pulls any.`,
-    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--press <label>] [--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.
-  --press does the same BY ITS LABEL, in the reply the conversation is waiting on
-  — for a form or checkout step, whose tap id carries a run id that changes.
-  --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.
-
-  Each reply line says who sent it. Plain \`← …\` is the AI Agent. \`← [notify] …\` is a
-  reminder or notification (a \`schedule_notify\`, a reaction) — NOT the turn's answer,
-  so the wait for the real reply goes on. \`← [operator: Name] …\` is a person in
-  Live chat; \`← [platform] …\` is a platform line (a handoff joining or returning).
-  After the last turn the stream stays open ${LATE_DRAIN_MS / 1000}s more, so a late message
-  still prints (marked "after the last turn") instead of reaching a closed connection.
-
-  --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
-    press:Confirm
-
-  press:<label> taps the button of the reply just received whose label matches —
-  exactly, or the same words without emoji or case, or the one label containing
-  them. None, or several buttons, stops the script and lists the buttons. A form
-  step's tap id carries its run id (t:resume:…:run_id=…), which exists only once
+    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.
+  Writes into the folder you are in when it is this pack, else ./<packId>; --dir overrides.
+  Replaces only files that still match your last pull or deploy (${BASE_FILE}); a file
+  you changed since stops it — save your edit first, or --force overwrites it.
+  The pulled dir redeploys where it came from — the target is your saved login.
+  You may pull a pack your workspace OWNS, or any first-party (Octwin) pack — those are
+  free to copy as a starting point; an operator token pulls any.`,
+    chat: `octwin chat "message" [--as <handle>] [--tap <tap-id>] [--press <label>] [--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.
+  --press does the same BY ITS LABEL, in the reply the conversation is waiting on
+  — for a form or checkout step, whose tap id carries a run id that changes.
+  --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.
+
+  Each reply line says who sent it. Plain \`← …\` is the AI Agent. \`← [notify] …\` is a
+  reminder or notification (a \`schedule_notify\`, a reaction) — NOT the turn's answer,
+  so the wait for the real reply goes on. \`← [operator: Name] …\` is a person in
+  Live chat; \`← [platform] …\` is a platform line (a handoff joining or returning).
+  After the last turn the stream stays open ${LATE_DRAIN_MS / 1000}s more, so a late message
+  still prints (marked "after the last turn") instead of reaching a closed connection.
+
+  --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
+    press:Confirm
+
+  press:<label> taps the button of the reply just received whose label matches —
+  exactly, or the same words without emoji or case, or the one label containing
+  them. None, or several buttons, stops the script and lists the buttons. A form
+  step's tap id carries its run id (t:resume:…:run_id=…), which exists only once
   the reply arrives, so a script reaches past the first form step only by press.`,
-    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,
+    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
+    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] [--offset n] [--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 —
+  \`none\` = no payment opened (no gateway), \`pending\` = checkout not confirmed yet.
+
+  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>] [--limit n] [--offset n] [--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] [--limit n] [--offset n] [--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.`,
-    automation: `octwin automation [campaigns] [--limit n] [--offset n] [--json]
-  No args = every job the pack's automation declaration produced, with its status,
-  interval and LAST RESULT (matched / acted / errors), under a health line whose
-  counts come from SQL rather than from filtering the page — the job list is capped
-  server-side, so a client-side count would depend on the cap. Needs automation:read.
-
-  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
-  the pack means no jobs, and \`octwin deploy\` is what installs them.
-
-  WRITES (automation:write):
-    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
-    octwin automation pause|resume <jobId>
-    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
-
-  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
-  accept only a uuid — the CLI resolves the key for you, and names the keys that do
-  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
+    automation: `octwin automation [campaigns | --campaigns] [--limit n] [--offset n] [--json]
+  No args = every job the pack's automation declaration produced, with its status,
+  interval and LAST RESULT (matched / acted / errors), under a health line whose
+  counts come from SQL rather than from filtering the page — the job list is capped
+  server-side, so a client-side count would depend on the cap. Needs automation:read.
+
+  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
+  the pack means no jobs, and \`octwin deploy\` is what installs them.
+
+  WRITES (automation:write):
+    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
+    octwin automation pause|resume <jobId>
+    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
+
+  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
+  accept only a uuid — the CLI resolves the key for you, and names the keys that do
+  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
   missing scope: the action is re-checked against the job.`,
-    integrations: `octwin integrations [--json]
-  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
-  connection that is declared and never configured is the commonest reason an
-  integration silently never fires, and neither list alone can show it. Flags the
-  gap explicitly. Needs integrations:read.
-
-  DIAGNOSE ONE CONNECTION:
-    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
-                                           # outbound call — needs only integrations:read
-    octwin integrations test <key>         # a LIVE call to its health: operation
-                                           # (integrations:write). Exits 1 when it fails.
-
-  THE DELIVERY LOG:
-    octwin integrations deliveries [--status s] [--operation id] [--limit n]
-    octwin integrations deliveries <id>    # + the redacted request/response snapshots
-    octwin integrations retry|cancel|send-now <id>     # integrations:write
-    octwin integrations events             # INBOUND events (what arrived at your webhook)
-
-  retry/cancel answer 409 when the delivery is in the wrong state; the message
+    integrations: `octwin integrations [--json]
+  What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
+  connection that is declared and never configured is the commonest reason an
+  integration silently never fires, and neither list alone can show it. Flags the
+  gap explicitly. Needs integrations:read.
+
+  DIAGNOSE ONE CONNECTION:
+    octwin integrations preflight <key>    # every check, with a fix hint. Makes NO
+                                           # outbound call — needs only integrations:read
+    octwin integrations test <key>         # a LIVE call to its health: operation
+                                           # (integrations:write). Exits 1 when it fails.
+
+  THE DELIVERY LOG:
+    octwin integrations deliveries [--status s] [--operation id] [--limit n] [--offset n]
+    octwin integrations deliveries <id>    # + the redacted request/response snapshots
+    octwin integrations retry|cancel|send-now <id>     # integrations:write
+    octwin integrations events             # INBOUND events (what arrived at your webhook)
+
+  retry/cancel answer 409 when the delivery is in the wrong state; the message
   carries the rule.`,
-    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
-                  [--stage <stageId>] [--limit n] [--json]
-  No args = the journeys the pack declares. With an id, one of six views —
-  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
-  converted plus the biggest drop-off · --goals completions, contacts, value and
-  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
-  --definition what was DECLARED, unmeasured (the one view that works with no
-  traffic). Needs journeys:read.
-
-  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
-  not the funnel's cumulative reached counts).
-
-  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
-  entity funnel are the same question about different subjects. Journeys carry RBAC
-  on top of the scope, so an empty answer can be a missing \`view\` grant rather
+    journeys: `octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]
+                  [--stage <stageId>] [--limit n] [--offset n] [--json]
+  No args = the journeys the pack declares. With an id, one of six views —
+  --funnel (default) stage-by-stage reach and drop-off · --overview entered vs
+  converted plus the biggest drop-off · --goals completions, contacts, value and
+  p50 time · --trends per-bucket activity · --cost tokens and dollars per goal ·
+  --definition what was DECLARED, unmeasured (the one view that works with no
+  traffic). Needs journeys:read.
+
+  --stage <stageId> lists the runs sitting at a stage right now (a live snapshot,
+  not the funnel's cumulative reached counts).
+
+  Same flag grammar as \`octwin analytics\` on purpose: a journey funnel and an
+  entity funnel are the same question about different subjects. Journeys carry RBAC
+  on top of the scope, so an empty answer can be a missing \`view\` grant rather
   than missing data — the output says which causes are possible.`,
-    performance: `octwin performance [--detail] [--json]
-  The project's business indicators — value produced, conversion, duration — each
-  with its delta against the previous window and a \`why\` naming the declaration it
-  came from. --detail adds the per-indicator breakdown.
-
-  Needs records:read, NOT a performance scope (there is none), so a read-only token
-  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
+    performance: `octwin performance [--detail] [--range <days>] [--channel <ch>] [--json]
+  The project's business indicators — value produced, conversion, duration — each
+  with its delta against the previous window and a \`why\` naming the declaration it
+  came from. --detail adds the per-indicator breakdown. --range <days> sets the window
+  and --channel <whatsapp|web> narrows every figure to one channel — the console's two
+  controls on the same page.
+
+  Needs records:read, NOT a performance scope (there is none), so a read-only token
+  already reaches it. Indicators are DERIVED: a pack that declares no journey goal
   value and no pipelined entity produces none, which is a different thing from zero.`,
-    usage: `octwin usage [--json]
-  Model calls, tokens and cost for the resolved scope — project when one is pinned
-  or passed with --project, otherwise the whole workspace. Broken down by model,
-  kind, agent and channel.
-
-  Needs no particular scope: any valid token reaches it.
-
-  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
+    charts: `octwin charts [<key>] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--json]
+  The pack's own \`charts:\` (xrm.yaml), as the owner's dashboard draws them. No key = the
+  list; with a key = that chart's figure, its parts (a \`by:\` chart) or its points (an
+  \`over:\` chart) for the window. A token sees the charts whose entity it may view.
+  Needs records:read.`,
+    handoff: `octwin handoff [<id>] [--bucket waiting|mine|all|ended] [--limit n] [--offset n] [--json]
+  The Live chat desk, read-only: the handoffs in a bucket (default all), or one with
+  its transcript — who said what: customer, AI Agent, operator, platform. Needs work:read
+  and the live_chat plan feature. Accepting, answering and returning one stay in the
+  console: those need a signed-in PERSON to hold the conversation, and a token is not one.`,
+    surveys: `octwin surveys [<key>] [--limit n] [--offset n] [--json]
+  No key = the declared surveys with their responses and headline score (under the
+  survey's own model — average, top box or NPS). With a key = its questions, the rollup,
+  and the recent responses (--limit / --offset page them). Needs records:read.`,
+    usage: `octwin usage [--json]
+  Model calls, tokens and cost for the resolved scope — project when one is pinned
+  or passed with --project, otherwise the whole workspace. Broken down by model,
+  kind, agent and channel.
+
+  Needs no particular scope: any valid token reaches it.
+
+  This is MODEL spend only. WhatsApp/Meta message billing is operator-only and
   deliberately outside the token scope registry — no API token can read it.`,
-    '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,
-  and this command never sends one. --token is accepted and ignored, so an older
-  script that passes it keeps working.
-
-  --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 / no reference served). For
+    '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,
+  and this command never sends one. --token is accepted and ignored, so an older
+  script that passes it keeps working.
+
+  --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 / no reference served). 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.`,
-    memos: `octwin memos [--all] [--json]
-  Read what the platform has told you: a REPLY to a report you sent with
-  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
-  a deprecation, a breaking change). Bodies are printed in full.
-  Reading marks them read, so the reminder stops. --all re-reads history and
-  acks nothing. --json to branch on \`severity\`
+    test: `octwin test [--dir .] [--require-kb] [--strict-primitives]
+  Alias for \`octwin validate --remote\` — the full platform check, REQUIRED (a skipped full
+  check is an error). --offline contradicts it; the other validate flags mean what they mean there.`,
+    memos: `octwin memos [--all] [--json]
+  Read what the platform has told you: a REPLY to a report you sent with
+  \`octwin feedback\`, or a NOTICE published to every author (a new capability,
+  a deprecation, a breaking change). Bodies are printed in full.
+  Reading marks them read, so the reminder stops. --all re-reads history and
+  acks nothing. --json to branch on \`severity\`
   (info | action_required | breaking).`,
-    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.`,
 };
 /**
@@ -5887,36 +6390,48 @@ octwin projects rm <slug> [--yes]
  * (`cli.json-contract.test.ts`).
  */
 export const COMMANDS = {
-    init: { run: cmdInit, json: false },
-    validate: { run: cmdValidate, json: false },
-    login: { run: cmdLogin, json: 'lines' }, // pending, then approved — two objects
-    whoami: { run: cmdWhoami, json: false },
-    deploy: { run: cmdDeploy, json: false },
-    pull: { run: cmdPull, json: false },
-    status: { run: cmdStatus, json: false },
-    records: { run: cmdRecords, json: 'document' },
-    work: { run: cmdWork, json: 'document' },
-    logs: { run: cmdLogs, json: 'document' },
-    chat: { run: cmdChat, json: 'lines' }, // one line per event the turn produced
-    media: { run: cmdMedia, json: 'document' },
-    seed: { run: cmdSeed, json: false },
-    projects: { run: cmdProjects, json: 'document' },
-    agents: { run: cmdAgents, json: 'document' },
-    orders: { run: cmdOrders, json: 'document' },
-    analytics: { run: cmdAnalytics, json: 'document' },
-    catalog: { run: cmdCatalog, json: 'document' },
-    scheduling: { run: cmdScheduling, json: 'document' },
-    automation: { run: cmdAutomation, json: 'document' },
-    integrations: { run: cmdIntegrations, json: 'document' },
-    journeys: { run: cmdJourneys, json: 'document' },
-    performance: { run: cmdPerformance, json: 'document' },
-    usage: { run: cmdUsage, json: 'document' },
-    'platform-kb': { run: cmdPlatformKb, json: false },
-    feedback: { run: cmdFeedback, json: false },
-    memos: { run: cmdMemos, json: 'document' },
+    init: { run: cmdInit, json: false, flags: ['id', 'description', 'display-name'] },
+    recipe: { run: cmdRecipe, json: false, flags: ['dry-run'] },
+    validate: { run: cmdValidate, json: false, flags: ['offline', 'remote', 'require-kb', 'strict-primitives'] },
+    login: { run: cmdLogin, json: 'lines', flags: ['wait'] }, // pending, then approved — two objects
+    whoami: { run: cmdWhoami, json: false, flags: [] },
+    deploy: { run: cmdDeploy, json: false, flags: ['force', 'seed', 'request-listing', 'withdraw-listing'] },
+    pull: { run: cmdPull, json: false, flags: ['force', 'version'] },
+    status: { run: cmdStatus, json: false, flags: [] },
+    records: { run: cmdRecords, json: 'document', flags: ['contact', 'entity', 'fields-json', 'limit', 'note', 'offset', 'outcome', 'search', 'set', 'stage', 'to'] },
+    work: { run: cmdWork, json: 'document', flags: ['action', 'dry-run', 'limit', 'note', 'offset', 'param', 'queues', 'to', 'unrouted'] },
+    logs: { run: cmdLogs, json: 'document', flags: ['as'] },
+    chat: { run: cmdChat, json: 'lines', flags: ['as', 'media', 'press', 'script', 'tap'] }, // one line per event the turn produced
+    media: { run: cmdMedia, json: 'document', flags: ['out'] },
+    seed: { run: cmdSeed, json: false, flags: ['pack', 'reset'] },
+    projects: { run: cmdProjects, json: 'document', flags: ['archived', 'pack', 'slug', 'yes'] },
+    agents: { run: cmdAgents, json: 'document', flags: ['disable-tool', 'enable-tool', 'enabled', 'model', 'overlay', 'prompt'] },
+    orders: { run: cmdOrders, json: 'document', flags: ['force', 'limit', 'mark-returned', 'offset', 'payment', 'reason', 'status', 'to'] },
+    analytics: { run: cmdAnalytics, json: 'document', flags: ['funnel', 'overview', 'milestones', 'trends', 'cost', 'stage', 'limit', 'offset'] },
+    catalog: { run: cmdCatalog, json: 'document', flags: ['limit', 'offset', 'readiness', 'set-on-hand', 'to'] },
+    scheduling: { run: cmdScheduling, json: 'document', flags: ['capacity', 'date', 'days', 'dow', 'end', 'from', 'kind', 'resource', 'slot-minutes', 'slots', 'start'] },
+    automation: { run: cmdAutomation, json: 'document', flags: ['campaigns', 'limit', 'offset'] },
+    integrations: { run: cmdIntegrations, json: 'document', flags: ['limit', 'offset', 'operation', 'status'] },
+    journeys: { run: cmdJourneys, json: 'document', flags: ['funnel', 'overview', 'goals', 'trends', 'cost', 'definition', 'stage', 'limit', 'offset'] },
+    performance: { run: cmdPerformance, json: 'document', flags: ['detail', 'range', 'channel'] },
+    usage: { run: cmdUsage, json: 'document', flags: [] },
+    charts: { run: cmdCharts, json: 'document', flags: ['from', 'to'] },
+    handoff: { run: cmdHandoff, json: 'document', flags: ['bucket', 'limit', 'offset'] },
+    surveys: { run: cmdSurveys, json: 'document', flags: ['limit', 'offset'] },
+    'platform-kb': { run: cmdPlatformKb, json: false, flags: ['check', 'if-stale'] },
+    feedback: { run: cmdFeedback, json: false, flags: [] },
+    memos: { run: cmdMemos, json: 'document', flags: ['all'] },
     // A6: `test` = the full remote validate, not a validate-clone.
-    test: { run: flags => cmdValidate({ ...flags, remote: true }), json: false },
+    test: { run: flags => cmdValidate({ ...flags, remote: true }), json: false, flags: ['offline', 'remote', 'require-kb', 'strict-primitives'] },
 };
+/**
+ * The flags every command takes: the target (`--url` / `--tenant` / `--project` / `--token`, read by
+ * `resolveTarget`), `--json` (held to `json:` above), `--help`, and `--dir` — the pack directory, which
+ * `runCli` itself reads on every run to find the pulled KB (`readLocalKb`). Each command's OWN flags are its
+ * `flags:` row — the one list `runCli` refuses against, and `cli.flags.test.ts` holds to the code that
+ * reads them, to `help()` / `COMMAND_HELP`, and to the README.
+ */
+export const GLOBAL_FLAGS = ['url', 'tenant', 'project', 'token', 'json', 'help', 'dir'];
 /** Exit code when a `--json` command ended without the result it promised — a bug in this CLI. */
 export const EXIT_NO_RESULT = 70;
 /**
@@ -5967,6 +6482,13 @@ export async function runCli(argv, io) {
         if (flags.json === true && spec.json === false) {
             die(`\`octwin ${command}\` has no --json output — the commands that do are: ${Object.entries(COMMANDS).filter(([, c]) => c.json !== false).map(([n]) => n).join(', ')}`);
         }
+        // A flag the command does not read is REFUSED, before it runs. It used to be ignored, so a
+        // typo — or a flag the command never learned, like `performance --channel` until 2026-10-11 —
+        // ran the command with its default and printed an answer to a question nobody asked.
+        const unknownFlags = Object.keys(flags).filter(k => k !== '_' && !GLOBAL_FLAGS.includes(k) && !spec.flags.includes(k));
+        if (unknownFlags.length) {
+            die(`\`octwin ${command}\` has no ${unknownFlags.map(f => `--${f}`).join(', ')} — its flags: ${spec.flags.length ? spec.flags.map(f => `--${f}`).join(' ') : '(none of its own)'}; on every command: ${GLOBAL_FLAGS.map(f => `--${f}`).join(' ')}. Usage: octwin ${command} --help`);
+        }
         // Compute the trailing nudges BEFORE the command runs, so they survive a `die()` — see the
         // notice-channel block above. They are PRINTED after the command, by `flushNotices` here on the
         // success path and by `exitNow` on every failure path. Fail-silent by construction (each helper