@zibby/cli 0.1.87 → 0.1.95

package/dist/commands/workflows/trigger.js

@@ -1,22 +1,22 @@
-import h from"ora";import{select as I}from"@inquirer/prompts";import{readFileSync as $,existsSync as U}from"fs";import{homedir as b}from"os";import{join as j,resolve as _}from"path";var g={local:{name:"Local Development",apiUrl:"http://localhost:3001",accountApiUrl:"http://localhost:3001",frontendUrl:"http://localhost:3000",description:"Local backend running on port 3001"},prod:{name:"Production",apiUrl:process.env.ZIBBY_PROD_API_URL||"https://api-prod.zibby.app",accountApiUrl:process.env.ZIBBY_PROD_ACCOUNT_API_URL||"https://account-api-prod.zibby.app",frontendUrl:process.env.ZIBBY_PROD_FRONTEND_URL||"https://studio.zibby.app",description:"Production environment"}};function u(){let o;if(process.env.ZIBBY_API_URL)o=process.env.ZIBBY_API_URL;else{let e=process.env.ZIBBY_ENV||"prod";g[e]?o=g[e].apiUrl:o=g.prod.apiUrl}try{let e=new URL(o);return e.protocol!=="http:"&&e.protocol!=="https:"?(console.error(`\u26A0\uFE0F  Invalid API URL protocol: ${e.protocol} (only http/https allowed)`),g.prod.apiUrl):o}catch{return console.error(`\u26A0\uFE0F  Invalid API URL: ${o}`),g.prod.apiUrl}}var v=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function m(o){return o?v.test(o)?{ok:!0}:{ok:!1,error:`'${o}' is not a UUID. Cloud workflows are identified by UUID only. Run \`zibby workflow list\` to find yours, or run \`zibby workflow trigger\` with no argument for interactive selection.`}:{ok:!0}}function B(o){return o==="true"?!0:o==="false"?!1:o==="null"?null:o!==""&&!isNaN(Number(o))?Number(o):o}function E(o){let e={};for(let r of o||[]){let i=r.indexOf("=");if(i===-1){console.warn(`  Warning: ignored param "${r}" \u2014 expected key=value format`);continue}let t=r.slice(0,i).trim(),n=B(r.slice(i+1)),l=t.split("."),c=e;for(let s=0;s<l.length-1;s++)(typeof c[l[s]]!="object"||c[l[s]]===null)&&(c[l[s]]={}),c=c[l[s]];c[l[l.length-1]]=n}return e}function N(o){let e=_(o);U(e)||(console.log(`
+import h from"ora";import{select as v}from"@inquirer/prompts";import{readFileSync as x,existsSync as N}from"fs";import{homedir as R}from"os";import{join as T}from"path";var u={local:{name:"Local Development",apiUrl:"http://localhost:3001",accountApiUrl:"http://localhost:3001",frontendUrl:"http://localhost:3000",description:"Local backend running on port 3001"},prod:{name:"Production",apiUrl:process.env.ZIBBY_PROD_API_URL||"https://api-prod.zibby.app",accountApiUrl:process.env.ZIBBY_PROD_ACCOUNT_API_URL||"https://account-api-prod.zibby.app",frontendUrl:process.env.ZIBBY_PROD_FRONTEND_URL||"https://studio.zibby.app",description:"Production environment"}};function g(){let o;if(process.env.ZIBBY_API_URL)o=process.env.ZIBBY_API_URL;else{let e=process.env.ZIBBY_ENV||"prod";u[e]?o=u[e].apiUrl:o=u.prod.apiUrl}try{let e=new URL(o);return e.protocol!=="http:"&&e.protocol!=="https:"?(console.error(`\u26A0\uFE0F  Invalid API URL protocol: ${e.protocol} (only http/https allowed)`),u.prod.apiUrl):o}catch{return console.error(`\u26A0\uFE0F  Invalid API URL: ${o}`),u.prod.apiUrl}}var b=/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;function y(o){return o?b.test(o)?{ok:!0}:{ok:!1,error:`'${o}' is not a UUID. Cloud workflows are identified by UUID only. Run \`zibby workflow list\` to find yours, or run \`zibby workflow trigger\` with no argument for interactive selection.`}:{ok:!0}}import{existsSync as j,readFileSync as _}from"fs";import{resolve as B}from"path";function I(o){return o==="true"?!0:o==="false"?!1:o==="null"?null:o!==""&&!isNaN(Number(o))?Number(o):o}function $(o){let e={};for(let r of o||[]){let i=r.indexOf("=");if(i===-1){console.warn(`  Warning: ignored param "${r}" \u2014 expected key=value format`);continue}let t=r.slice(0,i).trim(),n=I(r.slice(i+1)),l=t.split("."),c=e;for(let s=0;s<l.length-1;s++)(typeof c[l[s]]!="object"||c[l[s]]===null)&&(c[l[s]]={}),c=c[l[s]];c[l[l.length-1]]=n}return e}function E(o){let e=B(o);j(e)||(console.log(`
   Error: --input-file not found: ${o}
-`),process.exit(1));try{return JSON.parse($(e,"utf-8"))}catch(r){console.log(`
+`),process.exit(1));try{return JSON.parse(_(e,"utf-8"))}catch(r){console.log(`
   Error: --input-file is not valid JSON: ${r.message}
-`),process.exit(1)}}function x(o){let e={};if(o.inputFile&&(e={...N(o.inputFile)}),o.input)try{e={...e,...JSON.parse(o.input)}}catch(r){console.log(`
+`),process.exit(1)}}function U(o){let e={};if(o.inputFile&&(e={...E(o.inputFile)}),o.input)try{e={...e,...JSON.parse(o.input)}}catch(r){console.log(`
   Error: --input is not valid JSON`),console.log(`  ${r.message}
-`),process.exit(1)}return o.param?.length&&(e={...e,...E(o.param)}),e}function R(){let o=j(b(),".zibby","config.json");if(U(o))try{let r=JSON.parse($(o,"utf-8"));if(r.sessionToken)return r.sessionToken}catch{}let e=process.env.ZIBBY_API_KEY;if(e)return e;console.log(`
+`),process.exit(1)}return o.param?.length&&(e={...e,...$(o.param)}),e}function A(){let o=T(R(),".zibby","config.json");if(N(o))try{let r=JSON.parse(x(o,"utf-8"));if(r.sessionToken)return r.sessionToken}catch{}let e=process.env.ZIBBY_API_KEY;if(e)return e;console.log(`
   Not authenticated`),console.log("  Run: zibby login"),console.log(`  OR set ZIBBY_API_KEY env var (for CI/CD)
-`),process.exit(1)}async function T(o){let e=u(),r=h("Fetching projects...").start();try{let i=await fetch(`${e}/projects`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${o}`}});i.ok||(r.fail("Failed to fetch projects"),process.exit(1));let t=await i.json();Array.isArray(t)||(t.projects?t=t.projects:t.data&&(t=t.data)),(!t||t.length===0)&&(r.fail("No projects found"),process.exit(1)),r.succeed(`Found ${t.length} project${t.length===1?"":"s"}`),console.log("");let n=t.map(l=>({name:`${l.name||"Unnamed"} (${l.projectId||l.id})`,value:l.projectId||l.id}));return await I({message:"Select a project:",choices:n})}catch(i){r.fail(`Error: ${i.message}`),process.exit(1)}}async function A(o,e){let r=u(),i=h("Fetching deployed workflows...").start();try{let t=["analysis","implementation","run_test"],n=[];for(let c of t){let s=await fetch(`${r}/projects/${o}/workflows/${c}`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${e}`}});if(s.ok){let a=await s.json();a.graph&&n.push({name:c,version:a.version||0,isDefault:a.isDefault!==!1})}}n.length===0&&(i.fail("No deployed workflows found for this project"),process.exit(1)),i.succeed(`Found ${n.length} deployed workflow${n.length===1?"":"s"}`),console.log("");let l=n.map(c=>({name:`${c.name} (v${c.version})${c.isDefault?" [default]":""}`,value:c.name}));return await I({message:"Select a workflow to trigger:",choices:l})}catch(t){i.fail(`Error: ${t.message}`),process.exit(1)}}async function J(o,e={}){let r=m(o);r.ok||(console.log(`
+`),process.exit(1)}async function D(o){let e=g(),r=h("Fetching projects...").start();try{let i=await fetch(`${e}/projects`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${o}`}});i.ok||(r.fail("Failed to fetch projects"),process.exit(1));let t=await i.json();Array.isArray(t)||(t.projects?t=t.projects:t.data&&(t=t.data)),(!t||t.length===0)&&(r.fail("No projects found"),process.exit(1)),r.succeed(`Found ${t.length} project${t.length===1?"":"s"}`),console.log("");let n=t.map(l=>({name:`${l.name||"Unnamed"} (${l.projectId||l.id})`,value:l.projectId||l.id}));return await v({message:"Select a project:",choices:n})}catch(i){r.fail(`Error: ${i.message}`),process.exit(1)}}async function P(o,e){let r=g(),i=h("Fetching deployed workflows...").start();try{let t=["analysis","implementation","run_test"],n=[];for(let c of t){let s=await fetch(`${r}/projects/${o}/workflows/${c}`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${e}`}});if(s.ok){let a=await s.json();a.graph&&n.push({name:c,version:a.version||0,isDefault:a.isDefault!==!1})}}n.length===0&&(i.fail("No deployed workflows found for this project"),process.exit(1)),i.succeed(`Found ${n.length} deployed workflow${n.length===1?"":"s"}`),console.log("");let l=n.map(c=>({name:`${c.name} (v${c.version})${c.isDefault?" [default]":""}`,value:c.name}));return await v({message:"Select a workflow to trigger:",choices:l})}catch(t){i.fail(`Error: ${t.message}`),process.exit(1)}}async function M(o,e={}){let r=y(o);r.ok||(console.log(`
   Error: ${r.error}
-`),process.exit(1));let i=R(),t=e.project||process.env.ZIBBY_PROJECT_ID,n;if(o){let s=u();try{let a=await fetch(`${s}/projects`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`}});if(a.ok){let d=(await a.json()).projects||[];for(let p of d){let y=await fetch(`${s}/projects/${p.projectId}/workflows`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`}});if(y.ok){let w=(await y.json()).find(k=>k.uuid===o);if(w){t=p.projectId,n=w.workflowType||w.name,console.log(`
+`),process.exit(1));let i=A(),t=e.project||process.env.ZIBBY_PROJECT_ID,n;if(o){let s=g();try{let a=await fetch(`${s}/projects`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`}});if(a.ok){let d=(await a.json()).projects||[];for(let p of d){let m=await fetch(`${s}/projects/${p.projectId}/workflows`,{method:"GET",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`}});if(m.ok){let w=(await m.json()).find(k=>k.uuid===o);if(w){t=p.projectId,n=w.workflowType||w.name,console.log(`
   \u2713 Found workflow "${n}" (UUID: ${o})
 `);break}}}(!n||n===o)&&(console.log(`
   Error: Workflow with UUID "${o}" not found`),console.log(`  Check: zibby workflow list
 `),process.exit(1))}}catch(a){console.log(`
   Error looking up workflow UUID: ${a.message}
-`),process.exit(1)}}t||(console.log(""),t=await T(i)),n||(console.log(""),n=await A(t,i));let l=x(e);if(console.log(`
+`),process.exit(1)}}t||(console.log(""),t=await D(i)),n||(console.log(""),n=await P(t,i));let l=U(e);if(console.log(`
   Triggering Workflow
-`),console.log("  ".padEnd(60,"-")),console.log(`  Workflow:  ${n}`),console.log(`  Project:   ${t}`),Object.keys(l).length>0){let s=JSON.stringify(l);console.log(`  Input:     ${s.length>60?`${s.substring(0,57)}...`:s}`)}e.idempotencyKey&&console.log(`  Idempotency: ${e.idempotencyKey}`),console.log("  ".padEnd(60,"-")),console.log("");let c=h("Triggering workflow execution...").start();try{let s=u(),a={input:l};e.idempotencyKey&&(a.idempotencyKey=e.idempotencyKey);let f=await fetch(`${s}/projects/${t}/workflows/${n}/trigger`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`},body:JSON.stringify(a)});if(!f.ok){let p=await f.json().catch(()=>({}));f.status===429&&(c.fail("Quota exceeded"),console.log(`
+`),console.log("  ".padEnd(60,"-")),console.log(`  Workflow:  ${n}`),console.log(`  Project:   ${t}`),Object.keys(l).length>0){let s=JSON.stringify(l);console.log(`  Input:     ${s.length>60?`${s.substring(0,57)}...`:s}`)}e.idempotencyKey&&console.log(`  Idempotency: ${e.idempotencyKey}`),console.log("  ".padEnd(60,"-")),console.log("");let c=h("Triggering workflow execution...").start();try{let s=g(),a={input:l};e.idempotencyKey&&(a.idempotencyKey=e.idempotencyKey);let f=await fetch(`${s}/projects/${t}/workflows/${n}/trigger`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${i}`},body:JSON.stringify(a)});if(!f.ok){let p=await f.json().catch(()=>({}));f.status===429&&(c.fail("Quota exceeded"),console.log(`
   Your workflow execution quota has been exceeded`),p.quotaInfo&&(console.log(`  Used: ${p.quotaInfo.used}/${p.quotaInfo.limit} executions`),console.log(`  Plan: ${p.quotaInfo.planId}`),p.quotaInfo.periodEnd&&console.log(`  Resets: ${new Date(p.quotaInfo.periodEnd).toLocaleDateString()}`)),console.log(""),process.exit(1)),c.fail("Trigger failed"),console.log(`  Error: ${p.message||f.statusText}
 `),process.exit(1)}let d=await f.json();c.succeed("Workflow triggered successfully"),console.log(""),console.log("  Job Details:"),console.log(`    Job ID:    ${d.jobId}`),console.log(`    Status:    ${d.status}`),console.log(`    Version:   ${d.version}`),console.log(`    Triggered: ${new Date(d.triggeredAt).toLocaleString()}`),console.log(""),console.log("  Monitor execution:"),o?(console.log(`    zibby workflow logs ${o}`),console.log(`    zibby workflow logs ${o} -t`)):(console.log(`    zibby workflow logs --workflow ${n} --project ${t}`),console.log(`    zibby workflow logs --workflow ${n} --project ${t} -t`)),console.log("")}catch(s){c.fail("Trigger failed"),console.log(`  Error: ${s.message}
-`),process.exit(1)}}export{B as coerceValue,E as parseParams,x as resolveInput,J as triggerWorkflowCommand};
+`),process.exit(1)}}export{I as coerceValue,$ as parseParams,U as resolveInput,M as triggerWorkflowCommand};

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/cli",
-  "version": "0.1.87",
+  "version": "0.1.95",
   "description": "Zibby CLI - Test automation generator and runner",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "build": "node ../scripts/build.mjs --extra-dirs bin",
-    "test": "vitest run test/auth*.test.js test/two-layer-auth.test.js test/trigger-params.test.js test/trigger-helpers.test.js test/deploy-helpers.test.js test/cli-namespace-consistency.test.js test/cli-workflow-subcommands.test.js test/run-bundle-core-import.test.js test/start-respects-config.test.js test/sse-backoff.test.js test/sse-reconnect-loop.test.js",
+    "test": "vitest run test/auth*.test.js test/two-layer-auth.test.js test/trigger-params.test.js test/trigger-helpers.test.js test/deploy-helpers.test.js test/deploy-bundles-user-config.test.js test/run-loads-user-config.test.js test/env-helpers.test.js test/env-cli.test.js test/cli-namespace-consistency.test.js test/cli-workflow-subcommands.test.js test/run-bundle-core-import.test.js test/start-respects-config.test.js test/sse-backoff.test.js test/sse-reconnect-loop.test.js test/run-helpers.test.js test/sse-parser.test.js",
     "test:unit": "vitest run src/",
     "test:auth": "vitest run test/auth*.test.js test/two-layer-auth.test.js",
     "lint": "eslint .",
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-sqs": "^3.1038.0",
-    "@zibby/agent-workflow": "^0.1.2",
-    "@zibby/core": "^0.1.47",
+    "@zibby/agent-workflow": "^0.2.0",
+    "@zibby/core": "^0.2.0",
     "@zibby/memory": "^0.1.5",
     "@zibby/skills": "^0.1.11",
     "adm-zip": "^0.5.17",

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

@@ -0,0 +1,113 @@
+<!-- BEGIN zibby-workflows zibby-template-version: 3 -->
+## Zibby
+
+This project uses **Zibby** — there are two surfaces:
+
+1. **Workflows** — graphs of AI-agent-driven steps that run inside an ECS Fargate sandbox in Zibby Cloud. Used for automation that needs an LLM in the loop (analyze tickets, draft replies, write code, etc.).
+
+2. **Tests** — plain-language `.txt` specs that Zibby's runner converts to Playwright executions. Produces video + JSON results. Used for end-to-end UI testing where specs survive UI churn better than raw selector-based tests.
+
+Both share `.zibby.config.mjs` at the project root.
+
+---
+
+### Workflows
+
+Files:
+```
+<paths.workflows or .zibby/workflows>/<name>/
+├── workflow.json    name, entryClass, triggers, schemas
+├── graph.mjs        nodes + edges from START to END
+├── nodes/
+│   ├── index.mjs    barrel export
+│   └── *.mjs        one node per file: { id, description, run(ctx) }
+└── package.json     deps; bundled at deploy time
+```
+
+Each node has `async run(ctx)` where `ctx` provides:
+- `ctx.input` — outputs from upstream nodes
+- `ctx.agent({ prompt, schema })` — call the configured LLM with structured output
+- `ctx.shell(cmd)` — run shell in the sandbox (egress proxy enabled)
+- `ctx.log(...)` — emit a log line (visible via `zibby workflow logs`)
+
+Common dev loop:
+```
+zibby workflow new <name>               # scaffold
+zibby workflow run <name>               # one-shot local run (mirrors trigger flags)
+zibby workflow run <name> -p k=v        # with input
+zibby workflow deploy <name>            # build + push to Zibby Cloud
+zibby workflow trigger <uuid>           # invoke the cloud workflow
+zibby workflow logs <uuid> -t           # tail live logs (docker-compose-style)
+zibby workflow list                     # find UUIDs and statuses
+zibby workflow delete <uuid>            # remove a deployed workflow
+```
+
+`run` and `trigger` accept the same input flags (`-p key=value`, `--input '<json>'`, `--input-file path.json`) — flip the verb to switch between local and cloud. `workflow start` exists too but is the long-lived dev server (Studio integration); for plain CLI iteration prefer `run`.
+
+Static outbound IPs (for customers behind firewalls): see `--dedicated-ip` flag on `deploy`.
+
+---
+
+### Tests
+
+Files:
+```
+test-specs/                 source `.txt` specs (paths.specs)
+tests/                      generated `.spec.js` (paths.generated; regenerated each run)
+test-results/               videos, traces, JSON results per run
+playwright.config.js
+```
+
+A spec is plain-language imperative English describing what to test. Zibby's runner reads the spec, drives the browser via MCP, generates Playwright, and produces a video.
+
+Common dev loop:
+```
+zibby test test-specs/<name>.txt        # run a spec
+zibby test "go to example.com and ..."  # inline, no file
+zibby generate -t ENG-1234              # generate specs from a Jira ticket
+zibby video                             # organize videos next to spec files
+zibby upload <spec-path>                # upload existing artifacts to cloud
+```
+
+When debugging a failed test, watch the video at `test-results/<spec>/video.webm` — that's almost always faster than reading logs.
+
+---
+
+### How to invoke the CLI
+
+The `zibby` command might be on PATH (if installed globally via npm) OR not — depending on the user's setup. **If `zibby` returns "command not found", fall back to `./.zibby/bin/zibby`** — a project-local shim auto-generated by the scaffolder that routes to whichever CLI binary the user has. Always exists in this project.
+
+```
+# Try first:
+zibby workflow list
+
+# If "command not found":
+./.zibby/bin/zibby workflow list
+```
+
+Don't waste time on `npx @zibby/cli` — not always published.
+
+---
+
+### Reference (always prefer canonical docs over these notes)
+
+**Workflows**
+- Concepts: https://docs.zibby.app/workflows
+- Node SDK (ctx.*): https://docs.zibby.app/workflows/sdk
+- Deploying & bundling: https://docs.zibby.app/workflows/deploying
+- Triggering & inputs: https://docs.zibby.app/workflows/triggers
+- Live log streaming: https://docs.zibby.app/workflows/logs
+- Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
+- Security & secrets: https://docs.zibby.app/workflows/security
+- Debugging: https://docs.zibby.app/workflows/debugging
+
+**Tests**
+- Spec format: https://docs.zibby.app/tests/specs
+- Running (`zibby test`): https://docs.zibby.app/tests/running
+- Generating from Jira: https://docs.zibby.app/tests/generating
+- Test memory: https://docs.zibby.app/tests/memory
+- Debugging: https://docs.zibby.app/tests/debugging
+- MCP browser config: https://docs.zibby.app/tests/playwright-mcp
+
+When in doubt about behavior, fetch the docs URL — these notes are a snapshot, the docs are kept current.
+<!-- END zibby-workflows -->

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

@@ -0,0 +1,72 @@
+<!-- zibby-template-version: 1 -->
+---
+name: zibby-test-author
+description: Sub-agent that helps the user design and author Zibby test specs end-to-end. Invoke when the user says "help me write a test for X", "I need to test this flow", or asks for guidance on what to put in a spec.
+---
+
+You are an expert at authoring Zibby test specs and running them. The user has invoked you because they want guidance on testing a feature or flow.
+
+## What you know
+
+A **Zibby test spec** is a plain-language `.txt` file that Zibby's runner converts to a Playwright execution at runtime. The runner's AI agent (configured per-project in `.zibby.config.mjs`) reads the spec, navigates the browser via MCP, generates a Playwright script, and produces a video + JSON results.
+
+It's the right tool when:
+- The user wants tests that survive UI churn (specs are higher-level than CSS selectors)
+- They have non-engineers writing test descriptions
+- They want test memory across runs (Dolt-backed, so the agent learns the app over time)
+
+It's NOT the right tool when:
+- The user wants 1000s of micro-tests in a tight CI loop (Zibby runs are LLM-mediated; slower than raw Playwright)
+- They have a fully-deterministic API testing need (use plain `pytest` or similar)
+
+## Spec layout
+
+```
+<workflowsBasePath if any>/...
+├── .zibby.config.mjs
+├── test-specs/                     ← spec source (paths.specs)
+│   ├── login-happy-path.txt
+│   ├── checkout-flow.txt
+│   └── ...
+├── tests/                          ← Generated Playwright (paths.generated)
+│   └── *.spec.js                   ← regenerated each run by default
+├── test-results/                   ← Videos, traces, JSON results per run
+└── playwright.config.js
+```
+
+A spec is unambiguous English with one action per line. See `/zibby-test-write` for the format.
+
+## Your job in this conversation
+
+1. **Listen for the goal.** What user-facing behavior is being tested? What's the success criterion? Be skeptical of vague specs.
+
+2. **Decompose into one user goal per spec.** Don't write a spec that does login + signup + checkout + admin in one file — that's four specs. Smaller specs = easier to debug, easier to localize regressions.
+
+3. **Write the spec(s)** to `test-specs/<kebab-name>.txt` — concrete, one action per line, stable selectors (visible text, ARIA labels, not CSS classes).
+
+4. **Run iteratively.** Author → run → watch the video → tighten ambiguous lines → re-run. Encourage:
+   ```
+   zibby test test-specs/<name>.txt           # run it
+   open test-results/<name>/video.webm        # watch what the agent did
+   ```
+   When the run fails, the video usually pinpoints the issue in 30 seconds.
+
+5. **Stop when the spec exercises the goal end-to-end.** Don't pile on "while we're at it" verifications — they bloat runtime and make failures harder to attribute.
+
+## Hard rules
+
+- **Never recommend `--headless` for first runs.** Watching the browser is the primary debugging tool when authoring; headless hides everything.
+- **Never recommend disabling video.** Videos are 99% of post-mortem signal; they're cheap.
+- **Don't write CSS selectors into specs.** Use what a human user would describe — visible text, role labels, the field's placeholder. Selectors belong in generated `.spec.js`, not the source.
+- **Don't suggest `npx playwright test` directly** to bypass Zibby for "speed". They lose the agent + memory; only suggest if the user explicitly wants raw Playwright.
+
+## Reference
+
+- Spec format and conventions: https://docs.zibby.app/tests/specs
+- Running specs (`zibby test`): https://docs.zibby.app/tests/running
+- Generating specs from a Jira ticket: https://docs.zibby.app/tests/generating
+- Test memory (Dolt-backed): https://docs.zibby.app/tests/memory
+- Debugging failures: https://docs.zibby.app/tests/debugging
+- MCP browser config: https://docs.zibby.app/tests/playwright-mcp
+
+When in doubt about behavior, fetch the docs URL — these are kept current; this prompt is a snapshot.

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

@@ -0,0 +1,81 @@
+<!-- zibby-template-version: 2 -->
+---
+name: zibby-workflow-builder
+description: Sub-agent that walks the user through building, testing, and deploying a Zibby agent workflow end-to-end. Use it when the user says "help me build a workflow that does X" or asks broad architectural questions about a workflow they're starting.
+---
+
+You are an expert at building Zibby agent workflows. The user has invoked you because they want guidance on designing or implementing a workflow.
+
+## What you know
+
+A **Zibby workflow** is a graph of AI-agent-driven steps that run inside an ECS Fargate sandbox. It's the right tool when the user wants to:
+- Automate something that requires an LLM in the loop (analyze, summarize, decide, draft, write code)
+- Combine LLM steps with deterministic shell or HTTP work
+- Run reliably in the cloud, with retries, audit logs, and IP-allowlistable egress
+
+It's NOT the right tool when the user wants:
+- Pure deterministic data transformation (use a Lambda)
+- Real-time interactive UI work (LLM calls are too slow for sub-second response)
+- One-off scripts (just run them locally)
+
+## Anatomy of a workflow
+
+```
+<workflowsBasePath>/<workflow-name>/
+├── workflow.json          # name, entryClass, triggers, optional input/output schemas
+├── graph.mjs              # exports the workflow graph (nodes + edges)
+├── nodes/
+│   ├── index.mjs          # registry of all nodes
+│   ├── example.mjs        # one node = one .mjs file
+│   └── <your-nodes>.mjs
+└── package.json           # deps; bundled at deploy time
+```
+
+Each **node** has a `run(ctx)` method. `ctx` provides:
+- `ctx.input` — outputs from upstream nodes (and the trigger's input)
+- `ctx.agent({ prompt, schema })` — call the configured LLM with structured output
+- `ctx.shell(command)` — run shell in the sandbox (egress proxy is on, see docs.zibby.app)
+- `ctx.log(...)` — emit a log line that shows up in `-t`
+
+The return value of `run()` is the node's output, available to downstream nodes via `ctx.input.<this-node-id>`.
+
+## Your job in this conversation
+
+1. **Listen for the goal.** Ask clarifying questions until you understand what the user wants the workflow to DO from input to output. Be skeptical of vague specs.
+
+2. **Decompose into nodes.** Each node should have ONE clear responsibility. If a step is "fetch data, analyze it, draft a reply, send the reply" — that's 3-4 nodes, not one. Smaller nodes = easier to retry, replace, debug.
+
+3. **Sketch the graph.** Tell the user the node list and the edges. Confirm before generating code.
+
+4. **Generate the scaffold** if they don't have one yet:
+   ```
+   zibby workflow generate <slug>
+   ```
+   Then add nodes one at a time using the `/zibby-add-node` command.
+
+5. **Run iteratively.** Encourage the loop:
+   ```
+   zibby workflow run <slug>            # one-shot local run (mirrors trigger flags)
+   # ... iterate ...
+   zibby workflow deploy <slug>         # when ready
+   zibby workflow trigger <uuid>        # cloud test
+   zibby workflow logs <uuid> -t        # watch
+   ```
+
+6. **Stop when the workflow does the goal end-to-end.** Don't pile on speculative nodes.
+
+## Hard rules
+
+- **Never recommend `--force` flags or skipping checks** to make a deploy go faster. Build problems are signal.
+- **Never write API keys / secrets into workflow source.** Use the project's secret store (configured in `.zibby.config.mjs` or via the cloud UI).
+- **Don't tell the user to manually edit `bundleS3Key` or other CFN-managed fields in DynamoDB.** These get overwritten on next deploy.
+- **If a node uses external APIs, mention the egress proxy** (`http://<egress-ip>:3128` is set in `HTTP_PROXY` env at runtime) and the customer-IP-allowlist story.
+
+## Reference
+
+- Concepts and node API: https://docs.zibby.app/workflows/concepts
+- Node SDK (ctx.agent, ctx.shell, ctx.log): https://docs.zibby.app/workflows/sdk
+- Triggers and inputs: https://docs.zibby.app/workflows/triggers
+- Egress and security: https://docs.zibby.app/workflows/egress
+
+When in doubt about API surface or recent changes, **fetch the docs URL** for current info — these docs are the canonical reference and are updated more often than your training data.

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

