@soku-ai/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/http/client.d.ts

@@ -6,6 +6,22 @@ interface RequestOptions {
     /** Require the active org/brand headers (data endpoints). */
     workspace?: boolean;
     apiBase?: string;
+    /**
+     * Throw {@link ApiError} instead of printing and exiting.
+     *
+     * The default is to exit, which is right for a one-shot command: the error
+     * envelope is the output. It is wrong inside a batch, where one file's
+     * transient 503 would take down a run of hundreds and leave the caller no
+     * chance to retry it. Batch callers set this and handle the error themselves.
+     */
+    throwOnError?: boolean;
+}
+/** A failed request, raised only when the caller asked for `throwOnError`. */
+export declare class ApiError extends Error {
+    readonly type: string;
+    readonly status: number;
+    readonly hint?: string | undefined;
+    constructor(type: string, message: string, status: number, hint?: string | undefined);
 }
 export declare function apiRequest<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
 export {};

package/dist/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA;gFACgF;AAMhF,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CA0FjG"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"AAAA;gFACgF;AAMhF,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,8EAA8E;AAC9E,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAHb,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAwGjG"}

package/dist/http/client.js

@@ -3,6 +3,19 @@
 import { clearToken, loadToken } from '../auth/store.js';
 import { loadConfig, resolveApiBaseUrl } from '../config.js';
 import { emitError, ExitCode } from '../output/envelope.js';
