@soku-ai/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/skills/soku/SKILL.md

@@ -1,461 +1,131 @@
 ---
 name: soku
 description: >-
-  Use when calling Soku ads/GA4/PostHog marketing-data capabilities or SEO
-  Hosting domain connections from the shell —
-  running `soku auth login`, switching org/brand with `soku org use` /
-  `soku brand use`, discovering capabilities, calling a data action, routing a
-  third-party API call (Ahrefs/DataForSEO/Firecrawl/Gemini/…) through
-  `soku egress`, managing `soku seo-hosting connections`, managing
-  `soku automation`, handling 401/403 errors, or installing/updating the Soku
-  CLI.
+  Use when calling Soku CLI capabilities from a shell: auth, workspace
+  selection, ads/GA4/PostHog data reads, typed ads writes, SEO Hosting,
+  automations, Context Hub files, temporary file publishing, brand skills,
+  third-party egress, review-gated writes, skill installation, or CLI updates.
 license: Proprietary
 metadata:
   author: nex-ad
-  version: "0.2"
+  version: "0.4"
 ---
 
 # Soku CLI
 
-The `soku` CLI calls Soku's ads, GA4, PostHog, SEO Hosting, and Automation
-capabilities over HTTP. It is the preferred way for an agent to use Soku from
-any shell, with no MCP host required. Output is JSON on stdout; errors are a
-JSON envelope on stderr with a semantic exit code.
+The `soku` CLI is the shell-native way for an AI agent to use Soku from Claude
+Code, Codex, Cursor, or any terminal. It talks to Soku over `/api/cli/*`; no MCP
+host is required. Treat this file as the router. Load the relevant reference
+file before acting on a detailed workflow.
 
-## Output & exit codes
+## Reference Router
 
-Every command prints JSON. When piped (non-TTY) success is
-`{"ok": true, "data": ...}`; errors are `{"ok": false, "error": {"type", "message", "hint"}}`.
+Read only the reference files needed for the user's task:
 
