@zibby/skills 0.1.11 → 0.1.13

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

package/docs/packages/core.md

@@ -1,256 +1,72 @@
 ---
-sidebar_position: 1
-title: "@zibby/core"
+sidebar_position: 2
+title: '@zibby/core'
 ---
 
 # @zibby/core
 
-Core test automation engine with multi-agent and multi-MCP support.
+[![npm](https://img.shields.io/npm/v/@zibby/core.svg)](https://www.npmjs.com/package/@zibby/core)
+
+The batteries — five built-in agent strategies, the runtime, and a re-export of the `@zibby/agent-workflow` engine. This is what `zibby workflow new` scaffolds workflows against.
 
 ```bash
 npm install @zibby/core
 ```
 
-> Most users don't install this directly — `@zibby/cli` depends on it automatically.
-
-## What's Inside
+## What's in it
 
-`@zibby/core` is the runtime heart of Zibby. It provides:
+### Built-in agent strategies
 
-| Module | Purpose |
+| Strategy | Backed by |
 |---|---|
-| **Workflow Framework** | `WorkflowGraph`, `Node`, `WorkflowState`, graph compiler |
-| **Agent Strategies** | `CursorAgentStrategy`, `ClaudeAgentStrategy`, `CodexAgentStrategy` |
-| **Skill Registry** | `registerSkill`, `getSkill`, `listSkillIds` |
-| **Graph Compiler** | `compileGraph`, `validateGraphConfig` — JSON → executable graph |
-| **Tool Resolver** | Maps node skill declarations to concrete MCP tool permissions |
-| **Code Generator** | `generateWorkflowCode` — serializes graphs to code |
-| **Templates** | Built-in workflow templates (browser-test-automation, code-analysis) |
-| **Enrichment Pipeline** | DOM enrichers, accessibility enrichers, page-state enrichers |
-| **Runtime** | Stable-ID runtime, verification strategies, Playwright integration |
-| **Sync** | Cloud upload/download for test results |
-
-## Exports
-
-```javascript
-// Framework
-import {
-  WorkflowGraph,
-  Node,
-  ConditionalNode,
-  WorkflowState,
-  OutputParser,
-  compileGraph,
-  validateGraphConfig,
-  extractSteps,
-} from '@zibby/core';
+| `CursorAgentStrategy` | `cursor-agent` CLI |
+| `ClaudeAgentStrategy` | `@anthropic-ai/claude-agent-sdk` |
+| `CodexAgentStrategy` | `@openai/codex` CLI |
+| `GeminiAgentStrategy` | `@google/gemini-cli` |
+| `AssistantStrategy` | OpenAI Assistants API |
 
-// Agent strategies
-import {
-  invokeAgent,
-  getAgentStrategy,
-  CursorAgentStrategy,
-  ClaudeAgentStrategy,
-  AgentStrategy,
-} from '@zibby/core';
-
-// Skill registry
-import {
-  registerSkill,
-  getSkill,
-  hasSkill,
-  getAllSkills,
-  listSkillIds,
-} from '@zibby/core';
-
-// Zod (re-exported for convenience)
-import { z } from '@zibby/core';
+Importing `@zibby/core` registers all five into the `@zibby/agent-workflow` strategy registry automatically. So:
 
-// Skills enum
-import { SKILLS } from '@zibby/core';
-```
-
-## WorkflowGraph
-
-The central class. Create a graph, add nodes and edges, then run it.
-
-```javascript
+```js
 import { WorkflowGraph } from '@zibby/core';
-import { z } from '@zibby/core';
-
-const graph = new WorkflowGraph({
-  stateSchema: z.object({        // Optional: validates initial state
-    testSpec: z.string(),
-    cwd: z.string().optional(),
-  }),
-  middleware: [],                 // Optional: wrap every node execution
-});
-
-graph.addNode('step_a', myNode);
-graph.addEdge('step_a', 'step_b');
-graph.setEntryPoint('step_a');
-
-const result = await graph.run(agent, { testSpec: '...' });
-```
-
-**Key methods:**
-
-| Method | Description |
-|---|---|
-| `addNode(name, config, options?)` | Add an executable node |
-| `addConditionalNode(name, config)` | Add a node that routes based on state |
-| `addEdge(from, to)` | Linear connection between nodes |
-| `addConditionalEdges(from, routeFn)` | Branch based on state — `routeFn(state) => 'next_node'` |
-| `setEntryPoint(name)` | Declare which node runs first |
-| `setStateSchema(zodSchema)` | Validate initial state before execution |
-| `use(middlewareFn)` | Add graph-level middleware |
-| `serialize()` | Export graph as JSON (for dashboard visual editor) |
-| `run(agent, initialState)` | Execute the graph |
-
-## Node Definition
-
-A node is a plain object with `name`, `prompt`, and `outputSchema`:
-
-```javascript
-import { z } from '@zibby/core';
-
-export const myNode = {
-  name: 'my_node',
-
-  // Prompt: function receiving state, returns string
-  prompt: (state) => `Analyze: ${state.testSpec}`,
 
-  // Output schema: Zod object validated at runtime
-  outputSchema: z.object({
-    title: z.string().describe('Short title'),
-    confidence: z.number().min(0).max(1),
-  }),
-
-  // Optional: skills needed (MCP tools)
-  skills: ['browser', 'memory'],
-
-  // Optional: timeout in ms (default 300000)
-  timeout: 600000,
-
-  // Optional: retry count
-  retries: 1,
-
-  // Optional: post-processing hook
-  onComplete: async (state, result) => {
-    // Transform result before it goes into state
-    return { ...result, processedAt: Date.now() };
-  },
-};
-```
-
-For nodes that don't call an LLM (pure data transforms), use a custom `execute` function:
-
-```javascript
-export const transformNode = {
-  name: 'transform',
-  _isCustomCode: true,
-  outputSchema: z.object({ cleaned: z.string() }),
-  execute: async (context) => {
-    const raw = context.state.get('raw_data');
-    return { cleaned: raw.trim().toLowerCase() };
-  },
-};
+const graph = new WorkflowGraph()
+  .addNode('plan', { prompt, outputSchema, agent: 'cursor' })   // already registered
+  .setEntryPoint('plan');
 ```
 
-## Agent Strategy Framework
+### Re-exports from agent-workflow
 
-All agents implement the same `AgentStrategy` base class:
+So you can do `import { WorkflowGraph, z, AgentStrategy } from '@zibby/core'` without separately importing the engine:
 
-```javascript
-import { AgentStrategy } from '@zibby/core';
+- `WorkflowGraph`, `WorkflowAgent`, `Node`, `WorkflowState`
+- `AgentStrategy`, `registerStrategy`, `getAgentStrategy`, `invokeAgent`
+- `registerSkill`, `getSkill`, `getAllSkills`
+- `compileGraph`, `validateGraphConfig`
+- `timeline`, session helpers, constants
 
-class MyCustomAgent extends AgentStrategy {
-  constructor() {
-    super('my-agent', 'My Custom Agent', 50);
-  }
+### z (Zod)
 
-  canHandle(context) {
-    return !!process.env.MY_AGENT_KEY;
-  }
-
-  async invoke(prompt, options) {
-    // options.schema — Zod schema for structured output
-    // options.workspace — working directory
-    // options.skills — skill IDs to resolve
-    // options.model — model name or 'auto'
-    // options.timeout — execution timeout
-    const response = await myApiCall(prompt, options);
-    if (options.schema) {
-      return { raw: response, structured: options.schema.parse(JSON.parse(response)) };
-    }
-    return response;
-  }
-}
-```
-
-Select and invoke an agent:
-
-```javascript
-import { invokeAgent, getAgentStrategy } from '@zibby/core';
-
-// Auto-select based on config
-const result = await invokeAgent(prompt, { state: { agentType: 'cursor' } }, {
-  model: 'auto',
-  workspace: process.cwd(),
-  schema: MyZodSchema,
-  skills: ['browser'],
-});
-```
+Re-exports `zod/v3` so you don't need a separate Zod dep:
 
-## Graph Compiler
-
-Compile a JSON graph definition (from the Zibby dashboard visual editor) into an executable `WorkflowGraph`:
-
-```javascript
-import { compileGraph, validateGraphConfig } from '@zibby/core';
-
-const graphJson = {
-  nodes: [
-    { id: 'preflight', type: 'preflight', data: { nodeType: 'preflight' } },
-    { id: 'execute_live', type: 'execute_live', data: { nodeType: 'execute_live' } },
-  ],
-  edges: [
-    { source: 'preflight', target: 'execute_live' },
-    { source: 'execute_live', target: 'END' },
-  ],
-  nodeConfigs: {
-    preflight: { prompt: 'Analyze: {{testSpec}}' },
-  },
-};
-
-// Validate
-const { valid, errors } = validateGraphConfig(graphJson);
-
-// Compile
-const graph = compileGraph(graphJson, { stateSchema: MySchema });
+```js
+import { z } from '@zibby/core';
 
-// Run
-await graph.run(agent, initialState);
+const Plan = z.object({ tasks: z.array(z.string()) });
 ```
 
-## Built-in Templates
+### Cloud-runtime helpers
 
-### Browser Test Automation
+Functions used by the cloud executor and Studio integration — `ZibbyRuntime`, `StableIdRuntime`, `resolveIntegrationToken`, `cloneRepo`, `patchCursorAgentForCI`, `runPlaywrightTestTool`. Most users don't import these directly.
 
-```
-preflight → execute_live → generate_script → END
-```
-
-| Node | Skills | Output |
-|---|---|---|
-| `preflight` | — | `{ title, assertions[] }` |
-| `execute_live` | browser, memory | `{ success, steps[], actions[], assertions[] }` |
-| `generate_script` | — | `{ testCode, filename }` |
+## When to depend on this vs. agent-workflow
 
-### Code Analysis
+| Goal | Pick |
+|---|---|
+| Build a workflow with built-in agents (cursor/claude/codex/gemini/assistant) | `@zibby/core` |
+| Embed the engine in your own app with custom agents only | `@zibby/agent-workflow` |
+| Use the CLI | `@zibby/cli` (transitively pulls both) |
 
-```
-setup → analyze_ticket → generate_code → generate_test_cases → finalize → END
-```
+## Source
 
-Used by the cloud pipeline for Jira ticket analysis and code generation.
+- npm: [`@zibby/core`](https://www.npmjs.com/package/@zibby/core)

package/docs/recipes/index.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+title: Recipes overview
+---
+
+# Built-in workflow recipes
+
+Zibby ships with a few **vertical slice workflows** — production-ready pipelines you can run today, demonstrating what the platform does. Each recipe is a real Zibby workflow under the hood, eating its own dog food.
+
+```
+                       ┌─────────────────────┐
+   ┌──────────────────►│  zibby workflow new │  ◄── Build your own
+   │                   │  zibby workflow ... │
+   │                   └─────────────────────┘
+   │                              ▲
+   │                              │ uses the same primitives
+   │                              │
+   │                   ┌─────────────────────┐
+   │  Recipes built ──►│  zibby test         │  ◄── Browser testing
+   │  on top of the    │  zibby analyze      │  ◄── Code analysis
+   │  same platform    │  zibby video        │  ◄── Test playback
+   │                   │  zibby generate     │  ◄── Spec generation
+   │                   └─────────────────────┘
+```
+
+You don't have to use the recipes. You can build whatever pipeline you want with `zibby workflow new`. The recipes just save you from writing the obvious starter graphs for common cases.
+
+## Available recipes
+
+| Recipe | What it does | Best for |
+|---|---|---|
+| [`zibby test`](./test) | Drives a browser via Cursor or Claude, runs assertions, generates a Playwright script + verification video | E2E test generation from plain-English specs |
+| `zibby analyze` | Reads a Jira/Linear ticket, walks the codebase, produces an implementation plan | Pre-implementation planning, ticket triage |
+| `zibby generate` | Generates test specs from a ticket + codebase | Backfilling test coverage on legacy projects |
+| `zibby video` | Re-records or organizes verification videos for an existing test | Producing demos, regenerating after code changes |
+
+## Why recipes matter
+
+Three reasons we ship vertical workflows alongside the platform:
+
+1. **Proof of concept** — every recipe IS a Zibby workflow. If `zibby test` works, the platform works. You can see the actual graph definition and adapt it.
+2. **Faster onboarding** — you don't need to design a full graph on day one. Run a recipe, see the output, then build your own.
+3. **Demonstrates multi-vendor** — the test recipe runs across Cursor / Claude / Codex / Gemini. Pick the agent that gives you the best results for your use case; the recipe doesn't care.
+
+## Building your own recipe
+
+If you have a workflow you'd want shipped as a built-in:
+
+```bash
+zibby workflow new my-recipe          # scaffold
+# ... build it out ...
+zibby workflow run my-recipe          # test locally
+zibby workflow deploy my-recipe       # ship to your cloud account
+```
+
+If it's broadly useful, we may pull it into the official recipes set. Open an issue or PR.
+
+## Next
+
+- **[`zibby test` recipe](./test)** — the most-used recipe, walked through end-to-end
+- **[Build your own workflow](../get-started/your-first-workflow)** — scaffold and customize
+- **[Concepts: graph](../concepts/graph)** — the primitives every recipe is built on