+/** A failed request, raised only when the caller asked for `throwOnError`. */
+export class ApiError extends Error {
+    type;
+    status;
+    hint;
+    constructor(type, message, status, hint) {
+        super(message);
+        this.type = type;
+        this.status = status;
+        this.hint = hint;
+        this.name = 'ApiError';
+    }
+}
 export async function apiRequest(path, opts = {}) {
     const token = await loadToken();
     if (!token) {
@@ -28,6 +41,13 @@ export async function apiRequest(path, opts = {}) {
         headers['X-Soku-Brand'] = brandId;
     }
     const base = resolveApiBaseUrl(opts.apiBase);
+    // Status 0 marks a failure that never reached the server, so a caller
+    // classifying retriability sees "no answer" rather than a fabricated code.
+    const fail = (type, message, status, code, hint) => {
+        if (opts.throwOnError)
+            throw new ApiError(type, message, status, hint);
+        return emitError(type, message, code, hint);
+    };
     let res;
     try {
         res = await fetch(`${base}${path}`, {
@@ -41,7 +61,7 @@ export async function apiRequest(path, opts = {}) {
         });
     }
     catch (err) {
-        return emitError('network_error', `Could not reach ${base}: ${err.message}`, ExitCode.RUNTIME, 'Behind a proxy? Set ALL_PROXY.');
+        return fail('network_error', `Could not reach ${base}: ${err.message}`, 0, ExitCode.RUNTIME, 'Behind a proxy? Set ALL_PROXY.');
     }
     const text = await res.text();
     const parsed = text ? safeJson(text) : null;
@@ -51,16 +71,16 @@ export async function apiRequest(path, opts = {}) {
         // cleanly instead of looping on a dead credential.
         const code = parsed?.error ?? 'unauthorized';
         await clearToken();
-        return emitError('unauthorized', `Authentication failed (${code}).`, ExitCode.AUTH, 'Run `soku auth login`.');
+        return fail('unauthorized', `Authentication failed (${code}).`, res.status, ExitCode.AUTH, 'Run `soku auth login`.');
     }
     if (res.status === 403) {
-        return emitError('forbidden', describeError(parsed) ?? 'Access denied.', ExitCode.AUTH);
+        return fail('forbidden', describeError(parsed) ?? 'Access denied.', res.status, ExitCode.AUTH);
     }
     if (res.status === 404) {
-        return emitError('not_found', describeError(parsed) ?? 'Not found.', ExitCode.NOT_FOUND);
+        return fail('not_found', describeError(parsed) ?? 'Not found.', res.status, ExitCode.NOT_FOUND);
     }
     if (res.status >= 400) {
-        return emitError(describeCode(parsed) ?? 'request_failed', describeError(parsed) ?? `HTTP ${res.status}`, exitCodeForStatus(res.status), describeHint(parsed) ?? undefined);
+        return fail(describeCode(parsed) ?? 'request_failed', describeError(parsed) ?? `HTTP ${res.status}`, res.status, exitCodeForStatus(res.status), describeHint(parsed) ?? undefined);
     }
     return parsed;
 }

package/dist/http/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/http/client.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -6,6 +6,7 @@ import { registerAuthCommands } from './commands/auth.js';
 import { registerAutomationCommands } from './commands/automation.js';
 import { registerBrandCommands } from './commands/brand.js';
 import { registerCallCommand } from './commands/call.js';
+import { registerChangelogCommand } from './commands/changelog.js';
 import { registerContextCommands } from './commands/context.js';
 import { registerEgressCommands } from './commands/egress.js';
 import { registerFilesCommands } from './commands/files.js';
@@ -41,6 +42,7 @@ registerContextCommands(program);
 registerFilesCommands(program);
 registerSkillCommand(program);
 registerUpdateCommand(program);
+registerChangelogCommand(program);
 registerUpdateCheckCommand(program);
 function commandNames(command) {
     const names = new Set();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/upload-journal.d.ts

@@ -0,0 +1,46 @@
+/** Durable record of one `soku context upload` run.
+ *
+ * A bulk upload of hundreds of files will lose some of them to transient
+ * failures no matter how many times it retries. Without a record of what the
+ * run intended to do, the only recovery is to re-run the whole command and
+ * hope, which is what forced manual batching and hand-checking of file counts.
+ * The journal makes a run resumable: it stores every planned file and the
+ * outcome of each one, so a later `--resume <run-id>` re-attempts exactly the
+ * files that never landed.
+ *
+ * Journals live under `~/.soku/uploads/` and are pruned by age, not by count,
+ * so a resume is still possible days later.
+ */
+export type UploadEntryStatus = 'pending' | 'done' | 'failed';
+export interface UploadJournalEntry {
+    localPath: string;
+    targetDir: string;
+    filename: string;
+    status: UploadEntryStatus;
+    error?: string;
+    sizeBytes?: number;
+    contentType?: string;
+}
+export interface UploadJournal {
+    runId: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Workspace the run targeted; a resume into a different brand is refused. */
+    orgId: string | null;
+    brandId: string | null;
+    dir: string;
+    entries: UploadJournalEntry[];
+}
+/** Journals older than this are pruned on the next run. */
+export declare const JOURNAL_RETENTION_DAYS = 14;
+export declare function journalDir(): string;
+export declare function newRunId(): string;
+export declare function saveJournal(journal: UploadJournal): void;
+export declare function loadJournal(runId: string): UploadJournal | null;
+export declare function deleteJournal(runId: string): void;
+/** Entries a resume should re-attempt: everything that is not confirmed done. */
+export declare function pendingEntries(journal: UploadJournal): UploadJournalEntry[];
+export declare function listJournals(): UploadJournal[];
+/** Drop journals past the retention window so the directory cannot grow forever. */
+export declare function pruneJournals(now?: number): number;
+//# sourceMappingURL=upload-journal.d.ts.map

package/dist/upload-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-journal.d.ts","sourceRoot":"","sources":["../src/upload-journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAE7D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAC9B;AAED,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,KAAK,CAAA;AAExC,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAMD,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAMxD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAM/D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMjD;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,kBAAkB,EAAE,CAE3E;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAe9C;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,GAAG,SAAa,GAAG,MAAM,CAsBtD"}

package/dist/upload-journal.js

@@ -0,0 +1,102 @@
+/** Durable record of one `soku context upload` run.
+ *
+ * A bulk upload of hundreds of files will lose some of them to transient
+ * failures no matter how many times it retries. Without a record of what the
+ * run intended to do, the only recovery is to re-run the whole command and
+ * hope, which is what forced manual batching and hand-checking of file counts.
+ * The journal makes a run resumable: it stores every planned file and the
+ * outcome of each one, so a later `--resume <run-id>` re-attempts exactly the
+ * files that never landed.
+ *
+ * Journals live under `~/.soku/uploads/` and are pruned by age, not by count,
+ * so a resume is still possible days later.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { configDir } from './config.js';
+/** Journals older than this are pruned on the next run. */
+export const JOURNAL_RETENTION_DAYS = 14;
+export function journalDir() {
+    return join(configDir(), 'uploads');
+}
+function journalPath(runId) {
+    return join(journalDir(), `${runId}.json`);
+}
+export function newRunId() {
+    return randomUUID();
+}
+export function saveJournal(journal) {
+    const path = journalPath(journal.runId);
+    mkdirSync(journalDir(), { recursive: true });
+    writeFileSync(path, JSON.stringify({ ...journal, updatedAt: new Date().toISOString() }, null, 2), {
+        mode: 0o600,
+    });
+}
+export function loadJournal(runId) {
+    try {
+        return JSON.parse(readFileSync(journalPath(runId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function deleteJournal(runId) {
+    try {
+        rmSync(journalPath(runId));
+    }
+    catch {
+        // Already gone; a finished run leaving no journal behind is the goal.
+    }
+}
+/** Entries a resume should re-attempt: everything that is not confirmed done. */
+export function pendingEntries(journal) {
+    return journal.entries.filter((entry) => entry.status !== 'done');
+}
+export function listJournals() {
+    let names;
+    try {
+        names = readdirSync(journalDir());
+    }
+    catch {
+        return [];
+    }
+    const journals = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const journal = loadJournal(name.slice(0, -'.json'.length));
+        if (journal)
+            journals.push(journal);
+    }
+    journals.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    return journals;
+}
+/** Drop journals past the retention window so the directory cannot grow forever. */
+export function pruneJournals(now = Date.now()) {
+    const cutoff = now - JOURNAL_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    let names;
+    try {
+        names = readdirSync(journalDir());
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const path = join(journalDir(), name);
+        try {
+            if (statSync(path).mtimeMs < cutoff) {
+                rmSync(path);
+                removed += 1;
+            }
+        }
+        catch {
+            // A journal that vanished mid-prune needs no further attention.
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=upload-journal.js.map

package/dist/upload-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-journal.js","sourceRoot":"","sources":["../src/upload-journal.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const CLI_PACKAGE_NAME = "@soku-ai/cli";
-export declare const CLI_VERSION = "0.1.0-alpha.16";
+export declare const CLI_VERSION = "0.1.0-alpha.18";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 export const CLI_PACKAGE_NAME = '@soku-ai/cli';
-export const CLI_VERSION = '0.1.0-alpha.16';
+export const CLI_VERSION = '0.1.0-alpha.18';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soku-ai/cli",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "description": "Soku CLI — call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.",
   "license": "MIT",
   "author": "About Intelligence",
@@ -39,9 +39,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json dist/generated/capabilities.json",
+    "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json src/generated/changelog.json dist/generated/",
     "typecheck": "tsc --noEmit",
-    "test": "tsc -p tsconfig.test.json && find .test-build -name '*.test.js' -print | sort | xargs node --test",
+    "test": "tsc -p tsconfig.test.json && mkdir -p .test-build/generated && cp src/generated/capabilities.json src/generated/changelog.json .test-build/generated/ && find .test-build -name '*.test.js' -print | sort | xargs node --test && node --test scripts/*.test.mjs",
     "clean": "rm -rf dist .test-build",
     "postinstall": "node postinstall.cjs",
     "prepublishOnly": "pnpm run clean && pnpm run build"

package/skills/soku/SKILL.md

@@ -9,7 +9,10 @@ description: >-
 license: MIT
 metadata:
   author: About Intelligence
-  version: "0.4"
+  version: "0.5"
+  # CLI release this skill was written against. `soku changelog --since <that
+  # version>` lists what moved if the installed CLI is newer.
+  cliVersion: "0.1.0-alpha.18"
 ---
 
 # Soku CLI
@@ -30,7 +33,7 @@ Read only the reference files needed for the user's task:
 | Meta/Google/ChatGPT Ads writes, uploads, bulk create, review-gated approval | `references/ads-write.md` |
 | SEO Hosting, automations, Context Hub files, temporary public file URLs | `references/seo-automation-files.md` |
 | Third-party APIs through server-side credential injection; security rules | `references/egress-security.md` |
-| Installing, updating, or removing Soku-managed local skills | `references/skills-updates.md` |
+| Installing, updating, or removing Soku-managed local skills; finding out what an upgrade changed | `references/skills-updates.md` |
 | Migrate context, project files, or workspaces from Claude into Soku | Run `soku skill install migrate-from-claude`, then read the installed `soku-migrate-from-claude` skill. |
 
 For an installed business skill such as `soku-ads-report`, read that skill too.
@@ -71,6 +74,18 @@ soku <namespace> <action> --help
 
 ## Non-Negotiable Rules
 
+- **Confirm the target brand immediately before any write, and read it back
+  after.** Run `soku workspace status` in the same turn as the write — not
+  earlier in the session — and check the reported brand is the one the user
+  named (its `source` field tells you whether saved config or a `SOKU_BRAND_ID`
+  environment variable decided it, which is what you would have to change). The
+  CLI keeps whatever brand was selected last, and it does not follow the brand
+  the user is looking at in the web app, so a brand confirmed three turns ago
+  proves nothing about this write. After the write, read the object back
+  (`soku automation get`, `soku context list`, `soku seo-hosting pages list`)
+  and confirm it landed where you intended. A write into the wrong brand
+  succeeds silently and looks identical to a correct one; the read-back is the
+  only thing that tells them apart.
 - Never print or persist the Soku access token.
 - Never ask the user to paste third-party provider keys for covered providers.
 - Do not fail just because an upstream provider key env var is unset. Use

package/skills/soku/references/ads-write.md

@@ -157,32 +157,61 @@ The command path determines platform. Do not add `--platform`; the CLI injects
 
 ## ChatGPT Ads Writes
 
-ChatGPT Ads uses the generic `ads` action surface. The platform object model is
-ad unit first, campaign second:
+Use:
 
-1. Create one or more ad units with `ads/create_ad_unit`.
-2. Create the campaign with `ads/create_campaign`, `platform=chatgpt_ads`, and a
-   non-empty `ad_unit_ids` list.
-3. Keep new campaigns paused. The backend forces create to paused; do not submit
-   `update_campaign(status=active)` unless the user explicitly asks for
-   activation and approves that exact review.
+```bash
+soku ads chatgpt --help
+soku ads chatgpt account --help
+soku ads chatgpt campaign --help
+soku ads chatgpt ad-group --help
+soku ads chatgpt ad --help
+```
 
-Use `soku call` when a typed command is not obvious:
+The command path determines platform. Do not add `--platform`; the CLI injects
+`platform=chatgpt_ads`.
+
+The object model is `Campaign → Ad Group → Ad`. `campaign create` requires a
+non-empty inline ad-groups array (`--ad-groups '<json>'` or
+`--ad-groups-file groups.json`); each group is `manual` (with authored `ads`)
+or `generative`. Campaign, ad group, and ad creates are all forced paused by
+the backend; activation is a separate review-gated
+`soku ads chatgpt campaign activate` that the user must explicitly request and
+approve. ChatGPT Ads status literals are lowercase `active` / `paused`, ads
+live under `ad_group_id` (never `adset_id`), and every mutation requires
+`--account-id`.
 
 ```bash
-soku call ads create_ad_unit \
-  --payload '{"platform":"chatgpt_ads","account_id":"<account_id>","platform_extras":{"description":"Ad unit description","landing_page":"https://example.com/?utm_source=chatgpt_ads","static_ad_text":"Primary text","static_cta":"Learn more"}}' \
-  --summary "Create paused ChatGPT Ads ad unit input"
-
-soku call ads create_campaign \
-  --payload '{"platform":"chatgpt_ads","account_id":"<account_id>","name":"Launch Test","budget_daily_micros":300000000,"platform_extras":{"landing_page":"https://example.com/?utm_source=chatgpt_ads","campaign_objective":"clicks","ad_unit_ids":["<ad_unit_id>"]}}' \
+soku ads chatgpt campaign create \
+  --account-id <account_id> --name "Launch Test" \
+  --landing-page "https://example.com/?utm_source=chatgpt_ads" \
+  --objective clicks --budget-daily 300 \
+  --ad-groups '[{"group_type":"manual","name":"AG 1","landing_page":"https://example.com/?utm_source=chatgpt_ads","brand_name":"Example","ads":[{"name":"Ad 1","headline":"Headline","copy":"Body","cta":"Learn more","landing_page":"https://example.com/?utm_source=chatgpt_ads"}]}]' \
   --summary "Create paused ChatGPT Ads campaign Launch Test"
+
+soku ads chatgpt ad-group create \
+  --account-id <account_id> --campaign-id <campaign_id> \
+  --name "AG 2" --landing-page "https://example.com/?utm_source=chatgpt_ads" \
+  --brand-name "Example" --group-type generative \
+  --summary "Add generative ad group AG 2"
+
+soku ads chatgpt ad create \
+  --account-id <account_id> --ad-group-id <ad_group_id> \
+  --name "Ad 2" --headline "Headline" --copy "Body" --cta "Learn more" \
+  --landing-page "https://example.com/?utm_source=chatgpt_ads" \
+  --summary "Add authored ad Ad 2"
 ```
 
-Available ChatGPT Ads write actions: `create_ad_unit`, `create_campaign`,
-`generate_ad_units`, `add_campaign_ad_units`, `replace_campaign_ad_units`,
-`update_campaign`, and `archive_ad_unit`. Treat `archive_ad_unit` as a toggle:
-verify current state before using it.
+Reads need no `--summary`: `soku ads chatgpt account info` (billing facts plus
+activation/tracking preflight), `campaign list|get`, `ad-group list|get`.
+Archives (`campaign remove`, `ad-group archive`, `ad archive`) are
+provider-side archive toggles — verify current state with a read first.
+
+Legacy ad-unit campaigns (`create_ad_unit`, `generate_ad_units`,
+`add_campaign_ad_units`, `replace_campaign_ad_units`, `archive_ad_unit`) are
+deprecated and stay on the raw `soku call ads <action>` surface for existing
+campaigns only; do not use them for new deployments. Migrate a legacy campaign
+with `soku ads chatgpt campaign migrate-legacy` (moves ad units into paused Ad
+Groups and authored Ads).
 
 ## Review Gate
 

package/skills/soku/references/auth-workspace.md

@@ -30,9 +30,8 @@ with the exact `next` command returned by the CLI, prefixed the same way:
 SOKU_NO_KEYCHAIN=1 soku auth login --device-code <device_code>
 ```
 
-If the browser approval page shows no workspace options (for example, a
-platform admin with no org memberships), the user can approve directly without
-selecting a workspace. Select a brand after login with
+If the browser approval page shows no workspace options, the user can approve
+directly without selecting a workspace. Select a brand after login with
 `soku workspace use-brand`.
 
 For CI or headless contexts, use `SOKU_TOKEN`; do not echo it.
@@ -47,6 +46,22 @@ still return a HITL review the user approves; that is the only gate left
 (besides the active org/brand). The `--resource` flag and the `soku resources`
 command have been removed from the CLI.
 
+## What The Login Grants
+
+The token is account-level, not brand-level. It reaches **every brand the signed-in
+account can already access**, and the brand chosen on the approval page only sets
+where the CLI starts.
+
+Users regularly read that selection as the scope of the grant and are then
+surprised to see other brands. If a user asks why they can see a brand they did
+not authorize, say this plainly: the approval covered their whole account, and
+the picker chose a starting point. `soku brand list` shows the full set.
+
+The practical consequence is the opposite of a security concern and needs
+stating too: **nothing stops a command from writing into the wrong brand.** The
+active brand is sticky, does not follow the web app, and survives across
+sessions. Confirm it in the same turn as any write.
+
 ## Workspace
 
 Never infer Soku workspace state from the local shell directory.
@@ -61,6 +76,15 @@ If `resolve` is ambiguous, show the candidates and ask the user which exact
 brand/org to use. For one-off scripts, `SOKU_ORG_ID` and `SOKU_BRAND_ID` can
 override saved config.
 
+`workspace status` resolves the same way requests do, so it reports the brand a
+write would actually reach whichever source set it. Its `source` field says
+which one won:
+
+- `config` — the saved active brand. `soku workspace use-brand` changes it.
+- `env` — `SOKU_ORG_ID` / `SOKU_BRAND_ID` are set and override the saved config.
+  In this case `use-brand` writes the config file but does **not** change where
+  writes land; change the environment variables instead.
+
 Legacy commands still work, but prefer `workspace` for agent flows:
 
 ```bash
@@ -70,15 +94,6 @@ soku brand list
 soku brand use <slug-or-id>
 ```
 
-## Platform Admins
-
-`soku auth status` reports `is_platform_admin`, which is `true` only for an
-active platform admin. An active platform admin can work across every active
-org without holding an org membership: `soku workspace use-brand`,
-`soku workspace resolve`, `soku org list`, and `soku brand list` cover the
-full set of active orgs and brands. Everyone else stays scoped to the orgs
-where they have a membership.
-
 ## Session State
 
 ```bash

package/skills/soku/references/egress-security.md

@@ -14,6 +14,50 @@ soku egress -- curl -H "Authorization: Bearer $AHREFS_API_KEY" "https://api.ahre
 `$AHREFS_API_KEY` may be unset locally. That is expected. The CLI strips empty
 placeholder auth and the Soku API injects the real credential.
 
+### Which curl flags are understood
+
+`soku egress` forwards four things to the proxy — method, URL, headers, body —
+so it parses the curl flags that decide those, and nothing else.
+
+**Honored** (they change the request):
+
+| Flag | Effect |
+| --- | --- |
+| `-X` / `--request` | HTTP method |
+| `-I` / `--head` | method `HEAD` |
+| `-H` / `--header` | request header |
+| `-d` / `--data` / `--data-raw` / `--data-ascii` / `--data-binary` | body, sent verbatim |
+| `--data-urlencode` | body, URL-encoded exactly as curl does |
+| `-G` / `--get` | fold the accumulated data into the query string |
+| `--url` | request URL |
+| `-o` / `--output` | write the response body to this file |
+
+Repeated data flags **accumulate**, joined with `&`, the way curl joins them.
+`@file` reads a file and `@-` reads stdin, for both `-d` and `--data-urlencode`.
+
+**Accepted and ignored**: `-s`, `-S`, `-i`, `-v`, `-k`, `-f`/`--fail`, `-L`,
+`--compressed`, `-w`, `-m`/`--max-time`, `--connect-timeout`, `--retry`,
+`--retry-delay`, `--retry-max-time`, `--retry-all-errors`, `--resolve`,
+`--max-redirs`, `--limit-rate`, `-D`, and their long forms. These shape curl's
+local behaviour — output noise, timeouts, retry policy — and cannot change the
+request that is forwarded. Bundled short flags (`-sSL`) are understood.
+
+**Anything else is an error.** A flag this list does not name stops the command
+with a usage error naming the flag; the request is not sent. That is deliberate:
+the previous behaviour skipped an unrecognised flag *and did not consume its
+value*, so the value fell through and was dropped too. The request went out with
+parameters missing and the third party answered about whatever it noticed first
+— an error that pointed nowhere near the real cause. If a skill needs a flag
+that is not listed, rewrite the request without it (inline the query in the URL,
+move a `--form` upload to a body) rather than expecting it to be ignored.
+
+### Encoding matches curl exactly
+
+`--data-urlencode` is form encoding: a space becomes `+` (not `%20`) and
+percent-escapes use lowercase hex (`%2c`, not `%2C`). The CLI reproduces this
+byte for byte, so prefixing an existing curl does not change what the third
+party receives.
+
 List covered hosts:
 
 ```bash