@zibby/cli 0.2.1 → 0.4.0

package/dist/templates/zibby-workflow-claude/agents-md-block.md

@@ -1,4 +1,4 @@
-<!-- BEGIN zibby-workflows zibby-template-version: 3 -->
+<!-- BEGIN zibby-workflows zibby-template-version: 4 -->
 ## Zibby
 
 This project uses **Zibby** — there are two surfaces:
@@ -16,7 +16,7 @@ Both share `.zibby.config.mjs` at the project root.
 Files:
 ```
 <paths.workflows or .zibby/workflows>/<name>/
-├── workflow.json    name, entryClass, triggers, schemas
+├── workflow.json    name, entryClass, triggers, schemas (manifest)
 ├── graph.mjs        nodes + edges from START to END
 ├── nodes/
 │   ├── index.mjs    barrel export
@@ -33,19 +33,42 @@ Each node has `async run(ctx)` where `ctx` provides:
 Common dev loop:
 ```
 zibby workflow new <name>               # scaffold
-zibby workflow run <name>               # one-shot local run (mirrors trigger flags)
+zibby workflow run <name>               # one-shot local run (preferred for the dev loop)
 zibby workflow run <name> -p k=v        # with input
 zibby workflow deploy <name>            # build + push to Zibby Cloud
 zibby workflow trigger <uuid>           # invoke the cloud workflow
 zibby workflow logs <uuid> -t           # tail live logs (docker-compose-style)
-zibby workflow list                     # find UUIDs and statuses
+zibby workflow list                     # find UUIDs and statuses (local + cloud)
+zibby workflow download <uuid>          # pull the cloud workflow source back to .zibby/workflows/
 zibby workflow delete <uuid>            # remove a deployed workflow
 ```
 
-`run` and `trigger` accept the same input flags (`-p key=value`, `--input '<json>'`, `--input-file path.json`) — flip the verb to switch between local and cloud. `workflow start` exists too but is the long-lived dev server (Studio integration); for plain CLI iteration prefer `run`.
+**`run` vs `start`.** `workflow run` is the one-shot CLI iteration command — load the graph, execute it once, print the result, exit. That's the right primitive for the dev loop and for CI/CD. `workflow start` is a *long-lived* local dev server (default port 3848) used by Studio for replay/debug; for plain CLI iteration always prefer `run`.
+
+`run` and `trigger` accept the same input flag surface — flip the verb to switch between local and cloud:
+- `-p key=value` (repeatable) — highest precedence
+- `--input '<json>'` — JSON string
+- `--input-file path.json` — JSON file, lowest precedence
 
 Static outbound IPs (for customers behind firewalls): see `--dedicated-ip` flag on `deploy`.
 
+#### Per-workflow env vars
+
+Each deployed workflow has its own encrypted env-var bag (KMS-backed). Vars get injected into the Fargate task at trigger time, and **workflow env wins over project secrets on conflict**. Use this for per-pipeline credentials (different `ANTHROPIC_API_KEY` per workflow, a workflow-only `DATABASE_URL`, etc.).
+
+```
+zibby workflow env list <uuid>                          # show key names (values never returned)
+zibby workflow env set  <uuid> ANTHROPIC_API_KEY=sk-…   # add or rotate one key
+zibby workflow env unset <uuid> OLD_KEY                 # remove one key
+zibby workflow env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
+```
+
+Fast path on first deploy — sync a `.env` in one shot:
+```
+zibby workflow deploy my-pipeline --env .env [--env .env.prod]
+```
+The CLI deploys, then runs `push` against the freshly-minted UUID.
+
 ---
 
 ### Tests
@@ -55,6 +78,7 @@ Files:
 test-specs/                 source `.txt` specs (paths.specs)
 tests/                      generated `.spec.js` (paths.generated; regenerated each run)
 test-results/               videos, traces, JSON results per run
+.zibby/memory/.dolt/        local test memory DB (selectors, page model, history)
 playwright.config.js
 ```
 
