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

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

@@ -0,0 +1,137 @@
+# Ads Writes
+
+Meta and Google write commands use typed CLI surfaces where available. Most
+delivery-changing writes are review-gated: the command creates a pending review
+and does not execute until a human approves.
+
+## Prerequisites
+
+```bash
+soku auth login --no-wait
+soku workspace status
+soku ads list-ad-accounts --platform meta
+```
+
+A default login can reach ads writes (no resource needed); each
+delivery-changing write still returns a pending review for a human to approve.
+
+## Meta Account 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>
+```
+
+## Meta Assets
+
+Image upload mutates the Meta asset library but does not change delivery, so it
+executes immediately and returns `image_hash` values:
+
+```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
+```
+
+## Meta Single-Object Flow
+
+Always inspect help for the exact flags before using a new command:
+
+```bash
+soku ads meta campaign create --help
+soku ads meta adset create --help
+soku ads meta creative create --help
+soku ads meta ad create --help
+```
+
+Common flow:
+
+```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 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 Meta Create
+
+Bulk commands are one layer at a time. Each item in `--items-file` must be an
+object with a unique non-empty `client_ref`.
+
+```bash
+soku ads meta campaign bulk-create --account-id <meta_account_id> --items-file campaigns.json --summary "Bulk-create campaigns"
+soku ads meta adset bulk-create --account-id <meta_account_id> --items-file adsets.json --summary "Bulk-create ad sets"
+soku ads meta creative bulk-create --account-id <meta_account_id> --items-file creatives.json --summary "Bulk-create creatives"
+soku ads meta ad bulk-create --account-id <meta_account_id> --items-file ads.json --summary "Bulk-create ads"
+```
+
+After approval, bulk reviews execute asynchronously. Poll with:
+
+```bash
+soku review show <review_id>
+```
+
+## Google Ads Writes
+
+Use:
+
+```bash
+soku ads google --help
+soku ads google campaign --help
+soku ads google ad-group --help
+soku ads google ad --help
+soku ads google keyword --help
+```
+
+The command path determines platform. Do not add `--platform`; the CLI injects
+`platform=google`.
+
+## Review Gate
+
+Review-gated commands return a review id:
+
+```bash
+soku review list
+soku review show <review_id>
+```
+
+As an agent, show the review id and summary to the user. Do not approve on the
+user's behalf. Approval is single-use; failed approval is terminal, so create a
+fresh review for retry.

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

@@ -0,0 +1,79 @@
+# Authentication And Workspace
+
+Soku CLI auth is machine-level and org-agnostic. The active org and brand are
+selected separately and sent on each workspace-scoped request.
+
+## Agent Login: Non-Blocking Split Flow
+
+Do not block a turn waiting for browser approval. Start login with:
+
+```bash
+soku auth login --no-wait
+```
+
+Return the exact `verification_uri` and `user_code` to the user, then stop. Do
+not edit, re-encode, or reconstruct the URL. After the user approves, resume
+with the exact `next` command returned by the CLI:
+
+```bash
+soku auth login --device-code <device_code>
+```
+
+For CI or headless contexts, use `SOKU_TOKEN`; do not echo it.
+
+## Resources
+
+The CLI resource model has been retired — `--resource` is **no longer needed
+for anything**. A default `soku auth login` reaches the entire CLI surface: all
+data commands (`soku ads / ga4 / posthog / call ...`) **and** every sub-command
+(`soku seo-hosting / automation / files / context / brand skill ...`). Writes
+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.
+
+## Workspace
+
+Never infer Soku workspace state from the local shell directory.
+
+```bash
+soku workspace status
+soku workspace resolve <brand>
+soku workspace use-brand <brand>
+```
+
+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.
+
+Legacy commands still work, but prefer `workspace` for agent flows:
+
+```bash
+soku org list
+soku org use <slug-or-id>
+soku brand list
+soku brand use <slug-or-id>
+```
+
+## Session State
+
+```bash
+soku auth status
+soku auth logout
+```
+
+On exit code 2 with an expired or revoked token, the CLI drops the stored token.
+Run the split login flow again.
+
+## Brand Memory
+
+Memory is scoped to the active Soku workspace:
+
+```bash
+soku memory list
+soku memory search "policy"
+soku memory get reference noiz-policy-event
+```
+
+Use memory as background and investigation leads. Do not report memory-derived
+context as verified fact unless the same turn confirms it with data actions,
+change history, billing evidence, or another authoritative source.

package/skills/soku/references/capability-flow.md

@@ -1,44 +1,53 @@
-# Capability discovery flow
+# Capability Discovery Flow
 