-| Exit | Meaning | What to do |
-|------|---------|------------|
-| 0 | Success | Parse `data`. |
-| 1 | Usage / no workspace selected | Fix arguments, or run `soku org use` / `soku brand use`. |
-| 2 | Auth — not signed in or token expired/revoked | Run `soku auth login` (or set `SOKU_TOKEN`). |
-| 4 | Not found (unknown capability) | Re-check via `soku --help` / `soku <ns> --help`. |
-| 5 | Runtime / network | Retry; if behind a proxy set `ALL_PROXY`. |
+| Task | Read |
+| --- | --- |
+| First-time setup, expired token, workspace selection, org/brand ambiguity | `references/auth-workspace.md` |
+| Ads, GA4, or PostHog reads; raw `soku call`; command discovery | `references/data-capabilities.md` and `references/capability-flow.md` |
+| Meta/Google 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` |
 
-## Authentication
+For an installed business skill such as `soku-ads-report`, read that skill too.
+Business skills carry their own "Running this skill with the Soku CLI" section.
 
-`soku` authenticates once per machine with a long-lived, **org-agnostic** session
-token. The org and brand are chosen at runtime (see Workspace), not at login.
+## Default Flow
 
-### Agent path (recommended): non-blocking split-flow
-
-Do NOT block a turn waiting for a human at a browser. Start login with
-`--no-wait`, surface the URL, end your turn, then resume:
-
-```bash
-soku auth login --no-wait
-```
-
-This returns immediately, e.g.:
-
-```json
-{"ok":true,"data":{"user_code":"MWVP-ZTSZ","verification_uri":"https://studio.nex.ad/device","verification_uri_complete":"https://studio.nex.ad/device?user_code=MWVP-ZTSZ","device_code":"...","next":"soku auth login --device-code ..."}}
-```
-
-Surface `verification_uri` and `user_code` to the user as your turn's final
-message (treat the URL as an opaque string — do not edit, re-encode, or
-re-assemble it). After the user says they approved, resume polling:
-
-```bash
-soku auth login --device-code <device_code>
-```
-
-### Human path
-
-`soku auth login` opens the browser and polls until the user approves. Add
-`--qr` to render the verification URL as a QR code.
-
-### CI / non-interactive
-
-Set `SOKU_TOKEN` to a pre-issued token; it overrides stored credentials and
-skips all interactive auth. This is the right path for CI and headless agents —
-it also avoids the OS keychain, which may be unavailable in containers.
-
-### Session state
-
-- `soku auth status` — show the current identity.
-- `soku auth logout` — delete the stored token.
-- On exit code 2 with `expired` / `key_revoked`, the stored token is dropped
-  automatically; re-run `soku auth login`.
-
-## Workspace (org + brand)
-
-The session token carries no org/brand. Pick a workspace before calling data
-actions; the selection is saved to `~/.soku/config.json` and sent as
-`X-Soku-Org` / `X-Soku-Brand` headers.
-
-```bash
-soku org list             # organizations you belong to
-soku org use <slug|id>    # set active org (id, slug, or name; clears a now-mismatched brand)
-soku brand list           # brands in the active org
-soku brand use <slug|id>  # id, slug, or name
-soku workspace status     # show the active org/brand and whether it is ready
-soku workspace resolve <brand>    # inspect accessible brand matches across orgs
-soku workspace use-brand <brand>  # set org + brand together when the match is unique
-```
-
-Env overrides for one-off invocations: `SOKU_ORG_ID`, `SOKU_BRAND_ID`.
-
-Do not infer Soku workspace state from the current shell directory. The working
-directory may contain unrelated README/AGENTS/context files from the user's local
-project. Start with `soku workspace status`; if the target brand is unknown, use
-`soku workspace resolve <brand>` and then `soku workspace use-brand <brand>`.
-
-## Brand memory
-
-Memory is scoped to the active Soku workspace, not to the local shell directory.
-After `soku workspace status` is ready, these commands read memory for the
-current brand only:
-
-```bash
-soku memory list
-soku memory search "policy 2026-05-31"
-soku memory get reference noiz-policy-event
-```
-
-Use brand memory as background, hypotheses, and investigation leads. Do not
-treat a memory note as a verified data fact unless this turn also confirms it
-with data actions, change history, billing evidence, or another authoritative
-source. In reports, label memory-derived context separately from data-confirmed
-findings.
-
-## Calling capabilities (discover with --help, then run)
-
-Each data capability is a typed sub-command under its namespace. Discover and
-inspect them with `--help` — never guess action names or flags.
-
-```bash
-soku resources list                       # what's granted (e.g. data-infra, seo-hosting, automation)
-soku --help                               # namespaces: ads, ga4, posthog, …
-soku ads --help                           # actions in the ads namespace
-soku posthog --help                       # customer PostHog read actions
-soku ads query-single-dimension --help    # flags, types, and usage for one action
-
-soku ads list-ad-accounts --platform google
-soku ads query-single-dimension --account-id 123 --dimension campaign \
-  --date-start 2026-05-01 --date-end 2026-05-18
-```
-
-`<command> --help` is authoritative for valid flags, required vs optional, types,
-and usage. Read it before invoking an unfamiliar action. Typed command names use
-kebab-case (`soku ads query-single-dimension`); raw `soku call` action names use
-registry snake_case (`soku call ads query_single_dimension`). Object/list flags
-take a JSON string, e.g. `--filters '{"campaign_id":["123"]}'`.
-
-### Google Ads GAQL fallback
-
-Prefer cached ads analytics first:
-
-```bash
-soku ads list-dimensions --platform google --account-id 123
-soku ads query-single-dimension --account-id 123 --dimension campaign ...
-soku ads query-multi-dimension --account-id 123 --dimensions '["campaign","device"]' ...
-```
-
-Use GAQL only when cached query actions cannot expose the Google-native fields
-or segment combination you need:
-
-```bash
-soku ads get-resource-metadata --platform google --account-id 123 --resource-name campaign
-soku ads gaql-search --platform google --account-id 123 \
-  --dimensions '["date","campaign"]' --metrics '["cost","clicks"]' --limit 20
-```
-
-Do not write full `SELECT ... FROM ...` GAQL SQL. `gaql-search` takes structured
-`dimensions`, `metrics`, `filters`, `date_range`, `order_by`, and `limit`; the
-server translates those into real GAQL. For the same action through the raw
-escape hatch, use snake_case: `soku call ads gaql_search --payload '{...}'`.
-
-### PostHog customer analytics
-
-PostHog data uses the same backend MCP forwarding gateway as the sandbox agent.
-Start by listing the current brand's granted projects, then inspect the live
-tool menu, then run an allowlisted read tool. Do not ask the user for a project
-id before listing projects.
-
-```bash
-soku posthog list-projects
-soku posthog list-tools --project-id 12345
-soku posthog query --project-id 12345 --tool execute-sql \
-  --arguments '{"query":"SELECT count() FROM events WHERE event = '\''$pageview'\''"}'
-```
-
-Use `read-data-schema` before writing HogQL if field names are unclear:
-
-```bash
-soku posthog query --project-id 12345 --tool read-data-schema --arguments '{}'
-```
-
-The CLI default read surface does not expose `posthog/request_change`; writes and
-unvetted PostHog MCP tools remain outside the generated command tree.
-
-### Raw escape hatch
-
-`soku call <namespace> <action>` runs any action by its raw (snake_case) name
-with a JSON payload. Use it only when a typed sub-command isn't available — e.g.
-a newer action than this CLI version ships:
-
-```bash
-soku call ads list_ad_accounts -p platform=google
-soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
-soku call posthog query --payload '{"project_id":"12345","tool":"execute-sql","arguments":{"query":"SELECT count() FROM events"}}'
-```
-
-## Automations
-
-Use `soku automation` to manage automations for the active brand. The session
-must include the `automation` resource. Request it at login:
-
-```bash
-soku auth login --resource automation
-# or include it with data access:
-soku auth login --resource data-infra,automation
-```
-
-The workspace must be ready before any automation call:
+1. Check auth/workspace state:
 
 ```bash