@@ -64,6 +88,8 @@ Common dev loop:
 ```
 zibby test test-specs/<name>.txt        # run a spec
 zibby test "go to example.com and ..."  # inline, no file
+zibby test <spec> --agent claude        # override the configured agent (claude|cursor|codex|gemini)
+zibby test --sources <ids> --execution <id>   # cloud test cases (run from a stored execution)
 zibby generate -t ENG-1234              # generate specs from a Jira ticket
 zibby video                             # organize videos next to spec files
 zibby upload <spec-path>                # upload existing artifacts to cloud
@@ -71,6 +97,39 @@ zibby upload <spec-path>                # upload existing artifacts to cloud
 
 When debugging a failed test, watch the video at `test-results/<spec>/video.webm` — that's almost always faster than reading logs.
 
+#### Test memory
+
+`.zibby/memory/.dolt/` is a **local-first Dolt SQL database** (Git-for-data) that learns from every test run — selectors that worked, page-element fingerprints, navigation transitions, timing quirks, recorded insights. The runner auto-pulls before a run and auto-pushes after a passing run. Keying is **per-domain** (not per-spec), so any spec that hits `myapp.com` benefits from selectors learned by every other spec on the same domain.
+
+When `zibby test` runs and `.zibby/memory/.dolt/` exists, the agent gets 5 MCP tools auto-exposed:
+
+- `memory_get_test_history` — query recent runs (pass/fail/timing); filter by spec-path substring
+- `memory_get_selectors` — query known selectors per page with stability metrics (success/fail counts)
+- `memory_get_page_model` — query page structure (elements, roles, accessible names, best selector)
+- `memory_get_navigation` — known page-to-page transitions (what click/submit produced what URL)
+- `memory_save_insight` — save an observation. Categories: `selector_tip | timing | navigation | workaround | flaky | general`
+
+> **AFTER completing the test, you MUST call `memory_save_insight` at least once.** Save any useful finding: reliable selectors, timing quirks, navigation patterns, workarounds. Be specific — future runs will read your insights. (Lifted from the memory skill's `promptFragment`.)
+
+Local CLI:
+```
+zibby memory stats         # row counts, last commit, per-spec breakdown
+zibby memory cost          # real LLM token spend per spec / per domain
+zibby memory compact       # prune old runs + Dolt GC (--max-runs 50, --max-age 90d)
+zibby memory reset -f      # wipe the DB
+```
+
+**Team sync.** Memory is local-first; opt into a shared remote so teammates' learnings flow back to you:
+
+```
+zibby memory remote add aws://my-bucket/team/proj/main   # BYO S3 / GCS / DoltHub / file:///
+zibby memory remote use --hosted                         # OR: Zibby-managed S3 (signed-in only)
+zibby memory pull                                        # manual override (auto on test start)
+zibby memory push                                        # manual override (auto on passing test)
+```
+
+Set `memorySync.remote` in `.zibby.config.mjs` (`'hosted'` or an `aws://...` URL) and `zibby init` auto-wires the remote — teammates clone the repo, run `zibby init`, and they're plugged into the same memory.
+
 ---
 
 ### How to invoke the CLI
@@ -97,6 +156,7 @@ Don't waste time on `npx @zibby/cli` — not always published.
 - Deploying & bundling: https://docs.zibby.app/workflows/deploying
 - Triggering & inputs: https://docs.zibby.app/workflows/triggers
 - Live log streaming: https://docs.zibby.app/workflows/logs
+- Per-workflow env vars: https://docs.zibby.app/cloud/env-vars
 - Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
 - Security & secrets: https://docs.zibby.app/workflows/security
 - Debugging: https://docs.zibby.app/workflows/debugging

package/dist/templates/zibby-workflow-claude/claude/agents/zibby-test-author.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 ---
 name: zibby-test-author
 description: Sub-agent that helps the user design and author Zibby test specs end-to-end. Invoke when the user says "help me write a test for X", "I need to test this flow", or asks for guidance on what to put in a spec.
@@ -53,12 +53,27 @@ A spec is unambiguous English with one action per line. See `/zibby-test-write`
 
 5. **Stop when the spec exercises the goal end-to-end.** Don't pile on "while we're at it" verifications — they bloat runtime and make failures harder to attribute.
 