-A worked example of the discover → inspect → run loop the agent should follow.
-Each data capability is a typed sub-command under its namespace; `--help` is the
-discovery and inspection surface.
+Use this discover -> inspect -> run loop for data capabilities. `--help` is the
+authoritative runtime surface for command names, flags, required params, and
+usage notes.
 
-## 1. Confirm what's granted
+## 1. Confirm Workspace
 
 ```bash
-soku resources list
+soku auth status
+soku workspace status
 ```
 
-```json
-{"ok":true,"data":{"resources":[{"id":"data-infra","label":"Data Infra","description":"Read-only Soku synchronized data actions for ads and GA4.","enabled":true}],"count":1}}
-```
+A default `soku auth login` reaches the entire CLI surface — there is no
+resource model to grant or check (writes are still HITL-approved). Just make
+sure you are signed in and pointed at the right org/brand.
 
-## 2. Discover namespaces and actions with --help
+## 2. Discover Namespaces
 
 ```bash
-soku --help          # top level: namespaces (ads, ga4, …) plus auth/org/brand
-soku ads --help      # actions in the ads namespace
-soku ga4 --help      # actions in the ga4 namespace
+soku --help
+soku ads --help
+soku ga4 --help
+soku posthog --help
 ```
 
-Common ads actions:
+Common read actions:
 
-- `soku ads list-ad-accounts` — discover account_id values (run first when you have none)
-- `soku ads list-dimensions` — discover queryable dimensions/metrics/filters
-- `soku ads query-single-dimension`, `soku ads query-multi-dimension` — metric queries
-- `soku ads gaql-search` — raw Google Ads GAQL
-- `soku ga4 list-properties`, `soku ga4 get-property-overview`, `soku ga4 list-top-pages`, …
+- `soku ads list-ad-accounts`
+- `soku ads list-dimensions`
+- `soku ads query-single-dimension`
+- `soku ads query-multi-dimension`
+- `soku ads gaql-search`
+- `soku ga4 list-properties`
+- `soku ga4 get-property-overview`
+- `soku posthog list-projects`
+- `soku posthog list-tools`
+- `soku posthog query`
 
-## 3. Inspect a command's flags before running
+## 3. Inspect Before Running
 
 ```bash
 soku ads query-single-dimension --help
 ```
 
-The help is authoritative for flag names, required vs optional, types, and the
-appended usage notes. Never guess flags — read `--help` first. Object/list flags
-take a JSON string (e.g. `--filters '{"campaign_id":["123"]}'`).
+Never guess flags. Object and list flags take JSON strings, for example:
+
+```bash
+soku ads query-single-dimension --filters '{"campaign_id":["123"]}'
+```
 
 ## 4. Run
 
@@ -51,21 +60,19 @@ soku ads query-single-dimension \
   --date-end 2026-05-07
 ```
 
-## Raw escape hatch
+## Raw Escape Hatch
 
-When no typed sub-command exists for an action (e.g. a newer action than this
-CLI version ships), call it by its raw snake_case name:
+Use raw calls only when a typed sub-command is missing:
 
 ```bash
