@zibby/cli 0.5.8 → 0.6.0

package/dist/templates/.claude/commands/zibby-app-destroy.md

@@ -0,0 +1,60 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-app-destroy — permanently remove a Zibby Managed App
+
+You are helping the user destroy a hosted app. **This is irreversible.** Always confirm with the user before running.
+
+Canonical docs: **https://docs.zibby.app/apps/lifecycle**
+
+## What destroy does
+
+`zibby app destroy <instanceId>`:
+
+1. Stops the ECS task (drains in-flight requests for ~30s, then SIGKILL).
+2. **Deletes the EFS volume** attached to the instance — this is where the app stored its database, config, uploads, anything stateful. **This data is gone.** No backup, no recovery.
+3. Releases the public URL (cookie-pinned routes invalidate immediately).
+4. Removes the instance row from DynamoDB. The instanceId is invalid after this.
+5. Tears down the per-instance Caddy auth sidecar (if any) and the task definition.
+
+Billing stops at the destroy timestamp.
+
+## Steps
+
+1. **Identify the instanceId.** If user gave a friendly name:
+   ```
+   Bash(zibby app list)
+   ```
+   Verify with the user that the row you're about to destroy is the right one. Show them `name`, `appType`, `url`, `createdAt`.
+
+2. **Spell out the data loss explicitly.** Examples:
+   - For an n8n instance: "destroying will delete your workflows, credentials, execution history, and SQLite DB."
+   - For wordpress: "destroying will delete the site files, uploads, and MySQL data."
+   - For grafana: "destroying will delete your dashboards, data sources config, and SQLite DB."
+   - For a goal-mode install: "destroying will delete whatever the agent installed AND the EFS volume holding its state."
+
+3. **Get explicit confirmation.** Don't proceed on a "yeah" — make them name the app:
+   > "Type the instance's friendly name to confirm destroy: `<name>`"
+
+4. **Run destroy:**
+   ```
+   Bash(zibby app destroy <instanceId> --yes)
+   ```
+   The `--yes` flag skips the CLI's own interactive confirm. Only pass it AFTER you've confirmed with the user yourself.
+
+5. **Verify.** After 30-60s:
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+   Should return 404 (instance gone). If it's stuck in `destroying`, that's a backend cleanup race — let it sit another 60s.
+
+## When NOT to destroy
+
+- **Just want to stop billing for the night** → there's no "pause" today (every running app is billed by the minute). Destroy is the only way to stop billing, and it's destructive. Tell the user.
+- **Want to upgrade** → use `/zibby-app-upgrade` instead. Upgrade preserves EFS data.
+- **Want to change auth** → use `/zibby-set-auth` instead.
+- **Want to retry a failed bootstrap** → for goal-mode failures, destroy + redeploy with a different goal is reasonable. For catalog failures, file a bug (catalog should self-heal).
+
+## Common pitfalls
+
+- **Race with in-flight requests.** Destroy SIGTERMs the task first; long-running webhooks can be cut off mid-response. Tell the user to drain their callers if they care.
+- **`destroyed` status briefly returns 200 with `status: destroying`** before flipping to 404. Don't panic.
+- **Multi-service instances destroy together** — there's no "destroy just the worker service". The whole instance goes.

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

