@soku-ai/cli 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAC9C,eAAO,MAAM,WAAW,kBAAkB,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,iBAAiB,CAAA;AAC9C,eAAO,MAAM,WAAW,mBAAmB,CAAA"}

package/dist/version.js

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

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAA;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,gBAAgB,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soku-ai/cli",
-  "version": "0.1.0-alpha.1",
-  "description": "Soku CLI — call Soku ads/GA4 data capabilities from any AI agent or shell.",
+  "version": "0.1.0-alpha.11",
+  "description": "Soku CLI — call Soku ads/GA4/PostHog data capabilities from any AI agent or shell.",
   "license": "Proprietary",
   "author": "Soku",
   "homepage": "https://soku.ai/cli",
@@ -19,7 +19,8 @@
     "ai-agent",
     "marketing-analytics",
     "google-ads",
-    "ga4"
+    "ga4",
+    "posthog"
   ],
   "type": "module",
   "bin": {
@@ -27,6 +28,7 @@
   },
   "files": [
     "dist",
+    "postinstall.cjs",
     "skills"
   ],
   "engines": {
@@ -39,9 +41,10 @@
   "scripts": {
     "build": "tsc && mkdir -p dist/generated && cp src/generated/capabilities.json dist/generated/capabilities.json",
     "typecheck": "tsc --noEmit",
-    "test": "tsc -p tsconfig.test.json && node --test \".test-build/**/*.test.js\"",
+    "test": "tsc -p tsconfig.test.json && find .test-build -name '*.test.js' -print | sort | xargs node --test",
     "gen:capabilities": "pnpm run build && node scripts/gen-capabilities.ts",
     "clean": "rm -rf dist .test-build",
+    "postinstall": "node postinstall.cjs",
     "prepublishOnly": "pnpm run clean && pnpm run build"
   },
   "dependencies": {

package/postinstall.cjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/*
+ * Refresh previously installed bundled Soku meta-skills after a global npm
+ * install. Business skills still update through `soku update skills`, because
+ * that path verifies catalog zip checksums and may need network access.
+ */
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const MANIFEST_FILE = '.soku-skills.json'
+const SOKU_META = 'soku'
+
+function shouldRun() {
+  return process.env.npm_config_global === 'true' || process.env.npm_config_global === '1'
+}
+
+function copyDir(source, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name)
+    const to = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(from, to)
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to)
+    }
+  }
+}
+
+function loadManifest(baseDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(baseDir, MANIFEST_FILE), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function hasSokuSkill(baseDir) {
+  const manifest = loadManifest(baseDir)
+  return (
+    Object.keys(manifest).length > 0 ||
+    fs.existsSync(path.join(baseDir, SOKU_META, 'SKILL.md'))
+  )
+}
+
+function refreshMetaSkill(baseDir, bundledDir) {
+  if (!hasSokuSkill(baseDir)) return
+
+  const dest = path.join(baseDir, SOKU_META)
+  fs.mkdirSync(dest, { recursive: true })
+  fs.rmSync(path.join(dest, 'SKILL.md'), { force: true })
+  fs.rmSync(path.join(dest, 'references'), { recursive: true, force: true })
+  fs.copyFileSync(path.join(bundledDir, 'SKILL.md'), path.join(dest, 'SKILL.md'))
+  const referencesDir = path.join(bundledDir, 'references')
+  if (fs.existsSync(referencesDir)) {
+    copyDir(referencesDir, path.join(dest, 'references'))
+  }
+
+  const manifest = loadManifest(baseDir)
+  manifest[SOKU_META] = {
+    sha256: '',
+    installed_at: new Date().toISOString(),
+    source: 'bundled',
+  }
+  fs.writeFileSync(path.join(baseDir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function main() {
+  if (!shouldRun()) return
+  const bundledDir = path.join(__dirname, 'skills', SOKU_META)
+  if (!fs.existsSync(path.join(bundledDir, 'SKILL.md'))) return
+
+  for (const agentDir of ['.claude/skills', '.codex/skills', '.cursor/skills']) {
+    try {
+      refreshMetaSkill(path.join(os.homedir(), agentDir), bundledDir)
+    } catch {
+      // Best-effort lifecycle hook: npm install must not fail because an agent
+      // skill directory is missing, locked, or otherwise temporarily unreadable.
+    }
+  }
+}
+
+main()

package/skills/soku/SKILL.md

@@ -1,23 +1,26 @@
 ---
 name: soku
 description: >-
-  Use when calling Soku ads/GA4 marketing-data capabilities from the shell —
+  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`, handling 401/403 errors, or installing/updating the Soku CLI.
+  `soku egress`, managing `soku seo-hosting connections`, managing
+  `soku automation`, using typed Meta Ads write commands, handling 401/403
+  errors, or installing/updating the Soku CLI.
 license: Proprietary
 metadata:
   author: nex-ad
-  version: "0.1"
+  version: "0.3"
 ---
 
 # Soku CLI
 
-The `soku` CLI calls Soku's ads + GA4 data capabilities over HTTP. It is the
-preferred way for an agent to use Soku data — it works in 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 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.
 
 ## Output & exit codes
 
@@ -36,6 +39,10 @@ Every command prints JSON. When piped (non-TTY) success is
 
 `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.
+By default, `soku auth login` requests every resource bundle known to the CLI so
+agents can use reads, approved writes, SEO Hosting, automations, Context Hub,
+asset publishing, and Brand Skills without re-authenticating. Only pass
+`--resource` when the user explicitly wants a narrower token.
 
 ### Agent path (recommended): non-blocking split-flow
 
@@ -89,19 +96,46 @@ 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)
-soku --help                               # namespaces: ads, ga4, …
+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
@@ -110,8 +144,57 @@ soku ads query-single-dimension --account-id 123 --dimension campaign \
 ```
 
 `<command> --help` is authoritative for valid flags, required vs optional, types,
-and usage. Read it before invoking an unfamiliar action. Object/list flags take a
-JSON string, e.g. `--filters '{"campaign_id":["123"]}'`.
+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
 
@@ -122,18 +205,284 @@ 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"}}'
+```
+
+### Meta Ads typed commands
+
+Meta Ads campaign-tree and creative workflows have an ergonomic typed command
+tree under `soku ads meta`. Use these commands before the raw escape hatch; they
+wrap the same backend actions but expose stable, platform-specific flags and
+client-side validation. Always inspect the exact command help before invoking a
+new verb:
+
+```bash
+soku ads meta --help
+soku ads meta campaign create --help
+soku ads meta asset upload-images --help
+soku ads meta creative create --help
+```
+
+Use the normal agent login before Meta write workflows:
+
+```bash
+soku auth login --no-wait
+soku workspace status
+soku ads list-ad-accounts --platform meta
+```
+
+If you are intentionally using a restricted token, it must include
+`data-infra,ads-write` for this workflow.
+
+Useful read helpers:
+
+```bash
+soku ads meta account pages --account-id <meta_account_id>
+soku ads meta campaign get --account-id <meta_account_id> --campaign-id <campaign_id>
+soku ads meta ad get --account-id <meta_account_id> --ad-id <ad_id>
+```
+
+Asset upload is a direct support action: it mutates Meta's asset library but
+does not change delivery and does not require a review summary. Local image
+files are read by the CLI and sent as bytes; public URLs are passed as URLs.
+The result includes `image_hash` values for creative creation.
+
+```bash
+soku ads meta asset upload-images --account-id <meta_account_id> ./hero.png ./square.jpg
+soku ads meta asset upload-images --account-id <meta_account_id> \
+  --url https://example.com/hero.png --name-prefix launch
+```
+
+Common single-object write flow. Campaign and ad creation land paused; other
+delivery-changing writes are review-gated. Every gated command requires
+`--summary`, returns a review id, and executes only after human approval.
+
+```bash
+soku ads meta campaign create \
+  --account-id <meta_account_id> \
+  --name "Launch Test" \
+  --objective OUTCOME_TRAFFIC \
+  --summary "Create paused Meta traffic campaign Launch Test"
+
+soku ads meta adset create \
+  --account-id <meta_account_id> \
+  --campaign-id <campaign_id> \
+  --name "US Prospecting" \
+  --optimization-goal LINK_CLICKS \
+  --billing-event IMPRESSIONS \
+  -p targeting='{"geo_locations":{"countries":["US"]}}' \
+  --summary "Create paused Meta ad set US Prospecting"
+
+soku ads meta creative create \
+  --account-id <meta_account_id> \
+  --name "Hero image creative" \
+  --page-id <page_id> \
+  --image-hash <image_hash> \
+  --message "Primary text" \
+  --headline "Headline" \
+  --link https://example.com \
+  --call-to-action-type LEARN_MORE \
+  --summary "Create Meta image creative for Launch Test"
+
+soku ads meta ad create \
+  --account-id <meta_account_id> \
+  --adset-id <adset_id> \
+  --name "Hero image ad" \
+  --creative-id <creative_id> \
+  --summary "Create paused Meta ad Hero image ad"
+```
+
+Status controls exist at all three delivery levels:
+
+```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"
+```
+
+Bulk commands are intentionally one layer at a time. Each command takes a JSON
+array file, and each item must be an object with a unique non-empty
+`client_ref`. The CLI injects `platform=meta` and the `--account-id`; item fields
+mirror the corresponding raw action payload (`create_campaign`,
+`create_adset`, `create_ad_creative`, or `create_ad`). Bulk approvals execute
+asynchronously after the human approves the review; poll with
+`soku review show <review_id>`.
+
+```bash
+cat > campaigns.json <<'JSON'
+[
+  {
+    "client_ref": "campaign-us-traffic",
+    "name": "US Traffic Test",
+    "objective": "OUTCOME_TRAFFIC"
+  }
+]
+JSON
+
+soku ads meta campaign bulk-create \
+  --account-id <meta_account_id> \
+  --items-file campaigns.json \
+  --summary "Bulk-create paused Meta campaigns for launch test"
+
+soku ads meta adset bulk-create --account-id <meta_account_id> --items-file adsets.json --summary "Bulk-create Meta ad sets"
+soku ads meta creative bulk-create --account-id <meta_account_id> --items-file creatives.json --summary "Bulk-create Meta creatives"
+soku ads meta ad bulk-create --account-id <meta_account_id> --items-file ads.json --summary "Bulk-create paused Meta ads"
 ```
 
+Use `soku call ads <raw_action>` only when the Meta action is not exposed in the
+typed tree, such as some audience, pixel, lead form, label, rule, targeting, or
+live-insights operations.
+
+## Automations
+
+Use `soku automation` to manage automations for the active brand. Default agent
+login includes the `automation` resource. If you are intentionally using a
+restricted token, include `automation` explicitly:
+
+```bash
+# Restricted-token examples only:
+soku auth login --resource automation
+soku auth login --resource data-infra,automation
+```
+
+The workspace must be ready before any automation call:
+
+```bash
+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
+
+Use `soku seo-hosting` to manage SEO Hosting for the active brand. Default agent
+login includes the `seo-hosting` resource. If you are intentionally using a
+restricted token, include `seo-hosting` explicitly:
+
+```bash
+# Restricted-token examples only:
+soku auth login --resource seo-hosting
+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>
+```
+
+### Posts
+
+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:
+
+```bash
+soku seo-hosting status
+```
+
+`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
+
+Connection commands:
+
+```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
+```
+
+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`:
+
+```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.
+
 ## Write actions (human approval required)
 
-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.
+Some actions mutate state and are **review-gated**. Prefer typed commands when
+they exist (`soku ads meta ...`, `soku ads google ...`). Use `soku call` for raw
+actions that are not exposed as typed commands. Review-gated commands do NOT
+execute immediately; they return a review that a human approves.
 
 ```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":"..."}}
+# → {"ok":true,"data":{"status":"pending_review","review_id":"<id>","summary":"..."}}
 
 soku review list                  # see pending reviews
 soku review show <id>             # full payload + (after approval) result
@@ -141,15 +490,16 @@ soku review approve <id>          # a human approves → the action executes now
 soku review deny <id> --feedback "wrong account"
 ```
 
-- 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.
+- The write resource must be granted to the session. Default login includes
+  `conversion-groups-write`; restricted tokens must include it explicitly, for
+  example `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.
+- As an agent: surface the `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)
 
@@ -180,18 +530,25 @@ returned verbatim on stdout.
 ## Installing / updating the skill
 
 ```bash
-soku update-check          # check whether the CLI itself needs updating
+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
 ```
 
-If `soku update-check` reports an available CLI update, ask the user before
-running:
+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.
 
-```bash
-npm i -g @soku-ai/cli
-```
+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, …)
 
@@ -205,10 +562,21 @@ 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 installed                  # what's installed locally
+soku skill status                     # what's installed locally
+soku skill list-installed             # same as status
 soku skill remove account-audit
 ```
 
+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.
@@ -217,9 +585,11 @@ so it runs through this same CLI — no in-sandbox tools, no local API keys.
 
 - 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.
+- Reads (`data-infra`) run directly. Review-gated writes, whether invoked with
+  typed commands or `soku call`, create a pending review and only
+  `soku review approve` (a human action) executes them. Direct support writes
+  such as Meta image upload or SEO Hosting page writes execute immediately, so
+  confirm user intent before running them. 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.