@zibby/skills 0.1.11 → 0.1.13

package/docs/get-started/trigger-and-logs.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 5
+title: 5. Trigger & tail logs
+pagination_prev: get-started/deploy
+---
+
+# Run a deployed workflow and watch logs
+
+## Trigger
+
+```bash
+zibby workflow trigger 2b1ea07f-3ede-4bfd-a51d-431f0bab008e
+```
+
+The CLI returns immediately with a job ID:
+
+```
+✔ Workflow triggered successfully
+
+  Job Details:
+    Job ID:    ee333411-22e6-4733-b790-d480af3f662e
+    Status:    running
+    Version:   3
+    Triggered: 02/05/2026, 10:23:13
+
+  Monitor execution:
+    zibby workflow logs 2b1ea07f-... 
+    zibby workflow logs 2b1ea07f-... -t
+```
+
+Pass input the same way as locally:
+
+```bash
+zibby workflow trigger <uuid> -p ticket=BUG-123
+zibby workflow trigger <uuid> --input '{"ticket":"BUG-123"}'
+zibby workflow trigger <uuid> --input-file ./input.json
+```
+
+If you omit the UUID, the CLI shows an interactive picker over your deployed workflows.
+
+## Tail logs (Heroku-style)
+
+```bash
+zibby workflow logs 2b1ea07f-3ede-4bfd-a51d-431f0bab008e -t
+```
+
+`-t` follows live. Without `-t` it dumps the last execution and exits.
+
+```
+  Streaming logs for workflow 2b1ea07f-3ede-4bfd-a51d-431f0bab008e...
+  Press Ctrl+C to stop.
+
+2026-05-02 23:30:51.345  zibby v0.1.x
+────────────────────────────────────────────────────────────
+ Workflow:  my-pipeline
+ Job:       ee333411-...
+ Project:   6b60049d-...
+ Agent:     cursor (model: auto)
+────────────────────────────────────────────────────────────
+[setup] Bundle extracted (3.2s)
+[setup] Loaded MyPipelineWorkflow
+[setup] Registered 5 agent strategies (...)
+
+┌ example
+│ ◆ Model: auto | key: ***bc97
+│ ...
+└ done 19.4s
+[done] my-pipeline completed in 19.4s
+```
+
+The stream covers the full execution end-to-end — agent reasoning, tool calls, schema validation, completion summary.
+
+## Multiple executions
+
+Workflow UUIDs follow the workflow, not a single run. After one execution finishes, `logs -t` waits for the next trigger of the same workflow and auto-switches to streaming it. Like `heroku logs --tail`.
+
+To exit after the current run, just Ctrl+C — there's no "exit on completion" mode (yet).
+
+## Triggering from anywhere
+
+The CLI is the easiest way, but workflows expose an HTTP API for programmatic triggering — see [Cloud → Triggering programmatically](../cloud/triggering).
+
+## You're done
+
+You've now scaffolded, run locally, deployed, triggered, and tailed a workflow. The rest of the docs go deeper:
+
+- [Concepts](../concepts/graph) — how the graph engine works
+- [CLI Reference](../cli-reference) — every command
+- [Cloud](../cloud/triggering) — HTTP triggers, log archives, bundle internals
+- [Packages](../packages/agent-workflow) — package-level docs

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)