@zibby/cli 0.4.16 → 0.4.18

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

@@ -0,0 +1,75 @@
+<!-- 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.
+
+## Context: what is a Zibby workflow?
+
+A workflow is a graph of nodes that an AI agent (cursor / claude / codex / gemini) executes in a sandboxed ECS Fargate container.
+- Each node is one `.mjs` file under `<workflow>/nodes/`
+- The graph wires nodes together (`<workflow>/graph.mjs`)
+- `<workflow>/workflow.json` declares the workflow's name, entry class, triggers
+- Workflows live under `<workflowsBasePath>/<workflow-name>/` (default `.zibby/workflows/`, configured in the project root's `.zibby.config.mjs`)
+
+For canonical, evolving docs see **https://docs.zibby.app/workflows/nodes**
+
+## Steps for this command
+
+1. **Identify the target workflow.** Look under the path configured in `.zibby.config.mjs` `paths.workflows` (default `.zibby/workflows/`). If multiple workflows exist, ask the user which one. If they're already `cd`'d inside one, infer from `${cwd}`.
+
+2. **Get the node spec from the user.** Ask:
+   - Node name (kebab-case, e.g. `analyze-ticket`)
+   - One-sentence description of what it does
+   - Inputs (variables it reads from prior nodes)
+   - Outputs (variables it produces — these become available to downstream nodes)
+
+3. **Create the node file** at `<workflow>/nodes/<name>.mjs`. Pattern from the existing `example.mjs`:
+   ```js
+   export default {
+     id: '<name>',
+     description: '<one-sentence description>',
+     async run(ctx) {
+       // ctx.input — outputs from upstream nodes
+       // ctx.agent — call the configured AI agent
+       // ctx.shell — run shell commands in the sandbox
+       // return value becomes the node's output
+       return { /* ... */ };
+     },
+   };
+   ```
+
+4. **Register the node in `nodes/index.mjs`** — add the import + export.
+
+5. **Wire into `graph.mjs`** — add the node id to the graph's `nodes` array, then add an `edge` from its predecessor (or from `START` if it's first) and an edge to `END` (or its successor).
+
+6. **Update `workflow.json`** if the new node introduces an `outputSchema` the workflow's caller relies on. Most nodes don't need this.
+
+7. **Test locally:**
+   ```
+   zibby workflow run <workflow-name>
+   zibby workflow run <workflow-name> -p ticket=BUG-123     # with input
+   ```
+   One-shot — exits when the run finishes. Same input flag surface as `zibby workflow trigger` (cloud).
+
+8. **Deploy when ready:**
+   ```
+   zibby workflow deploy <workflow-name>
+   ```
+   Then `zibby workflow trigger <uuid>` and `zibby workflow logs <uuid> -t` to verify.
+
+## Common pitfalls
+
+- **Node name must match the file name and `id`** — mismatches cause silent skip.
+- **`ctx.agent` calls block on the LLM** — large prompts can take 30+ seconds. Stream output for visibility.
+- **Don't import npm packages inside `run()`** — declare deps in `<workflow>/package.json`. The deploy bundler installs them.
+- **Failed nodes terminate the workflow** unless wrapped in try/catch and explicit `outputSchema.status: 'warn'`.
+
+## When to consult the user vs proceed
+
+Always ask before:
+- Creating a node that calls external APIs (cost / data egress concern)
+- Modifying `workflow.json` (changes the contract for downstream callers)
+
+Proceed without asking when:
+- Just adding a self-contained node and wiring it
+- Tweaking the example/implementation in response to user spec

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

