@zibby/cli 0.5.8 → 0.6.0

package/dist/templates/.claude/commands/zibby-login.md

@@ -0,0 +1,68 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-login — authenticate the CLI to Zibby Cloud
+
+You are helping the user log in (or switch accounts) on the Zibby CLI.
+
+Canonical docs: **https://docs.zibby.app/cli/auth**
+
+## What login does
+
+`zibby login` opens a browser flow to https://zibby.dev that:
+
+1. Authenticates the user via their normal account login (email/password, Google, GitHub, …).
+2. Issues a CLI session token, scoped to the user's default workspace.
+3. Writes the token to `~/.zibby/session.json` (mode `0600`). This is what all subsequent `zibby workflow / app / project / memory` commands authenticate with.
+
+Workspaces are switched via `zibby workspace use <slug>` (separate command).
+
+## Steps
+
+1. **Check whether login is already valid:**
+   ```
+   Bash(zibby status)
+   ```
+   (See `/zibby-status` for the full surface.) If `Authenticated as <email>` and a recent timestamp, login is fresh — skip.
+
+2. **Decide: interactive browser flow or API key?**
+   - **Browser flow** — default. Run `zibby login`, opens a browser, user clicks "Authorize", token lands on disk. Best for human users on a workstation with a browser.
+   - **API key** (PAT) — non-interactive. Set `ZIBBY_API_KEY=zby_<key>` in the env (or `--api-key` flag per-command). Best for CI, headless servers, no-browser environments.
+
+3. **Run interactive login:**
+   ```
+   Bash(zibby login)
+   ```
+   The CLI prints a URL + 6-digit code. The user opens the URL, signs in, the CLI's local listener picks up the token and writes it to disk. Usually takes ~10 seconds end to end.
+
+4. **If browser-less**, walk the user through API key:
+   - Direct them to https://zibby.dev/settings/api-keys
+   - "Create a new API key with the scopes you need" — usually `workflows:rw projects:r apps:rw`
+   - They copy `zby_xxx`
+   - For interactive use: `export ZIBBY_API_KEY=zby_xxx` in their shell
+   - For one-off: pass `--api-key zby_xxx` per command
+
+5. **Verify:**
+   ```
+   Bash(zibby status)
+   ```
+   Should report email + workspace + token type (`session` or `api-key`).
+
+## Switching accounts
+
+```
+Bash(zibby logout)                  # clears ~/.zibby/session.json
+Bash(zibby login)                   # re-auth as the other account
+```
+
+There's no multi-account session; one login at a time. For workspace switching within an account, `zibby workspace use <slug>`.
+
+## Common pitfalls
+
+- **Headless server, no browser** → the browser flow assumes a local browser can reach the loopback listener. On a remote SSH session, the listener URL won't resolve. Use API key path instead.
+- **Token expired** → session tokens last 30 days. Re-run `zibby login`. CI should use API keys to avoid this.
+- **`ZIBBY_API_KEY` env shadows the session token.** If the user has both, the env wins. Surprise sometimes: `unset ZIBBY_API_KEY` to fall back to the session token.
+- **Wrong workspace** — if the user has multiple workspaces, login lands them on whichever is `default`. Switch with `zibby workspace use <slug>`.
+
+## Out of scope here
+
+- Multi-factor → handled at https://zibby.dev/security, not from CLI.
+- Org / role management → web UI only.

package/dist/templates/.claude/commands/zibby-mcp-install.md