@@ -0,0 +1,80 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-app-list — list your running Zibby Managed Apps + browse the catalog
+
+You are helping the user see what hosted apps they have deployed (and optionally, what they could deploy).
+
+Canonical docs: **https://docs.zibby.app/apps/listing**
+
+## Two surfaces
+
+| Surface | Command | Purpose |
+|---|---|---|
+| **Deployed instances** | `zibby app list` | What's running NOW under the user's projects |
+| **Catalog browse** | `zibby app templates` | What's available to deploy (read-only) |
+
+## List deployed instances
+
+```
+Bash(zibby app list)                          # all instances across all projects
+Bash(zibby app list --project <projectId>)    # filter to one project
+Bash(zibby app list --quiet)                  # JSON output for scripting
+```
+
+Output rows (default human format):
+- `instanceId` — the `app-<short-hex>` ID to use in every other `/zibby-app-*` command
+- `name` — friendly name (from `--name` at deploy time, or auto-generated)
+- `appType` — catalog id (`n8n`, `grafana`, …) OR `goal` for free-form deploys
+- `status` — `running | pending | failed | stopped | upgrading | destroying`
+- `url` — public `https://*.apps.zibby.app` URL
+- `project` — the project the instance lives under
+- `createdAt` — when deployed
+
+## Browse the catalog
+
+```
+Bash(zibby app templates)
+Bash(zibby app templates --quiet)              # JSON
+```
+
+Output rows:
+- `id` — what you pass to `zibby app deploy <id>`
+- `name` — human-friendly title
+- `description` — one-line summary
+- `category` — `automation | observability | dev-tools | wikis | …`
+- `architecture` — `arm64 | x86_64 | both`
+
+## Steps
+
+1. **What is the user asking?**
+   - "What do I have running?" → `zibby app list`
+   - "What can I deploy?" → `zibby app templates`
+   - "Show me my n8n" → list, then filter by `appType=n8n` mentally
+
+2. **Pick the right scope.**
+   - If they have multiple projects and only want one project's apps, `--project <id>`. Use `/zibby-status` to get current project context.
+   - If they want JSON for piping into jq, pass `--quiet`.
+
+3. **Run the command:**
+   ```
+   Bash(zibby app list)
+   ```
+
+4. **Summarize for the user.** Don't just dump every row. Group by status, highlight any `failed` or stuck-`pending` rows that need attention, then list the `running` ones.
+
+5. **Lead them to the next action.**
+   - Multiple instances + user wants to interact with one → ask which `instanceId`.
+   - User wants to clean up → suggest `/zibby-app-destroy` per row, or batch them.
+   - User wants to add another → suggest `/zibby-deploy-app`.
+
+## When the list is empty
+
+The user hasn't deployed any apps yet. Don't show an empty table — say so plainly:
+> "You don't have any Managed Apps deployed yet. Run `/zibby-deploy-app` to add one."
+
+Optionally show `zibby app templates` so they can see what's available.
+
+## Catalog gotchas
+
+- The catalog is **frozen at CLI build time** for offline use. For the live source-of-truth list, run with `--remote` (when implemented) or check https://zibby.dev/apps.
+- Some catalog entries have `architecture: arm64` only — they won't deploy to `--arch x86_64` and vice versa. The CLI 400s if mismatched; surface the error message.
+- Catalog entries marked `goal-mode-only` exist for templates that can't be cleanly catalog'd (n8n historically was here; now it's catalog-promoted). Read the `description` field.

package/dist/templates/.claude/commands/zibby-app-logs.md

@@ -0,0 +1,60 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-app-logs — tail or fetch logs from a Zibby Managed App
+
+You are helping the user see what an app is doing — container stdout/stderr, agent-ops supervisor turns, and (for multi-service entries) per-service streams.
+
+Canonical docs: **https://docs.zibby.app/apps/logs**
+
+## Two modes
+
+| Mode | Flag | What it does |
+|---|---|---|
+| **Snapshot** | (no `-t`) | Fetch last N lines and exit. Good for "what happened?". |
+| **Tail** | `-t` | Live-follow new lines until Ctrl-C. Good for boot-watching. |
+
+```
+Bash(zibby app logs <instanceId>)                 # snapshot, default 200 lines
+Bash(zibby app logs <instanceId> --lines 1000)    # bigger snapshot, max 5000
+Bash(zibby app logs <instanceId> -t)              # live tail
+```
+
+For `-t`, ALWAYS run it in the background. A live tail blocks indefinitely:
+```
+Bash({ command: "zibby app logs <instanceId> -t", run_in_background: true })
+```
+
+## Multi-service: --service
+
+Some catalog entries (e.g. `wordpress + mysql`, `gas-town` with worker + scheduler) run multiple containers in one task. By default the log stream is the **app's primary service** (whatever the catalog manifest declared as `mainService`). To tail another:
+
+```
+Bash(zibby app logs <instanceId> --service mysql)
+Bash(zibby app logs <instanceId> --service agent-ops)   # the supervisor itself
+```
+
+If you don't know what services exist, `Bash(zibby app status <instanceId>)` lists them under `services[]`.
+
+## What you see for each app type
+
+- **Catalog deploys** → stdout/stderr of the app's container. E.g. n8n prints `Editor is now accessible via: http://localhost:5678/`.
+- **Goal-mode deploys** → the `agent-ops` supervisor's turns. Each turn shows the prompt, the tool call(s), and the response. This is the install/repair trail.
+- **`--service agent-ops`** (on any app) → the supervised loop's heartbeat: scheduled checks, periodic goal verification, repair attempts.
+
+## Steps
+
+1. **Identify the instanceId** — `Bash(zibby app list)` if user only has the friendly name.
+2. **Decide snapshot vs tail.** If they're asking "what happened?" → snapshot. If "I just deployed, watch it come up" → tail.
+3. **Decide which service.** For single-service catalog apps, default. For multi-service or "show me the supervisor", pass `--service`.
+4. **Run the command.** For tail, background it; for snapshot, foreground is fine.
+5. **Surface the meaningful part to the user.** Don't dump 200 lines — find the error / the success marker / the agent-ops decision, paraphrase it.
+
+## Watch for
+
+- **`--service` value typos** → 400 with the list of valid service names. Read that list back to the user.
+- **No log stream yet** → if the task hasn't started, there's nothing to tail. Status will say `pending`. Wait 30s and retry.
+- **Goal-mode tail looks frozen** → agent turns can each take 30-90s. If you've been quiet for 2 min, the task is likely stuck mid-tool-call. Check `/zibby-app-status` for `lastSupervisorRun` timestamp.
+- **Lines flag clamping** — `--lines` is clamped to 1..5000. Don't bother passing 100000; you'll get 5000.
+
+## Stop tailing
+
+Kill the backgrounded Bash task. The CLI exits cleanly. The app keeps running.

package/dist/templates/.claude/commands/zibby-app-status.md

@@ -0,0 +1,53 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-app-status — show a Zibby Managed App's current state
+
+You are helping the user check the live status of one of their hosted apps.
+
+Canonical docs: **https://docs.zibby.app/apps/lifecycle**
+
+## What status returns
+
+`zibby app status <instanceId>` hits the AppsFleet REST API and prints:
+
+- **status** — `pending | running | failed | stopped | upgrading | destroying`
+- **url** — public `https://*.apps.zibby.app` URL (always assigned, may 502 until task is running)
+- **architecture** — `arm64` or `x86_64`
+- **provider / model** — for goal-mode deploys, which agent drove the bootstrap
+- **lastSupervisorRun** — timestamp of the most recent agent-ops health check (goal-mode + supervised installs)
+- **authType** — `basic | token | none` if a Caddy auth sidecar is enabled
+- **task health** — last 3 task transitions (start / restart / oom)
+
+## Steps
+
+1. **Get the instanceId.** If user gave a friendly name (not an id starting with `app-`), look it up:
+   ```
+   Bash(zibby app list)
+   ```
+   Find the matching `name` and grab the `instanceId`.
+
+2. **Run status:**
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+
+3. **Interpret the result for the user.** Don't just dump the JSON — read it:
+   - `running` + URL responds → "It's healthy. Open <url>."
+   - `pending` for <5 min → "Still booting, ~3 min cold start is normal."
+   - `pending` for >10 min → likely stuck. Suggest `/zibby-app-logs` to see why.
+   - `failed` → fetch the failure reason field, summarize. Suggest `/zibby-app-logs` for the supervisor's last turn.
+   - `stopped` → the app was destroyed or scaled to 0. Suggest `/zibby-app-restart` to bring it back.
+
+## When to escalate to logs
+
+If status alone doesn't explain the symptom (sticky pending, failed without reason), pivot to `/zibby-app-logs` — that surfaces the agent-ops supervisor trail + container stderr.
+
+## Multiple services on one instance
+
+Some catalog entries (e.g. `wordpress + mysql`) are multi-service. The top-level status reflects the **whole** instance. Per-service status lives in the response body under `services[]` — surface that if there is more than one. To tail one specific service, see `/zibby-app-logs` `--service` flag.
+
+## Quiet output for scripting
+
+`--quiet` flips the command to JSON-only output (no human formatting). Use this when you want to grep / parse:
+```
+Bash(zibby app status <instanceId> --quiet | jq -r .status)
+```

package/dist/templates/.claude/commands/zibby-app-upgrade.md

@@ -0,0 +1,67 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-app-upgrade — upgrade a Zibby Managed App's agent-ops base image
+
+You are helping the user roll an instance to a newer `agent-ops` base image. This bumps the supervisor, not the user-facing app inside.
+
+Canonical docs: **https://docs.zibby.app/apps/upgrading**
+
+## What upgrade does
+
+`zibby app upgrade <instanceId> [--version vX.Y.Z]`:
+
+1. Switches the ECS task definition to a new `ghcr.io/zibbyhq/agent-ops:<version>` image (or `:latest` if no version is passed).
+2. Rolling task replacement — same EFS, same URL, ~60s of overlap.
+3. **EFS data is preserved.** Disk state survives.
+4. **Caddy auth sidecar config is preserved.** Basic-auth / bearer-token settings carry over.
+
+This is **only an upgrade of the agent-ops supervisor**, not of the application running inside. For example, upgrading an `n8n` instance won't pull a newer `n8nio/n8n` image — that's an in-app concern (n8n's own upgrader, or destroy + redeploy).
+
+For goal-mode instances, an upgrade gives the supervisor newer tool definitions, bug fixes, model defaults, etc.
+
+## Steps
+
+1. **Identify the instanceId.** `Bash(zibby app list)` if needed.
+
+2. **Check current version:**
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+   Look at `agentOpsVersion` (or the equivalent — it's in the JSON). Compare to the latest tag at https://github.com/ZibbyHQ/agent-ops/releases.
+
+3. **Decide the target.**
+   - If user said "upgrade" without specifying → use `--version` of the latest stable tag (don't blindly use `:latest` floating tag; pin it).
+   - If user gave a specific version → pass `--version vX.Y.Z`.
+
+4. **Confirm with the user.** Show: current version, target version, what changes (link to the GitHub release notes if you have them).
+
+5. **Run upgrade:**
+   ```
+   Bash(zibby app upgrade <instanceId> --version vX.Y.Z --yes)
+   ```
+   `--yes` skips the CLI's interactive confirm. Only pass after explicit user confirmation.
+
+6. **Watch the roll:**
+   ```
+   Bash({ command: "zibby app logs <instanceId> -t", run_in_background: true })
+   ```
+   New task should come up within 60s. App should be responsive again on the same URL.
+
+7. **Verify post-upgrade:**
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+   `agentOpsVersion` should reflect the new tag.
+
+## When upgrade is the right tool
+
+- "Use the latest agent-ops" → yes.
+- "Pin to a specific version because vN+1 had a regression" → yes, pass `--version vN`.
+- "I want to upgrade n8n itself" → no, that's inside the app. Use n8n's own upgrade flow inside the app, or destroy + redeploy.
+- "Apply security patches to the host OS" → no, the host is managed by AWS Fargate; no user-side OS to patch.
+
+## Common pitfalls
+
+- **Floating `:latest` is allowed but discouraged.** Pin a version so a future agent-ops release can't surprise-break the install.
+- **Downgrades work but might break.** If the older version doesn't know about a feature the current task uses (e.g. multi-service config), the task will fail to start. ECS retries → eventually rolls back. Watch logs.
+- **Mid-upgrade restart loops.** If the new image fails to boot, ECS will retry until it succeeds OR you manually run `/zibby-app-upgrade` again to a known-good version. Don't leave it in a crash-loop overnight.
+- **EFS schema migration.** If a version bump changes the on-disk schema (rare, called out in release notes), the upgrade can't safely roll back. Read release notes for breaking changes before upgrading prod instances.

package/dist/templates/.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/dist/templates/.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/dist/templates/.claude/commands/zibby-deploy-app.md

@@ -0,0 +1,92 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-deploy-app — deploy a hosted app (n8n / grafana / custom goal-mode)
+
+You are helping the user deploy a **Zibby Managed App** — a long-running hosted SaaS instance (n8n, Grafana, Outline, whatever) that runs on Zibby's Fargate fleet with an `agent-ops` sidecar.
+
+There are two deploy paths. Pick **one** with the user before running anything.
+
+| Path | When to use | Command shape |
+|---|---|---|
+| **Catalog** | The user wants a known-good off-the-shelf app | `zibby app deploy <appType>` |
+| **Goal-mode** | The user describes a custom install in natural language | `zibby app deploy --goal "<text>"` |
+
+Canonical docs: **https://docs.zibby.app/apps/deploying**
+
+## Decision tree
+
+1. **Ask the user what they want to deploy.** Examples:
+   - "I want n8n" → catalog (`n8n` is in the catalog)
+   - "I want Outline wiki" → catalog if present, else goal-mode
+   - "Install Rails 7 + Postgres from this git repo" → goal-mode
+   - "Set up a SonarQube on this VPS" → goal-mode
+
+2. **If catalog**, list available templates first so the user picks an exact id:
+   ```
+   Bash(zibby app templates)
+   ```
+   Pick the row's `id` column (e.g. `n8n`, `grafana`, `gas-town`). Use that as the positional arg.
+
+3. **If goal-mode**, get one concise English sentence describing the desired end-state — e.g. `"a running n8n instance with the latest stable image, exposing port 5678"`. Goal-mode is the **LLM bootstrap path**: `agent-ops` reads the goal and runs an autonomous install loop inside the app's Fargate task.
+
+## Pre-flight (both paths)
+
+Always confirm with the user:
+
+- **Project** — the deploy lives under a project. If they have multiple, run `Bash(zibby list)` to show options. The CLI will prompt interactively if `--project` isn't passed.
+- **Friendly name** — `--name "<text>"` (optional). Defaults to `<appType>-<short-id>`. Useful when running multiple instances of the same template.
+- **Auth on the public URL** — every app gets a `https://*.apps.zibby.app` URL. Anyone with the URL can hit it unless you put auth in front. Ask: "Should this be public, or behind basic-auth / a bearer token?" See `/zibby-set-auth` for the deeper walkthrough. Pass `--auth-type basic|token|none` at deploy time to set it from the start.
+
+## Catalog deploy
+
+```
+Bash(zibby app deploy <appType> --project <id> [--name "..."] [--auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16)])
+```
+
+The catalog path is **deterministic** — no LLM runs to figure out the install; the backend uses a baked task definition. Cold start is ~2-3 minutes (image pull + first boot).
+
+## Goal-mode deploy
+
+```
+Bash(zibby app deploy --goal "<text>" --project <id> \
+    [--provider claude|codex] [--model <id>] [--anthropic-token sk-ant-...] \
+    [--max-turns 80] [--timeout-min 45] \
+    [--auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16)])
+```
+
+Key flags:
+
+- `--provider` — `claude` (default) or `codex`. Picks which agent drives the install.
+- `--model` — explicit model id (e.g. `claude-sonnet-4-6`). Defaults to a known-cheap model.
+- `--anthropic-token` — per-deploy Claude credential override. Format: `sk-ant-oat01-...` (OAuth) or `sk-ant-api03-...` (API key). **Sensitive — never echo back.** Defaults to the workspace-stored token configured in Settings.
+- `--max-turns` — caps the agent's tool-call budget. Range 1..200. Heavy installs (n8n, OpenHands, anything that npm-installs hundreds of packages) blow past the 25 default — bump to 60-100.
+- `--timeout-min` — caps the bootstrap task's wall-clock. Range 1..120. Heavy installs need 30-45 min.
+
+Cold start for goal-mode is **5-30 minutes** depending on what's being installed. Don't be surprised by long-running bootstrap.
+
+## After the deploy call
+
+The CLI prints `{ instanceId, url, projectId, status }`. Save the `instanceId` — every other `/zibby-app-*` command takes it.
+
+1. **Tail the supervised loop** while it boots so you (and the user) can see what's happening:
+   ```
+   Bash({ command: "zibby app logs <instanceId> -t", run_in_background: true })
+   ```
+   Goal-mode prints each agent turn. Catalog prints the app's stdout.
+2. **Check status periodically** until `status` reaches `running`:
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+3. **Tell the user the URL** (from the deploy output). If they set `--auth-type basic`, also print the credentials (and tell them to save them — auth is rotateable but the initial password isn't recoverable).
+
+## Common failure modes
+
+- **402 from billing** → workspace doesn't have an active Apps subscription. Direct to https://zibby.dev/billing.
+- **`--anthropic-token must start with sk-ant-oat01- or sk-ant-api03-`** → user pasted a Claude Code interactive session token; those are IP-bound and don't work in cloud. Tell them to run `claude setup-token` for a long-lived OAuth token, or use an Anthropic API key.
+- **Goal-mode times out at `--timeout-min`** → install was too heavy. Suggest re-running with `--timeout-min 60 --max-turns 120` and a more specific goal.
+- **Status sticks at `pending`** → ECS image pull is slow. Wait another 90s. If still pending, run `/zibby-app-status` and surface the failure reason from the response body.
+
+## Goal-mode safety
+
+Goal-mode runs `agent-ops` autonomously inside the app's task. It can `shell` to anything inside the task's filesystem + egress proxy. It CANNOT touch other apps, other accounts, or your local machine — it's sandboxed. But you ARE responsible for what gets installed; license terms of any software the agent picks apply to the user, not Zibby.
+
+Ask before goal-mode if the user's request is ambiguous about cost or licensing ("install a database on a real server" → "open-source or commercial? Postgres/MySQL/SQLite?").

package/dist/templates/.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/dist/templates/.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.