@@ -0,0 +1,67 @@
+<!-- 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.
+
+Canonical docs: **https://docs.zibby.app/workflows/debugging**
+
+## Diagnostic recipe
+
+Apply in order. Stop at the first thing that explains the symptom.
+
+### 1. Did the deploy succeed?
+
+```
+zibby workflow list
+```
+Find the workflow. If `bundleStatus` isn't `ready`, the deploy didn't finish. Re-run `zibby workflow deploy <name> --verbose` and read the CodeBuild output.
+
+### 2. Did the trigger reach ECS?
+
+```
+zibby workflow trigger <uuid>
+```
+Look at the response — it should include a `Job ID` immediately. If you get an HTTP error, it's an auth or quota problem (CodeBuild concurrency, ECS task limit, etc.). Surface to the user.
+
+### 3. Did the agent task START?
+
+```
+zibby workflow logs <uuid> -t
+```
+Within 30s of the trigger you should see `[setup] Fetching bundle...` then `zibby v<version>`. If silence past 30s:
+- Maybe ECS couldn't pull the image — check CloudWatch alarm `zibby-sse-fanout-no-task-prod`
+- Maybe the task started but its log stream is delayed — wait another 30s
+- Maybe the workflow row hasn't been written yet (rare — would only affect the very first second)
+
+### 4. Did the workflow execute the wrong path?
+
+If the tail shows nodes running but in unexpected order, your `graph.mjs` edges are wrong. Common causes:
+- Edge from `START` is missing — first node never runs
+- Cycle in the graph — runtime errors with "cycle detected"
+- Node id in `nodes/` array doesn't match the file's exported `id`
+
+### 5. Did a node fail?
+
+The tail will show `Error: Node '<name>' failed: <reason>`. Common reasons:
+- Agent (LLM) returned malformed output that didn't match the node's `outputSchema`
+- Node code threw an uncaught exception
+- Shell command in the sandbox returned non-zero
+
+For agent errors, look for `│ Prompt sent to LLM:` and `│ Response:` blocks in the tail. The model's reply is right there.
+
+### 6. Did the task die without finishing?
+
+Look for `[fanout] hard timeout` in the SSE fan-out logs (sse-fanout container) — means the task ran past the cap. Or the status in DDB stays `running` indefinitely (zombie row). Re-trigger.
+
+### 7. Are you seeing logs from a stale execution?
+
+`-t` on a workflow UUID auto-attaches to the **latest** existing execution at connect time, plus new ones triggered while it's open. If you're tailing an old failed run, drain it (Ctrl+C, re-run after triggering fresh).
+
+## Quick reference: what each piece does
+
+- **Trigger** → writes a row to `zibby-prod-executions` (DDB) + spawns an ECS task
+- **Task** → pulls bundle from S3, runs `node graph.mjs`, writes logs to CloudWatch, updates DDB status as it progresses
+- **SSE fan-out** → polls CloudWatch, fans events out to subscribers (`-t` clients)
+- **Status** → moves through `starting → running → completed/failed/error`
+
+If `status` in DDB is wrong (e.g. stuck `running` after the task is gone), it's an upstream zombie — separate from any workflow logic issue.

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

@@ -0,0 +1,37 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-delete — delete a deployed Zibby workflow
+
+You are helping the user remove a workflow from Zibby Cloud.
+
+**This is destructive.** It removes the workflow record, its bundle in S3, and its routing — but does NOT delete in-flight executions or their CloudWatch logs (those age out per their retention policy). New triggers against the deleted UUID will fail.
+
+Canonical docs: **https://docs.zibby.app/workflows/lifecycle**
+
+## Steps
+
+1. **Get the UUID.** If user gave a name, look it up:
+   ```
+   Bash(zibby workflow list)
+   ```
+   Find the matching `name` and grab its `uuid`.
+
+2. **Confirm with the user.** Always confirm before deleting — show them the workflow's name, project, last-triggered timestamp. Don't proceed silently.
+   ```
+   "Delete workflow 'pr-summarizer' (uuid abc-123, last run 2 days ago)? This cannot be undone."
+   ```
+
+3. **Run the delete:**
+   ```
+   Bash(zibby workflow delete <uuid>)
+   ```
+
+4. **Clean up local files** if the user wants. The local `.zibby/workflows/<name>/` folder isn't auto-deleted — ask before removing:
+   ```
+   rm -rf .zibby/workflows/<name>
+   ```
+
+## When NOT to delete
+
+- If the user might want to re-deploy later — keep the local folder, just stop triggering it.
+- If there are running executions — the deploy is gone but those will keep running until they exit. Tell the user to wait or `Ctrl+C`-equivalent (kill the ECS task) if urgent.
+- For a "hide from list" feeling without losing history — there's no soft-delete; it's all-or-nothing.

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