-soku call ads query_single_dimension --payload '{"account_id":"1234567890","dimension":"campaign","date_start":"2026-05-01","date_end":"2026-05-07"}'
+soku call ads query_single_dimension \
+  --payload '{"account_id":"1234567890","dimension":"campaign","date_start":"2026-05-01","date_end":"2026-05-07"}'
 ```
 
-## Typical chaining
-
-1. `soku ads list-ad-accounts` → pick an `account_id`.
-2. `soku ads list-dimensions` → learn valid dimension/metric slugs for that account.
-3. `soku ads query-single-dimension` / `query-multi-dimension` with the chosen
-   `--account-id` + slugs.
+## Typical Chaining
 
-Each command's `--help` lists related actions (`see_also`) so you can jump
-between them without re-scanning everything.
+1. `soku ads list-ad-accounts` -> pick `account_id`.
+2. `soku ads list-dimensions` -> learn legal dimensions, metrics, and filters.
+3. `soku ads query-single-dimension` or `query-multi-dimension`.
+4. Use `gaql-search` only if cached actions cannot expose the needed
+   Google-native field or segment combination.

package/skills/soku/references/data-capabilities.md

@@ -0,0 +1,118 @@
+# Data Capabilities
+
+Use typed commands for read workflows. Read `capability-flow.md` first when you
+are unfamiliar with the namespace.
+
+## Ads: Cached First
+
+Start with account and schema discovery:
+
+```bash
+soku ads list-ad-accounts --platform google
+soku ads list-dimensions --platform google --account-id <account_id>
+```
+
+Use cached analytics for normal reporting:
+
+```bash
+soku ads query-single-dimension \
+  --account-id <account_id> \
+  --dimension campaign \
+  --date-start 2026-05-01 \
+  --date-end 2026-05-07
+
+soku ads query-multi-dimension \
+  --account-id <account_id> \
+  --dimensions '["campaign","device"]' \
+  --date-start 2026-05-01 \
+  --date-end 2026-05-07
+```
+
+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`:
+
+```bash
+soku ads list-ad-accounts --platform chatgpt_ads
+soku ads query-single-dimension \
+  --platform chatgpt_ads \
+  --account-id <account_id> \
+  --dimension campaign \
+  --date-start 2026-05-01 \
+  --date-end 2026-05-07
+```
+
+ChatGPT Ads is synced reporting only — no campaign/ad write actions, and
+`query-multi-dimension` does not support it (use `query-single-dimension`
+instead).
+
+## Google Ads GAQL Fallback
+
+Use GAQL only when cached actions cannot answer the request:
+
+```bash
+soku ads get-resource-metadata --platform google --account-id <account_id> --resource-name campaign
+soku ads gaql-search \
+  --platform google \
+  --account-id <account_id> \
+  --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 them.
+
+## GA4
+
+Prefer cached overview commands:
+
+```bash
+soku ga4 list-properties
+soku ga4 get-property-overview --property-id <property_id>
+soku ga4 list-top-pages --property-id <property_id>
+soku ga4 list-traffic-sources --property-id <property_id>
+soku ga4 get-daily-trend --property-id <property_id>
+soku ga4 get-conversion-overview --property-id <property_id>
+soku ga4 list-events --property-id <property_id>
+```
+
+Use live fallback only for dimensions, metrics, filters, or custom definitions
+not covered by cached commands:
+
+```bash
+soku ga4 get-metadata --property-id <property_id>
+soku ga4 run-report \
+  --property-id <property_id> \
+  --metrics '["activeUsers"]' \
+  --dimensions '["sessionDefaultChannelGroup"]'
+```
+
+## PostHog
+
+Do not ask the user for a project id before listing accessible projects:
+
+```bash
+soku posthog list-projects
+soku posthog list-tools --project-id <project_id>
+soku posthog query --project-id <project_id> --tool read-data-schema --arguments '{}'
+soku posthog query --project-id <project_id> --tool execute-sql \
+  --arguments '{"query":"SELECT count() FROM events WHERE event = '\''$pageview'\''"}'
+```
+
+The CLI exposes read allowlisted PostHog tools. Writes and unvetted MCP tools
+stay outside the generated command tree.
+
+## Raw Calls
+
+Use `soku call <namespace> <action>` only when a typed command is missing:
+
+```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"}}'
+```
+
+Review-gated writes through `soku call` require `--summary`.

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

@@ -0,0 +1,51 @@
+# Egress And Security
+
+Use `soku egress` for covered third-party APIs. Soku injects provider
+credentials server-side; no third-party API key lives on this machine.
+
+## Egress Pattern
+
+Prefix the skill's `curl` with `soku egress --`:
+
+```bash
+soku egress -- curl -H "Authorization: Bearer $AHREFS_API_KEY" "https://api.ahrefs.com/v3/..."
+```
+
+`$AHREFS_API_KEY` may be unset locally. That is expected. The CLI strips empty
+placeholder auth and the Soku API injects the real credential.
+
+List covered hosts:
+
+```bash
+soku egress providers
+```
+
+For a host not listed, the proxy does not inject credentials. Follow that
+skill's own auth instructions instead.
+
+## Do Not Preflight Local Keys
+
+Do not write guards such as:
+
+```bash
+test -n "$AHREFS_API_KEY"
+```
+
+Do not abort a skill because a key looks missing. Route the call through
+`soku egress -- curl ...`.
+
+## Response Semantics
+
+Successful upstream responses are returned verbatim on stdout, not wrapped in a
+success envelope. Soku-level failures use the normal CLI error envelope.
+
+## General Security Rules
+
+- Never print the Soku access token.
+- Prefer `SOKU_TOKEN` for CI and headless agents.
+- Do not approve review-gated writes on behalf of the user.
+- Avoid literal secret argv values. For Cloudflare Worker setup use
+  `--cf-token-env` or `--cf-token-stdin`.
+- Pass user-provided values as separate argv elements.
+- Treat `verification_uri`, signed URLs, review ids, and provider URLs as
+  opaque strings.

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

@@ -0,0 +1,93 @@
+# SEO Hosting, Automations, And Files
+
+These commands operate on the active Soku workspace. Confirm workspace first:
+
+```bash
+soku workspace status
+```
+
+## SEO Hosting Pages
+
+SEO Hosting pages are complete HTML documents, not Markdown. They are addressed
+by `section` and `slug`.
+
+```bash
+soku seo-hosting status
+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
+```
+
+Run `status` before publishing. If no domain is live for the section, do not
+publish yet.
+
+`put` creates or overwrites a draft and requires exactly one HTML source:
+`--html`, `--html-file`, or `--html-stdin`. Reference uploaded assets by the
+absolute URL returned from `upload-asset`. No custom JavaScript.
+
+Writes run immediately. Confirm user intent before publishing or deleting.
+
+## SEO Hosting Domain Connections
+
+```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:
+
+```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
+```
+
+Never pass Cloudflare tokens as literal argv values. Use `--cf-token-env` or
+`--cf-token-stdin`. Add conflict override flags only after the user confirms the
+risk.
+
+## Automations
+
+```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>`; 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.
+
+## Context Hub
+
+```bash
+soku context list
+soku context upload ./brief.pdf --dir research
+soku context mkdir research
+soku context rename old/path new/path
+soku context rm research/brief.pdf
+```
+
+Paths are context-relative. Do not include a `context/` prefix.
+
+## Temporary Public File URLs
+
+```bash
+soku files publish ./creative.png
+```
+
+URLs are short-lived signed URLs, usually around 30 minutes. If a downstream API
+later fails to fetch the file, check expiration first.

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

