octwin-cli 0.8.16 → 0.9.0

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?
@@ -28,7 +28,7 @@
  *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
  *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
  *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
- *   octwin automation [campaigns]    # the jobs your declarations produced + health + last result (automation:read)
+ *   octwin automation [coming|happened|why <id>|campaigns]  # the project's rules in words, what is coming up, what happened (automation:read)
  *   octwin integrations [deliveries|events|preflight|test …]  # declared vs configured, and the delivery log (integrations:read)
  *   octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]  # declared journeys, measured (journeys:read)
  *   octwin performance [--detail]    # the project's business indicators (records:read — there is no performance scope)
@@ -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,10 +78,14 @@ 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 { phraseText, resolveRuleKey, shortTime } from './lib/rules.js';
 import { chatLabel, answersTheTurn } from './lib/chat-line.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
 import { buildSymbols, linkExplainers, renderSymbolsMarkdown } from './lib/kb-symbols.js';
@@ -235,9 +241,9 @@ const VERB_REQUIREMENTS = {
     // which does NOT confer this — that 403 is otherwise baffling.
     'projects create': { scope: 'projects:write' },
     'projects rm': { scope: 'projects:write' },
-    // Jobs are declaration-derived, so there is no `create` — only acting on one.
-    // `campaigns` is absent on purpose: it is a READ sharing the verb slot, and an
-    // entry here would print "needs automation:write" on a read failure.
+    // Rules are declared, so there is no `create` — only acting on one (or a campaign).
+    // `coming` / `happened` / `why` / `campaigns` are absent on purpose: they are READS sharing
+    // the verb slot, and an entry here would print "needs automation:write" on a read failure.
     'automation run': { scope: 'automation:write' },
     'automation pause': { scope: 'automation:write' },
     'automation resume': { scope: 'automation:write' },
@@ -291,6 +297,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 +923,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 +939,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 +960,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 +1316,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 +1780,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 +1821,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 +1849,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 +2035,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 +2097,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 +2143,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 +2157,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 +2167,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 +2193,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 +2227,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 +2315,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 +2552,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) {
@@ -2533,12 +2764,16 @@ async function cmdRecords(flags) {
                 out.print('No AI Agent is loaded in this project.');
                 return;
             }
-            if (json?.has_xrm === false) {
-                // No record TYPES of its own — but the platform's own records (an order, a case) still read by name.
+            // The LISTED types, as the console's switcher shows them: the catalog carries every platform
+            // entity for lookups by name. A server older than the `listed` field sent declared types only,
+            // so a missing one reads as listed.
+            const ents = (json?.entities ?? []).filter(e => e.listed !== false);
+            if (json?.has_xrm === false && ents.length === 0) {
+                // No record TYPES of its own and no platform records yet — the platform's (an order, a case)
+                // still read by name.
                 out.print('This pack declares no record types of its own. Platform records still read by name: octwin records order | product | case | …');
                 return;
             }
-            const ents = (json?.entities ?? []);
             if (ents.length === 0) {
                 out.print('No entities visible — mint a token with the `records:read` scope to inspect data.');
                 return;
@@ -4092,12 +4327,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 +4346,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);
@@ -4694,49 +4932,51 @@ async function cmdScheduling(flags) {
     out.print(`  upcoming slots: ${json?.upcoming_slots ?? 0}   booked seats: ${json?.booked_seats ?? 0}`);
     out.print('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
 }
-// ── automation: declaration-derived jobs + campaigns ─────────────────────────
+// ── automation: the project's rules + campaigns ──────────────────────────────
 /**
- * Verbs that mean "act on a job", not "an id".
+ * Verbs of `octwin automation` — a view (`coming`, `happened`, `why`, `campaigns`) or an act (`run`, `pause`,
+ * `resume`, `send`) — not a rule key.
  *
- * `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
- * per verb — so one verb per intent makes both the permission hint and the 403
- * say the right thing.
+ * Until 0.9.0 the command read JOB ROWS (`…/automation/jobs`). Since the platform's migration 126 those are only its
+ * own two sweeps: a pack's `rules:` — and its older `segment` / `stale_records` / `sla_sweep` jobs and `on:` hooks,
+ * which run as compiled rules — were invisible in the terminal. It reads the rules routes the console's Outbound →
+ * Automatic tab reads now, so the words are the server's.
  */
-const AUTOMATION_VERBS = new Set(['run', 'pause', 'resume', 'campaigns', 'send']);
+const AUTOMATION_VERBS = new Set(['coming', 'happened', 'why', 'run', 'pause', 'resume', 'campaigns', 'send']);
+const AUTOMATION_WRITES = new Set(['run', 'pause', 'resume', 'send']);
 /**
- * Turn whatever the author typed into the UUID the route demands.
- *
- * (`UUID_RE` is the one already declared for `--media`, deliberately reused rather
- * than a second copy of the same pattern.)
- *
- * The write routes take a UUID path param and reject anything else with a bare
- * *"Malformed identifier in the URL — expected a UUID"* 400. But the thing an author
- * has in front of them is the declaration KEY (`cart_recovery_nudge`) — that is what
- * the list prints, and it is the name in their own YAML. Measured: passing the key
- * 400s on all three write verbs.
- *
- * So the key is resolved here, against the list route, rather than documented as a
- * gotcha. A UUID passes straight through, and an unknown key fails naming the keys
- * that DO exist — which is the answer to the question the author is actually asking.
+ * Turn the campaign an author typed into the UUID the send route demands — the id `octwin automation campaigns`
+ * prints, or the campaign's key. An unknown one fails naming those that exist.
  */
-async function resolveAutomationId(kind, typed, base, t) {
+async function resolveCampaignId(typed, t) {
     if (UUID_RE.test(typed))
         return typed;
-    const { status, json } = await apiGet(`${base}/${kind}`, t);
-    if (status !== 200) {
-        die(`could not resolve '${typed}' — reading ${kind} failed (HTTP ${status})${errDetail(json)}`);
-    }
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const { status, json } = await apiGet(`${base}/campaigns`, t);
+    if (status !== 200)
+        die(`could not resolve '${typed}' — reading campaigns failed (HTTP ${status})${errDetail(json)}`);
     const rows = readPage(json).rows;
     const hit = rows.find(r => r.key === typed || r.id === typed);
     if (hit?.id)
         return hit.id;
     const keys = rows.map(r => r.key ?? r.id).filter(Boolean);
-    die(`no ${kind === 'jobs' ? 'job' : 'campaign'} '${typed}' in this project.`
-        + (keys.length ? ` Available: ${keys.join(', ')}` : ` This project declares none.`));
+    die(`no campaign '${typed}' in this project.` + (keys.length ? ` Available: ${keys.join(', ')}` : ' This project has none.'));
 }
-/** `pause`/`resume`/`run`/`send` — the writes behind `octwin automation`. */
+/** The rule an author typed, against the project's rules (`resolveRuleKey`) — or the command dies naming them. */
+async function resolveRule(typed, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const { status, json } = await apiGet(`${base}/rules`, t);
+    if (status !== 200)
+        die(`could not resolve '${typed}' — reading the rules failed (HTTP ${status})${errDetail(json)}`);
+    const keys = (json?.rules ?? []).map(r => r.key).filter((k) => typeof k === 'string');
+    const r = resolveRuleKey(typed, keys);
+    if ('error' in r)
+        die(r.error);
+    return r.key;
+}
+/** `pause` / `resume` / `run` a rule, `send` a campaign — the writes behind `octwin automation`. */
 async function cmdAutomationWrite(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
@@ -4744,88 +4984,212 @@ async function cmdAutomationWrite(flags) {
     const verb = flags._[0];
     const typed = flags._[1];
     const asJson = flags.json === true;
-    if (!typed)
-        die(`usage: octwin automation ${verb} <${verb === 'send' ? 'campaignId' : 'jobId'}>   (ids: octwin automation${verb === 'send' ? ' campaigns' : ''})`);
-    const id = await resolveAutomationId(verb === 'send' ? 'campaigns' : 'jobs', typed, base, t);
-    if (verb === 'pause' || verb === 'resume') {
-        const { status, json } = await apiSend('PATCH', `${base}/jobs/${encodeURIComponent(id)}/status`, { status: verb === 'pause' ? 'paused' : 'active' }, t);
+    if (verb === 'send') {
+        if (!typed)
+            die('usage: octwin automation send <campaignId>   (ids: octwin automation campaigns)');
+        const id = await resolveCampaignId(typed, t);
+        if (!asJson)
+            out.print(`→ Sending campaign '${typed}' in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/campaigns/${encodeURIComponent(id)}/send`, undefined, t);
         if (status === 404)
-            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
-        // RBAC re-checks the ACTION on the job, so a 403 here can be a grant gap
-        // rather than a missing scope — same caveat as a record write.
+            die(`campaign '${typed}' not found in ${targetLabel(t)} (ids: octwin automation campaigns)`);
         if (status !== 200)
-            writeFail(`${verb} job '${typed}'`, status, json, url, true);
+            writeFail(`send campaign '${typed}'`, status, json, url, true);
         if (asJson) {
             out.result(json);
             return;
         }
-        const j = json?.job ?? {};
-        out.print(`✓ job '${j.key ?? typed}' is now ${j.status}`);
-        if (j.next_run_at)
-            out.print(`  next run: ${j.next_run_at}`);
+        const r = json?.result ?? {};
+        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 automation happened`');
+        return;
+    }
+    if (!typed)
+        die(`usage: octwin automation ${verb} <ruleKey>   (keys: octwin automation)`);
+    const key = await resolveRule(typed, t);
+    const path = `${base}/rules/${encodeURIComponent(key)}/${verb}`;
+    if (!asJson && verb === 'run')
+        out.print(`→ Running rule '${key}' in ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('POST', path, undefined, t);
+    if (status === 404)
+        die(`rule '${key}' not found in ${targetLabel(t)} (keys: octwin automation)`);
+    // RBAC re-checks the ACTION on `automation.rule`, so a 403 can be a grant gap rather than a missing scope; a 409
+    // is the rule saying why not (only a rule on a timetable can be run now) — the server's words.
+    if (status !== 200)
+        writeFail(`${verb} rule '${key}'`, status, json, url, true);
+    if (asJson) {
+        out.result(json);
         return;
     }
     if (verb === 'run') {
-        if (!asJson)
-            out.print(`→ Running job '${typed}' in ${targetLabel(t)} …`);
-        const { status, json } = await apiSend('POST', `${base}/jobs/${encodeURIComponent(id)}/run`, undefined, t);
-        if (status === 404)
-            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
-        if (status !== 200)
-            writeFail(`run job '${typed}'`, status, json, url, true);
-        if (asJson) {
-            out.result(json);
-            return;
-        }
-        const r = json?.result ?? {};
-        out.print(`✓ ran '${typed}': matched ${r.matched ?? 0}, acted ${r.acted ?? 0}, errors ${r.errors ?? 0}`);
-        // `acted < matched` is the route's own definition of a PARTIAL run, so say so
-        // rather than leaving three numbers for the author to compare.
-        if ((r.errors ?? 0) > 0)
-            out.print('  ⚠ some rows errored — see the job\'s last_result in `octwin automation`');
-        else if ((r.acted ?? 0) < (r.matched ?? 0))
-            out.print('  partial: matched rows were skipped (cooldown, or already acted on)');
+        out.print(`✓ '${key}' runs now — it reaches ${json?.reaches ?? 0} record(s); next time after this run: ${shortTime(json?.next)}`);
+        out.print('  see what it did: octwin automation happened');
+    }
+    else if (verb === 'pause') {
+        out.print(`✓ '${key}' is paused — its times still arm, and nothing runs (nothing is caught up when it resumes)`);
+    }
+    else {
+        out.print(json?.resumed === false ? `  '${key}' was not paused` : `✓ '${key}' runs again`);
+    }
+}
+/**
+ * A campaign's delivery progress — the per-status counts of its deliveries. 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);
+}
+/** A line's record and customer, as one tail — `· Booking #7 · Sara`. */
+function lineTail(l) {
+    const rec = l?.record ? ` · ${l.record.noun ?? l.record.entity ?? 'record'} #${l.record.number ?? '?'}` : '';
+    const who = l?.contact ? ` · ${l.contact.name ?? 'customer'}` : '';
+    return `${rec}${who}`;
+}
+/** A query string of the values that are set — `range=week&q=cairo`. Each caller names the flags it passes. */
+function setQs(values) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(values))
+        if (typeof v === 'string')
+            p.set(k, v);
+    return p.toString();
+}
+/** `octwin automation coming` — every time still to come: a rule's, or a flow's own message (a send). */
+async function automationComing(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    if (!asJson)
+        out.print(`→ Reading what is coming up in ${targetLabel(t)} …`);
+    const qs = setQs({ range: flags.range, entity: flags.entity, q: flags.q, cursor: flags.cursor });
+    const { status, json } = await apiGet(`${base}/upcoming?${qs || 'range=week'}`, t);
+    if (status !== 200)
+        die(`could not read what is coming up (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+    if (asJson) {
+        out.result(json);
         return;
     }
-    // send — one campaign
+    const lines = (json?.lines ?? []);
+    out.print(`Coming up in ${targetLabel(t)} (${typeof flags.range === 'string' ? flags.range : 'week'}): ${json?.total ?? lines.length}`);
+    if (lines.length === 0)
+        out.print('  (nothing — a rule\'s time arms when its record is made or changed)');
+    for (const l of lines) {
+        const mark = l.skipped ? '  [skipped]' : l.paused ? '  [paused]' : '';
+        out.print(`  ${shortTime(l.at)}  ${phraseText(l.headline)}${lineTail(l)}${mark}  ${l.kind === 'queued' ? 'message' : 'timer'} ${l.id}`);
+    }
+    if (json?.next)
+        out.print(`\nMore: octwin automation coming --cursor ${json.next}`);
+    if (lines.length)
+        out.print('Why one goes, and what it will say:  octwin automation why <id>');
+}
+/** `octwin automation happened` — every fire of the period: its final word, and why a message did not go. */
+async function automationHappened(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
     if (!asJson)
-        out.print(`→ Sending campaign '${typed}' in ${targetLabel(t)} …`);
-    const { status, json } = await apiSend('POST', `${base}/campaigns/${encodeURIComponent(id)}/send`, undefined, t);
-    if (status === 404)
-        die(`campaign '${typed}' not found in ${targetLabel(t)} (ids: octwin automation campaigns)`);
+        out.print(`→ Reading what happened in ${targetLabel(t)} …`);
+    const qs = setQs({ chip: flags.chip, period: flags.period, q: flags.q, cursor: flags.cursor });
+    const { status, json } = await apiGet(`${base}/history?${qs || 'period=7d'}`, t);
     if (status !== 200)
-        writeFail(`send campaign '${typed}'`, status, json, url, true);
+        die(`could not read what happened (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
     if (asJson) {
         out.result(json);
         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)');
-    out.print('  enqueued ≠ delivered — watch the sends land with `octwin logs`');
+    const lines = (json?.lines ?? []);
+    const c = json?.counts ?? {};
+    out.print(`Happened in ${targetLabel(t)} (${typeof flags.period === 'string' ? flags.period : '7d'}): ${json?.total ?? lines.length}`
+        + `  —  ${c.not_delivered ?? 0} not delivered, ${c.failed ?? 0} failed, ${c.skipped ?? 0} skipped`);
+    if (lines.length === 0)
+        out.print('  (nothing yet)');
+    for (const l of lines) {
+        const why = l.code || l.reason ? `  (${l.code ?? l.reason})` : '';
+        out.print(`  ${shortTime(l.at)}  ${String(l.outcome ?? '—').padEnd(13)} ${phraseText(l.headline)}${lineTail(l)}${why}  ${l.id}`);
+    }
+    if (json?.next)
+        out.print(`\nMore: octwin automation happened --cursor ${json.next}`);
+    if (lines.length)
+        out.print('Each step and the words sent:  octwin automation why <id>');
+}
+/**
+ * `octwin automation why <id>` — one line's *Why?*, as the console's drawer: the rule in words, each step with its
+ * outcome, the words the customer reads. The line's kind picks the route (`--kind timer|fire|queued`); without it
+ * each is asked in turn — a coming time, a fire, a send.
+ */
+async function automationWhy(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    const id = flags._[1];
+    if (!id)
+        die('usage: octwin automation why <id> [--kind timer|fire|queued]   (ids: octwin automation coming | happened)');
+    const kinds = typeof flags.kind === 'string' ? [flags.kind] : ['timer', 'fire', 'queued'];
+    for (const kind of kinds) {
+        if (!['timer', 'fire', 'queued'].includes(kind))
+            die(`--kind is timer, fire or queued (got '${kind}')`);
+        const { status, json } = await apiGet(`${base}/why/${kind}/${encodeURIComponent(id)}`, t);
+        if (status === 404)
+            continue;
+        if (status !== 200)
+            die(`could not read why (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+        if (asJson) {
+            out.result(json);
+            return;
+        }
+        const v = json ?? {};
+        out.print(`${phraseText(v.line?.headline)}${lineTail(v.line)}  — ${shortTime(v.line?.at)}`);
+        if (v.rule)
+            out.print(`  rule ${v.rule.key}: ${phraseText(v.rule.sentence)}`);
+        if (v.line?.outcome)
+            out.print(`  outcome: ${v.line.outcome}${v.line.code ? ` (${v.line.code})` : ''}${v.line.reason ? ` — ${v.line.reason}` : ''}`);
+        for (const check of (v.checks ?? []))
+            out.print(`  checked again before it acts: ${phraseText(check)}`);
+        if (v.words?.text)
+            out.print(`  the customer reads${v.words.tag ? ` (${v.words.tag})` : ''}: ${v.words.text}`);
+        for (const s of (v.steps ?? [])) {
+            const send = s.send ? ` · ${s.send.status}${s.send.reason ? ` (${s.send.reason})` : ''}` : '';
+            out.print(`  step ${s.verb}: ${s.skipped ? `held back (${s.skipped})` : s.state}${send}${s.detail ? ` — ${s.detail}` : ''}`);
+        }
+        if (v.queued)
+            out.print(`  a flow's own message: ${v.queued.status}${v.queued.error ? ` — ${v.queued.error}` : ''}`);
+        return;
+    }
+    die(`nothing under '${id}' in ${targetLabel(t)} — a coming time may have just happened, and a fire is kept 30 days`);
 }
 /**
- * `octwin automation [--campaigns] [--json]` — the jobs a pack's declarations
- * produced, with their last result, plus the health counts.
+ * `octwin automation [--json]` — the project's rules, each in the server's words, under the week's numbers.
  *
- * Needs `automation:read`. The job list is CAPPED server-side and the counts are
- * computed in SQL, so the header numbers come from `/health` rather than from
- * filtering the page — past the cap a client-side count would depend on the cap
- * instead of the data.
+ * Needs `automation:read`. The words are the console's (`rules/describe.ts` writes each rule as a sentence), so the
+ * terminal says what the Automatic tab says.
  */
 async function cmdAutomation(flags) {
-    if (typeof flags._[0] === 'string' && AUTOMATION_VERBS.has(flags._[0])) {
-        // `campaigns` is a READ that shares the verb slot with the writes.
-        if (flags._[0] !== 'campaigns')
-            return cmdAutomationWrite(flags);
+    const verb = typeof flags._[0] === 'string' ? flags._[0] : null;
+    if (verb && AUTOMATION_WRITES.has(verb))
+        return cmdAutomationWrite(flags);
+    if (verb && !AUTOMATION_VERBS.has(verb)) {
+        die(`unknown automation verb '${verb}' — octwin automation [coming | happened | why <id> | campaigns | run|pause|resume <ruleKey> | send <campaignId>]`);
     }
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/automation`;
     const asJson = flags.json === true;
-    const campaigns = flags._[0] === 'campaigns' || flags.campaigns === true;
-    if (campaigns) {
+    if (verb === 'coming')
+        return automationComing(flags, t);
+    if (verb === 'happened')
+        return automationHappened(flags, t);
+    if (verb === 'why')
+        return automationWhy(flags, t);
+    if (verb === 'campaigns' || flags.campaigns === true) {
         if (!asJson)
             out.print(`→ Reading campaigns from ${targetLabel(t)} …`);
         const { status, json } = await apiGet(`${base}/campaigns?${pagingQs(flags)}`, t);
@@ -4838,50 +5202,51 @@ 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)
-        out.print(`→ Reading automation jobs from ${targetLabel(t)} …`);
-    const [jobs, health] = await Promise.all([
-        apiGet(`${base}/jobs`, t),
-        apiGet(`${base}/health`, t),
-    ]);
-    if (jobs.status !== 200)
-        die(`could not read automation jobs (HTTP ${jobs.status})${errDetail(jobs.json)}${authFailureDetail(jobs.status, url)}`);
+        out.print(`→ Reading the rules of ${targetLabel(t)} …`);
+    const [rules, summary] = await Promise.all([apiGet(`${base}/rules`, t), apiGet(`${base}/summary`, t)]);
+    if (rules.status !== 200)
+        die(`could not read the rules (HTTP ${rules.status})${errDetail(rules.json)}${authFailureDetail(rules.status, url)}`);
+    const s = summary.status === 200 ? summary.json : null;
     if (asJson) {
-        out.result({ jobs: jobs.json, health: health.json });
+        out.result({ summary: s, rules: rules.json?.rules ?? [] });
         return;
     }
-    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`);
-    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.)');
-        return;
+    const list = (rules.json?.rules ?? []);
+    const w = s?.week ?? {};
+    out.print(`Automation in ${targetLabel(t)}: ${list.length} rule(s)`
+        + (s ? `  —  this week ${w.sent ?? 0} sent, ${w.notDelivered ?? 0} not delivered, ${w.failed ?? 0} failed, ${s.counts?.upcoming ?? 0} coming up` : ''));
+    for (const n of (s?.needsLook ?? [])) {
+        out.print(`  ⚠ ${n.rule?.key ?? '?'}: ${n.kind === 'paused' ? 'paused' : n.kind === 'not_delivered' ? `${n.n} not delivered${n.codes?.length ? ` (${n.codes.join(', ')})` : ''}` : `${n.n} failed`}`);
     }
-    for (const j of page.rows) {
-        const r = j.last_result ?? {};
-        const ran = j.last_run_at ? `last ${j.last_run_at}` : 'never ran';
-        const result = j.last_result
-            ? `  matched ${r.matched ?? 0}/acted ${r.acted ?? 0}${(r.errors ?? 0) > 0 ? `/ERRORS ${r.errors}` : ''}`
-            : '';
-        out.print(`  ${String(j.key ?? j.id).padEnd(26)} ${String(j.status).padEnd(7)} ${j.kind}/${j.entity ?? '—'}`
-            + `  every ${j.interval_seconds}s  ${ran}${result}`);
+    if (list.length === 0) {
+        out.print('  (none — a pack writes rules in automation.yaml `rules:`; `octwin deploy` installs them)');
+        return;
     }
-    out.print('\nRun one now:  octwin automation run <jobId>     (jobId = the `key` above, or its uuid)');
-    out.print('Pause/resume: octwin automation pause|resume <jobId>');
-    out.print('Campaigns:    octwin automation campaigns');
+    for (const r of list) {
+        const wk = r.week ?? {};
+        out.print(`  ${String(r.key)}  [${r.paused ? 'paused' : 'on'}]  next ${shortTime(r.next)}`
+            + `  ·  week ${wk.total ?? 0}: ${wk.sent ?? 0} sent, ${wk.notDelivered ?? 0} not delivered, ${wk.failed ?? 0} failed, ${wk.skipped ?? 0} skipped`);
+        out.print(`      ${phraseText(r.sentence)}`);
+    }
+    out.print('\nComing up:     octwin automation coming [--range today|tomorrow|week|all]');
+    out.print('Happened:      octwin automation happened [--chip not_delivered|failed|skipped|moves|tasks] [--period 7d|30d]');
+    out.print('Why one line:  octwin automation why <id>');
+    out.print('Act:           octwin automation pause|resume|run <ruleKey>   (needs automation:write)');
+    out.print('Campaigns:     octwin automation campaigns');
 }
 // ── integrations: declared connections, their credentials, and the delivery log ──
 /** Verbs that act on a connection or a delivery, rather than naming one. */
@@ -5334,8 +5699,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 +5922,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) {
@@ -5466,427 +6038,472 @@ 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 [coming|happened|why <id>|campaigns] [--json]   # the rules in words; coming up; happened, and why
+  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 pause|resume|run <ruleKey> | 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
+    automation: `octwin automation [coming | happened | why <id> | campaigns | --campaigns] [--json]
+  No args = every RULE of the project — each in the platform's own words (the
+  sentence the console's Outbound → Automatic tab shows), on or paused, its week
+  (sent / not delivered / failed / skipped) and its next time — under the week's
+  numbers and what needs a look. Needs automation:read.
 
-  <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.
+  A pack writes rules in automation.yaml \`rules:\`; its older \`segment\` /
+  \`stale_records\` / \`sla_sweep\` jobs and xrm \`on:\` hooks run as rules too,
+  listed under the key they compile to (\`segment:<job key>\`).
 
-  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.
+  READ:
+    octwin automation coming   [--range today|tomorrow|week|all] [--entity e] [--q text] [--cursor c]
+                               # every time still to come — a rule's, or a flow's own message
+    octwin automation happened [--chip all|not_delivered|failed|skipped|moves|tasks] [--period 7d|30d] [--cursor c]
+                               # every fire: its final word, and why a message did not go
+    octwin automation why <id> [--kind timer|fire|queued]
+                               # one line: the rule in words, each step, the words sent
+    octwin automation campaigns [--limit n] [--offset n]
 
-  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)
+  WRITES (automation:write):
+    octwin automation pause|resume <ruleKey>   # paused: its times arm, nothing runs, nothing caught up
+    octwin automation run <ruleKey>            # a rule on a timetable, now
+    octwin automation send <campaignId>        # enqueue a campaign; enqueued != delivered
 
-  retry/cancel answer 409 when the delivery is in the wrong state; the message
+  <ruleKey> is the key the list prints; the key of the older job in your own
+  automation.yaml finds the rule it runs as. A 403 on a write can be an RBAC grant
+  gap rather than a missing scope: the action is re-checked on automation.rule.
+  (Until 0.9.0 this command listed job rows — since the platform ran every pack's
+  automation as rules, those were only its own two sweeps.)`,
+    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.`,
 };
 /**
@@ -5897,36 +6514,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', 'chip', 'cursor', 'entity', 'kind', 'limit', 'offset', 'period', 'q', 'range'] },
+    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;
 /**
@@ -5977,6 +6606,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