@@ -0,0 +1,93 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-mcp-install — wire the Zibby Remote MCP server into the user's IDE agent
+
+You are helping the user configure their AI IDE (Claude Code, Cursor, Codex CLI) to talk to Zibby's hosted MCP server.
+
+Once installed, the IDE agent can directly trigger workflows, list apps, tail logs, etc. — without shelling out to `zibby`.
+
+Canonical docs: **https://docs.zibby.app/cli/mcp**
+
+## What gets installed
+
+A single MCP server entry pointing at `https://mcp.zibby.app` (or your workspace's tenant URL), authenticated via the user's CLI session token or a PAT.
+
+Tool surface (mirrors the CLI):
+- `zibby_workflow_*` — list / deploy / trigger / logs / status
+- `zibby_app_*` — list / deploy / status / logs / destroy / set-auth
+- `zibby_project_*` — list / use
+- `zibby_memory_*` — stats / pull / push
+
+The IDE agent picks these up automatically once the MCP entry is configured.
+
+## Per-IDE config
+
+| IDE | Config file | Format |
+|---|---|---|
+| Claude Code | `~/.claude/settings.json` (or project `.claude/settings.json`) | `mcpServers` map |
+| Cursor | `~/.cursor/mcp.json` (or project `.cursor/mcp.json`) | `mcpServers` map |
+| Codex CLI | `~/.codex/config.toml` | `[mcp_servers.zibby]` TOML table |
+| Aider | command-line flag | `--mcp-server https://mcp.zibby.app` |
+
+The CLI has a helper that writes the right shape for each:
+```
+Bash(zibby mcp install --ide claude)
+Bash(zibby mcp install --ide cursor)
+Bash(zibby mcp install --ide codex)
+```
+
+## Steps
+
+1. **Find out which IDE the user is in.** Ask, or infer from active files:
+   - `.claude/` in the project → Claude Code
+   - `.cursor/` in the project → Cursor
+   - `~/.codex/` exists → Codex CLI
+
+2. **Pick the scope.** Project (only this repo can use it) or user-wide (every project).
+   ```
+   Bash(zibby mcp install --ide cursor --scope project)
+   Bash(zibby mcp install --ide cursor --scope user)
+   ```
+
+3. **Pick the auth source.** Either the existing CLI session token (default, reuses `~/.zibby/session.json`), or a long-lived PAT for headless / CI use:
+   ```
+   Bash(zibby mcp install --ide claude)                              # session-token auth
+   Bash(zibby mcp install --ide claude --pat zby_xxx)                # PAT auth (recommended for shared configs)
+   ```
+
+4. **Run install:**
+   ```
+   Bash(zibby mcp install --ide <ide> --scope <project|user>)
+   ```
+   The CLI patches the config file in-place (idempotent — re-running updates the entry). It prints what it wrote.
+
+5. **Reload the IDE.** Claude Code: restart the CLI process. Cursor: `Cmd+Shift+P → "MCP: Reload"`. Codex: `codex reload` or restart.
+
+6. **Verify** by asking the IDE agent to "list my Zibby apps" — it should call `zibby_app_list` and return rows.
+
+## Manual config (if `zibby mcp install` is unavailable)
+
+For Claude Code, add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "zibby": {
+      "url": "https://mcp.zibby.app",
+      "headers": { "Authorization": "Bearer zby_xxx" }
+    }
+  }
+}
+```
+
+For Codex CLI, add to `~/.codex/config.toml`:
+```toml
+[mcp_servers.zibby]
+url = "https://mcp.zibby.app"
+headers = { Authorization = "Bearer zby_xxx" }
+```
+
+## Common pitfalls
+
+- **Session token expires after 30 days** → MCP calls 401 silently. Re-run `zibby login` OR install with `--pat` for non-rotating auth.
+- **Two entries with the same name** → IDEs vary in conflict resolution. Use distinct names (`zibby-prod`, `zibby-staging`) if you have multiple workspaces.
+- **Project + user scope both set** → project wins for that repo, user is fallback elsewhere. Usually fine; mention it if it surprises the user.
+- **Cursor doesn't pick up the config until a reload.** Cmd+Shift+P → MCP: Reload.

package/dist/templates/.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/.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/.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/.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/.claude/commands/new-workflow.md → dist/templates/.claude/commands/zibby-new-workflow.md}

@@ -3,7 +3,7 @@ description: Scaffold a new Zibby workflow from a natural-language description
 argument-hint: <description of what the workflow should do>
 ---
 
-# /new-workflow
+# /zibby-new-workflow
 
 You're about to create a new Zibby workflow. The user's request is:
 

package/dist/templates/.claude/commands/zibby-set-auth.md

@@ -0,0 +1,85 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-set-auth — set, rotate, or disable auth on a Zibby Managed App
+
+You are helping the user put auth in front of their app's public URL — or rotate / remove it.
+
+Canonical docs: **https://docs.zibby.app/apps/auth**
+
+## Why this matters
+
+Every Managed App gets a public `https://<id>.apps.zibby.app` URL. Without auth, ANYONE with the URL can hit the app. For tools like n8n / Grafana / Outline that's a real risk — the URL is guessable from the catalog.
+
+Zibby fronts the app with a **Caddy auth sidecar** that supports two modes:
+
+| Mode | What it does | When to use |
+|---|---|---|
+| `basic` | HTTP Basic auth (browser prompt) | Quick personal tools, dashboards you visit yourself |
+| `token` | `Authorization: Bearer <token>` header | API-only apps, scripted callers, webhook receivers |
+| `none` | No auth (raw app) | Apps with their own auth (n8n has built-in login) — `--off` to disable |
+
+## Three operations
+
+### 1. Set auth (first time)
+
+```
+Bash(zibby app set-auth <instanceId> --auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16))
+Bash(zibby app set-auth <instanceId> --auth-type token --auth-token $(openssl rand -hex 32))
+```
+
+The Caddy sidecar updates within ~5s. No app-container restart.
+
+### 2. Rotate (change password / token)
+
+Same command shape as set. Old credentials stop working immediately when the Caddy reload completes.
+
+```
+Bash(zibby app set-auth <instanceId> --auth-type basic --auth-user admin --auth-password $(openssl rand -hex 16))
+Bash(zibby app set-auth <instanceId> --auth-type token --auth-token $(openssl rand -hex 32))
+```
+
+### 3. Disable (remove auth — go raw)
+
+```
+Bash(zibby app set-auth <instanceId> --off)
+```
+
+`--off` short-circuits to `authType=none`. The Caddy sidecar is removed; the app's URL exposes the app directly. Only safe if the app has its own login (e.g. n8n, wordpress, grafana with `GF_AUTH_*` configured).
+
+## Steps
+
+1. **Identify the instanceId.** `Bash(zibby app list)` if user only has the friendly name.
+
+2. **Find the current state:**
+   ```
+   Bash(zibby app status <instanceId>)
+   ```
+   Look at `authType`. If it's already what they want, skip the change.
+
+3. **Decide which mode.** Ask the user:
+   - "Will you hit this from a browser (basic) or only from scripts / webhooks (token)?"
+   - If the answer is "it has its own login" → `--off`, and confirm they trust the app's built-in auth.
+
+4. **Generate credentials securely.** For passwords / tokens, use `openssl rand -hex 16` (basic) / `openssl rand -hex 32` (token). NEVER reuse a password the user typed in chat — credentials in chat history leak.
+
+5. **Run the command.** ALWAYS pass credentials via env / `$(…)` substitution rather than as literal strings in the command. The CLI also accepts `ZIBBY_APP_AUTH_PASSWORD` / `ZIBBY_APP_AUTH_TOKEN` env vars if the user prefers.
+
+6. **Show the user the credentials ONCE.** The CLI prints them on success. Tell the user to save them — they're not recoverable from the backend (only re-rotateable).
+
+7. **Verify auth is on:**
+   ```
+   Bash(curl -i https://<id>.apps.zibby.app/)            # should be 401 with basic, 401 with token
+   Bash(curl -i -u admin:<password> https://<id>.apps.zibby.app/)   # should be 200
+   Bash(curl -i -H "Authorization: Bearer <token>" https://<id>.apps.zibby.app/)  # 200
+   ```
+
+## When NOT to rotate
+
+- App is being used live — rotation invalidates old creds immediately, mid-session. Coordinate with the user.
+- You don't have a place to put the new creds — losing track of a freshly rotated token locks you out of your own app. Save first.
+
+## Common pitfalls
+
+- **`--auth-user` must be a single ASCII printable token, 1-64 chars.** Spaces, unicode, control chars all 400.
+- **Forgetting to confirm `--off`** on an app without its own auth → public URL exposed. The CLI will let you do it. The user might regret it.
+- **Bearer-token mode + app has its own login** → users see a confusing 401 from Caddy before the app login page shows. Pick one auth layer, not two.
+- **Reloading Caddy mid-request** can briefly 502 inflight responses. Set / rotate during a quiet window if the app is high-traffic.

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

