@soku-ai/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

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

@@ -114,12 +114,16 @@ soku ads meta creative create \
   --summary "Create Meta dynamic creative"
 ```
 
-Status controls exist at delivery levels:
+Status controls exist at delivery levels. A write that names an existing
+campaign / ad set / ad must first read that object back (`soku ads meta
+campaign get` / `adset get` / `ad get`, or the matching list command) and quote
+its current name **and** literal id in `--summary`; the server rejects a summary
+that omits a literal target id with `invalid_ads_payload`:
 
 ```bash
-soku ads meta campaign activate --campaign-id <campaign_id> --account-id <meta_account_id> --summary "Activate campaign"
-soku ads meta adset pause --adset-id <adset_id> --account-id <meta_account_id> --summary "Pause ad set"
-soku ads meta ad pause --ad-id <ad_id> --account-id <meta_account_id> --summary "Pause ad"
+soku ads meta campaign activate --campaign-id <campaign_id> --account-id <meta_account_id> --summary "Activate campaign 'Launch Test' (campaign_id <campaign_id>)"
+soku ads meta adset pause --adset-id <adset_id> --account-id <meta_account_id> --summary "Pause ad set 'US Prospecting' (adset_id <adset_id>)"
+soku ads meta ad pause --ad-id <ad_id> --account-id <meta_account_id> --summary "Pause ad 'Hero image ad' (ad_id <ad_id>)"
 ```
 
 ## Bulk Meta Create
@@ -223,8 +227,10 @@ soku review show <review_id>
 ```
 
 As an agent, always show the review id and summary to the user first — a human
