@zibby/cli 0.4.16 → 0.4.18

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

@@ -0,0 +1,63 @@
+---
+description: Add a node to an existing Zibby workflow graph
+argument-hint: <workflow-name> <node-purpose>
+---
+
+# /add-node
+
+The user wants to extend an existing workflow with a new node.
+
+**Arguments:** $ARGUMENTS
+
+## Steps
+
+1. **Find the workflow** — should be at `.zibby/workflows/<name>/`. If
+   the user didn't specify a name and there's only one workflow, use
+   that. If there are multiple, ask which.
+
+2. **Read the existing `graph.mjs`** to understand:
+   - Current node sequence
+   - State shape (what each prior node returns)
+   - Where the new node should slot in (before / after / parallel)
+
+3. **Decide LLM vs custom-code:**
+   - Custom-code (`execute`): the work is deterministic — git ops,
+     file IO, HTTP, parsing structured data, math
+   - LLM (`prompt`): the work needs judgement — summarization,
+     classification, generation, planning
+
+4. **Create the node file** at `.zibby/workflows/<name>/nodes/<node>.mjs`:
+
+   ```js
+   import { z } from 'zod';
+
+   export const myNode = {
+     name: 'my_node',
+     outputSchema: z.object({ /* what this returns to state */ }),
+     prompt: (state) => `…use state.previousNodeName.field…`,
+     // OR for custom-code:
+     // execute: async (state) => ({ /* match outputSchema */ }),
+   };
+   ```
+
+5. **Wire it into `graph.mjs`:**
+   - `import { myNode } from './nodes/my-node.mjs';`
+   - `graph.addNode('my_node', myNode);`
+   - `graph.addEdge('prev_node', 'my_node');`
+   - `graph.addEdge('my_node', 'next_node');` (or 'END')
+
+6. **Validate + run** to confirm it integrates:
+   ```bash
+   zibby workflow validate <name>
+   zibby workflow run <name> -p ...
+   ```
+
+7. **Report**: what node you added, how state changed, the test result.
+
+## Watch for
+
+- The new node's `prompt` references `state.X.field` — make sure that
+  field exists in the previous node's `outputSchema`. If it doesn't,
+  fix the producer schema, not the consumer prompt.
+- Don't change other nodes' schemas without telling the user — that's
+  a breaking change to downstream consumers.

package/templates/.claude/commands/add-skill.md

@@ -0,0 +1,83 @@
+---
+description: Add a custom MCP skill to a Zibby workflow
+argument-hint: <workflow-name> <skill-purpose-or-mcp-server-name>
+---
+
+# /add-skill
+
+The user wants to add a custom skill (MCP tool bundle) to a workflow.
+
+**Arguments:** $ARGUMENTS
+
+## Steps
+
+1. **Identify the MCP server** the skill wraps:
+   - If the user named one (e.g. "slack", "linear", "filesystem"), find
+     the official MCP server. Standard ones live at
+     `@modelcontextprotocol/server-<name>`.
+   - If unsure, ask: "Which MCP server should this skill wrap, or
+     should it be a JS-only middleware?"
+
+2. **Find the workflow** at `.zibby/workflows/<name>/`. Create a
+   `skills/` subfolder if it doesn't exist.
+
+3. **Write `skills/<id>.mjs`:**
+
+   ```js
+   import { registerSkill } from '@zibby/agent-workflow';
+
+   registerSkill({
+     id: 'slack',                       // referenced by node `skills: ['slack']`
+     serverName: 'slack-mcp',
+     command: 'npx',
+     args: ['-y', '@modelcontextprotocol/server-slack'],
+     allowedTools: ['mcp__slack__*'],   // pattern of tools the agent gets access to
+     envKeys: ['SLACK_BOT_TOKEN'],
+     description: 'Read channels, post messages, search history',
+   });
+   ```
+
+4. **Import the skill file from `graph.mjs`** at the TOP, before
+   `new WorkflowGraph()`:
+
+   ```js
+   import './skills/slack.mjs';        // side-effect: registers the skill
+   import { WorkflowGraph } from '@zibby/agent-workflow';
+   // ...
+   ```
+
+5. **Opt nodes into the skill:**
+
+   ```js
+   graph.addNode('post_summary', {
+     ...postSummaryNode,
+     skills: ['slack'],                // ← agent gets slack tools here
+   });
+   ```
+
+6. **Document the env requirement.** Add to the workflow's README or
+   tell the user which env var they need to set:
+   - Locally: `export SLACK_BOT_TOKEN=xoxb-...` or put in `.env`
+   - Cloud: `zibby workflow env set <workflow> SLACK_BOT_TOKEN=...`
+
+7. **Validate + test:**
+   ```bash
+   zibby workflow validate <name>
+   zibby workflow run <name> -p ...
+   ```
+
+   The agent should now have access to `mcp__slack__*` tools in the
+   nodes that opted in.
+
+## When NOT to use a custom skill
+
+- If the work can be done with plain Node.js (HTTP call, file write,
+  git command) — use a custom-code node with `execute()` instead. MCP
+  skills are for tool surfaces the agent decides to use, not for
+  deterministic glue.
+
+## When to use `middleware` instead of MCP
+
+If you don't have an MCP server but want to attach a JS helper that
+nodes can use, see the "Custom skill via a non-MCP function" section
+of `.claude/CLAUDE.md`. This is rare — prefer MCP when one exists.

