@soku-ai/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

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,26 @@ 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's frontmatter records the CLI release it was written against under
+`metadata.cliVersion`. If the installed CLI is newer, run the command above
+before relying on details in these reference files.