@@ -0,0 +1,89 @@
+# Skills And Updates
+
+Soku distributes two kinds of local agent skills:
+
+- Bundled meta skill: `soku` teaches the CLI basics and references.
+- Business skills: catalog skills installed as `soku-<slug>`, for example
+  `soku-ads-report`.
+
+## Install
+
+Install the bundled meta skill:
+
+```bash
+soku skill install
+soku skill install --global
+soku skill install --agent claude --global
+```
+
+Install business skills:
+
+```bash
+soku skill list
+soku skill install account-audit
+soku skill install ads-report google-ads
+soku skill install --all
+soku skill status
+soku skill list-installed
+```
+
+Business skill install automatically ensures the `soku` meta skill exists.
+Installed business skill names are Soku-prefixed:
+
+```text
+use @soku-ads-report skill
+```
+
+Use catalog slugs for install/remove (`ads-report`) and agent names for
+invocation (`soku-ads-report`).
+
+## Update
+
+```bash
+soku update status
+soku update skills
+soku update cli
+```
+
+Normal `soku` commands schedule a background skill refresh at most once every 24
+hours. Controls:
+
+```bash
+SOKU_NO_SKILL_AUTO_UPDATE=1
+SOKU_UPDATE_INTERVAL_HOURS=6
+SOKU_AUTO_UPDATE_CLI=1
+```
+
+The CLI binary itself is advisory by default. Run `soku update cli` to install
+the latest npm package unless the user explicitly opted into auto CLI updates.
+
+## Legacy Meta-Only Installs
+
+Older installations may have only:
+
+```text
+<skillsDir>/soku/SKILL.md
+```
+
+with no `.soku-skills.json` manifest and no `references/` directory.
+`soku update skills` detects those legacy meta-only installs, refreshes
+`SKILL.md`, copies `references/`, and writes a Soku-managed manifest entry.
+
+Global `npm i -g @soku-ai/cli` also refreshes already-installed global meta
+skills after npm finishes installing. It does not install new business skills
+and does not scan project-local directories.
+
+`soku update cli` runs that same global `npm i -g` under the hood, so its JSON
+result includes `mustRereadMetaSkill` and `metaSkillRefreshed: [<paths>]`. When
+`mustRereadMetaSkill` is true, re-read this skill from the listed path(s)
+before continuing — the on-disk copy just changed underneath this session.
+
+## Remove
+
+```bash
+soku skill remove ads-report
+soku skill remove soku
+```
+
+Removing the last Soku-managed skill removes the local `.soku-skills.json`
+manifest.

package/dist/commands/resources.d.ts

@@ -1,4 +0,0 @@
-/** `soku resources list` — show the external resources granted to this session. */
-import { Command } from 'commander';
-export declare function registerResourceCommands(program: Command): void;
-//# sourceMappingURL=resources.d.ts.map

package/dist/commands/resources.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/commands/resources.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAYnC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0B/D"}