package/templates/.claude/commands/new-workflow.md

@@ -0,0 +1,61 @@
+---
+description: Scaffold a new Zibby workflow from a natural-language description
+argument-hint: <description of what the workflow should do>
+---
+
+# /new-workflow
+
+You're about to create a new Zibby workflow. The user's request is:
+
+**$ARGUMENTS**
+
+## Steps
+
+1. **Sketch the graph.** Based on the user's request, decide:
+   - How many nodes? (Typically 2-5. More than 7 is usually a sign of
+     overdesign — collapse adjacent nodes.)
+   - Which nodes need an LLM (judgement, generation) vs custom-code
+     (deterministic: git ops, HTTP, file IO)?
+   - What's the linear sequence vs conditional branching?
+   - What's the final output the user cares about?
+
+2. **Pick a workflow name** — kebab-case, ≤24 chars, descriptive.
+   Examples: `code-review`, `pr-summary`, `nightly-changelog`.
+
+3. **Run the scaffold:**
+   ```bash
+   zibby workflow new <name>
+   ```
+   This creates `.zibby/workflows/<name>/` with starter files.
+
+4. **Edit the files** in this order (read CLAUDE.md §1 if you've forgotten the shapes):
+   - `workflow.json` — set `name`, `description`, `defaultAgent`
+   - `nodes/*.mjs` — one file per node, each with `name`, `outputSchema`
+     (Zod), and either `prompt` (LLM) or `execute` (custom-code)
+   - `graph.mjs` — wire them up with `addNode` + `addEdge` + `setEntryPoint`
+
+5. **Validate** (this catches 80% of mistakes before running anything):
+   ```bash
+   zibby workflow validate <name>
+   ```
+   Fix any reported issues.
+
+6. **Test locally** with a realistic input:
+   ```bash
+   zibby workflow run <name> -p <key>=<value>
+   ```
+   Watch the timeline. If a node fails, the `raw` field shows what the
+   agent actually returned vs what the schema expected.
+
+7. **Report back to the user** with:
+   - The workflow path
+   - The local test result
+   - The exact `zibby workflow run` command they can use
+   - Ask if they want to deploy
+
+## DO NOT
+
+- Don't deploy without asking (`zibby workflow deploy` has cost)
+- Don't use `state.set()` / `state.get()` inside `execute()` — just `return`
+- Don't skip `zibby workflow validate` — it catches schema typos fast
+- Don't add nodes the request didn't ask for

package/templates/.claude/commands/validate-workflow.md

@@ -0,0 +1,67 @@
+---
+description: Statically validate a Zibby workflow + run it locally with sample input
+argument-hint: <workflow-name> [optional input as key=value pairs]
+---
+
+# /validate-workflow
+
+The user wants to verify a workflow works before deploying.
+
+**Arguments:** $ARGUMENTS
+
+## Steps
+
+1. **Static validation first** (fast — does NOT call any LLM):
+
+   ```bash
+   zibby workflow validate <name>
+   ```
+
+   Checks:
+   - Graph topology (entry point set, edges reach END, no orphan nodes)
+   - Every node has `outputSchema`
+   - Every `skills: ['x']` reference is registered
+   - Zod schemas parse cleanly
+
+   If this fails, **fix the reported issues before running anything
+   else**. Validation errors mean the workflow can't possibly work.
+
+2. **Local dry-run** with realistic input:
+
+   ```bash
+   zibby workflow run <name> -p key1=value1 -p key2=value2
+   ```
+
+   Watch the timeline (`┌ nodeName … └ done`). Each node should:
+   - Show timing under ~30s for LLM nodes, <1s for custom-code
+   - Print its output
+   - Hand off to the next node
+
+3. **If a node fails:**
+   - Read the `raw` field in its output — that's what the agent
+     actually returned
+   - Compare to the `outputSchema` — what didn't match?
+   - Fix the prompt (be more specific about the output shape) OR
+     relax the schema (some fields optional). Prefer fixing prompts.
+
+4. **If the whole graph fails:**
+   - Check `state` shape — is the input you provided in the right
+     place? Top-level keys, not nested under `input`.
+   - Check the entry point — `graph.setEntryPoint('first_node')`.
+
+5. **Report back:**
+   - Validation result (pass / fail + what)
+   - Local run result (pass / fail + which node)
+   - If failed: a one-line diagnosis + a proposed fix
+   - If passed: the exact command the user can use to deploy
+
+## DO
+
+- Run validate before run before deploy. Cost increases 10× at each step.
+- Use realistic inputs (`-p`) — defaults are usually placeholders.
+
+## DON'T
+
+- Don't deploy a workflow that hasn't passed local run.
+- Don't suppress / ignore Zod errors — they're telling you the agent
+  produced something the next node won't accept.

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

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

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

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