@@ -0,0 +1,87 @@
+<!-- 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.
+
+## What `zibby workflow deploy` does
+
+1. Bundles the workflow's source (graph.mjs + nodes/ + package.json) into a tarball
+2. Uploads it to S3 via a presigned URL
+3. Triggers AWS CodeBuild to install deps + bake the bundle
+4. Updates DynamoDB so future triggers run the new bundle
+
+A successful deploy is required before `zibby workflow trigger <uuid>` works against the cloud.
+
+Canonical docs: **https://docs.zibby.app/workflows/deploying**
+
+## Steps for this command
+
+1. **Identify the workflow.** If the user passes a name, use it. Otherwise list everything under `paths.workflows` (from `.zibby.config.mjs`) and ask.
+
+2. **Pre-flight checks.** Read the workflow folder and confirm:
+   - `graph.mjs` exists and exports a graph
+   - `nodes/` has at least one node
+   - `workflow.json` is valid (must have `name`, `entryClass`, `triggers`)
+   - `package.json` declares all imports used in nodes (run a quick grep to spot missing deps)
+
+3. **Run the deploy:**
+   ```
+   zibby workflow deploy <workflow-name>
+   ```
+   This is interactive if `--project` isn't passed. The user picks a project, the CLI handles auth via the saved session token.
+
+4. **Watch the build.** The CLI streams CodeBuild output. If it succeeds, it prints the workflow's UUID. If it fails, the build logs show why — usually a missing dep in `package.json` or a syntax error in a node.
+
+5. **Verify post-deploy:**
+   ```
+   zibby workflow trigger <uuid> --input '{}'
+   zibby workflow logs <uuid> -t
+   ```
+   Tail logs until the workflow reaches `completed` (or `failed` — diagnose from logs).
+
+## Common failure modes
+
+- **Build fails with module-not-found** → node imports a package not in `package.json`. Add it and redeploy.
+- **Build succeeds but trigger fails immediately** → `entryClass` in `workflow.json` doesn't match a class exported by `graph.mjs`.
+- **Workflow runs but a node fails** → tail the live logs and read the error. Most are in the agent's prompt/output handling.
+
+## 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)
+
+### Seeding per-workflow env on first deploy
+
+If the workflow needs its own `ANTHROPIC_API_KEY`, `DATABASE_URL`, etc., put them in a `.env` and pass `--env`:
+
+```
+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 |
+|------|-------------|
+| `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 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. See `/zibby-static-ip` for the deeper walkthrough.

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

@@ -0,0 +1,30 @@
+<!-- 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/cli-reference#workflow-list**
+
+## Steps
+
+1. **Run the list command:**
+   ```
+   Bash(zibby workflow list)
+   ```
+   This shows both local (in `.zibby/workflows/`) and remote (deployed to Zibby Cloud) workflows. Each row has: name, UUID, project, last triggered.
+
+2. **Filter on demand.** If the user wants only local or only remote:
+   ```
+   zibby workflow list --local-only
+   zibby workflow list --remote-only --project <id>
+   ```
+
+## When you'd use this
+
+- User asks "what workflows do I have?" → run it, show the result.
+- You need a UUID to pass into `/zibby-trigger`, `/zibby-tail`, `/zibby-delete` and the user only knows the name → run it, look up the UUID.
+- After a deploy to confirm the bundle landed.
+
+## Output expectations
+
+The output is human-readable text (not JSON). If you need to extract a specific UUID programmatically, parse the line for the workflow name. If the user has many workflows, ask which one they want — don't grep blind.

package/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/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/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/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/templates/zibby-workflow-claude/claude/commands/zibby-static-ip.md