@@ -0,0 +1,54 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-status — show current Zibby CLI context: auth, workspace, project
+
+You are helping the user understand the CLI's current state — who they're authenticated as, which workspace they're in, which project is selected, and what credentials are active.
+
+Canonical docs: **https://docs.zibby.app/cli-reference#status**
+
+## What status reports
+
+`zibby status` prints:
+
+- **Authenticated as** — email + workspace slug + token type (`session` / `api-key`)
+- **Token age** — when it was issued and when it expires (session only)
+- **Default project** — `paths.workspace.defaultProject` from `.zibby.config.mjs` (or unset)
+- **API URL** — usually `https://api-prod.zibby.app`; differs in dev / local
+- **Credentials** — which provider tokens (ANTHROPIC, OPENAI, CURSOR, GEMINI) are configured for local agent runs
+
+## Steps
+
+1. **Run status:**
+   ```
+   Bash(zibby status)
+   ```
+
+2. **Read the result for the user.** Group by section:
+   - **Auth** — say "Logged in as `<email>` (workspace `<slug>`)" or "Not authenticated".
+   - **Project** — say "Working in project `<id>`" or "No default project set."
+   - **Creds** — list the providers with tokens configured. Flag missing critical ones (e.g. "No `ANTHROPIC_API_KEY` — `claude` agent will fail unless you set one").
+
+3. **Suggest follow-ups based on state:**
+   - Not authenticated → `/zibby-login`
+   - Token near expiry → "Run `zibby login` to refresh before the token expires on `<date>`."
+   - No default project → "Pick one with `zibby project use <id>`" or `zibby list` to see options.
+   - Missing creds for an agent the user uses → walk them through setting it.
+
+## When to use
+
+- User asks "am I logged in?" → status.
+- User asks "what project am I in?" → status.
+- After every login / workspace switch, to confirm the change landed.
+- Before any cross-account operation that depends on workspace context.
+
+## Quiet / scriptable
+
+`--quiet` returns JSON for scripts:
+```
+Bash(zibby status --quiet | jq -r .workspace)
+```
+
+## Common pitfalls
+
+- **Session token + `ZIBBY_API_KEY` both set** → status prints both. The env var wins. Tell the user.
+- **Stale `.zibby/session.json`** → if the file is unreadable (permissions, partial write), status reports "Not authenticated" even when a recent login looked successful. Re-run `zibby login`.
+- **`api-prod.zibby.app` unreachable** — status hits the API to validate the token. Without network, it reports cached info only. Don't conflate "no network" with "logged out".

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