+soku auth status
 soku workspace status
-soku org use <slug|id>
-soku brand use <slug|id>
 soku resources list
 ```
 
-Commands:
-
-```bash
-soku automation list
-soku automation create --name "Fast check" --prompt "Check account health" --cron "* * * * *" --timezone UTC
-soku automation trigger <automation_id>
-soku automation runs <automation_id>
-```
-
-`create` requires exactly one schedule option:
-
-- `--cron <expr>` with optional `--timezone <iana>` (default `UTC`).
-- `--interval-seconds <seconds>` for interval schedules; must be at least
-  `3600` and divisible by `60`.
-- `--once-at <iso>` for a one-time UTC instant.
-
-`runs` shows run status and a browser link when a conversation exists. The CLI
-does not read conversation content; open the printed link in Studio to inspect
-the actual chat. For local development links, set `SOKU_WEB_BASE`, for example:
-
-```bash
-SOKU_WEB_BASE=http://127.0.0.1:47627 soku automation runs <automation_id>
-```
-
-## SEO Hosting domain connections
+2. If auth is missing or expired, use the agent split-flow from
+`references/auth-workspace.md`.
 
-Use `soku seo-hosting` to manage SEO Hosting for the active brand. The session
-must include the `seo-hosting` resource. Request it at login:
+3. If the workspace is not ready, resolve and select the remote Soku brand:
 
 ```bash