@@ -0,0 +1,75 @@
+<!-- zibby-template-version: 2 -->
+# /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/dist/templates/zibby-workflow-claude/claude/commands/zibby-debug.md

@@ -0,0 +1,67 @@
+<!-- zibby-template-version: 1 -->
+# /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/zibby-workflow-claude/claude/commands/zibby-delete.md

@@ -0,0 +1,37 @@
+<!-- zibby-template-version: 1 -->
+# /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/zibby-workflow-claude/claude/commands/zibby-deploy.md

@@ -0,0 +1,77 @@
+<!-- zibby-template-version: 1 -->
+# /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
+
+- `--project <id>` — skip the interactive project picker
+- `--api-key <key>` — use a PAT instead of the session token (for CI)
+- `--verbose` — print raw CodeBuild output during the build (helpful for debugging build failures)
+- `--dedicated-ip <action>` — opt this workflow into the dedicated egress addon (static outbound IP). See `/zibby-static-ip` for setup.
+
+## Static outbound IP (dedicated egress) at deploy time
+
+If the user's workflow needs to call APIs that require IP allowlisting (corporate GitHub, GitLab Enterprise, paranoid SaaS firewalls), the workflow needs the **dedicated egress IP** addon enabled on their account, AND the workflow must opt in.
+
+Three flags map to three things:
+
+| Flag | What it does |
+|------|-------------|
+| `--dedicated-ip status` | Show current addon state for the account (active / inactive / billing) |
+| `--dedicated-ip enable` | Enable the addon on the account (Pro subscription required, ~$50/mo). One-time per account. |
+| `--dedicated-ip use` | Mark THIS workflow as using the static egress IP (per-workflow opt-in, after `enable`) |
+| `--dedicated-ip unuse` | Stop routing this workflow through the static IP |
+| `--dedicated-ip disable` | Disable the addon for the whole account |
+
+Typical first-time flow when the user says "I need a static outbound IP":
+1. `zibby workflow deploy <name> --dedicated-ip status` — check whether they have it
+2. If inactive → `zibby workflow deploy <name> --dedicated-ip enable` — enables the account-wide addon (interactive billing prompt; prerequisite Pro subscription)
+3. `zibby workflow deploy <name> --dedicated-ip use` — opts this specific workflow in
+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.

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

@@ -0,0 +1,30 @@
+<!-- zibby-template-version: 1 -->
+# /zibby-list — list workflows (local + cloud) with their UUIDs and statuses
+
+You are helping the user see what workflows exist — locally scaffolded and remotely deployed.
+
+Canonical docs: **https://docs.zibby.app/workflows/listing**
+
+## 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.