octwin-cli 0.1.21 → 0.3.0

package/dist/index.js

@@ -9,9 +9,10 @@
  *
  *   octwin --version | -v           # print the CLI version (+ any upgrade notice)
  *   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
- *   octwin validate [--dir .] [--remote]   # --remote → the platform's FULL schema check, all errors at once
+ *   octwin validate [--dir .] [--remote] [--require-kb]   # --remote → the platform's FULL schema check + lint, all errors at once
  *   octwin login   --url <platformUrl> --token oct_…
  *   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 pull    <packId> [--dir <out>] [--version v] [--force]  # write a DEPLOYED pack's source back to disk
  *   octwin status  [--dir .]        # did my deploy land? which version is live?
@@ -60,7 +61,9 @@ import { applyRenames } from './lib/rename.js';
 import { validatePackBundle } from './lib/validate.js';
 import { loadAllowedRenderKeys, findRenderKeyViolations, describeRenderFinding } from './lib/render-check.js';
 import { loadPrimitiveArgSpecs, findArgViolations, describeArgFinding } from './lib/args-check.js';
+import { describeKbLookup, findPlatformKbDir } from './lib/kb-path.js';
 import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
+import { readPage, morePageHint } from './lib/page.js';
 // The in-package starter template ships alongside `dist/` and `src/` (both one
 // level under the package root), so `../templates/starter` resolves for the
 // built CLI and `tsx` dev alike.
@@ -76,17 +79,64 @@ const VERSION = (() => {
         return '0.0.0';
     }
 })();
+/**
+ * Flags that may be REPEATED, collecting into an array (`--set a=1 --set b=2`).
+ *
+ * An explicit list rather than "collect every repeat", so no existing flag changes
+ * shape: `--limit 5 --limit 9` stays last-wins, and a caller reading `flags.limit`
+ * as a string keeps working. Only field-builders belong here.
+ */
+const REPEATABLE_FLAGS = new Set(['set', 'param']);
+/** Read a repeatable flag as a list, whatever arity it was passed with. */
+function flagList(flags, key) {
+    const v = flags[key];
+    if (Array.isArray(v))
+        return v;
+    if (typeof v === 'string')
+        return [v];
+    return [];
+}
+/**
+ * `--flag value` · `--flag=value` · `--flag` (boolean) · positionals into `_`.
+ *
+ * `--flag=value` support was missing and failed SILENTLY in the worst way: the
+ * whole token became the key, so `--limit=5` set `flags['limit=5'] = true` and
+ * the command ran with its default limit rather than erroring. That is the same
+ * class of bug as the `Page` rename — a wrong result, not a message.
+ */
 function parseFlags(argv) {
     const f = { _: [] };
+    const put = (key, value) => {
+        if (!REPEATABLE_FLAGS.has(key)) {
+            f[key] = value;
+            return;
+        }
+        const prev = f[key];
+        if (prev === undefined)
+            f[key] = typeof value === 'string' ? [value] : value;
+        else if (Array.isArray(prev)) {
+            if (typeof value === 'string')
+                prev.push(value);
+        }
+        else if (typeof prev === 'string' && typeof value === 'string')
+            f[key] = [prev, value];
+        else
+            f[key] = value;
+    };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a.startsWith('--')) {
-            const key = a.slice(2);
+            const body = a.slice(2);
+            const eq = body.indexOf('=');
+            if (eq > 0) {
+                put(body.slice(0, eq), body.slice(eq + 1));
+                continue;
+            }
             const next = argv[i + 1];
             if (next === undefined || next.startsWith('--'))
-                f[key] = true;
+                put(body, true);
             else {
-                f[key] = next;
+                put(body, next);
                 i++;
             }
         }
@@ -119,17 +169,35 @@ function authFailureHint(status, url) {
         : `the token is valid but not authorized here (missing scope, plan feature, or role)`;
 }
 /**
- * The scope (and plan feature, where the route is entitlement-gated) each command's
- * endpoints require — a client-side mirror of the platform's scope registry
- * (`src/platform/core/identity/scopes.ts` `SCOPE_REGISTRY`) narrowed to what the CLI
- * calls. A 403 that names the missing scope is the difference between a two-minute
- * fix (mint a wider token) and a support thread.
+ * Write VERBS need a different scope than the read they share a command with —
+ * `octwin cases` is `cases:read`, `octwin cases note` is `cases:write` — so the
+ * requirement is resolved by `<command> <verb>` first, then by command.
  *
- * `pack:deploy` and `media:generate` have access `special`: they match by DIRECT
- * grant only, so even a `tenant:admin` preset token does NOT confer them
- * (`scopeSatisfies` — the preset branches only reach `:read`/`:write`). That is the
- * single most common "but my token is admin" confusion, hence the explicit note below.
+ * Keyed on the verb rather than duplicating whole commands, because the hint's
+ * whole value is naming the scope that would actually fix the 403.
  */
