@zibby/skills 0.1.10 → 0.1.12

package/docs/get-started/your-first-workflow.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+title: 2. Your first workflow
+pagination_prev: get-started/install
+pagination_next: get-started/run-locally
+---
+
+# Scaffold a workflow
+
+```bash
+zibby workflow new my-pipeline
+```
+
+This creates:
+
+```
+.zibby/workflows/my-pipeline/
+├── graph.mjs         # the workflow definition (entry point)
+├── nodes/
+│   └── example.mjs   # a sample node
+├── package.json      # workflow's own deps (each workflow is a self-contained npm project)
+└── workflow.json     # manifest (workflow name, entry class)
+```
+
+If `.zibby/workflows/` doesn't exist yet, the scaffold creates it. If you have a `.zibby.config.mjs` with a custom `paths.workflows`, the scaffold respects it.
+
+The first time you run this in a fresh directory, you'll be asked where to keep workflows (default: `.zibby/workflows`). The CLI also runs `npm install` inside the new workflow folder so deps are ready.
+
+## What's in graph.mjs
+
+```js
+import { z } from '@zibby/core';
+import { WorkflowAgent, WorkflowGraph } from '@zibby/agent-workflow';
+import { exampleNode } from './nodes/example.mjs';
+
+export class MyPipelineWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+
+    graph.addNode('example', {
+      prompt: exampleNode.prompt,
+      outputSchema: z.object({
+        summary: z.string(),
+        status: z.enum(['ok', 'warn', 'error']),
+      }),
+      agent: 'cursor',          // per-node agent override
+    });
+
+    graph.setEntryPoint('example');
+    return graph;
+  }
+}
+```
+
+The shape is:
+
+- `graph.addNode(name, config)` — register a node. `prompt` becomes the agent's input; `outputSchema` (Zod) defines the contract for what comes back.
+- `graph.addEdge(from, to)` — wire two nodes together.
+- `graph.addConditionalEdges(from, fn)` — branch on state.
+- `graph.setEntryPoint(name)` — first node to run.
+
+## Picking the agent
+
+Each node can specify its own agent via `agent: 'cursor' | 'claude' | 'codex' | 'gemini' | 'assistant'`. If you omit it, the workflow falls back to the project default (set in `.zibby.config.mjs` or `AGENT_TYPE` env var).
+
+→ Next: [Run it locally](./run-locally)

package/docs/intro.md

@@ -2,86 +2,58 @@
 slug: /
 sidebar_position: 1
 title: Introduction
+pagination_next: get-started/install
 ---
 
 # Zibby
 
-Zibby is an AI-powered test automation platform. Write plain-text test instructions, and Zibby drives a real browser, records video, and generates Playwright scripts — no manual test code required.
+**The cloud pipeline for Claude Code, Cursor, Codex, and Gemini.** Compose them into structured workflows with Zod-validated handoff between nodes. Vendor-neutral. JavaScript-first.
 
-## Quick Start
-
-```bash
-npm install -g @zibby/cli
-echo "Go to example.com and verify the page title" > test.txt
-zibby test test.txt --agent cursor
 ```