-must authorize the write. If your harness prompts for explicit human
-confirmation before each shell command (e.g. Claude Code's permission prompt),
+must authorize the write. Do not tell the user a change is applied or live until
+`soku review show <review_id>` reports the execution result and the read-back
+matches; approval alone is not execution. If your harness prompts for explicit human
+confirmation before each shell command (a per-command permission prompt),
 you MAY then run `soku review approve <id>` yourself: that prompt is the human
 gate, so never allowlist or auto-approve it. If your harness auto-runs commands
 without confirmation, do not self-approve — let the user run it. Approval is

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/data-capabilities.md

@@ -31,7 +31,9 @@ soku ads query-multi-dimension \
 Use `query-single-dimension` for CPA, ROAS, conversion group fan-out, or one
 dimension. Use `query-multi-dimension` for raw multi-dimensional breakdowns.
 
-`--platform` accepts `google`, `meta`, `tiktok`, or `chatgpt_ads`:
+Platform support varies by action and rollout. Read the command help and
+connected accounts; do not assume every reporting action supports every ads
+platform. For example:
 
 ```bash
 soku ads list-ad-accounts --platform chatgpt_ads
@@ -138,3 +140,22 @@ soku call posthog query --payload '{"project_id":"12345","tool":"execute-sql","a
 ```
 
 Review-gated writes through `soku call` require `--summary`.
+
+## Recently Added Integrations And Parameters
+
+Discover the current command tree with `soku --help`. Recent data namespaces
+include `admob`, `applovin_max`, `topon`, `cloudx`, `sensortower`, `thinkingdata`,
+and Adjust API Token reporting (`adjust list-apps` / `adjust get-report`).
+They still require the corresponding connected account, brand access, and
+server rollout; command availability alone does not grant access. Soku-supplied
+providers such as AIsa and BYOK egress providers are discovered with
+`soku egress providers`, not a guessed data namespace.
+
+Boolean flags support both explicit values: `--use-cache` sends true and
+`--no-use-cache` sends false; omitting both leaves the server default intact.
+For example, `soku thinkingdata query-metric --help` and
+`soku applovin_max run-report --help` describe the relevant input flags.
+
+Google `soku ads update-campaign` accepts `--tracking-url-template` and
+`--final-url-suffix`. Omission preserves the current value; an explicitly empty
+string clears it. The existing ads review and readback requirements still apply.

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
@@ -52,3 +96,22 @@ success envelope. Soku-level failures use the normal CLI error envelope.
 - Pass user-provided values as separate argv elements.
 - Treat `verification_uri`, signed URLs, review ids, and provider URLs as
   opaque strings.
+
+## Discover And Call Endpoint Cards
+
+```bash
+soku egress capabilities --provider adyntel --query linkedin
+soku egress call adyntel linkedin_ads --args '{"company_domain":"example.com"}' --dry-run
+soku egress call adyntel linkedin_ads --args @arguments.json --output result.json
+```
+
+`capabilities` returns parameter contracts and quotes from the live server
+registry. `call --dry-run` validates and binds arguments on the server, then
+returns the request and `quote_usd_micros` without contacting the vendor or
+incurring vendor charges. Review the quote and intended call with the user
+before a paid execution. Removing `--dry-run` executes through the existing
+metered egress proxy and streams the upstream response verbatim; `--output`
+saves it to a file. Authentication stays server-side. A binding error stops
+before execution. Raw `soku egress -- curl ...` remains available for endpoints
+without published cards. Do not infer that an unlisted vendor is unsupported:
+BYOK providers may be host-discoverable without priced endpoint cards.

package/skills/soku/references/seo-automation-files.md

@@ -1,11 +1,17 @@
 # SEO Hosting, Automations, And Files
 
-These commands operate on the active Soku workspace. Confirm workspace first:
+These commands all write to the **active** Soku workspace. Confirm the brand in
+the same turn as the write, and read the result back afterwards:
 
 ```bash
 soku workspace status
 ```
 
+The CLI keeps whatever brand was selected last and does not follow the brand the
+user has open in the web app. A write into the wrong brand succeeds and looks
+exactly like a correct one, so the confirmation has to be immediate, not
+something done earlier in the session.
+
 ## SEO Hosting Pages
 
 SEO Hosting pages are complete HTML documents, not Markdown. They are addressed
@@ -57,7 +63,13 @@ risk.
 
 ```bash
 soku automation list
+soku automation get <automation_id>
 soku automation create --name "Fast check" --prompt "Check account health" --cron "* * * * *" --timezone UTC
+soku automation update <automation_id> --prompt "Check account health and budget"
+soku automation pause <automation_id>
+soku automation resume <automation_id>
+soku automation delete <automation_id> --confirm
+soku automation deps <automation_id>
 soku automation trigger <automation_id>
 soku automation runs <automation_id>
 ```
@@ -68,8 +80,31 @@ soku automation runs <automation_id>
 - `--interval-seconds <seconds>`; at least 3600 and divisible by 60.
 - `--once-at <iso>` for a one-time UTC instant.
 
-`runs` prints a Studio link when a conversation exists. The CLI does not read
-conversation content.
+`update` sends only the flags you pass; everything else keeps its stored value.
+It takes the same schedule flags as `create` (at most one), plus `--name`,
+`--prompt`, and `--status`. `--timezone` is only accepted together with
+`--cron`, because the server rebuilds the schedule from a whole contract and a
+lone timezone would be silently dropped.
+
+**Do not rebuild an automation to change it.** `update` edits the existing row
+and keeps its id, run history, and schedule version. Rebuilding loses all three,
+and leaves the original still scheduled unless you also pause or delete it.
+
+`pause` stops an automation and clears its next run; `resume` puts it back to
+active and recomputes the next run. Both are `update --status` underneath.
+
+`deps` reports whether the automation's saved dependencies still resolve:
+
+- **attachments** are looked up for real, so a deleted or cross-brand file shows
+  as `missing` before the automation next fires.
+- **context references** are classified, not verified. A reference marked
+  `brand-pinned` (ad account, campaign, ad set, ad, report) names a row inside
+  the current brand: copying the automation into another brand carries the id
+  across but not the thing it points at, so those must be re-picked there. A
+  `portable` reference (skill, integration) does not have that problem.
+
+Run `deps` before migrating an automation between brands, and after any change
+that may have deleted a referenced file.
 
 ## Context Hub
 
@@ -83,6 +118,35 @@ soku context rm research/brief.pdf
 
 Paths are context-relative. Do not include a `context/` prefix.
 
+### Bulk uploads
+
+`upload` takes directories (recursing and preserving structure under `--dir`)
+and runs files concurrently. For a large migration:
+
+```bash
+soku context upload ./assets --dir assets --concurrency 8 --verify
+soku context uploads                                  # runs with unfinished files
+soku context upload --resume <run_id>                 # finish one of them
+soku context verify ./assets --dir assets             # reconcile without uploading
+```
+
+- Each file is retried on transient failures (no response, HTTP 408/429/5xx)
+  before the run gives up on it; `--retries <n>` changes the attempt count. A
+  permanent failure such as 403 is not retried.
+- Every run records a resumable run id. If any file is still unfinished when the
+  run ends, the output carries `resume_command` — run it to re-upload only the
+  files that never landed. Finished runs leave no record behind.
+- `--resume` refuses to run if the active brand is not the one the recorded run
+  targeted. Switch back with `soku workspace use-brand` rather than forcing it:
+  the files would otherwise land, in the wrong brand, and look successful.
+- `--verify` (and the standalone `soku context verify`) reconciles against the
+  server by size **and** checksum. A file the server reports no checksum for is
+  reported as `unverified`, not `ok` — a missing hash is not proof of a good
+  upload. Both `upload --verify` and `verify` exit non-zero if anything is
+  missing, mismatched, or unverified, so a script can gate on them.
+
+Do not hand-count files to check a migration. `verify` is the reconciliation.
+
 ## Temporary Public File URLs
 
 ```bash

package/skills/soku/references/skills-updates.md

@@ -87,3 +87,57 @@ soku skill remove soku
 
 Removing the last Soku-managed skill removes the local `.soku-skills.json`
 manifest.
+
+## After Upgrading The CLI
+
+An upgrade can add, change, or retire capabilities, which invalidates whatever
+this session believed the CLI could do. Ask the CLI itself rather than guessing:
+
+```bash
+soku changelog --since <the version you upgraded from> --summary
+soku changelog --since <the version you upgraded from>
+```
+
+`--summary` gives counts per version; without it, each entry lists the actions
+that were added or removed and, for a surviving action, which fields changed.
+Output is the usual JSON envelope in a non-TTY context, so it can be parsed.
+
+The changelog is bundled with the installed CLI, so it always describes the
+binary that is running and needs no network call. It cannot speak for versions
+older than its `historyStartsAt`; when `--since` reaches past that, the response
+sets `truncated: true` and says so rather than implying nothing changed.
+
+This skill records the CLI release it was written against in the line right
+under its title. If the installed CLI is newer, run the command
+above before relying on details in these reference files.
+
+## Community Skills In The Active Brand
+
+Local `soku skill install` installs a business skill into the calling agent.
+`brand skill` manages skills in the active Soku brand instead. Official catalog
+installs and community installs have separate commands:
+
+```bash
+soku workspace status
+soku brand skill community list --query "audit" --sort installs --limit 30 --offset 0
+soku brand skill community install growth-audit
+soku brand skill community install growth-audit --expected-price-credits 300
+soku brand skill publish my-skill --categories analytics,ads --price-credits 300
+```
+
+Browse first: the list includes price, entitlement, installed version, and
+available updates. Only pass `--expected-price-credits` after the user agrees
+to that skill's exact one-time price for the active organization. Without the
+flag, a paid skill needing purchase returns `purchase_required`; already owned,
+free, and publisher-entitled skills can install without a new purchase.
+A changed price returns `conflict` with `error.details.code = price_changed` and
+`error.details.price_credits`. Obtain agreement to the new price before retrying;
+never automatically restate the server's price. Reinstall upgrades an existing
+community copy. Read it first if the brand has local edits.
+
+`publish` publishes an uploaded private skill. Omit `--price-credits` to retain
+the listing price; use 0 for free or 100–20000 for paid. Publishing paid versions
+requires a paid plan and review: inspect `skill.status` and
+`skill.pending_version.review_status`, and never describe a pending version as
+live. New versions require a version bump in SKILL.md. These mutations are not
+ads review-gated and run immediately subject to server admission.