+## Test memory (`.zibby/memory/.dolt/`)
+
+When `zibby test` runs and `.zibby/memory/.dolt/` exists (initialized by `zibby memory init` or auto-created on first run with `-m` / a `memorySync.remote` config), the agent gets 5 MCP tools auto-exposed. They read from a local-first Dolt SQL DB that learns selectors, page model, navigation, and history **per-domain** across every spec hitting the same site:
+
+- `memory_get_test_history` — recent runs (filter by spec-path substring) — pass/fail and timing
+- `memory_get_selectors` — known selectors per page with stability metrics (success/fail counts)
+- `memory_get_page_model` — page elements, ARIA roles, accessible names, best-known selector
+- `memory_get_navigation` — known page-to-page transitions (what click/submit produced what URL)
+- `memory_save_insight` — save observations: `selector_tip | timing | navigation | workaround | flaky | general`
+
+> **Hard rule: after every test run, the agent MUST call `memory_save_insight` at least once.** Save reliable selectors, timing quirks, navigation patterns, workarounds — be specific. Future runs read these. (This is in the memory skill's prompt fragment; surface it to the user if they ask why their tests keep getting smarter.)
+
+Team sync (optional): a project may have `memorySync.remote: 'hosted'` (Zibby-managed S3, signed-in only) or `'aws://...' / 'gs://...'` (BYO) configured in `.zibby.config.mjs`. If set, the runner auto-pulls before each run and auto-pushes after passing runs. Manual override: `zibby memory pull` / `zibby memory push`.
+
 ## Hard rules
 
 - **Never recommend `--headless` for first runs.** Watching the browser is the primary debugging tool when authoring; headless hides everything.
 - **Never recommend disabling video.** Videos are 99% of post-mortem signal; they're cheap.
 - **Don't write CSS selectors into specs.** Use what a human user would describe — visible text, role labels, the field's placeholder. Selectors belong in generated `.spec.js`, not the source.
 - **Don't suggest `npx playwright test` directly** to bypass Zibby for "speed". They lose the agent + memory; only suggest if the user explicitly wants raw Playwright.
+- **Always call `memory_save_insight` at the end of a test run.** This is non-negotiable — without it, memory degrades to the seeded baseline and stops compounding.
 
 ## Reference
 

package/dist/templates/zibby-workflow-claude/claude/agents/zibby-workflow-builder.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 2 -->
+<!-- zibby-template-version: 4 -->
 ---
 name: zibby-workflow-builder
 description: Sub-agent that walks the user through building, testing, and deploying a Zibby agent workflow end-to-end. Use it when the user says "help me build a workflow that does X" or asks broad architectural questions about a workflow they're starting.
@@ -49,7 +49,7 @@ The return value of `run()` is the node's output, available to downstream nodes
 
 4. **Generate the scaffold** if they don't have one yet:
    ```
-   zibby workflow generate <slug>
+   zibby workflow new <slug>
    ```
    Then add nodes one at a time using the `/zibby-add-node` command.
 
@@ -64,6 +64,26 @@ The return value of `run()` is the node's output, available to downstream nodes
 
 6. **Stop when the workflow does the goal end-to-end.** Don't pile on speculative nodes.
 
+## Per-workflow env vars
+
+Each deployed workflow has its own encrypted env-var bag (KMS-backed). Workflow env wins over project secrets on conflict.
+
+- `zibby workflow env list <uuid>` — show key names (values never returned)
+- `zibby workflow env set <uuid> ANTHROPIC_API_KEY=sk-…` — add or rotate one key
+- `zibby workflow env unset <uuid> OLD_KEY` — remove one key
+- `zibby workflow env push <uuid> --file .env [--file .env.prod]` — bulk replace from .env files (later files override)
+- `zibby workflow deploy <slug> --env .env` — fast path: deploy + auto-`push` of .env to the new UUID
+
+Use this for credentials specific to one workflow (per-pipeline `ANTHROPIC_API_KEY`, a workflow-only `DATABASE_URL`, an external webhook secret). Project-wide secrets stay on the project record.
+
+## Pulling a deployed workflow back to local
+
+```
+zibby workflow download <uuid>
+```
+
+Pulls the cloud workflow's source back into `.zibby/workflows/<name>/`. Useful when collaborators need the source from cloud (e.g. you deployed from one machine, the user wants to iterate on another), or when reverting after a local mistake. UUIDs come from `zibby workflow list`.
+
 ## Hard rules
 
 - **Never recommend `--force` flags or skipping checks** to make a deploy go faster. Build problems are signal.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-add-node.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 2 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-add-node — scaffold a new node in a Zibby workflow
 
 You are helping the user add a new **node** to one of their Zibby agent workflows.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-debug.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-debug — diagnose a failing or stuck Zibby workflow
 
 You are helping the user debug a workflow that didn't behave as expected.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-delete.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-delete — delete a deployed Zibby workflow
 
 You are helping the user remove a workflow from Zibby Cloud.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-deploy.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-deploy — deploy a Zibby workflow to the cloud
 
 You are helping the user deploy a workflow they've been building locally.
@@ -47,31 +47,41 @@ Canonical docs: **https://docs.zibby.app/workflows/deploying**
 
 ## Optional flags worth knowing
 
+`zibby workflow deploy` accepts:
 - `--project <id>` — skip the interactive project picker
 - `--api-key <key>` — use a PAT instead of the session token (for CI)
+- `--env <path>` — sync a `.env` file into per-workflow env vars after deploy. Repeatable; later files override.
 - `--verbose` — print raw CodeBuild output during the build (helpful for debugging build failures)
-- `--dedicated-ip <action>` — opt this workflow into the dedicated egress addon (static outbound IP). See `/zibby-static-ip` for setup.
 
-## Static outbound IP (dedicated egress) at deploy time
+### Seeding per-workflow env on first deploy
 
-If the user's workflow needs to call APIs that require IP allowlisting (corporate GitHub, GitLab Enterprise, paranoid SaaS firewalls), the workflow needs the **dedicated egress IP** addon enabled on their account, AND the workflow must opt in.
+If the workflow needs its own `ANTHROPIC_API_KEY`, `DATABASE_URL`, etc., put them in a `.env` and pass `--env`:
 
-Three flags map to three things:
+```
+zibby workflow deploy <name> --env .env
+zibby workflow deploy <name> --env .env --env .env.prod   # later files win
+```
+
+After deploy, manage them surgically with `zibby workflow env set/unset/list/push <uuid>`. See `/zibby-list` to recover the UUID; full guide at https://docs.zibby.app/cloud/env-vars.
+
+## Static outbound IP (dedicated egress)
+
+If the user's workflow needs to call APIs that require IP allowlisting (corporate GitHub, GitLab Enterprise, paranoid SaaS firewalls), the workflow needs the **dedicated egress IP** addon. The flag lives on the legacy alias `zibby deploy` (NOT `zibby workflow deploy`):
 
 | Flag | What it does |
 |------|-------------|
-| `--dedicated-ip status` | Show current addon state for the account (active / inactive / billing) |
-| `--dedicated-ip enable` | Enable the addon on the account (Pro subscription required, ~$50/mo). One-time per account. |
-| `--dedicated-ip use` | Mark THIS workflow as using the static egress IP (per-workflow opt-in, after `enable`) |
-| `--dedicated-ip unuse` | Stop routing this workflow through the static IP |
-| `--dedicated-ip disable` | Disable the addon for the whole account |
+| `zibby deploy <name> --dedicated-ip status` | Show current addon state for the account (active / inactive / billing) |
+| `zibby deploy <name> --dedicated-ip enable` | Enable the addon on the account (Pro subscription required, ~$50/mo). One-time per account. |
+| `zibby deploy <name> --dedicated-ip use` | Mark THIS workflow as using the static egress IP (per-workflow opt-in, after `enable`) |
+| `zibby deploy <name> --dedicated-ip unuse` | Stop routing this workflow through the static IP |
+| `zibby deploy <name> --dedicated-ip disable` | Disable the addon for the whole account |
 
 Typical first-time flow when the user says "I need a static outbound IP":
-1. `zibby workflow deploy <name> --dedicated-ip status` — check whether they have it
-2. If inactive → `zibby workflow deploy <name> --dedicated-ip enable` — enables the account-wide addon (interactive billing prompt; prerequisite Pro subscription)
-3. `zibby workflow deploy <name> --dedicated-ip use` — opts this specific workflow in
+1. `zibby deploy <name> --dedicated-ip status` — check whether they have it
+2. If inactive → `zibby deploy <name> --dedicated-ip enable` — enables the account-wide addon (interactive billing prompt; prerequisite Pro subscription)
+3. `zibby deploy <name> --dedicated-ip use` — opts this specific workflow in
 4. Regular `zibby workflow deploy <name>` from now on uses the static IP
 
 After `--dedicated-ip use`, every node in this workflow gets its outbound HTTP routed through the egress proxy, and `process.env.HTTP_PROXY` / `HTTPS_PROXY` are set in the sandbox automatically. Their static IPs are visible to customers via `https://docs.zibby.app/workflows/egress`.
 
-**Don't** run `--dedicated-ip enable` without confirming with the user — it has billing impact ($50/mo addon). Always confirm.
+**Don't** run `--dedicated-ip enable` without confirming with the user — it has billing impact ($50/mo addon). Always confirm. See `/zibby-static-ip` for the deeper walkthrough.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-list.md

@@ -1,9 +1,9 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-list — list workflows (local + cloud) with their UUIDs and statuses
 
 You are helping the user see what workflows exist — locally scaffolded and remotely deployed.
 
-Canonical docs: **https://docs.zibby.app/workflows/listing**
+Canonical docs: **https://docs.zibby.app/cli-reference#workflow-list**
 
 ## Steps
 

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-memory-cost.md

@@ -0,0 +1,39 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-memory-cost — show real LLM token spend across past test runs
+
+You are helping the user see how many input/output/cache tokens their tests have actually burned, broken down per spec and per domain. This is real measured spend (read off run records in `.zibby/memory/.dolt/`), not an estimate.
+
+Canonical docs: **https://docs.zibby.app/tests/memory**
+
+## What the command shows
+
+```
+Bash(zibby memory cost)
+```
+
+Per-spec and per-domain rollup of:
+- Input tokens
+- Output tokens
+- Cache hit / cache write tokens (when the agent supports prompt caching)
+- Estimated $ cost (uses current public model pricing)
+- Recent-runs trend, so you can see if a spec is getting cheaper or more expensive over time
+
+The numbers are pulled from `test_runs` rows in the Dolt DB — every test run records the agent's actual usage on completion.
+
+## When to invoke
+
+- User asks "how much are my tests costing me?" or "which spec is the expensive one?"
+- After enabling prompt caching to confirm cache hits are landing
+- When deciding whether to swap to a cheaper agent on hot specs (`--agent` per run)
+- When triaging a regression in test runtime — high token counts often correlate with the agent retrying
+
+## Caveats
+
+- **Only counts what's in local memory.** Runs on machines that haven't pulled from the team remote won't appear. Run `/zibby-memory-pull` first if you want the full team picture.
+- **Pricing is informational.** Public API pricing changes; treat the $ column as a guide, not a bill. The token counts themselves are exact.
+- **Empty if you've never run a test with memory enabled.** Confirm the runs are in there with `/zibby-memory-stats` first.
+
+## Related
+
+- `/zibby-memory-stats` — what's in the DB at all
+- `/zibby-memory-pull` — refresh from team remote before reading cost

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-memory-pull.md

@@ -0,0 +1,47 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-memory-pull — pull the team's latest test memory from the configured remote
+
+You are helping the user fetch the team's latest learnings (selectors, page model, insights, run history) from the project's configured memory remote into local `.zibby/memory/.dolt/`.
+
+Canonical docs: **https://docs.zibby.app/tests/memory**
+
+## When this is needed (vs. just runs automatically)
+
+`zibby test` auto-pulls before every run when a remote is configured, and auto-pushes after every passing run. So most of the time the user doesn't need to invoke pull manually. Manual pull is for:
+
+- Fresh clone of the repo — first sync to seed `.zibby/memory/.dolt/` from the remote
+- After a teammate landed a big batch of new learnings and the user wants them before running anything
+- Inspecting team memory (`/zibby-memory-stats`, `/zibby-memory-cost`) without running a test
+- Reconciling after a manual conflict in the Dolt DB
+
+## How to run
+
+```
+Bash(zibby memory pull)
+```
+
+The CLI fetches from whatever remote `zibby memory remote info` reports — BYO S3/GCS/DoltHub URL or the Zibby-hosted backend. No flags.
+
+## Pre-flight: is a remote configured?
+
+Before suggesting `pull`, check:
+
+```
+Bash(zibby memory remote info)
+```
+
+- **No remote configured** → pull errors out. Tell the user to either:
+  - Add their own: `zibby memory remote add aws://my-bucket/team/proj/main`
+  - Use the hosted one: `zibby memory remote use --hosted` (requires `zibby login`)
+  - See `/zibby-memory-remote-use-hosted` for the hosted path.
+- **Hosted remote, signed out** → `zibby login` first.
+
+## After pulling
+
+Confirm the pull landed with `/zibby-memory-stats` — row counts should jump (selectors, runs, insights) compared to before.
+
+## Related
+
+- `zibby memory push` — manual push (auto on passing test, but sometimes you want to share now)
+- `/zibby-memory-stats` — verify what came in
+- `/zibby-memory-remote-use-hosted` — switch to the Zibby-managed S3 backend

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-memory-remote-use-hosted.md

@@ -0,0 +1,61 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-memory-remote-use-hosted — switch this project's memory remote to Zibby-managed S3
+
+You are helping the user point their `.zibby/memory/.dolt/` at Zibby's hosted S3 backend, instead of running their own S3 bucket / GCS / DoltHub repo.
+
+Canonical docs: **https://docs.zibby.app/tests/memory**
+
+## What this does
+
+```
+Bash(zibby memory remote use --hosted)
+```
+
+Allocates a tenant-scoped prefix on Zibby-managed S3 for this project (keyed on the projectId in `.zibby.config.mjs`) and writes that as the local Dolt remote. After this, every `zibby test` run auto-pulls before and auto-pushes after — same as a BYO remote, just without the bucket plumbing.
+
+## Prerequisite: signed in
+
+Hosted remote is **signed-in users only**. Verify:
+
+```
+Bash(zibby status)
+```
+
+If not signed in, run `zibby login` first. The CLI uses the saved session to derive the tenant prefix; it won't fall back to anonymous.
+
+## When to use hosted vs BYO
+
+| | Hosted (`--hosted`) | BYO (`zibby memory remote add aws://...`) |
+|---|---|---|
+| Setup time | Zero — `--hosted` and you're done | Provision an S3 bucket, IAM, optional KMS |
+| Who can read | Everyone with project access on Zibby | Whoever you grant in IAM |
+| Where data lives | Zibby-managed AWS account | Your account |
+| Compliance / data-residency | Limited regions | Wherever you want |
+| Cost | Included in plan | Your S3 bill |
+
+If the user has any data-residency requirement or a regulated workload, prefer BYO. Otherwise hosted is the path of least resistance.
+
+## Switching from BYO to hosted
+
+`zibby memory remote use --hosted` overwrites the existing remote. If they had a BYO remote and might want to keep its history, run `zibby memory push` against the old remote first so nothing's lost — then switch.
+
+## After switching
+
+1. `zibby memory pull` — seed `.zibby/memory/.dolt/` from the hosted prefix (no-op the very first time per project)
+2. `/zibby-memory-stats` — confirm
+3. Commit `.zibby.config.mjs` if you set `memorySync.remote: 'hosted'` so teammates auto-wire on next `zibby init`
+
+## Reverting
+
+```
+Bash(zibby memory remote remove)
+```
+
+Drops the remote — memory becomes local-only again. The data on Zibby's S3 isn't deleted (it's still tenant-scoped), but nothing pushes or pulls until a new remote is configured.
+
+## Related
+
+- `/zibby-memory-pull` — manual pull (auto on test start)
+- `/zibby-memory-stats` — verify what's in the local DB
+- `zibby memory remote info` — show current remote config
+- `zibby memory remote add <url>` — BYO remote (S3/GCS/DoltHub/file:///)

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-memory-stats.md

@@ -0,0 +1,38 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-memory-stats — inspect the local test memory database
+
+You are helping the user see what's in their `.zibby/memory/.dolt/` test-memory DB — row counts per table, last commit, and per-spec breakdown.
+
+Canonical docs: **https://docs.zibby.app/tests/memory**
+
+## What the command shows
+
+```
+Bash(zibby memory stats)
+```
+
+Prints a summary of the local Dolt database:
+- **Test runs** — total runs recorded, pass/fail split, last run timestamp
+- **Selectors** — total cached selectors, top pages by selector count
+- **Page model** — pages mapped, total elements
+- **Navigation** — known transitions
+- **Insights** — count by category (`selector_tip | timing | navigation | workaround | flaky | general`)
+- **Dolt status** — current branch, last commit hash, uncommitted changes
+
+## When to invoke
+
+- User asks "what does Zibby know about my app?" or "show me what's in test memory"
+- After running a few tests, to confirm the agent is actually persisting learnings
+- Before a `zibby memory compact` to see how much there is to prune
+- Before a `zibby memory remote add` to know what's about to ship to the team
+
+## Empty database?
+
+If the user just ran `zibby memory init` (or it auto-initialized on first `zibby test`), most counts will be 0. That's fine — selectors and page model populate after the first successful run. Suggest running a test first.
+
+## Related commands
+
+- `/zibby-memory-cost` — real LLM token spend per spec / per domain
+- `/zibby-memory-pull` — pull team's latest learnings from the configured remote
+- `zibby memory compact` — prune old runs (`--max-runs N`, `--max-age <days>`)
+- `zibby memory reset -f` — wipe the DB (destructive — confirm first)

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-static-ip.md

@@ -1,10 +1,12 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-static-ip — set up dedicated outbound static IP for a workflow
 
 You are helping the user route a workflow's outbound traffic through a static IP address — needed when the workflow calls APIs that require IP allowlisting (corporate GitLab/GitHub Enterprise, internal SaaS, firewalls).
 
 Canonical docs: **https://docs.zibby.app/workflows/egress**
 
+> Note: the `--dedicated-ip` flag lives on the legacy alias `zibby deploy <name>`, NOT on `zibby workflow deploy <name>`. The two share a handler, but only `zibby deploy` exposes this flag in `--help`.
+
 ## What "static IP" means here
 
 By default, workflow tasks run on Fargate and their outbound traffic exits via AWS-managed IPs that rotate. With the **dedicated egress** addon enabled, the workflow's outbound traffic is routed through a Zibby-managed proxy whose IP is pinned and customer-allowlistable.
@@ -23,19 +25,19 @@ Two pieces:
 
 2. **Check current state:**
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip status)
+   Bash(zibby deploy <name> --dedicated-ip status)
    ```
    Output tells you: addon active or inactive, this workflow currently using it or not, and the assigned IPs to publish to customers.
 
 3. **If addon is inactive — enable it** (only after explicit user confirmation):
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip enable)
+   Bash(zibby deploy <name> --dedicated-ip enable)
    ```
    This is one-time per account. After this, the addon is active for ALL workflows in the account that opt in.
 
 4. **Opt this workflow in:**
    ```
-   Bash(zibby workflow deploy <name> --dedicated-ip use)
+   Bash(zibby deploy <name> --dedicated-ip use)
    ```
    From now on, every deploy of this workflow + every triggered execution routes outbound through the static IP.
 
@@ -52,8 +54,8 @@ Two pieces:
 
 ## Reverting
 
-- `Bash(zibby workflow deploy <name> --dedicated-ip unuse)` — stop routing this workflow's egress through the static IP. Other opted-in workflows are unaffected.
-- `Bash(zibby workflow deploy <name> --dedicated-ip disable)` — disable the addon entirely (also stops billing).
+- `Bash(zibby deploy <name> --dedicated-ip unuse)` — stop routing this workflow's egress through the static IP. Other opted-in workflows are unaffected.
+- `Bash(zibby deploy <name> --dedicated-ip disable)` — disable the addon entirely (also stops billing).
 
 ## Tell the user the IPs
 

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-tail.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-tail — stream live logs from a Zibby workflow
 
 You are helping the user tail logs from a workflow execution.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-debug.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-debug — diagnose a failing Zibby test
 
 You are helping the user figure out why a test failed.
@@ -34,7 +34,7 @@ Spec ambiguity is the most common cause. If the spec says "click the button" and
 ```
 Bash(zibby test test-specs/<name>.txt --verbose)        # info-level logs
 Bash(zibby test test-specs/<name>.txt --debug)          # all logs, lots
-Bash(zibby test test-specs/<name>.txt --headed)         # see the browser
+Bash(zibby test test-specs/<name>.txt)                  # default is headed — drop --headless to watch the browser
 ```
 
 ### 5. Re-execute one node from a prior session

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-generate.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-generate — generate test specs from a Jira ticket / requirements
 
 You are helping the user auto-generate test specs from a ticket description (Jira) or a free-text requirements doc. Zibby's `generate` command runs the configured AI agent against the codebase + ticket and produces `.txt` specs in `test-specs/`.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-run.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-run — execute a Zibby test spec
 
 You are helping the user run an existing test spec through Zibby. A spec is a `.txt` file describing what to test in plain language; Zibby's runner turns it into a Playwright execution and produces a video + JSON results.
@@ -40,9 +40,10 @@ Canonical docs: **https://docs.zibby.app/tests/running**
 - `--verbose` / `--debug` — escalate log levels
 - `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
 - `--sync` / `--no-sync` — force / skip cloud upload regardless of config
+- `--sources <ids> --execution <id>` — run cloud-stored test cases from a specific execution (comma-separated IDs)
 
 ## Common failure modes
 
 - **"No spec found"** — path is relative to project root, not cwd. Check `paths.specs` in `.zibby.config.mjs`.
-- **"Browser crashed"** — usually the playwright browser cache is stale. Re-run with `--headed` once to refresh, then `--headless`.
+- **"Browser crashed"** — usually the playwright browser cache is stale. Drop `--headless` once (default is headed) so you can see what's happening, then re-add `--headless` once it's healthy.
 - **MCP errors during `execute_live`** — the agent's MCP tool config may need refreshing. See `/zibby-test-debug`.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-test-write.md

@@ -1,4 +1,4 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-test-write — author a new Zibby test spec
 
 You are helping the user write a new test spec. Specs are plain-language `.txt` files in `test-specs/` (configurable via `.zibby.config.mjs` `paths.specs`). Zibby's runner converts them to Playwright at execution time.

package/dist/templates/zibby-workflow-claude/claude/commands/zibby-trigger.md

@@ -1,11 +1,11 @@
-<!-- zibby-template-version: 1 -->
+<!-- zibby-template-version: 4 -->
 # /zibby-trigger — run a deployed Zibby workflow
 
 You are helping the user trigger a deployed workflow execution.
 
 A trigger creates a new ECS Fargate task that loads the workflow's bundle, runs the graph, and writes status + logs as it goes.
 
-Canonical docs: **https://docs.zibby.app/workflows/triggering**
+Canonical docs: **https://docs.zibby.app/cloud/triggering**
 
 ## Steps
 
@@ -13,15 +13,19 @@ Canonical docs: **https://docs.zibby.app/workflows/triggering**
 
 2. **Construct the input.** Workflows take a JSON input that nodes can read via `ctx.input`. Ask the user what input the workflow expects (or read `workflow.json`'s `inputSchema` if present).
 
-3. **Run the trigger:**
+3. **Run the trigger.** Three ways to pass input — they merge with this **precedence (highest → lowest)**:
+   1. `-p key=value` (repeatable) — wins over everything; great for shell-friendly tweaks on top of a base payload
+   2. `--input '<json>'` — full JSON payload as a string
+   3. `--input-file path.json` — full JSON/YAML payload from a file (lowest precedence; `-p` and `--input` override individual keys)
+
    ```
    zibby workflow trigger <uuid> --input '{"key":"value"}'
-   ```
-   Or use `-p key=value` for individual params (more shell-friendly than embedded JSON):
-   ```
    zibby workflow trigger <uuid> -p ticket=ENG-1234 -p priority=high
+   zibby workflow trigger <uuid> --input-file payload.json -p priority=urgent   # mix
    ```
 
+   Same flag surface as `zibby workflow run` (local) — flip the verb and the same call shape goes from local to remote.
+
 4. **Tail the logs immediately:**
    ```
    zibby workflow logs <uuid> -t