-
-That's it. No `zibby init` required — the CLI uses a built-in workflow by default.
-
-## How It Works
-
+            ┌──────────┐    ┌──────────┐    ┌──────────┐
+trigger →   │  plan    │ →  │ implement│ →  │  verify  │ → result
+            │ (claude) │    │ (cursor) │    │ (codex)  │
+            └──────────┘    └──────────┘    └──────────┘
+                 │               │               │
+              Zod out         Zod out         Zod out
 ```
-Plain Text Spec → AI Agent → Browser Automation → Video + Playwright Script
-```
-
-1. **Write a test spec** — plain text describing what to test
-2. **Run it** — `zibby test spec.txt` launches an AI agent (Cursor, Claude, or Codex)
-3. **AI drives the browser** — navigates, clicks, fills forms, asserts results
-4. **Get artifacts** — video recording, action timeline, generated Playwright script
-5. **Upload to cloud** (optional) — review results in the [Zibby dashboard](https://zibby.app)
-
-## Architecture
-
-Zibby is a monorepo with five published npm packages, each with a distinct responsibility:
-
-| Package | Version | Description |
-|---|---|---|
-| [`@zibby/cli`](https://www.npmjs.com/package/@zibby/cli) | 0.1.27 | CLI entry point — the `zibby` command. Orchestrates runs, init, login, uploads, and workflow management. |
-| [`@zibby/core`](https://www.npmjs.com/package/@zibby/core) | 0.1.22 | Core engine — workflow graph runtime, agent strategy framework, graph compiler, state management, and template workflows. |
-| [`@zibby/skills`](https://www.npmjs.com/package/@zibby/skills) | 0.1.4 | Skill catalog — built-in skill definitions (Browser, Jira, GitHub, Slack, Memory) plus the `skill()` factory for custom MCP and function skills. |
-| [`@zibby/memory`](https://www.npmjs.com/package/@zibby/memory) | 0.1.4 | Test memory database — version-controlled (Dolt-backed) knowledge base that learns from every run. Stores selectors, page models, navigation patterns, and insights. |
-| [`@zibby/mcp-browser`](https://www.npmjs.com/package/@zibby/mcp-browser) | 0.1.6 | Browser MCP server — wrapper around `@playwright/mcp` with stable ID injection, event recording, and session-aware video capture. |
 
-Users only install `@zibby/cli` — it pulls in the others automatically.
-
-## Two Modes
-
-### Local Mode (no account needed)
-
-Run tests locally, get generated Playwright scripts:
-
-```bash
-zibby test test-specs/login.txt --agent cursor
+```js
+graph
+  .addNode('plan',      { prompt, outputSchema: Plan,   agent: 'claude' })
+  .addNode('implement', { prompt, outputSchema: Diff,   agent: 'cursor' })
+  .addNode('verify',    { prompt, outputSchema: Result, agent: 'codex'  });
 ```
 
-### Cloud Mode (with Zibby account)
-
-Upload results to the dashboard for video replay, team sharing, and CI integration:
+## Try it now
 
 ```bash
-zibby test test-specs/login.txt --agent cursor --sync
-```
+npm install -g @zibby/cli
+zibby workflow new my-pipeline      # scaffold
+zibby workflow run my-pipeline      # run locally (one-shot)
 
-## Supported AI Agents
+zibby login
+zibby workflow deploy my-pipeline   # ship to cloud
+zibby workflow trigger <uuid> -t    # fire + tail logs
+```
 
-Zibby's workflow engine is **agent-agnostic** — the same workflow graph runs identically across all three supported agents:
+→ Next: [Install](./get-started/install)
 
-| Agent | Provider | How It Works | Setup |
-|---|---|---|---|
-| **Cursor** | Cursor IDE | Uses Cursor's built-in agent with MCP tool access | Install [Cursor](https://cursor.com) or set `CURSOR_API_KEY` |
-| **Claude** | Anthropic | Uses Claude Agent SDK with native MCP integration | Set `ANTHROPIC_API_KEY` in `.env` |
-| **Codex** | OpenAI | Uses Codex SDK with full tool/file/bash access | Install `@openai/codex` CLI + set `OPENAI_API_KEY` |
+## What you get
 
-```bash
-# Pick your agent
-zibby test test.txt --agent cursor
-zibby test test.txt --agent claude
-zibby test test.txt --agent codex
-```
+- **Multi-vendor** — mix Claude Code + Codex + Cursor + Gemini in one pipeline. Anthropic will never help you orchestrate Codex; multi-vendor neutrality is structural.
+- **Schema-enforced handoff** — Zod validates every node's output before the next runs. No prompt-stuffing.
+- **Run anywhere** — local with hot reload, or cloud with Heroku-style bundles (~3s cold start).
+- **Session replay** — every run lands as on-disk JSONL + artifacts. Re-run any node via `--session <id> --node <name>`.
+- **Cloud-native** — SSE log streaming, dedicated egress IPs for firewalled GitLab / GitHub Enterprise / Salesforce.
 
-## Who Is Zibby For?
+## How it compares
 
-- **QA Engineers** who want AI-generated test cases from plain-text specs
-- **Developers** who want Playwright scripts without writing them manually
-- **Teams** adopting test automation without the upfront investment
-- **CI/CD pipelines** that need automated browser testing
+| | Zibby | Claude Code Agent Teams | Devin | Mastra / LangGraph / CrewAI |
+|---|---|---|---|---|
+| Wraps real coding-agent CLIs | ✅ Claude + Codex + Cursor + Gemini | ❌ Claude only | ❌ proprietary agent | ❌ wraps LLM APIs |
+| Multi-vendor | ✅ | ❌ | ❌ | N/A |
+| Cloud-hosted | ✅ | ❌ local IDE | ✅ | varies |
+| Schema-enforced handoff | ✅ Zod | ❌ free-form | proprietary | ✅ |
+| Session replay | ✅ on-disk JSONL | ❌ | partial | partial |
+| Static egress IP | ✅ addon | ❌ | ❌ | ❌ |

package/docs/legacy/test-automation.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 1
+title: Test automation (legacy)
+---
+
+# Test automation (legacy)
+
+> **The `zibby test` flow predates the workflow engine.** It still works, but new users should start with [Get Started](/get-started/install) — the workflow engine is the headline product. This page is kept for users with existing test-automation pipelines.
+
+Drive a real browser from a plain-text spec, get a Playwright script back.
+
+## Prerequisites
+
+- Node.js 18 or later
+- [Cursor](https://cursor.com) IDE installed (for `--agent cursor`), **or** an Anthropic API key (for `--agent claude`), **or** OpenAI API key + Codex CLI (for `--agent codex`)
+
+## Option A: Zero Setup (npx)
+
+No install needed — run directly:
+
+```bash
+echo "Go to example.com and verify the page title says Example Domain" > test.txt
+npx @zibby/cli run test.txt --agent cursor
+```
+
+## Option B: Global Install
+
+```bash
+npm install -g @zibby/cli
+```
+
+### 1. Create a test spec
+
+Create a plain-text file with your test instructions:
+
+```text title="test-specs/login.txt"
+1. Navigate to https://myapp.com/login
+2. Enter email: test@example.com
+3. Enter password: TestPass123
+4. Click the Sign In button
+5. Verify the dashboard page loads
+6. Verify the user's name appears in the header
+```
+
+### 2. Run it
+
+```bash
+zibby test test-specs/login.txt --agent cursor
+```
+
+You'll see:
+- A browser window open
+- The AI agent navigate and interact with your app
+- A generated Playwright script saved to `tests/`
+
+### 3. Run the generated test
+
+```bash
+npx playwright test tests/login.spec.js
+```
+
+## Customizing Your Setup (Optional)
+
+If you want to customize the workflow, config, or nodes:
+
+```bash
+zibby init --agent cursor
+```
+
+This scaffolds:
+
+```
+.zibby.config.js          # Project configuration (ESM)
+.zibby/
+├── graph.js               # Workflow definition (customizable)
+├── nodes/                 # Node implementations
+│   ├── execute-live.js
+│   ├── generate-script.js
+│   └── preflight.js
+└── result-handler.js      # Post-execution hooks
+```
+
+Without `zibby init`, the CLI uses the built-in default workflow automatically.
+
+## Environment Variables
+
+| Variable | When needed |
+|---|---|
+| `CURSOR_API_KEY` | CI/CD with `--agent cursor` (locally uses Cursor IDE credentials) |
+| `ANTHROPIC_API_KEY` | Using `--agent claude` |
+| `OPENAI_API_KEY` | Using `--agent codex` |
+| `ZIBBY_API_KEY` | Cloud sync (`--sync` flag) |
+
+For local development, add these to a `.env` file in your project root.
+
+## Cloud Sync (Optional)
+
+To upload results to the [Zibby dashboard](https://zibby.app):
+
+1. Create an account at [zibby.app](https://zibby.app)
+2. Get your API key from **Project Settings**
+3. Add to `.env`: `ZIBBY_API_KEY=zby_your_key_here`
+4. Login: `zibby login`
+5. Run with sync: `zibby test test-specs/login.txt --sync`
+
+## Next Steps
+
+- [Installation](/installation) — detailed setup and configuration
+- [Running Tests](/running-tests) — all run modes and options
+- [CLI Reference](/cli-reference) — every command and flag

package/docs/packages/agent-workflow.md

@@ -0,0 +1,88 @@
+---
+sidebar_position: 1
+title: '@zibby/agent-workflow'
+---
+
+# @zibby/agent-workflow
+
+[![npm](https://img.shields.io/npm/v/@zibby/agent-workflow.svg)](https://www.npmjs.com/package/@zibby/agent-workflow)
+[![GitHub](https://img.shields.io/badge/github-ZibbyHQ%2Fagent--workflow-blue)](https://github.com/ZibbyHQ/agent-workflow)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/ZibbyHQ/agent-workflow/blob/main/LICENSE)
+
+The graph engine itself. Zero agent strategies, zero skills bundled — bring your own. This is the package you'd depend on if you want to embed the workflow runtime in your own app without the rest of the Zibby ecosystem.
+
+```bash
+npm install @zibby/agent-workflow
+```
+
+## What's in it
+
+| Export | Purpose |
+|---|---|
+| `WorkflowGraph` | The graph builder. `addNode`, `addEdge`, `addConditionalEdges`, `setEntryPoint`, `run`. |
+| `WorkflowAgent` | Base class your `graph.mjs` exports — has `buildGraph()`. |
+| `Node`, `ConditionalNode` | Internal node classes (rarely used directly). |
+| `WorkflowState` | History-tracked state passed between nodes. |
+| `AgentStrategy` | Base class for custom agent strategies. |
+| `registerStrategy`, `listStrategies`, `getAgentStrategy`, `invokeAgent` | Strategy registry. |
+| `registerSkill`, `getSkill`, `hasSkill`, `getAllSkills` | Skill registry. |
+| `compileGraph` | Build a graph from a JSON config (the format Studio writes). |
+| `ContextLoader` | Walks the spec dir for `CONTEXT.md` / `AGENTS.md` and merges into state. |
+| `timeline`, `WORKFLOW_GRAPH_LOG_MARKER_PREFIX` | CLI progress UX + structured markers consumed by Studio. |
+
+## Standalone usage
+
+```js
+import { WorkflowGraph, AgentStrategy, registerStrategy } from '@zibby/agent-workflow';
+import { z } from 'zod';
+
+class FakeAgent extends AgentStrategy {
+  constructor() { super('fake', 'demo', 0); }
+  canHandle() { return true; }
+  async invoke(prompt, { schema }) {
+    return { raw: 'ok', structured: schema.parse({ summary: 'hello' }) };
+  }
+}
+registerStrategy(new FakeAgent());
+
+const graph = new WorkflowGraph()
+  .addNode('plan', {
+    prompt: 'List 3 tasks for: {{input.goal}}',
+    outputSchema: z.object({ summary: z.string() }),
+    agent: 'fake',
+  })
+  .setEntryPoint('plan');
+
+const { state } = await graph.run(null, {
+  input: { goal: 'add dark mode' },
+  agentType: 'fake',
+});
+
+console.log(state.plan.summary);   // → 'hello'
+```
+
+## What it is *not*
+
+`@zibby/agent-workflow` is **just the engine**. It does not:
+
+- Ship any agent strategies (no Claude/Cursor/Codex/Gemini implementations)
+- Ship any skills (no Browser/Jira/GitHub MCP)
+- Provide a CLI
+
+For the batteries-included experience, use `@zibby/cli` + `@zibby/core` + `@zibby/skills`. For an embeddable engine, this package alone is enough.
+
+## Public protocol surface (stable)
+
+These constants are part of the public contract and consumed by Zibby Studio + tooling. They won't break across minor versions:
+
+- `WORKFLOW_GRAPH_LOG_MARKER_PREFIX` (`__WORKFLOW_GRAPH_LOG__`)
+- `STUDIO_STOP_REQUEST_FILE` (`.zibby-studio-stop`)
+- `ZIBBY_RUN_SOURCE=studio` env trigger
+- `stoppedByStudio: true` return key
+- Marker payload `{ phase: 'node_begin' | 'node_end', node: string }`
+
+## Source
+
+- npm: [`@zibby/agent-workflow`](https://www.npmjs.com/package/@zibby/agent-workflow)
+- GitHub (public, MIT): [ZibbyHQ/agent-workflow](https://github.com/ZibbyHQ/agent-workflow)
+- Examples: [01-hello-world](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/01-hello-world) · [02-pipeline](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/02-pipeline) · [03-conditional-routing](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/03-conditional-routing) · [04-custom-agent](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/04-custom-agent) · [05-with-skills](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples/05-with-skills)

package/docs/packages/cli.md

@@ -1,238 +1,73 @@
 ---
-sidebar_position: 5
-title: "@zibby/cli"
+sidebar_position: 3
+title: '@zibby/cli'
 ---
 
 # @zibby/cli
 
-The user-facing entry point — the `zibby` command.
+[![npm](https://img.shields.io/npm/v/@zibby/cli.svg)](https://www.npmjs.com/package/@zibby/cli)
 
-```bash
-npm install -g @zibby/cli
-```
-
-## What It Does
-
-`@zibby/cli` is the only package most users install. It provides:
-
-- **`zibby run`** — execute test specs with AI agents
-- **`zibby init`** — scaffold a customizable workflow
-- **`zibby login/logout/status`** — authentication
-- **`zibby upload`** — push existing artifacts to Zibby Cloud
-- **`zibby workflow`** — download/upload/list workflow graphs
-- **`zibby setup-playwright`** — configure Playwright MCP
-- **`zibby ci-setup`** — configure for CI/CD pipelines
-- **`zibby memory`** — memory database management
-- **`zibby video`** — organize test video files
-
-## Quick Usage
-
-```bash
-# Zero setup — run immediately
-echo "Go to example.com and verify the page title" > test.txt
-zibby run test.txt --agent cursor
-
-# Or with npx (no install)
-npx @zibby/cli run test.txt --agent cursor
-```
-
-## Commands
-
-### `zibby run [spec-path]`
-
-Run a test specification.
-
-```bash
-# Local test spec
-zibby run test-specs/login.txt --agent cursor
-
-# With cloud sync
-zibby run test-specs/login.txt --sync
-
-# Cloud test cases
-zibby run --sources TC001,TC002 --execution abc123
-
-# Specific workflow
-zibby run test.txt --workflow QuickSmokeWorkflow
-
-# Single node (debugging)
-zibby run test.txt --node execute_live --session last
-
-# Headless (CI/CD)
-zibby run test.txt --headless --auto-approve
-```
-
-| Flag | Description |
-|---|---|
-| `--agent <type>` | `cursor`, `claude`, or `codex` |
-| `--workflow <name>` | Named workflow (e.g., `QuickSmokeWorkflow`, `quick-smoke`) |
-| `--headless` | Headless browser mode |
-| `--node <name>` | Run a single node (`preflight`, `execute_live`, `generate_script`) |
-| `--session <id>` | Reuse session (`last` for most recent) — requires `--node` |
-| `--sources <ids>` | Comma-separated cloud test case IDs |
-| `--execution <id>` | Execution ID (with `--sources`) |
-| `--project <id>` | Project ID |
-| `--collection <name>` | Collection to organize the run |
-| `--folder <path>` | Folder within collection |
-| `--sync` | Upload results to cloud |
-| `--no-sync` | Skip cloud upload |
-| `--config <path>` | Config file path (default: `.zibby.config.js`) |
-| `--auto-approve` | Auto-approve MCP tool calls (CI/CD) |
-| `-o, --open` | Open dashboard after upload |
-| `--verbose` | Info-level logs |
-| `--debug` | Full debug logs |
-
-### `zibby init [project-name]`
-
-Scaffold a Zibby project with config and workflow files.
-
-```bash
-zibby init
-zibby init my-project --agent cursor --cloud-sync
-```
-
-| Flag | Description |
-|---|---|
-| `--agent <type>` | `cursor`, `claude`, or `codex` |
-| `--cloud-sync` | Enable cloud sync |
-| `--headless` / `--headed` | Browser mode |
-| `--skip-install` | Skip `npm install` |
-| `-f, --force` | Overwrite existing config |
-| `--mem` | Initialize memory database |
-
-Creates:
-
-```
-.zibby.config.js
-.zibby/
-├── graph.js
-├── nodes/
-│   ├── preflight.js
-│   ├── execute-live.js
-│   └── generate-script.js
-└── result-handler.js
-```
-
-### `zibby login` / `zibby logout` / `zibby status`
+The user-facing entry point — the `zibby` command. Install once globally; it pulls in `@zibby/core`, `@zibby/agent-workflow`, `@zibby/skills` automatically.
 
 ```bash
-zibby login            # OAuth browser flow
-zibby logout           # Clear session
-zibby status           # Show auth status
-zibby status --json    # Machine-readable
-```
-
-### `zibby upload <spec-path>`
-
-Upload existing test artifacts to Zibby Cloud.
-
-```bash
-zibby upload test-specs/login.txt --collection "Auth Tests"
+npm install -g @zibby/cli
+zibby --version
 ```
 
-### `zibby workflow`
+## What it does
 
-Manage workflow graphs:
+- **Scaffolds** workflows: `zibby workflow new <name>`
+- **Runs** workflows locally (one-shot): `zibby workflow run <name>`
+- **Deploys** to Zibby Cloud (Heroku-style bundles): `zibby workflow deploy <name>`
+- **Triggers** deployed workflows: `zibby workflow trigger <uuid>`
+- **Tails** logs: `zibby workflow logs <uuid> -t`
+- **Manages** auth: `zibby login`, `zibby logout`, `zibby status`
 
-```bash
-zibby workflow list
-zibby workflow download --type run_test
-zibby workflow upload --type analysis --file .zibby/workflow-analysis.json
-```
+The full command catalog lives at [CLI Reference](../cli-reference).
 
-### `zibby setup-playwright`
+## Self-contained workflow projects
 
-Configure the Playwright MCP server:
+`zibby workflow new` creates a workflow as a **self-contained npm project** — its own `package.json`, its own `node_modules`. So a workflow can pull in arbitrary deps (PDF libraries, custom MCP servers, your own SDK) without polluting the parent project.
 
-```bash
-zibby setup-playwright
-zibby setup-playwright --headed --viewport-width 1920 --viewport-height 1080
 ```
-
-### `zibby ci-setup`
-
-Configure Cursor Agent for CI/CD:
-
-```bash
-zibby ci-setup
-zibby ci-setup --get-keys
-zibby ci-setup --save
+my-app/
+├── package.json
+├── src/
+└── .zibby/
+    └── workflows/
+        └── my-pipeline/
+            ├── package.json     # workflow's own deps
+            ├── node_modules/
+            ├── graph.mjs
+            └── nodes/
 ```
 
-### `zibby video`
-
-Organize test videos — moves videos from `test-results/` to sit next to test files:
+The cloud bundle build does the same — `npm install` runs *inside* the workflow folder, scoped to its own package.json.
 
-```bash
-zibby video
-```
+## Configuration
 
-### `zibby list`
+The CLI reads `.zibby.config.mjs` at the project root for defaults:
 
-List your projects and API tokens:
-
-```bash
-zibby list
-```
-
-## Configuration File
-
-`.zibby.config.js` (or `.zibby.config.mjs`) in your project root:
-
-```javascript
+```js
+// .zibby.config.mjs
 export default {
-  agent: {
-    cursor: {
-      model: 'auto',
-      // Options: 'auto', 'opus-4.5', 'sonnet-4.5', 'composer-1',
-      //          'gpt-5.2-codex', 'gpt-5.2', 'gpt-5.3', 'gpt-5.4',
-      //          'gemini-3-pro', 'gemini-3-flash'
-    },
-    // claude: { model: 'auto' },
-    // codex: { model: 'gpt-5.2-codex' },
-    strictMode: false,
-  },
-
-  // Per-node model overrides
-  // models: {
-  //   default: 'auto',
-  //   execute_live: 'claude-opus-4',
-  // },
-
   paths: {
-    specs: 'test-specs',
-    generated: 'tests',
+    workflows: '.zibby/workflows',   // override if you want a different folder
     output: '.zibby/output',
   },
-
-  context: {
-    filenames: ['CONTEXT.md', 'AGENTS.md'],
-    discovery: {
-      env: `env-${process.env.ENV || 'local'}.js`,
-    },
+  agent: {
+    default: 'cursor',                // fallback agent when no per-node override
+  },
+  models: {
+    default: 'auto',
+    execute_live: 'claude-opus-4.6', // per-node model override
   },
-
-  video: 'on',
-  viewport: { width: 1280, height: 720 },
-  playwrightArtifacts: true,
-  cloudSync: false,
 };
 ```
 
-## Environment Variables
-
-| Variable | Description |
-|---|---|
-| `CURSOR_API_KEY` | Cursor agent API key (required in CI, optional locally) |
-| `ANTHROPIC_API_KEY` | Claude agent API key |
-| `OPENAI_API_KEY` | Codex agent API key |
-| `ZIBBY_API_KEY` | Project API key for cloud sync |
-| `ZIBBY_USER_TOKEN` | Personal Access Token for CI/CD |
-| `ZIBBY_ENV` | Environment override: `local`, `staging`, `prod` |
+`zibby workflow deploy` resolves this file locally and ships the result as `zibby.config.json` inside the deploy bundle, so the cloud runtime sees the same `agent` block, per-node `models`, and other declarative knobs as your local runs. Function values are dropped at deploy time (config is data, not code) — if you need runtime variation in cloud, use [per-workflow env vars](../cloud/env-vars).
 
-## Dependencies
+## Source
 
-`@zibby/cli` automatically installs:
-- `@zibby/core` — workflow engine
-- `@zibby/skills` — skill catalog
-- `@zibby/memory` — test memory
+- npm: [`@zibby/cli`](https://www.npmjs.com/package/@zibby/cli)
+- See [CLI Reference](../cli-reference) for every command + option