-soku auth login --resource seo-hosting
-# or include it with data access:
-soku auth login --resource data-infra,seo-hosting
-```
-
-The workspace must be ready before any connection call:
-
-```bash
-soku workspace status
-soku org use <slug|id>
-soku brand use <slug|id>
+soku workspace resolve <brand>
+soku workspace use-brand <brand>
 ```
 
-### Posts
+4. Pick the reference for the task. Do not infer Soku org/brand from the current
+local repo directory.
 
-Use typed `pages` commands for the same SEO Hosting content actions exposed to
-runtime agents through `seo_hosting/*`. SEO Hosting pages are **complete HTML
-documents** (not Markdown) served as owned-media web pages on the brand's
-connected domain; they are identified by `section` + `slug` (there are no post
-ids). They are not social posts.
-
-Always check status first:
+5. Inspect command help before unfamiliar calls:
 
 ```bash
-soku seo-hosting status
+soku --help
+soku <namespace> --help
+soku <namespace> <action> --help
 ```
 
-`status` shows each connected domain, whether it is `live`, and which sections it
-serves. If no domain is live, do not publish yet; connect or fix a domain first.
-When hosting is live:
-
-```bash
-soku seo-hosting pages list --section blog --status draft
-soku seo-hosting pages put --section blog --slug how-to --title "How to ..." --html-file page.html
-soku seo-hosting pages publish --section blog --slug how-to
-soku seo-hosting pages unpublish --section blog --slug how-to
-soku seo-hosting pages delete --section blog --slug how-to --confirm
-soku seo-hosting pages upload-asset --path blog/how-to/hero.png --file ./hero.png
-```
-
-`put` creates or overwrites a page as a **draft** and requires `--section`,
-`--slug`, `--title`, and exactly one HTML source: `--html`, `--html-file`, or
-`--html-stdin`. Optional metadata flags are `--description`, `--template`, and
-`--seo '<json object>'`. Reference images / CSS / fonts by the absolute URL
-returned from `pages upload-asset` (no custom JavaScript — HTML + CSS only).
-
-`publish` runs the validation gate (no `<script>` / inline JS) and
-makes the page live once a domain serves its section; it also prints advisory
-`Link warnings` for dead internal links (these do not block publishing — fix the
-links and re-publish). `unpublish` reverts it to draft. Writes run immediately
-(no-review), so confirm intent with the user before publishing or deleting.
-
-### Domain connections
+6. Run the command and parse JSON output. In non-TTY contexts, success is
+`{"ok":true,"data":...}` and errors are `{"ok":false,"error":...}`.
 
-Connection commands:
+## Non-Negotiable Rules
 
-```bash
-soku seo-hosting connections list
-soku seo-hosting connections connect-cname --hostname blog.example.com
-soku seo-hosting connections verify <connection_id>
-soku seo-hosting connections disconnect <connection_id> --confirm
-```
+- 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
+  `soku egress -- curl ...` for covered third-party APIs.
+- Do not approve review-gated writes on the user's behalf. Surface the
+  `review_id` and let the user run `soku review approve <id>`.
+- Pass user values as separate argv elements. Do not build a shell command by
+  string-concatenating untrusted values.
+- Do not scan local repo files, `AGENTS.md`, or `context/` folders for Soku
+  workspace state unless the user explicitly asks about local files.
+- When a command prints a hint, follow it before retrying. Do not loop blindly.
 
-Cloudflare Worker reverse proxy setup runs a probe before provisioning. Use it
-when the customer's root or existing hostname is already on Cloudflare and SEO
-Hosting needs to mount sections such as `/blog`, `/use-cases`, or
-`/alternatives`:
+## Exit Codes
 
-```bash
-soku seo-hosting connections probe --hostname example.com --sections blog,use-cases
-soku seo-hosting connections connect-worker --hostname example.com \
-  --sections blog,use-cases --cf-token-env CLOUDFLARE_API_TOKEN
-printf %s "$CLOUDFLARE_API_TOKEN" | soku seo-hosting connections connect-worker \
-  --hostname example.com --sections blog --cf-token-stdin
-```
-
-Allowed sections are `blog`, `use-cases`, and `alternatives`; omitted sections
-default to `blog`. If the probe reports existing mounted content, add
-`--accept-conflicts` only after the user confirms SEO Hosting may shadow those
-paths. If the hostname serves its own Next.js assets, add
-`--accept-next-assets-warning` only after confirming `/_next/static/*` may route
-through the Worker.
-
-Do not pass Cloudflare API tokens as literal argv values or print them. Use
-`--cf-token-env <ENV_NAME>` or `--cf-token-stdin` exactly once. Vercel OAuth
-domain connections are not exposed in the CLI yet; use the Studio web settings
-for Vercel-backed domains.
+| Exit | Meaning | What to do |
+| --- | --- | --- |
+| 0 | Success | Parse `data`. |
+| 1 | Usage or no workspace | Fix args, or run `soku workspace status` / `use-brand`. |
+| 2 | Auth missing, expired, or revoked | Run `soku auth login --no-wait`. |
+| 4 | Not found or unknown capability | Re-check `soku --help` / `soku <ns> --help`. |
+| 5 | Runtime or network failure | Retry if transient; if behind a proxy set `ALL_PROXY`. |
 
-## Write actions (human approval required)
+## Capability Discovery
 
-Some actions mutate state (e.g. conversion-group writes) and are **review-gated**.
-They are NOT in the typed command tree — call them with `soku call` and a
-required `--summary` describing the change. The call does NOT execute; it returns
-a pending review that a human approves.
+Typed command names are kebab-case:
 
 ```bash
-soku call ads create_conversion_group --summary "create group: qualified leads" -p name="Qualified leads"
-# → {"ok":true,"data":{"status":"pending_review","pending_review_id":"<id>","summary":"..."}}
-
-soku review list                  # see pending reviews
-soku review show <id>             # full payload + (after approval) result
-soku review approve <id>          # a human approves → the action executes now
-soku review deny <id> --feedback "wrong account"
+soku ads query-single-dimension --help
 ```
 
-- The write resource must be granted to the session (request it at login:
-  `soku auth login --resource data-infra,conversion-groups-write`). Without it,
-  `soku call` returns 403.
-- Approval is **single-use**: one review = one execution. Approving an already
-  decided review is a no-op that returns the existing result.
-- Do NOT loop `soku review approve` expecting retries; a failed approval is
-  terminal — create a fresh `soku call` to try again.
-- As an agent: surface the `pending_review_id` + summary to the user and let
-  THEM run `soku review approve`. Do not approve on the user's behalf.
-
-## Third-party APIs (egress)
-
-Skills that call third-party providers (Ahrefs, DataForSEO, Firecrawl, Gemini, …)
-must route the call through `soku egress`. The credential is injected
-server-side, so **no third-party API key lives on this machine**.
-
-Prefix the skill's `curl` with `soku egress --`:
+Raw `soku call` action names use registry snake_case:
 
 ```bash
-soku egress -- curl -H "Authorization: Bearer $AHREFS_API_KEY" "https://api.ahrefs.com/v3/..."
+soku call ads query_single_dimension --payload '{"account_id":"123","dimension":"campaign"}'
 ```
 
-`$AHREFS_API_KEY` is not set here, and that is expected — `soku egress` strips the
-empty auth header, Soku injects the real key, and the upstream response is
-returned verbatim on stdout.
+Prefer typed commands when they exist. Use `soku call` only as a forward-compatible
+escape hatch for a newer action or an action not yet exposed ergonomically.
 
-- Do NOT pre-flight check whether an API key env var is set, and do NOT abort a
-  skill because a key looks missing (no `[ -z "$X_API_KEY" ]` guards, no
-  `if not os.environ.get(...)` early-exits). Assume the credential is available;
-  just make the call through `soku egress`.
-- A skill's own `SKILL.md` shows the raw `curl -H "Authorization: Bearer $X"`
-  form for reference. Ignore whether the key is set — prefix the whole command
-  with `soku egress --`.
-- `soku egress providers` lists the covered hosts. For a host NOT listed, the
-  proxy does not inject a credential — follow that skill's own auth instead.
+## Installed Skill Names
 
-## Installing / updating the skill
+The bundled CLI meta skill is named `soku`. Business skills are installed with a
+Soku prefix, for example `soku-ads-report` and `soku-google-ads`.
 
 ```bash
-soku update status            # show CLI + installed skill update status
-soku update skills            # refresh this meta-skill and installed business skills
-soku update cli               # install the latest CLI from npm
-soku skill install            # this meta-skill into .claude / .codex / .cursor (project)
-soku skill install --global   # into ~/.claude, ~/.codex, ~/.cursor
-soku skill install --agent claude --global
+soku skill list
+soku skill install ads-report google-ads
+soku skill status
 ```
 
-Normal `soku` commands schedule a background refresh for installed Soku-managed
-skills at most once every 24 hours. Set `SOKU_NO_SKILL_AUTO_UPDATE=1` to disable
-skill auto updates, or `SOKU_UPDATE_INTERVAL_HOURS=<n>` to change the interval.
+When asking an AI client to invoke a business skill, write
+`use @soku-ads-report skill`, not `@ads-report`.
 
-The CLI binary itself is advisory by default. To opt into automatic npm CLI
-updates, set `SOKU_AUTO_UPDATE_CLI=1`; otherwise run `soku update cli` when
-`soku update status` shows a newer version.
-
-A global `npm i -g @soku-ai/cli` refreshes this already-installed global
-meta-skill after npm finishes installing. It does not install new skills and it
-does not update project-local skills.
-
-## Installing business skills (account audits, Google Ads, reports, …)
-
-Beyond this meta-skill, Soku publishes a catalog of domain skills (e.g.
-`account-audit`, `google-ads`, `ads-report`) that already know which `soku call`
-actions and `soku egress` providers to use — install one and your agent gains
-that playbook.
-
-```bash
-soku skill list                       # browse the catalog
-soku skill install account-audit      # install one (into soku-account-audit/)
-soku skill install ads-report google-ads
-soku skill install --all              # install everything
-soku skill status                     # what's installed locally
-soku skill list-installed             # same as status
-soku skill remove account-audit
-```
+## Updating This Skill
 
-Catalog slugs are used for install/remove commands (`ads-report`). Installed AI
-client skill names are Soku-prefixed (`soku-ads-report`). When asking an agent to
-run an installed business skill, write `use @soku-ads-report skill`, not
-`@ads-report`.
-
-Business skill updates are detected from `.soku-skills.json`: for each installed
-catalog slug, Soku compares local `version`, `sha256`, and `source` against the
-latest catalog `index.json`. A changed version, changed hash, or old source is
-treated as an update; missing catalog entries are reported but not deleted.
-
-Each installed skill carries a "Running this skill with the Soku CLI" section
-(its data actions mapped to `soku call`, its third-party APIs to `soku egress`),
-so it runs through this same CLI — no in-sandbox tools, no local API keys.
-
-## Security rules
-
-- Never print the access token (it grants account access). Prefer `SOKU_TOKEN`
-  for CI rather than echoing it.
-- Reads (`data-infra`) run directly. Writes are review-gated: `soku call`
-  creates a pending review and only `soku review approve` (a human action)
-  executes it. Don't approve on the user's behalf, and don't assume a
-  `--yes`-style bypass exists — there isn't one.
-- Pass user-provided values as separate argv elements (the `-p key=value` form),
-  never by string-concatenating them into a shell command.
+`soku update skills` refreshes the bundled `soku` meta skill and every installed
+Soku-managed business skill recorded in `.soku-skills.json`. It also refreshes
+legacy meta-only installs that have `soku/SKILL.md` but no manifest, so older
+installations receive this `references/` directory.