+const VERB_REQUIREMENTS = {
+    'records create': { scope: 'records:write', feature: 'records' },
+    'records patch': { scope: 'records:write', feature: 'records' },
+    'records stage': { scope: 'records:write', feature: 'records' },
+    'records note': { scope: 'records:write', feature: 'records' },
+    'records tasks': { scope: 'records:read', feature: 'tasks' },
+    'records task': { scope: 'records:write', feature: 'tasks' },
+    'cases assign': { scope: 'cases:write', feature: 'cases' },
+    'cases note': { scope: 'cases:write', feature: 'cases' },
+    'cases transition': { scope: 'cases:write', feature: 'cases' },
+    // `decide --dry-run` hits the PREVIEW route, which is `cases:read`. Naming the
+    // write scope is still the right hint: the committing form is the default.
+    'cases decide': { scope: 'cases:write', feature: 'cases' },
+    'orders transition': { scope: 'orders:write', feature: 'orders' },
+    'orders refund': { scope: 'orders:write', feature: 'orders' },
+    'catalog availability': { scope: 'catalog:write', feature: 'catalog' },
+    'catalog stock': { scope: 'catalog:write', feature: 'catalog' },
+    'scheduling rules': { scope: 'scheduling:read' },
+    'scheduling rule': { scope: 'scheduling:write' },
+    'scheduling exception': { scope: 'scheduling:write' },
+    'agents set': { scope: 'agents:write' },
+};
 const COMMAND_REQUIREMENTS = {
     deploy: { scope: 'pack:deploy' },
     validate: { scope: 'pack:deploy' },
@@ -140,6 +208,7 @@ const COMMAND_REQUIREMENTS = {
     // only source copy printed the generic hint WITHOUT naming the scope to grant.
     pull: { scope: 'pack:deploy' },
     'platform-kb': { scope: 'pack:deploy' },
+    feedback: { scope: 'pack:deploy' },
     media: { scope: 'media:generate' },
     // The plan feature gates RECORD reads, not the entity list (`/xrm/entities` carries only
     // the scope guard) — so the hint says which half it applies to rather than blaming the
@@ -152,14 +221,22 @@ const COMMAND_REQUIREMENTS = {
     catalog: { scope: 'catalog:read', feature: 'catalog' },
     scheduling: { scope: 'scheduling:read' },
     agents: { scope: 'agents:read' },
+    // The route accepts `pack:deploy` too (that is the point of the command), but the
+    // hint names the scope a NON-deploy token would be missing — a `pack:deploy`
+    // holder never sees this line, because they never get the 403.
+    projects: { scope: 'projects:read' },
 };
 /** The command currently running — set once in `main()` so any failure printer can
- *  name the scope that command needs without threading it through every call. */
+ *  name the scope that command needs without threading it through every call.
+ *  Carries the write VERB too (`cases note`), since that is what decides the scope. */
 let CURRENT_COMMAND;
 /** `→ needs the \`orders:read\` scope …` — the requirement line for the running
  *  command, or '' when the command has no declared requirement. */
 function scopeRequirementHint() {
-    const req = CURRENT_COMMAND ? COMMAND_REQUIREMENTS[CURRENT_COMMAND] : undefined;
+    // Most specific first: `<command> <verb>` beats the command's own (read) entry.
+    const req = CURRENT_COMMAND
+        ? (VERB_REQUIREMENTS[CURRENT_COMMAND] ?? COMMAND_REQUIREMENTS[CURRENT_COMMAND.split(' ')[0]])
+        : undefined;
     if (!req)
         return '';
     const special = req.scope === 'pack:deploy' || req.scope === 'media:generate';
@@ -404,8 +481,11 @@ async function notifyIfOutdated() {
 /** A previously-pulled KB's identity in `<packDir>/.octwin/platform-kb/index.json`
  *  (content hash + per-entry index), or null if nothing has been pulled yet. */
 function readLocalKb(packDir) {
+    const kbDir = findPlatformKbDir(packDir); // walks up — a repo-root pull covers every pack under it
+    if (!kbDir)
+        return null;
     try {
-        const idx = JSON.parse(readFileSync(join(packDir, '.octwin', 'platform-kb', 'index.json'), 'utf8'));
+        const idx = JSON.parse(readFileSync(join(kbDir, 'index.json'), 'utf8'));
         return {
             content_hash: typeof idx.content_hash === 'string' ? idx.content_hash : null,
             index: Array.isArray(idx.index) ? idx.index : [],
@@ -501,11 +581,13 @@ function commandTouchesPlatform(command, flags) {
         case 'cases':
         case 'logs':
         case 'whoami':
+        case 'feedback':
         case 'agents':
         case 'orders':
         case 'analytics':
         case 'catalog':
-        case 'scheduling': return true;
+        case 'scheduling':
+        case 'projects': return true;
         default: return false;
     }
 }
@@ -560,22 +642,28 @@ async function cmdValidate(flags) {
     const packDir = resolve(flags.dir ?? '.');
     const { id, version, files, blobs } = localValidate(packDir); // offline structural gate first (fast, no server/token)
     console.log(`✓ ${id}@${version} passes the offline structural check (${Object.keys(files).length} files, ${Object.keys(blobs).length} image(s))`);
-    // Render-intent fields, checked against the pulled KB. Skipped (silently) when
-    // the author hasn't pulled the reference yet — Step 0.5 of the skill says to.
-    const allowedRenderKeys = loadAllowedRenderKeys(packDir);
-    if (allowedRenderKeys) {
-        const findings = Object.entries(files)
-            .filter(([p]) => /\.ya?ml$/i.test(p))
-            .flatMap(([p, body]) => {
-            let doc;
-            try {
-                doc = parseYaml(body);
-            }
-            catch {
-                return [];
-            } // a YAML syntax error is the structural gate's to report
-            return findRenderKeyViolations(doc, p, allowedRenderKeys);
-        });
+    /** Every YAML file in the bundle, parsed once. A syntax error is the structural gate's to report. */
+    const yamlDocs = () => Object.entries(files)
+        .filter(([p]) => /\.ya?ml$/i.test(p))
+        .flatMap(([p, body]) => {
+        try {
+            return [[p, parseYaml(body)]];
+        }
+        catch {
+            return [];
+        }
+    });
+    // Checks that need the pulled KB. Both DEGRADE when it is absent — the KB is a
+    // gitignored cache wiped by every pull, and `platform-kb pull` needs a
+    // `pack:deploy` scope a CI job may not have, so failing hard would break a fresh
+    // clone before the author could act. But a skip is now ANNOUNCED, and remembered:
+    // the ✓ used to print above these blocks unconditionally while the per-check ✓s
+    // lived inside the `if`s, so a KB-less run read as "one check, passed". An entire
+    // backlog batch reached production that way. The defect is the silence, not the skip.
+    const skipped = [];
+    const render = loadAllowedRenderKeys(packDir);
+    if (render.keys) {
+        const findings = yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys));
         if (findings.length) {
             console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -584,23 +672,15 @@ async function cmdValidate(flags) {
         }
         console.log('✓ render intents use only fields the platform renders');
     }
-    // Primitive `args:` keys, same source and same degrade-to-no-op contract.
-    // Cannot see inside a `use:` template body (expansion is the platform's job);
-    // `--remote` covers that.
-    const argSpecs = loadPrimitiveArgSpecs(packDir);
-    if (argSpecs) {
-        const findings = Object.entries(files)
-            .filter(([p]) => /\.ya?ml$/i.test(p))
-            .flatMap(([p, body]) => {
-            let doc;
-            try {
-                doc = parseYaml(body);
-            }
-            catch {
-                return [];
-            }
-            return findArgViolations(doc, p, argSpecs);
-        });
+    else {
+        console.log(`⚠ ${describeKbLookup(render.lookup, 'render-intent fields')}`);
+        skipped.push('render-intent fields');
+    }
+    // Primitive `args:` keys, same source and same contract. Cannot see inside a
+    // `use:` template body (expansion is the platform's job); `--remote` covers that.
+    const args = loadPrimitiveArgSpecs(packDir);
+    if (args.specs) {
+        const findings = yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs));
         if (findings.length) {
             console.error(`✗ ${findings.length} primitive-argument error${findings.length === 1 ? '' : 's'}:`);
             for (const f of findings)
@@ -609,9 +689,26 @@ async function cmdValidate(flags) {
         }
         console.log('✓ primitive arguments match their declared inputs');
     }
+    else {
+        console.log(`⚠ ${describeKbLookup(args.lookup, 'primitive arguments')}`);
+        skipped.push('primitive arguments');
+    }
+    // `--require-kb` is for CI, where a skip nobody reads is worse than a red build.
+    if (skipped.length && flags['require-kb'] === true) {
+        die(`--require-kb: ${skipped.length} check${skipped.length === 1 ? '' : 's'} could not run (${skipped.join(', ')})`);
+    }
     if (flags.remote !== true) {
-        console.log('  Run `octwin validate --remote` to run the platform\'s FULL manifest + flow-DSL validation');
-        console.log('  (all errors at once) before you deploy.');
+        // The LAST line carries the skip. A reader who sees a ✓ and stops there is the
+        // failure mode; a caveat printed ABOVE the ✓ does not fix it.
+        if (skipped.length) {
+            console.log(`\n⚠ ${id}@${version} passed the checks that RAN — ${skipped.join(' and ')} ${skipped.length === 1 ? 'was' : 'were'} skipped.`);
+            console.log('  Run `octwin platform-kb pull` (once, at your repo root — it covers every pack under it),');
+            console.log('  or `octwin validate --remote` to have the platform run everything server-side.');
+        }
+        else {
+            console.log('  Run `octwin validate --remote` to run the platform\'s FULL manifest + flow-DSL validation');
+            console.log('  (all errors at once) before you deploy.');
+        }
         return;
     }
     // Remote: the SAME validation the deploy route runs — manifest `.strict()` +
@@ -1011,7 +1108,17 @@ async function cmdStatus(flags) {
     console.log(`  live on instance  : registered=${json.registered}  loaded=${shortSha(json.loaded_content_sha)}`);
     console.log(`  catalog artifact  : ${shortSha(json.catalog_content_sha)}${json.origin ? `  origin=${json.origin}` : ''}`);
     console.log(`  flows             : ${(json.flows ?? []).join(', ') || '(none)'}`);
-    if (!json.registered) {
+    // 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
+    // the question status is actually asked: can this pack receive a message here?
+    // Dispatch takes the OLDEST active install and ignores the rest, so a second
+    // install is not a warning, it is a pack that will never run.
+    if (json.dispatches === false) {
+        console.log(`\n✗ installed, but project '${t.project ?? '(pinned)'}' dispatches to `
+            + `'${json.dispatches_to ?? '(nothing)'}' — this pack CANNOT receive a message.`);
+        console.log('  One pack per project: the oldest active install wins. Archive the other install to switch.');
+    }
+    else if (!json.registered) {
         console.log('\n… not warm on the instance you hit yet — it loads on the next inbound (chat once, then re-check).');
     }
     else if (json.up_to_date === false) {
@@ -1238,6 +1345,8 @@ async function cmdPlatformKb(flags) {
     console.log(`✓ Pulled the Octwin platform KB → ${outDir}`);
     console.log(`  ${mdCount} markdown docs + ${catalogCount} catalogs (${entryCount} entries, one file each) — reference version ${bundle.version ?? '?'}`);
     console.log('  Start at INDEX.md — it maps every doc and every catalog entry to its file.');
+    console.log('  Every pack UNDER this directory finds it — `octwin validate` walks up to locate it,');
+    console.log('  so one pull at a repo root covers a whole monorepo of packs.');
     // Changelog since the last pull — per-entry hashes tell us WHICH docs/catalogs
     // moved (a schema shape being replaced shows as a `~ changed`), not just a count.
     if (prior?.content_hash) {
@@ -1273,17 +1382,125 @@ async function apiGet(endpoint, t) {
     }
     return { status: res.status, json };
 }
+/**
+ * Send a WRITE to an admin endpoint with the deploy token; returns `{ status, json }`.
+ *
+ * The mirror of `apiGet`, and the reason every write command is three lines: the
+ * `content-type` + `authHeaders` block was inlined at each of the four original
+ * write sites, and fifteen more copies is how one of them ends up subtly different.
+ * A `204` (media delete) has no body to parse, hence the empty-text guard.
+ */
+async function apiSend(method, endpoint, body, t) {
+    const res = await fetchOrDie(endpoint, {
+        method,
+        headers: { 'content-type': 'application/json', ...authHeaders(t) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    }, 'request');
+    const text = await res.text();
+    if (!text)
+        return { status: res.status, json: null };
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = text;
+    }
+    return { status: res.status, json };
+}
+/**
+ * Fail a write with the server's own reason, the auth explanation, and — where it
+ * applies — the RBAC caveat a scope hint structurally cannot cover.
+ *
+ * Record and case writes are re-checked against the SPECIFIC row, so a 403 there
+ * can mean "your token has the scope but your role has no grant on this record",
+ * which is invisible to `COMMAND_REQUIREMENTS`. Saying so is the difference
+ * between a two-minute fix and re-minting a token that was never the problem.
+ */
+function writeFail(what, status, json, url, rbacScoped = false) {
+    if (status === 403 && rbacScoped) {
+        console.error('  → a 403 here can also be an RBAC grant gap: the scope is checked on the token,');
+        console.error('    then the verb is re-checked against THIS record. Check the pack\'s roles.yaml grants.');
+    }
+    die(`could not ${what} (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+}
+/**
+ * Build a fields object from repeated `--set k=v`, plus an optional
+ * `--fields-json` escape hatch for anything nested.
+ *
+ * Values are coerced as JSON scalars (`true` / `false` / `null` / a number),
+ * falling back to the raw string — so `--set price=9.99` sends a number and
+ * `--set name=9 Bakery` sends a string. Anything richer than a scalar belongs in
+ * `--fields-json`, rather than inventing a mini-syntax here.
+ */
+function fieldsFromFlags(flags) {
+    const out = {};
+    const raw = flags['fields-json'];
+    if (typeof raw === 'string') {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            die('--fields-json is not valid JSON');
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            die('--fields-json must be a JSON object');
+        }
+        Object.assign(out, parsed);
+    }
+    for (const pair of flagList(flags, 'set')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            die(`--set expects key=value (got '${pair}')`);
+        const key = pair.slice(0, eq);
+        const val = pair.slice(eq + 1);
+        if (val === 'true')
+            out[key] = true;
+        else if (val === 'false')
+            out[key] = false;
+        else if (val === 'null')
+            out[key] = null;
+        else if (val !== '' && !Number.isNaN(Number(val)) && /^-?\d+(\.\d+)?$/.test(val))
+            out[key] = Number(val);
+        else
+            out[key] = val;
+    }
+    return out;
+}
 /** A progress-line label for the target workspace. The token names the tenant, so
  *  we surface at most the project (when pinned or overridden by `--project`). */
 function targetLabel(t) {
     return t.project ? `project '${t.project}'` : 'your workspace';
 }
+/** `limit` + `offset` as a query string, from the two universal list flags.
+ *  `--offset` exists so `morePageHint`'s "next page" advice is a command the
+ *  author can actually run — every list route already accepted the parameter
+ *  (`parsePaging`), the CLI just never sent it. */
+function pagingQs(flags, defaultLimit = 50) {
+    const limit = flags.limit ?? String(defaultLimit);
+    const offset = flags.offset ?? '';
+    return `limit=${encodeURIComponent(limit)}${offset ? `&offset=${encodeURIComponent(offset)}` : ''}`;
+}
+/**
+ * Verbs that mean "write", not "an entity named this".
+ *
+ * `octwin records <entity>` and `octwin records note <id>` both land in `_[0]`, so
+ * the two shapes genuinely collide. Reserved words win, and they are listed (not
+ * guessed) so the ambiguity is documented rather than emergent — a pack that
+ * declares an entity actually called `note` reaches it via `--entity note`.
+ */
+const RECORD_VERBS = new Set(['create', 'patch', 'stage', 'note', 'tasks', 'task']);
 /** `octwin records [entity] [id]` — inspect the pack's XRM data (needs a `records:read` token). */
 async function cmdRecords(flags) {
+    // A leading reserved word is a write. To READ an entity whose name collides
+    // with one, name it with the flag and pass no positional: `octwin records --entity note`.
+    if (typeof flags._[0] === 'string' && RECORD_VERBS.has(flags._[0]))
+        return cmdRecordsWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
-    const entity = flags._[0];
+    const entity = (typeof flags.entity === 'string' ? flags.entity : flags._[0]);
     const recordId = flags._[1];
     console.log(`→ Reading ${recordId ? `${entity} record ${recordId}` : entity ? `${entity} records` : 'the entity catalog'} from ${targetLabel(t)} …`);
     if (!entity) {
@@ -1308,8 +1525,7 @@ async function cmdRecords(flags) {
         return;
     }
     if (!recordId) {
-        const limit = flags.limit ?? '50';
-        const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&limit=${limit}`, t);
+        const { status, json } = await apiGet(`${base}/xrm/records?entity=${encodeURIComponent(entity)}&${pagingQs(flags)}`, t);
         if (status !== 200) {
             // Always show the server's reason (it names the unknown entity). Cases are
             // casework (worklist), not pack-declared XRM — point at the right command.
@@ -1318,12 +1534,15 @@ async function cmdRecords(flags) {
             }
             die(`could not read records (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
         }
-        const rows = (json?.records ?? []);
-        console.log(`${entity}: ${json?.total ?? rows.length} record(s)`);
-        if (rows.length === 0)
+        const page = readPage(json);
+        console.log(`${entity}: ${page.total ?? page.rows.length} record(s)`);
+        if (page.rows.length === 0)
             console.log('  (none — if you expected data, mint a `records:read` token and check `octwin deploy --seed`)');
-        for (const r of rows)
+        for (const r of page.rows)
             console.log(`  #${r.record_number ?? '?'}  ${r.title ?? '(untitled)'}${r.stage ? `  [${r.stage}]` : ''}  ${r.id}`);
+        const more = morePageHint(page, `octwin records ${entity}`);
+        if (more)
+            console.log(more);
         return;
     }
     const { status, json } = await apiGet(`${base}/xrm/records/${encodeURIComponent(recordId)}`, t);
@@ -1333,6 +1552,186 @@ async function cmdRecords(flags) {
         die(`could not read record (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     console.log(JSON.stringify(json?.record ?? json, null, 2));
 }
+/**
+ * The write half of `octwin records` — create / patch / stage / note, plus tasks.
+ *
+ * Every verb here needs `records:write` (tasks need the `tasks` plan feature, not
+ * `records`), and every one is re-checked by RBAC against the specific record, so
+ * failures route through `writeFail(..., rbacScoped)`.
+ */
+async function cmdRecordsWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p`;
+    const verb = flags._[0];
+    const arg = flags._[1];
+    const readBack = (id) => console.log(`\nRead it back:  octwin records --entity <entity> ${id}`);
+    if (verb === 'create') {
+        const entity = arg ?? die('usage: octwin records create <entity> --set field=value …');
+        const fields = fieldsFromFlags(flags);
+        const body = { entity, fields };
+        if (typeof flags.stage === 'string')
+            body.stage = flags.stage;
+        if (typeof flags.contact === 'string')
+            body.contact_id = flags.contact;
+        console.log(`→ Creating a ${entity} record in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/records`, body, t);
+        if (status !== 200 && status !== 201)
+            writeFail(`create the ${entity} record`, status, json, url, true);
+        if (json?.has_xrm === false)
+            die('this pack declares no XRM entities');
+        const rec = json?.record ?? {};
+        // 200 = the dedupe key matched an existing row; 201 = genuinely new. Saying
+        // "created" for a match would misreport what the pack's `dedupe_by` did.
+        console.log(status === 201
+            ? `✓ Created #${rec.record_number ?? '?'}  ${rec.id ?? ''}`
+            : `✓ Matched an EXISTING record (the entity's dedupe key hit) — #${rec.record_number ?? '?'}  ${rec.id ?? ''}`);
+        if (rec.id)
+            readBack(rec.id);
+        return;
+    }
+    if (verb === 'patch') {
+        const id = arg ?? die('usage: octwin records patch <recordId> --entity <entity> --set field=value …');
+        // The route requires `entity` even on an update — it resolves the validator
+        // from it. A patch without it 400s server-side, so say it here instead.
+        const entity = typeof flags.entity === 'string' ? flags.entity
+            : die('octwin records patch needs --entity <entity> (the route resolves the field validator from it)');
+        const fields = fieldsFromFlags(flags);
+        if (Object.keys(fields).length === 0)
+            die('nothing to patch — pass --set field=value (or --fields-json)');
+        console.log(`→ Patching ${entity} ${id} in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('PATCH', `${base}/xrm/records/${encodeURIComponent(id)}`, { entity, fields }, t);
+        if (status !== 200)
+            writeFail(`patch record ${id}`, status, json, url, true);
+        console.log(`✓ Patched #${json?.record?.record_number ?? '?'}`);
+        readBack(id);
+        return;
+    }
+    if (verb === 'stage') {
+        const id = arg ?? die('usage: octwin records stage <recordId> --to <stage> [--note "..."]');
+        const to = typeof flags.to === 'string' ? flags.to : die('octwin records stage needs --to <stage>');
+        const body = { to_stage: to };
+        if (typeof flags.note === 'string')
+            body.note = flags.note;
+        console.log(`→ Moving ${id} to '${to}' in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/records/${encodeURIComponent(id)}/stage`, body, t);
+        if (status === 400 && Array.isArray(json?.allowed)) {
+            // The route returns the legal targets on an illegal move — the single most
+            // useful thing to show, so don't bury it in the generic error line.
+            console.error(`✗ '${to}' is not a legal move from this record's stage.`);
+            console.error(`  → allowed: ${json.allowed.join(', ') || '(none — terminal stage)'}`);
+            process.exit(1);
+        }
+        if (status !== 200)
+            writeFail(`move record ${id} to '${to}'`, status, json, url, true);
+        console.log(`✓ #${json?.record?.record_number ?? '?'} is now at '${json?.record?.stage ?? to}'`);
+        return;
+    }
+    if (verb === 'note') {
+        const id = arg ?? die('usage: octwin records note <recordId> "the note text"');
+        const note = flags._[2] ?? die('octwin records note needs the note text as the last argument');
+        console.log(`→ Adding a note to ${id} in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/records/${encodeURIComponent(id)}/note`, { note }, t);
+        if (status !== 200)
+            writeFail(`note record ${id}`, status, json, url, true);
+        console.log('✓ Note added to the record timeline.');
+        return;
+    }
+    if (verb === 'tasks') {
+        console.log(`→ Reading open tasks from ${targetLabel(t)} …`);
+        const { status, json } = await apiGet(`${base}/xrm/tasks?${pagingQs(flags)}`, t);
+        if (status !== 200)
+            writeFail('read tasks', status, json, url);
+        if (json?.has_xrm === false) {
+            console.log('This pack declares no XRM entities.');
+            return;
+        }
+        const page = readPage(json);
+        console.log(`Tasks: ${page.total ?? page.rows.length}`);
+        if (page.rows.length === 0)
+            console.log('  (none open)');
+        for (const k of page.rows) {
+            console.log(`  ${k.title ?? '(untitled)'}${k.due_at ? `  due:${k.due_at}` : ''}${k.status ? `  [${k.status}]` : ''}  ${k.id}`);
+        }
+        const more = morePageHint(page, 'octwin records tasks');
+        if (more)
+            console.log(more);
+        console.log('\nClose one:  octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]');
+        return;
+    }
+    if (verb === 'task') {
+        if (arg !== 'complete')
+            die('usage: octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]');
+        const id = flags._[2] ?? die('octwin records task complete needs a <taskId>');
+        const outcome = typeof flags.outcome === 'string' ? flags.outcome : 'done';
+        if (outcome !== 'done' && outcome !== 'cancelled')
+            die(`--outcome must be 'done' or 'cancelled' (got '${outcome}')`);
+        const body = { outcome };
+        if (typeof flags.note === 'string')
+            body.note = flags.note;
+        console.log(`→ Closing task ${id} as '${outcome}' …`);
+        const { status, json } = await apiSend('POST', `${base}/xrm/tasks/${encodeURIComponent(id)}/complete`, body, t);
+        if (status === 404)
+            die(`task '${id}' not found, or already closed`);
+        if (status !== 200)
+            writeFail(`complete task ${id}`, status, json, url, true);
+        console.log(`✓ Task closed (${outcome}).`);
+        return;
+    }
+    die(`unknown records verb '${verb}' — one of: ${[...RECORD_VERBS].join(', ')}`);
+}
+/**
+ * `octwin feedback [--dir .]` — submit the pack's `FEEDBACK.md` to the platform.
+ *
+ * The authoring skill's last step asks for a report bucketed by owner (CLI /
+ * platform / KB). It used to end there: delivery was copy-paste into a chat, so a
+ * report only counted if the author happened to hand it over.
+ *
+ * Attaches the two facts that decide triage and that nobody remembers to state —
+ * the CLI version, and the `content_hash` of the capability reference the author
+ * actually pulled. Most field reports so far were either already fixed in a newer
+ * CLI or written against a stale KB, and both are one line each here.
+ */
+async function cmdFeedback(flags) {
+    const packDir = resolve(flags.dir ?? '.');
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const reportPath = join(packDir, 'FEEDBACK.md');
+    if (!existsSync(reportPath)) {
+        die(`no FEEDBACK.md in ${packDir}\n`
+            + '  → the octwin-pack skill writes one in Step 4 (Report your authoring experience).\n'
+            + '    Group findings by owner — A · CLI, B · Platform, C · Skill/KB — then run this again.');
+    }
+    const report = readFileSync(reportPath, 'utf8');
+    if (!report.trim())
+        die('FEEDBACK.md is empty — nothing to submit');
+    // Pack identity from the manifest, not from the report's prose: the metadata
+    // block is a convention the skill owns and an author may reword it.
+    const manifestPath = join(packDir, 'manifest.yaml');
+    if (!existsSync(manifestPath))
+        die('no manifest.yaml in the pack directory (run from your pack dir or pass --dir)');
+    const doc = parseYaml(readFileSync(manifestPath, 'utf8'));
+    const packId = typeof doc?.id === 'string' ? doc.id : die('manifest.yaml must declare a string `id`');
+    const packVersion = typeof doc?.version === 'string' ? doc.version : undefined;
+    const kbHash = readLocalKb(packDir)?.content_hash ?? undefined;
+    console.log(`→ Submitting ${Math.round(Buffer.byteLength(report, 'utf8') / 1024)}KB of feedback on ${packId} to ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('POST', `${url}/api/self/p/packs/feedback`, {
+        pack_id: packId,
+        ...(packVersion ? { pack_version: packVersion } : {}),
+        report_md: report,
+        cli_version: VERSION,
+        ...(kbHash ? { kb_content_hash: kbHash } : {}),
+    }, t);
+    if (status !== 201 && status !== 200)
+        writeFail('submit feedback', status, json, url);
+    console.log('✓ Thanks — your report reached the platform team.');
+    if (!kbHash) {
+        // Without it, triage cannot tell "the platform is wrong" from "you were
+        // reading a stale reference", which is the single most common answer.
+        console.log('  ⓘ no local capability reference found, so the report carries no KB version.');
+        console.log('    Pull it before your next session: octwin platform-kb');
+    }
+}
 /** `octwin logs [conversationId] [--as <handle>] [--json]` — list conversations
  *  or show one's event timeline (full text + the renders each turn produced). */
 async function cmdLogs(flags) {
@@ -1807,9 +2206,106 @@ async function cmdMedia(flags) {
         console.log(`  saved → ${out}`);
     console.log(`  Send it into a chat: octwin chat "here you go" --media ${out ?? r.media_id} --as <handle>`);
 }
+/** Reserved leading words on `octwin cases` — see `RECORD_VERBS` for the rule. */
+const CASE_VERBS = new Set(['assign', 'note', 'transition', 'decide']);
+/**
+ * The write half of `octwin cases` — assign / note / transition / decide.
+ *
+ * `decide --dry-run` routes to the PREVIEW endpoint, which sits behind `cases:read`
+ * rather than `cases:write`: it renders the customer-facing copy and the resulting
+ * status without committing. That makes "show me what this disposition would do"
+ * safe to run with a read-only token, which is exactly when an author wants it.
+ */
+async function cmdCasesWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p`;
+    const verb = flags._[0];
+    const id = flags._[1] ?? die(`usage: octwin cases ${verb} <caseId> …`);
+    const readBack = () => console.log(`\nRead it back:  octwin cases ${id}`);
+    if (verb === 'assign') {
+        // `--to none` unassigns (the route takes null); anything else must carry the
+        // principal kind, because a bare uuid cannot say user-or-team.
+        const to = typeof flags.to === 'string' ? flags.to
+            : die('usage: octwin cases assign <caseId> --to user:<uuid>|team:<uuid>|none');
+        const assignee = to === 'none' ? null : to;
+        if (assignee !== null && !/^(user|team):/.test(assignee)) {
+            die(`--to must be 'user:<uuid>', 'team:<uuid>' or 'none' (got '${to}')`);
+        }
+        console.log(`→ ${assignee === null ? 'Unassigning' : `Assigning to ${assignee}`} case ${id} …`);
+        const { status, json } = await apiSend('PATCH', `${base}/cases/${encodeURIComponent(id)}/assign`, { assignee }, t);
+        if (status !== 200)
+            writeFail(`assign case ${id}`, status, json, url, true);
+        console.log(assignee === null ? '✓ Unassigned.' : `✓ Assigned to ${json?.assignee ?? assignee}.`);
+        return;
+    }
+    if (verb === 'note') {
+        const note = flags._[2] ?? die('usage: octwin cases note <caseId> "the note text"');
+        console.log(`→ Adding a note to case ${id} …`);
+        const { status, json } = await apiSend('POST', `${base}/cases/${encodeURIComponent(id)}/note`, { note }, t);
+        if (status !== 200)
+            writeFail(`note case ${id}`, status, json, url, true);
+        console.log('✓ Note added to the case timeline.');
+        readBack();
+        return;
+    }
+    if (verb === 'transition') {
+        const to = typeof flags.to === 'string' ? flags.to
+            : die('usage: octwin cases transition <caseId> --to <status> [--note "..."]');
+        const body = { to_status: to };
+        if (typeof flags.note === 'string')
+            body.note = flags.note;
+        console.log(`→ Moving case ${id} to '${to}' …`);
+        const { status, json } = await apiSend('POST', `${base}/cases/${encodeURIComponent(id)}/transition`, body, t);
+        if (status !== 200) {
+            // The case detail read carries the legal targets; point at it rather than
+            // leaving the author to guess the vocabulary.
+            if (status === 400)
+                console.error(`  → legal targets for this case: octwin cases ${id}  (see its workflow)`);
+            writeFail(`move case ${id} to '${to}'`, status, json, url, true);
+        }
+        console.log(`✓ Case is now '${json?.case?.status ?? to}'.`);
+        return;
+    }
+    // decide
+    const action = typeof flags.action === 'string' ? flags.action
+        : die('usage: octwin cases decide <caseId> --action <action> [--param k=v] [--note "..."] [--dry-run]');
+    const params = {};
+    for (const pair of flagList(flags, 'param')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            die(`--param expects key=value (got '${pair}')`);
+        params[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    const dryRun = flags['dry-run'] === true;
+    const body = { action, ...(Object.keys(params).length ? { params } : {}) };
+    if (!dryRun && typeof flags.note === 'string')
+        body.internal_note = flags.note;
+    console.log(`→ ${dryRun ? 'Previewing' : 'Applying'} '${action}' on case ${id} …`);
+    const endpoint = `${base}/cases/${encodeURIComponent(id)}/decision${dryRun ? '/preview' : ''}`;
+    const { status, json } = await apiSend('POST', endpoint, body, t);
+    if (status === 404)
+        die(`case '${id}' not found`);
+    if (status !== 200) {
+        console.error(`  → the case's applicable actions are listed by: octwin cases ${id}`);
+        writeFail(`${dryRun ? 'preview' : 'apply'} '${action}' on case ${id}`, status, json, url, true);
+    }
+    if (dryRun) {
+        console.log('Preview (nothing was committed):');
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    console.log(`✓ Applied '${action}' — case is now '${json?.case?.status ?? '?'}'.`);
+    // `notified` is the customer-facing half; silence here usually means the
+    // disposition had no message template, which is easy to mistake for a failure.
+    console.log(json?.notified ? '  ✓ the customer was notified.' : '  ⓘ no customer notification was sent by this action.');
+    readBack();
+}
 /** `octwin cases [caseId] [--queues]` — inspect casework (support tickets):
  *  the aggregate inbox, one case + its timeline, or the queue list. */
 async function cmdCases(flags) {
+    if (typeof flags._[0] === 'string' && CASE_VERBS.has(flags._[0]))
+        return cmdCasesWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p`;
@@ -1841,22 +2337,24 @@ async function cmdCases(flags) {
         return;
     }
     if (!caseId) {
-        const limit = flags.limit ?? '50';
-        const { status, json } = await apiGet(`${base}/cases?limit=${limit}`, t);
+        const { status, json } = await apiGet(`${base}/cases?${pagingQs(flags)}`, t);
         if (status !== 200)
             caseFail('cases', status, json);
         if (asJson) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        const rows = (json?.cases ?? []);
-        console.log(`Cases in ${targetLabel(t)}: ${json?.total ?? rows.length} total`);
-        if (rows.length === 0)
+        const page = readPage(json);
+        console.log(`Cases in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
+        if (page.rows.length === 0)
             console.log('  (none)');
-        for (const c of rows) {
+        for (const c of page.rows) {
             const sla = c.sla_due_at ? `  sla:${c.sla_due_at}` : '';
             console.log(`  #${c.case_number ?? '?'}  ${c.type}  [${c.status}]  ${c.priority}${c.queue_key ? `  q:${c.queue_key}` : ''}${sla}  ${c.id}`);
         }
+        const more = morePageHint(page, 'octwin cases');
+        if (more)
+            console.log(more);
         console.log('\nOne case + timeline:  octwin cases <caseId>    queues:  octwin cases --queues');
         return;
     }
@@ -1951,7 +2449,119 @@ function printGoverned(label, g) {
 /** `octwin agents [agentRef] [--prompt] [--json]` — the agent roster with the
  *  EFFECTIVE model/memory settings and which layer won, plus (`--prompt`) the exact
  *  system prompt the LLM sees for this project. Needs an `agents:read` token. */
+/**
+ * `octwin agents set <ref> …` — the per-project agent override row.
+ *
+ * Writes only what was passed, so an unmentioned setting is left alone rather than
+ * reset to a default. `--enable-tool` / `--disable-tool` edit `config_json.tools`,
+ * a `{ toolId: boolean }` map where absent means ON — so disabling is the only
+ * thing that needs recording, and the map is read-modify-written to avoid dropping
+ * a sibling entry.
+ */
+async function cmdAgentsWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/agents`;
+    const ref = flags._[1]
+        ?? die('usage: octwin agents set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t] [--enabled true|false]');
+    const patch = {};
+    if (typeof flags.model === 'string')
+        patch.model = flags.model;
+    if (typeof flags.overlay === 'string')
+        patch.instructions_overlay = flags.overlay === 'none' ? null : flags.overlay;
+    if (typeof flags.enabled === 'string') {
+        if (flags.enabled !== 'true' && flags.enabled !== 'false')
+            die("--enabled must be 'true' or 'false'");
+        patch.enabled = flags.enabled === 'true';
+    }
+    const on = flagList(flags, 'enable-tool');
+    const off = flagList(flags, 'disable-tool');
+    if (on.length || off.length) {
+        // Read first: `config_json` is replaced wholesale by the route, so a blind
+        // write would drop every tool decision not named on this command line.
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(ref)}`, t);
+        if (status === 404)
+            die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+        if (status !== 200)
+            writeFail(`read agent ${ref}`, status, json, url);
+        const cfg = { ...(json?.agent?.config_json ?? json?.config_json ?? {}) };
+        const tools = { ...(cfg.tools ?? {}) };
+        const known = (json?.agent?.available_tools ?? json?.available_tools);
+        for (const id of [...on, ...off]) {
+            if (Array.isArray(known) && known.length && !known.includes(id)) {
+                die(`'${id}' is not a tool on ${ref} — available: ${known.join(', ')}`);
+            }
+        }
+        for (const id of on)
+            tools[id] = true;
+        for (const id of off)
+            tools[id] = false;
+        cfg.tools = tools;
+        patch.config_json = cfg;
+    }
+    if (Object.keys(patch).length === 0) {
+        die('nothing to change — pass --model, --enabled, --overlay, --enable-tool or --disable-tool');
+    }
+    console.log(`→ Updating agent ${ref} in ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('PATCH', `${base}/${encodeURIComponent(ref)}`, patch, t);
+    if (status === 404)
+        die(`agent '${ref}' not found — run \`octwin agents\` for the roster`);
+    if (status === 403 && patch.model !== undefined) {
+        die(`this workspace does not expose model overrides — drop --model (the platform default governs)${errDetail(json)}`);
+    }
+    if (status !== 200)
+        writeFail(`update agent ${ref}`, status, json, url);
+    console.log(`✓ Updated ${ref}.`);
+    console.log(`\nRead it back (and see WHICH layer won):  octwin agents ${ref}`);
+}
+/**
+ * `octwin projects` — which `--project <slug>` values this token can actually name.
+ *
+ * Every project-scoped command takes a `--project` slug, and until now nothing
+ * printed the list: an author whose token was not pinned had to guess, and a wrong
+ * guess 404s identically to a project that exists but has no install. Tenant-scoped
+ * (`/api/self/t/`), unlike `agents` — the list is a property of the workspace.
+ */
+async function cmdProjects(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const asJson = flags.json === true;
+    const archived = flags.archived === true;
+    if (!asJson)
+        console.log(`→ Reading projects from ${targetLabel(t)} …`);
+    const qs = archived ? '?include_archived=1' : '';
+    const { status, json } = await apiGet(`${url}/api/self/t/projects${qs}`, t);
+    if (status !== 200)
+        die(`could not read projects (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
+    if (asJson) {
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    const projects = (json?.projects ?? []);
+    if (projects.length === 0) {
+        console.log(archived
+            ? 'No projects at all — create one in the console (Workspace → Projects).'
+            : 'No active projects. Try `octwin projects --archived` before creating one.');
+        return;
+    }
+    // The route already computes the plan cap; inventing a second "N of M" here
+    // would drift from the 402 the POST handler actually enforces.
+    const max = json?.limits?.max_projects ?? null;
+    const plan = json?.limits?.plan_label ? ` · ${json.limits.plan_label} plan` : '';
+    console.log(`Projects in ${json?.tenant?.slug ?? targetLabel(t)} — ${projects.length}${max ? ` of ${max}` : ''}${plan}:`);
+    for (const p of projects) {
+        const flags_ = [];
+        if (p.status && p.status !== 'active')
+            flags_.push(p.status.toUpperCase());
+        console.log(`  ${p.slug}${flags_.length ? `  [${flags_.join(', ')}]` : ''}${p.name ? `  "${p.name}"` : ''}`);
+    }
+    console.log('\nUse one as:  octwin deploy --project <slug>');
+    if (!archived)
+        console.log('Archived too: octwin projects --archived');
+}
 async function cmdAgents(flags) {
+    if (flags._[0] === 'set')
+        return cmdAgentsWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/agents`;
@@ -2048,7 +2658,77 @@ function printPaymentNote(paymentStatus) {
 /** `octwin orders [referenceId] [--status s] [--payment p] [--limit n] [--json]` —
  *  the orders a conversation created: money breakdown, payment state, allowed
  *  transitions. Needs an `orders:read` token + the `orders` plan feature. */
+/** Reserved leading words on `octwin orders`. A reference_id is opaque but never these. */
+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`).
+ */
+async function cmdOrdersWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/orders`;
+    const verb = flags._[0];
+    const ref = flags._[1]
+        ?? die(`usage: octwin orders ${verb} <reference_id> …   (the opaque reference_id, not the #number)`);
+    if (verb === 'transition') {
+        const to = typeof flags.to === 'string' ? flags.to
+            : die('usage: octwin orders transition <reference_id> --to <status>');
+        console.log(`→ Moving order ${ref} to '${to}' …`);
+        const { status, json } = await apiSend('POST', `${base}/${encodeURIComponent(ref)}/transition`, { to_status: to }, t);
+        if (status === 404)
+            die(`order '${ref}' not found (pass the opaque reference_id, not the #number)`);
+        if (status === 409) {
+            console.error(`✗ '${to}' is not a legal move for this order.`);
+            if (Array.isArray(json?.transitions))
+                console.error(`  → allowed: ${json.transitions.join(', ') || '(none)'}`);
+            else
+                console.error(`  → see the allowed set: octwin orders ${ref}`);
+            process.exit(1);
+        }
+        if (status !== 200)
+            writeFail(`move order ${ref} to '${to}'`, status, json, url);
+        console.log(`✓ Order is now '${json?.order?.status ?? to}'.`);
+        return;
+    }
+    // refund — irreversible, and money. `--force` rather than a prompt: the CLI is
+    // non-interactive by construction (same reasoning as `octwin pull --force`).
+    if (flags.force !== true) {
+        die(`refunding is irreversible and moves money — re-run with --force:\n  octwin orders refund ${ref} --force`);
+    }
+    const body = {};
+    if (typeof flags.reason === 'string')
+        body.reason = flags.reason;
+    if (flags['mark-returned'] === true)
+        body.mark_returned = true;
+    console.log(`→ Refunding order ${ref} …`);
+    const { status, json } = await apiSend('POST', `${base}/${encodeURIComponent(ref)}/refund`, body, t);
+    if (status === 404)
+        die(`order '${ref}' not found`);
+    if (status === 409)
+        die(`order '${ref}' cannot be refunded — only a payment in 'captured' state can be${errDetail(json)}`);
+    if (status !== 200)
+        writeFail(`refund order ${ref}`, status, json, url);
+    // THE trap: the route answers 200 even when the gateway REFUSED — the verdict
+    // is in `gateway`. Reporting the 200 as success would tell an operator money
+    // moved when it did not, so read the gateway result and exit non-zero on refusal.
+    const gw = json?.gateway;
+    const refused = gw != null && (gw.ok === false || gw.status === 'failed' || gw.status === 'error');
+    console.log(`  order status : ${json?.order?.status ?? '?'} / ${json?.order?.payment_status ?? '?'}`);
+    if (gw != null)
+        console.log(`  gateway      : ${gw.status ?? (gw.ok === false ? 'failed' : 'ok')}${gw.error || gw.message ? ` — ${gw.error ?? gw.message}` : ''}`);
+    if (refused) {
+        console.error('\n✗ the PAYMENT GATEWAY refused the refund — the order was updated but no money moved.');
+        process.exit(1);
+    }
+    console.log('✓ Refund accepted.');
+}
 async function cmdOrders(flags) {
+    if (typeof flags._[0] === 'string' && ORDER_VERBS.has(flags._[0]))
+        return cmdOrdersWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/orders`;
@@ -2058,6 +2738,8 @@ async function cmdOrders(flags) {
         console.log(`→ Reading ${referenceId ? `order ${referenceId}` : 'orders'} from ${targetLabel(t)} …`);
     if (!referenceId) {
         const q = new URLSearchParams({ limit: flags.limit ?? '50' });
+        if (typeof flags.offset === 'string')
+            q.set('offset', flags.offset);
         if (typeof flags.status === 'string')
             q.set('status', flags.status);
         if (typeof flags.payment === 'string')
@@ -2069,14 +2751,17 @@ async function cmdOrders(flags) {
             console.log(JSON.stringify(json, null, 2));
             return;
         }
-        const rows = (json?.orders ?? []);
-        console.log(`Orders in ${targetLabel(t)}: ${json?.total ?? rows.length} total`);
-        if (rows.length === 0)
+        const page = readPage(json);
+        console.log(`Orders in ${targetLabel(t)}: ${page.total ?? page.rows.length} total`);
+        if (page.rows.length === 0)
             console.log('  (none — drive a cart to `cart_submit` with `octwin chat`, or seed demo data)');
-        for (const o of rows) {
+        for (const o of page.rows) {
             const who = o.contact?.channel_contact_handle ?? o.contact?.display_name ?? '—';
             console.log(`  #${o.record_number}  ${o.status}/${o.payment_status}  ${fmtMinor(o.total_minor, o.currency)}  ${who}  ${o.reference_id}`);
         }
+        const more = morePageHint(page, 'octwin orders');
+        if (more)
+            console.log(more);
         console.log('\nOne order + its money breakdown:  octwin orders <reference_id>');
         return;
     }
@@ -2160,8 +2845,7 @@ async function cmdAnalytics(flags) {
     if (stage) {
         if (!asJson)
             console.log(`→ Reading ${entity} records at stage '${stage}' from ${targetLabel(t)} …`);
-        const limit = flags.limit ?? '50';
-        const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/stages/${encodeURIComponent(stage)}/records?limit=${limit}`, t);
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(entity)}/stages/${encodeURIComponent(stage)}/records?${pagingQs(flags)}`, t);
         if (status === 404)
             die(`unknown stage '${stage}' for '${entity}'${errDetail(json)}`);
         if (status !== 200)
@@ -2174,12 +2858,15 @@ async function cmdAnalytics(flags) {
             printNoAnalyticsData(entity);
             return;
         }
-        const rows = (json?.records ?? []);
-        console.log(`${entity} at '${stage}' (live snapshot): ${json?.total ?? rows.length} record(s)`);
-        for (const r of rows) {
+        const page = readPage(json);
+        console.log(`${entity} at '${stage}' (live snapshot): ${page.total ?? page.rows.length} record(s)`);
+        for (const r of page.rows) {
             const who = r.channel_contact_handle ?? r.display_name ?? '—';
             console.log(`  #${r.record_number ?? '?'}  ${r.title ?? '(untitled)'}  ${who}${r.completed ? '  [completed]' : ''}  ${r.record_id}`);
         }
+        const more = morePageHint(page, `octwin analytics ${entity} --stage ${stage}`);
+        if (more)
+            console.log(more);
         return;
     }
     if (!asJson)
@@ -2240,10 +2927,67 @@ async function cmdAnalytics(flags) {
     }
 }
 // ── catalog: the commerce products + their WhatsApp binding ──────────────────
+/** Reserved leading words on `octwin catalog`. */
+const CATALOG_VERBS = new Set(['availability', 'stock']);
+/**
+ * The write half of `octwin catalog` — the two per-SKU levers a pack author needs
+ * to exercise a commerce flow (is it sellable, and how many are there).
+ *
+ * Creating/deleting products and the Meta Graph binding/sync/pull are deliberately
+ * NOT here — see docs/BACKLOG.md. Those are catalog *operations*, need a bound
+ * access token to be meaningful, and belong to the console.
+ */
+async function cmdCatalogWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/catalog`;
+    const verb = flags._[0];
+    const sku = flags._[1] ?? die(`usage: octwin catalog ${verb} <retailerId> …`);
+    if (verb === 'availability') {
+        const to = typeof flags.to === 'string' ? flags.to
+            : die("usage: octwin catalog availability <retailerId> --to 'in stock'|'out of stock'|…");
+        console.log(`→ Setting ${sku} availability to '${to}' …`);
+        const { status, json } = await apiSend('PATCH', `${base}/${encodeURIComponent(sku)}/availability`, { availability: to }, t);
+        if (status !== 200)
+            writeFail(`set availability for '${sku}'`, status, json, url);
+        console.log(`✓ ${sku} is now '${to}'.`);
+        return;
+    }
+    // stock — read when no --set-on-hand, write when there is.
+    const raw = flags['set-on-hand'];
+    if (raw === undefined) {
+        const { status, json } = await apiGet(`${base}/${encodeURIComponent(sku)}/stock`, t);
+        if (status === 404)
+            die(`product '${sku}' not found`);
+        if (status !== 200)
+            writeFail(`read stock for '${sku}'`, status, json, url);
+        // null is a real answer, and a different one from zero: the SKU is not
+        // inventory-tracked, so it is always sellable.
+        console.log(json?.stock == null
+            ? `${sku}: not inventory-tracked (always sellable)`
+            : `${sku}: on_hand=${json.stock.on_hand ?? '?'}  reserved=${json.stock.reserved ?? 0}`);
+        return;
+    }
+    const onHand = Number(raw);
+    if (!Number.isInteger(onHand) || onHand < 0)
+        die(`--set-on-hand must be a non-negative integer (got '${String(raw)}')`);
+    console.log(`→ Setting ${sku} on_hand to ${onHand} …`);
+    const { status, json } = await apiSend('PUT', `${base}/${encodeURIComponent(sku)}/stock`, { on_hand: onHand }, t);
+    if (status === 404)
+        die(`product '${sku}' not found`);
+    if (status === 409) {
+        die(`refused: ${onHand} is below the units already RESERVED for open carts/orders${errDetail(json)}`);
+    }
+    if (status !== 200)
+        writeFail(`set stock for '${sku}'`, status, json, url);
+    console.log(`✓ ${sku}: on_hand=${json?.stock?.on_hand ?? onHand}  reserved=${json?.stock?.reserved ?? 0}`);
+}
 /** `octwin catalog [--readiness] [--json]` — the `product` records a commerce pack
  *  sells, their stock, and the WhatsApp catalog binding. Needs `catalog:read` + the
  *  `catalog` plan feature. */
 async function cmdCatalog(flags) {
+    if (typeof flags._[0] === 'string' && CATALOG_VERBS.has(flags._[0]))
+        return cmdCatalogWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/catalog`;
@@ -2274,15 +3018,17 @@ async function cmdCatalog(flags) {
     }
     if (!asJson)
         console.log(`→ Reading the product catalog from ${targetLabel(t)} …`);
-    const { status, json } = await apiGet(base, t);
+    const { status, json } = await apiGet(`${base}?${pagingQs(flags)}`, t);
     if (status !== 200)
         die(`could not read the catalog (HTTP ${status})${errDetail(json)}${authFailureDetail(status, url)}`);
     if (asJson) {
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    const products = (json?.products ?? []);
-    console.log(`Products in ${targetLabel(t)}: ${products.length}`);
+    const page = readPage(json);
+    const products = page.rows;
+    // The route reports the catalog-wide total; `products.length` is only this page.
+    console.log(`Products in ${targetLabel(t)}: ${page.total ?? products.length}`);
     if (products.length === 0)
         console.log('  (none — a commerce pack seeds `product` records, or add them in the console Catalog)');
     for (const p of products) {
@@ -2291,6 +3037,9 @@ async function cmdCatalog(flags) {
         console.log(`  ${String(p.retailer_id).padEnd(20)} ${String(p.name ?? '').padEnd(28)} ${fmtAmount(p.price, p.currency)}`
             + `  avail=${p.availability}  stock=${stock}  sync=${p.sync_status ?? '—'}`);
     }
+    const morePages = morePageHint(page, 'octwin catalog');
+    if (morePages)
+        console.log(morePages);
     // A binding row can exist with no catalog_id yet (a WABA is configured but no Meta
     // catalog picked) — that is "not bound" for selling purposes, so say so.
     const b = json?.binding;
@@ -2300,10 +3049,121 @@ async function cmdCatalog(flags) {
             + ' — the catalog works web-only (`--readiness` explains what Meta needs).');
 }
 // ── scheduling: the availability engine + a slot preview ─────────────────────
+/** Reserved leading words on `octwin scheduling`. */
+const SCHEDULING_VERBS = new Set(['rules', 'rule', 'exception']);
+/**
+ * The write half of `octwin scheduling` — the availability rules and exceptions
+ * behind the slots `octwin scheduling --slots` computes.
+ *
+ * `rules` (the LIST) ships with them on purpose: the deletes take a rule id, and
+ * without a way to see one there was no path from "a rule exists" to "remove it".
+ */
+async function cmdSchedulingWrite(flags) {
+    const t = resolveTarget(flags);
+    const { url } = t;
+    const base = `${url}/api/self/p/scheduling`;
+    const verb = flags._[0];
+    const asJson = flags.json === true;
+    if (verb === 'rules') {
+        const resource = typeof flags.resource === 'string' ? flags.resource
+            : die('usage: octwin scheduling rules --resource <resourceRecordId>');
+        if (!asJson)
+            console.log(`→ Reading availability for resource ${resource} …`);
+        const { status, json } = await apiGet(`${base}/availability?resource_id=${encodeURIComponent(resource)}`, t);
+        if (status !== 200)
+            writeFail('read availability', status, json, url);
+        if (asJson) {
+            console.log(JSON.stringify(json, null, 2));
+            return;
+        }
+        if (json?.has_scheduling === false) {
+            console.log('This pack declares no scheduling.');
+            return;
+        }
+        const rules = (json?.rules ?? []);
+        const exceptions = (json?.exceptions ?? []);
+        const DOW = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+        console.log(`Rules: ${rules.length}`);
+        for (const r of rules) {
+            console.log(`  ${DOW[r.dow] ?? `dow${r.dow}`}  ${r.start_time}–${r.end_time}`
+                + `  slot=${r.slot_minutes ?? '—'}m  cap=${r.capacity ?? '—'}  ${r.id}`);
+        }
+        console.log(`Exceptions: ${exceptions.length}`);
+        for (const e of exceptions) {
+            console.log(`  ${e.exception_date}  ${e.kind}${e.start_time ? `  ${e.start_time}–${e.end_time}` : ''}  ${e.id}`);
+        }
+        console.log('\nRemove one:  octwin scheduling rule rm <ruleId>   ·   octwin scheduling exception rm <exceptionId>');
+        return;
+    }
+    const sub = flags._[1];
+    const isRule = verb === 'rule';
+    const noun = isRule ? 'rule' : 'exception';
+    const path = isRule ? 'rules' : 'exceptions';
+    if (sub === 'rm') {
+        const id = flags._[2] ?? die(`usage: octwin scheduling ${noun} rm <${noun}Id>`);
+        console.log(`→ Removing ${noun} ${id} …`);
+        const { status, json } = await apiSend('DELETE', `${base}/availability/${path}/${encodeURIComponent(id)}`, undefined, t);
+        if (status === 404)
+            die(`${noun} '${id}' not found`);
+        if (status !== 200)
+            writeFail(`remove ${noun} ${id}`, status, json, url);
+        console.log(`✓ ${noun[0].toUpperCase()}${noun.slice(1)} removed.`);
+        return;
+    }
+    if (sub !== 'add') {
+        die(isRule
+            ? 'usage: octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00 [--slot-minutes 30] [--capacity 1]\n       octwin scheduling rule rm <ruleId>'
+            : 'usage: octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra [--start 09:00 --end 13:00]\n       octwin scheduling exception rm <exceptionId>');
+    }
+    const resource = typeof flags.resource === 'string' ? flags.resource
+        : die(`octwin scheduling ${noun} add needs --resource <resourceRecordId>`);
+    const body = { resource_id: resource };
+    if (typeof flags['slot-minutes'] === 'string')
+        body.slot_minutes = Number(flags['slot-minutes']);
+    if (typeof flags.capacity === 'string')
+        body.capacity = Number(flags.capacity);
+    if (typeof flags.start === 'string')
+        body.start_time = flags.start;
+    if (typeof flags.end === 'string')
+        body.end_time = flags.end;
+    if (isRule) {
+        const dowRaw = flags.dow;
+        if (typeof dowRaw !== 'string')
+            die('octwin scheduling rule add needs --dow <0-6>  (0 = Sunday)');
+        const dow = Number(dowRaw);
+        if (!Number.isInteger(dow) || dow < 0 || dow > 6)
+            die(`--dow must be an integer 0-6, 0 = Sunday (got '${dowRaw}')`);
+        body.dow = dow;
+        if (!body.start_time || !body.end_time)
+            die('octwin scheduling rule add needs --start HH:MM and --end HH:MM');
+    }
+    else {
+        const date = typeof flags.date === 'string' ? flags.date
+            : die('octwin scheduling exception add needs --date YYYY-MM-DD');
+        const kind = typeof flags.kind === 'string' ? flags.kind
+            : die("octwin scheduling exception add needs --kind closed|extra");
+        if (kind !== 'closed' && kind !== 'extra')
+            die(`--kind must be 'closed' or 'extra' (got '${kind}')`);
+        body.exception_date = date;
+        body.kind = kind;
+    }
+    console.log(`→ Adding a ${noun} for resource ${resource} …`);
+    const { status, json } = await apiSend('POST', `${base}/availability/${path}`, body, t);
+    if (status !== 201 && status !== 200)
+        writeFail(`add the ${noun}`, status, json, url);
+    if (json?.has_scheduling === false)
+        die('this pack declares no scheduling');
+    const created = json?.rule ?? json?.exception ?? {};
+    console.log(`✓ ${noun[0].toUpperCase()}${noun.slice(1)} added — ${created.id ?? '(no id returned)'}`);
+    console.log(`\nSee it:  octwin scheduling rules --resource ${resource}`);
+    console.log(`Verify the slots it produces:  octwin scheduling --slots ${resource}`);
+}
 /** `octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n] [--json]`
  *  — the scheduling engine's state, or the computed slots for one bookable resource
  *  (the verification the `--seed` availability fan-out was missing). `scheduling:read`. */
 async function cmdScheduling(flags) {
+    if (typeof flags._[0] === 'string' && SCHEDULING_VERBS.has(flags._[0]))
+        return cmdSchedulingWrite(flags);
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/scheduling`;
@@ -2368,9 +3228,10 @@ function help() {
 
   octwin --version                                      # print the CLI version (+ any upgrade notice)
   octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
-  octwin validate [--dir .] [--remote]                  # --remote runs the platform's FULL schema check (all errors at once)
+  octwin validate [--dir .] [--remote] [--require-kb]   # --remote runs the platform's FULL schema check + lint (all errors at once)
   octwin login   --url <platformUrl> --token oct_…      # a deploy token from the console
   octwin whoami  [--url <url>] [--tenant <slug>]         # verify the token works
+  octwin projects [--archived] [--json]                  # the --project slugs this token can name
   octwin deploy  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   octwin status  [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>]
   octwin pull    <packId> [--dir <out>] [--version <v>] [--force]  # write a DEPLOYED pack's source back to disk (the inverse of deploy)
@@ -2386,6 +3247,17 @@ function help() {
   octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
   octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   octwin test    [--dir .]                               # = validate --remote (the full platform check)
+  octwin feedback [--dir .]                              # submit this pack's FEEDBACK.md to the platform team
+
+Writes — exercise the state your pack creates (each needs the matching :write scope):
+  octwin records create <entity> --set field=value …     # also: patch <id> --entity <e>, stage <id> --to <s>, note <id> "…"
+  octwin records tasks | task complete <taskId> [--outcome done|cancelled]
+  octwin cases   assign <id> --to user:<uuid>|none | note <id> "…" | transition <id> --to <status>
+  octwin cases   decide <id> --action <a> [--param k=v] [--dry-run]   # --dry-run previews, commits nothing
+  octwin orders  transition <ref> --to <status> | refund <ref> --force
+  octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
+  octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
+  octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
 
 Multi-turn: the platform keeps ONE open conversation per --as handle — consecutive
 \`octwin chat --as <h>\` calls continue the same conversation; press a rendered
@@ -2400,26 +3272,57 @@ Per-command usage: octwin <command> --help`);
 const COMMAND_HELP = {
     init: `octwin init <dir> [--id my-pack] [--description "..."] [--display-name "..."]
   Scaffold a pure-YAML starter pack into <dir>.`,
-    validate: `octwin validate [--dir .] [--remote]
-  Offline structural check; --remote additionally runs the platform's FULL
-  manifest + flow-DSL validation (all errors at once) — same check as deploy.`,
+    validate: `octwin validate [--dir .] [--remote] [--require-kb]
+  Offline structural check, plus two checks driven by the pulled capability
+  reference (render-intent fields, primitive arguments). Those two SKIP when the
+  reference is missing — the run says so, and --require-kb turns the skip into a
+  failure for CI. --remote additionally runs the platform's FULL manifest +
+  flow-DSL validation and its flow lint (all errors at once) — same check as deploy.`,
     login: `octwin login --url <platformUrl> --token oct_…
   Save a deploy token (console → Settings → API tokens) for that platform url,
   make that url the DEFAULT deploy target for every later command, and echo the
   workspace + project pin + scopes the token reaches.`,
     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).`,
     deploy: `octwin deploy [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>] [--token <t>] [--seed]
   Upload the pack bundle, validate server-side, install onto the project.
   --seed additionally applies the pack's demo seed (streams progress).`,
     status: `octwin status [--dir .] [--url <url>] [--tenant <slug>] [--project <slug>]
   Show installed vs live version + the flow list for this pack.`,
-    records: `octwin records [entity] [id] [--limit 50]
+    records: `octwin records [entity] [id] [--limit 50] [--offset n]
   Inspect the pack's XRM data. No args = list entities. Cases/tickets are
-  casework, not XRM — use \`octwin cases\` for those.`,
-    cases: `octwin cases [caseId] [--queues] [--limit 50] [--json]
+  casework, not XRM — use \`octwin cases\` for those.
+
+  WRITES (need \`records:write\`; every one is re-checked by RBAC on the record):
+    octwin records create <entity> --set field=value [--set …] [--stage s] [--contact <id>]
+    octwin records patch  <recordId> --entity <entity> --set field=value
+    octwin records stage  <recordId> --to <stage> [--note "..."]
+    octwin records note   <recordId> "the note text"
+    octwin records tasks                       # open follow-up tasks (\`tasks\` plan feature)
+    octwin records task complete <taskId> [--outcome done|cancelled] [--note "..."]
+
+  --set coerces JSON scalars: \`--set rating=4.5\` sends a number, \`--set x=null\`
+  sends null. Use --fields-json '{"a":{"b":1}}' for anything nested.
+  \`patch\` needs --entity even though it has an id: the route resolves the field
+  validator from it. A leading \`create/patch/stage/note/tasks/task\` is read as a
+  VERB — to list an entity actually named one of those, use \`--entity <name>\`.`,
+    cases: `octwin cases [caseId] [--queues] [--limit 50] [--offset n] [--json]
   Inspect casework (support tickets): the inbox, one case + its timeline
-  (+ applicable decisions), or --queues for queue keys + open counts.`,
+  (+ applicable decisions), or --queues for queue keys + open counts.
+
+  WRITES (need \`cases:write\`):
+    octwin cases assign     <caseId> --to user:<uuid>|team:<uuid>|none
+    octwin cases note       <caseId> "the note text"
+    octwin cases transition <caseId> --to <status> [--note "..."]
+    octwin cases decide     <caseId> --action <action> [--param k=v] [--note "..."] [--dry-run]
+
+  \`decide\` applies one of the case's declared dispositions — \`octwin cases <id>\`
+  lists them with their params. --dry-run previews the customer-facing copy and the
+  resulting status WITHOUT committing (that route needs only \`cases:read\`).`,
     logs: `octwin logs [conversationId] [--as <handle>] [--json]
   No id = recent conversations (handle, status, last activity; --as filters).
   With id = the full event timeline including what each turn rendered.
@@ -2467,13 +3370,30 @@ const COMMAND_HELP = {
   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.`,
+  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.`,
+  so \`pending\` on a gateway-less workspace is expected, not a bug.
+
+  WRITES (need \`orders:write\`):
+    octwin orders transition <reference_id> --to <status>
+    octwin orders refund     <reference_id> [--reason "..."] [--mark-returned] --force
+
+  Refund is irreversible and moves money, hence --force. The route answers 200 even
+  when the GATEWAY refuses, so the CLI reads the gateway verdict and exits non-zero
+  on a refusal rather than reporting a refund that never happened. Only a payment in
+  \`captured\` state can be refunded; \`payment_status\` is never settable directly.`,
     analytics: `octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>] [--json]
   No args = the entities that carry a \`pipeline:\` (a funnel needs stages).
   With an entity = stage-by-stage conversion (default --funnel) over the last 30
@@ -2483,22 +3403,58 @@ const COMMAND_HELP = {
   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.`,
+  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.`,
+  the availability rules a \`deploy --seed\` created. Needs scheduling:read.
+
+  RULES (list needs scheduling:read; add/rm need scheduling:write):
+    octwin scheduling rules --resource <resourceRecordId>
+    octwin scheduling rule add --resource <id> --dow 1 --start 09:00 --end 17:00
+                               [--slot-minutes 30] [--capacity 1]
+    octwin scheduling rule rm  <ruleId>
+    octwin scheduling exception add --resource <id> --date YYYY-MM-DD --kind closed|extra
+                                    [--start 09:00 --end 13:00]
+    octwin scheduling exception rm  <exceptionId>
+
+  --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
+  \`--slots\` is how you check what a rule actually produces.`,
     'platform-kb': `octwin platform-kb [pull] [--dir .] [--url <url>] [--tenant <slug>] [--token <t>]
   Pull the platform capability reference (markdown + JSON catalogs) into
   .octwin/platform-kb/ for the octwin-pack authoring skill.`,
     test: `octwin test [--dir .]
   Alias for \`octwin validate --remote\` — the full platform check.`,
+    feedback: `octwin feedback [--dir .]
+  Submit this pack's FEEDBACK.md to the platform team.
+  The octwin-pack skill writes that file in its last step — findings grouped by
+  owner (A · CLI, B · Platform, C · Skill/KB). This delivers it instead of asking
+  you to paste it into a chat.
+  Attaches the pack id + version from manifest.yaml, this CLI's version, and the
+  content_hash of the capability reference in .octwin/platform-kb/ — triage needs
+  the last two to tell "the platform is wrong" from "that was already fixed" or
+  "you were reading a stale reference". Needs the \`pack:deploy\` scope.`,
 };
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
-    CURRENT_COMMAND = command; // so an auth failure can name the scope THIS command needs
+    // So an auth failure can name the scope THIS invocation needs. A leading write
+    // verb changes the answer (`cases` reads, `cases note` writes), so it rides along
+    // when the first positional is one — `VERB_REQUIREMENTS` is keyed that way.
+    const leadingVerb = flags._[0];
+    CURRENT_COMMAND = (typeof leadingVerb === 'string' && command && `${command} ${leadingVerb}` in VERB_REQUIREMENTS)
+        ? `${command} ${leadingVerb}`
+        : command;
     // Per-subcommand --help/-h — intercepted BEFORE the command runs, so help can
     // never hit the network or die on auth (author-feedback A8).
     if (command && command in COMMAND_HELP && (flags.help === true || flags._.includes('-h'))) {
@@ -2542,6 +3498,9 @@ async function main() {
         case 'media':
             await cmdMedia(flags);
             break;
+        case 'projects':
+            await cmdProjects(flags);
+            break;
         case 'agents':
             await cmdAgents(flags);
             break;
@@ -2560,6 +3519,9 @@ async function main() {
         case 'platform-kb':
             await cmdPlatformKb(flags);
             break;
+        case 'feedback':
+            await cmdFeedback(flags);
+            break;
         case 'test':
             await cmdValidate({ ...flags, remote: true });
             break; // A6: `test` = the full remote validate, not a validate-clone