Update to Soku

{
  "description": "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 399
    },
    {
      "relative_path": "references/ads-write.md",
      "size_in_bytes": 8763
    },
    {
      "relative_path": "references/auth-workspace.md",
      "size_in_bytes": 4466
    },
    {
      "relative_path": "references/capability-flow.md",
      "size_in_bytes": 1940
    },
    {
      "relative_path": "references/data-capabilities.md",
      "size_in_bytes": 4449
    },
    {
      "relative_path": "references/egress-security.md",
      "size_in_bytes": 3908
    },
    {
      "relative_path": "references/seo-automation-files.md",
      "size_in_bytes": 6586
    },
    {
      "relative_path": "references/skills-updates.md",
      "size_in_bytes": 3344
    }
  ],
  "name": "soku",
  "skill_md_contents": "---\nname: soku\ndescription: >-\n  Use when calling Soku CLI capabilities from a shell: auth, workspace\n  selection, ads/GA4/PostHog data reads, typed ads writes, SEO Hosting,\n  automations, Context Hub files, temporary file publishing, brand skills,\n  third-party egress,\n  review-gated writes, skill installation, or CLI updates.\nlicense: MIT\n---\n\n# Soku CLI\n\nWritten against Soku CLI release 0.1.0-alpha.18. If `soku --version` reports a\nnewer release, run `soku changelog --since` that release before relying on\ndetails here.\n\nThe `soku` CLI is the shell-native way for an AI agent to use Soku from your\ncoding agent or any terminal. It talks to Soku over `/api/cli/*`; no MCP\nhost is required. Treat this file as the router. Load the relevant reference\nfile before acting on a detailed workflow.\n\n## Reference Router\n\nRead only the reference files needed for the user's task:\n\n| Task | Read |\n| --- | --- |\n| First-time setup, expired token, workspace selection, org/brand ambiguity | `references/auth-workspace.md` |\n| Ads, GA4, or PostHog reads; raw `soku call`; command discovery | `references/data-capabilities.md` and `references/capability-flow.md` |\n| Meta/Google/ChatGPT Ads writes, uploads, bulk create, review-gated approval | `references/ads-write.md` |\n| SEO Hosting, automations, Context Hub files, temporary public file URLs | `references/seo-automation-files.md` |\n| Third-party APIs through server-side credential injection; security rules | `references/egress-security.md` |\n| Installing, updating, or removing Soku-managed local skills; finding out what an upgrade changed | `references/skills-updates.md` |\n\nFor an installed business skill such as `soku-ads-report`, read that skill too.\nBusiness skills carry their own \"Running this skill with the Soku CLI\" section.\n\n## Prerequisite: The CLI Must Be Installed\n\nThis skill only describes the `soku` command; it does not contain it. Check\nfirst:\n\n```bash\nsoku --version\n```\n\nIf the command is missing, install it (Node.js 20 or newer is required) and\ncheck again:\n\n```bash\nnpm i -g @soku-ai/cli\nsoku --version\n```\n\nIf npm says `@soku-ai/cli` is not found, report that the official package is\nunavailable. Do not invent an unofficial package name.\n\nWhen this skill arrived as a marketplace plugin, the CLI may also have\ninstalled its own copy under `~/.claude/skills/soku/`,\n`~/.codex/skills/soku/`, or `~/.cursor/skills/soku/`. Both copies are the same\ndocument at possibly different versions. The copy the CLI installed is refreshed\ntogether with the binary, so when the two disagree, prefer that one, and treat\n`soku --help` and `soku changelog` as the authority over either copy.\n\n## Default Flow\n\n1. Check auth/workspace state:\n\n```bash\nsoku auth status\nsoku workspace status\n```\n\n2. If auth is missing or expired, use the agent split-flow from\n`references/auth-workspace.md`.\n\n3. If the workspace is not ready, resolve and select the remote Soku brand:\n\n```bash\nsoku workspace resolve <brand>\nsoku workspace use-brand <brand>\n```\n\n4. Pick the reference for the task. Do not infer Soku org/brand from the current\nlocal repo directory.\n\n5. Inspect command help before unfamiliar calls:\n\n```bash\nsoku --help\nsoku <namespace> --help\nsoku <namespace> <action> --help\n```\n\n6. Run the command and parse JSON output. In non-TTY contexts, success is\n`{\"ok\":true,\"data\":...}` and errors are `{\"ok\":false,\"error\":...}`.\n\n## Non-Negotiable Rules\n\n- **Confirm the target brand immediately before any write, and read it back\n  after.** Run `soku workspace status` in the same turn as the write — not\n  earlier in the session — and check the reported brand is the one the user\n  named (its `source` field tells you whether saved config or a `SOKU_BRAND_ID`\n  environment variable decided it, which is what you would have to change). The\n  CLI keeps whatever brand was selected last, and it does not follow the brand\n  the user is looking at in the web app, so a brand confirmed three turns ago\n  proves nothing about this write. After the write, read the object back\n  (`soku automation get`, `soku context list`, `soku seo-hosting pages list`)\n  and confirm it landed where you intended. A write into the wrong brand\n  succeeds silently and looks identical to a correct one; the read-back is the\n  only thing that tells them apart.\n- Never print or persist the Soku access token.\n- Never ask the user to paste third-party provider keys for covered providers.\n- Do not fail just because an upstream provider key env var is unset. Use\n  `soku egress -- curl ...` for covered third-party APIs.\n- A human must authorize every review-gated write — but don't force a\n  copy-paste. If your harness prompts for explicit human confirmation before\n  each shell command (a per-command permission prompt), you MAY run\n  `soku review approve <id>` yourself after showing the user the diff/summary;\n  that confirmation prompt is the human gate. Never allowlist or auto-approve\n  `soku review approve`/`deny`, and never approve a write the user has not seen.\n  If your harness runs commands without per-command human confirmation, do NOT\n  self-approve — surface the `review_id` for the user to run.\n- Pass user values as separate argv elements. Do not build a shell command by\n  string-concatenating untrusted values.\n- Do not scan local repo files, `AGENTS.md`, or `context/` folders for Soku\n  workspace state unless the user explicitly asks about local files.\n- When a command prints a hint, follow it before retrying. Do not loop blindly.\n\n## Exit Codes\n\n| Exit | Meaning | What to do |\n| --- | --- | --- |\n| 0 | Success | Parse `data`. |\n| 1 | Usage or no workspace | Fix args, or run `soku workspace status` / `use-brand`. |\n| 2 | Auth missing, expired, or revoked | Run `soku auth login --no-wait`. |\n| 4 | Not found or unknown capability | Re-check `soku --help` / `soku <ns> --help`. |\n| 5 | Runtime or network failure | Retry if transient; if behind a proxy set `ALL_PROXY`. |\n\n## Capability Discovery\n\nTyped command names are kebab-case:\n\n```bash\nsoku ads query-single-dimension --help\n```\n\nRaw `soku call` action names use registry snake_case:\n\n```bash\nsoku call ads query_single_dimension --payload '{\"account_id\":\"123\",\"dimension\":\"campaign\"}'\n```\n\nPrefer typed commands when they exist. Use `soku call` only as a forward-compatible\nescape hatch for a newer action or an action not yet exposed ergonomically.\n\n## Installed Skill Names\n\nThe bundled CLI meta skill is named `soku`. Business skills are installed with a\nSoku prefix, for example `soku-ads-report` and `soku-google-ads`.\n\n```bash\nsoku skill list\nsoku skill install ads-report google-ads\nsoku skill status\n```\n\nWhen asking an AI client to invoke a business skill, write\n`use @soku-ads-report skill`, not `@ads-report`.\n\n## Updating This Skill\n\n`soku update skills` refreshes the bundled `soku` meta skill and every installed\nSoku-managed business skill recorded in `.soku-skills.json`. It also refreshes\nlegacy meta-only installs that have `soku/SKILL.md` but no manifest, so older\ninstallations receive this `references/` directory.\n\n`soku update cli` also silently refreshes an already-installed global `soku`\nmeta skill as an npm postinstall side effect. Its JSON result carries\n`mustRereadMetaSkill: true` plus `metaSkillRefreshed: [<paths>]` when that\nhappened. After running `soku update cli`, check that field: if true, re-read\nthis file (and `references/`) from the listed path before continuing — do not\nkeep acting on this session's previously loaded copy of this skill.\n"
}