@@ -0,0 +1,70 @@
+<!-- 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.
+
+Two pieces:
+1. **Account-level addon** — `~$50/mo`, requires Pro subscription. One-time toggle per account.
+2. **Per-workflow opt-in** — once the addon is on, each workflow opts in individually (some workflows might not need it, no point routing them).
+
+## Steps
+
+1. **Confirm the user understands the cost.** Before any `--dedicated-ip enable`, explicitly say:
+   ```
+   "This will enable a $50/mo dedicated-egress addon on your account. Confirm?"
+   ```
+   If they don't have a Pro subscription, the enable call returns 402 — direct them to https://zibby.dev/billing first.
+
+2. **Check current state:**
+   ```
+   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 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 deploy <name> --dedicated-ip use)
+   ```
+   From now on, every deploy of this workflow + every triggered execution routes outbound through the static IP.
+
+5. **Re-deploy the workflow** so the runtime picks up the change:
+   ```
+   Bash(zibby workflow deploy <name>)
+   ```
+
+6. **Verify in a node** by adding a quick log:
+   ```js
+   ctx.log(`HTTP_PROXY=${process.env.HTTP_PROXY}`);
+   ```
+   The proxy URL should be set on the node's process. The IP that external services see is the dedicated one.
+
+## Reverting
+
+- `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
+
+After `enable`, the assigned outbound IPs are visible in `--dedicated-ip status` output. Surface them clearly so the user can paste into their customer's firewall allowlist:
+```
+Outbound static IPs (allowlist these in the customer's firewall):
+  54.252.121.111
+```
+
+## Don't confuse with the inbound static IPs
+
+This is OUTBOUND (workflow → external API). There's also an INBOUND static-IP set for `https://logs-stream.zibby.app` (the SSE log endpoint customers tail with `zibby workflow logs -t`). That one is unrelated to this addon — see `https://docs.zibby.app/security/ip-allowlist`.

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

@@ -0,0 +1,53 @@
+<!-- zibby-template-version: 4 -->
+# /zibby-tail — stream live logs from a Zibby workflow
+
+You are helping the user tail logs from a workflow execution.
+
+`zibby workflow logs <jobId> -t` is the live-streaming variant (like `heroku logs --tail` or `docker compose logs -f`). Without `-t`, you get a one-shot fetch.
+
+Canonical docs: **https://docs.zibby.app/workflows/logs**
+
+## What `<jobId>` accepts
+
+- A **workflow UUID** (`2b1ea07f-...`) → tails ALL currently-active executions of that workflow, plus any new ones triggered while the tail is open. Lines are interleaved by arrival time, prefixed with `(taskId)` so concurrent runs are distinguishable.
+- An **execution ID** (`abc-...`) → tails just that single execution. Closes when the execution drains.
+
+## Example flow
+
+```
+$ zibby workflow trigger 2b1ea07f-3ede-4bfd-a51d-431f0bab008e
+Job ID: 569ef1ee-15c8-4ee7-af30-933c8bec7ea7
+
+$ zibby workflow logs 2b1ea07f-3ede-4bfd-a51d-431f0bab008e -t
+  Streaming logs for workflow 2b1ea07f-...
+  Press Ctrl+C to stop.
+
+  ┌─ Execution: 569ef1ee...7ea7 (task: 9e61c690)
+  └─ Streaming logs...
+
+2026-05-04 06:16:27.621  (9e61c690) zibby v0.1.91
+2026-05-04 06:16:27.997  (9e61c690)  Workflow:  hello-world
+2026-05-04 06:16:33.055  (9e61c690) │ Prompt sent to LLM:
+...
+2026-05-04 06:16:56.389  (9e61c690) ✓ Workflow completed
+```
+
+## Tail behavior worth knowing
+
+- **Auto-switch:** when the current execution drains and a new trigger lands, the tail seamlessly picks it up — no need to re-run the command.
+- **Multi-attach:** if you trigger two workflows in parallel, the tail attaches to both. Lines from each are interleaved by timestamp.
+- **Reconnect:** transient network blips reconnect silently. Long quiet windows (3+ min) are kept alive via 5s keepalives.
+
+## Steps for this command
+
+1. Identify the jobId. If user gives a workflow name (not UUID), look it up via `zibby workflow list` and use the UUID.
+2. **Run in the background** — `-t` is a long-running stream. If you call `Bash` without `run_in_background: true` it'll block the chat for minutes:
+   ```
+   Bash({ command: "zibby workflow logs <jobId> -t", run_in_background: true })
+   ```
+   Then use `BashOutput` (or whatever your background-output tool is) to read new lines as they arrive.
+3. If the user wants a **one-shot snapshot** (no follow), drop the `-t` flag and call Bash normally:
+   ```
+   Bash({ command: "zibby workflow logs <jobId>" })
+   ```
+4. To stop the live tail: kill the background bash task. The CLI exits cleanly with `Stopped streaming.`