@zibby/skills 0.2.23 → 0.2.24

package/docs/get-started/install.md

@@ -1,60 +0,0 @@
----
-sidebar_position: 1
-title: 1. Install
-pagination_prev: intro
-pagination_next: get-started/your-first-workflow
----
-
-# Install the CLI
-
-You build **Agents** with Zibby — deployed automations. The CLI command is `zibby agent`.
-
-```bash
-npm install -g @zibby/cli
-```
-
-Verify:
-
-```bash
-zibby --version
-```
-
-You should see something like `zibby v0.4.x`.
-
-## No global install? Use npx
-
-Every example below works with `npx @zibby/cli` instead of `zibby`:
-
-```bash
-npx @zibby/cli agent new my-agent
-```
-
-The first call downloads the package; subsequent calls use the cached copy.
-
-## Log in
-
-Cloud features (deploy, trigger, logs) need authentication:
-
-```bash
-zibby login
-```
-
-This opens your browser and writes a session token to `~/.zibby/config.json`. Logged in for 30 days.
-
-For CI/CD, set `ZIBBY_API_KEY` in the environment instead — the CLI prefers that over the saved session.
-
-## Pick an agent runtime
-
-Agents hand off to external coding-agent CLIs at runtime. You'll need at least one of these installed (locally — the cloud runtime has them pre-installed):
-
-| Agent | How to install | Auth |
-|---|---|---|
-| **Cursor** | Install [Cursor](https://cursor.com), or `npm i -g cursor-agent` | `cursor-agent login` (or `CURSOR_API_KEY`) |
-| **Claude Code** | `npm i -g @anthropic-ai/claude-agent-sdk` | `ANTHROPIC_API_KEY` |
-| **Codex** | `npm i -g @openai/codex` | `OPENAI_API_KEY` |
-| **Gemini** | `npm i -g @google/gemini-cli` | `GOOGLE_API_KEY` |
-| **Assistant** | None — uses OpenAI Assistants API | `OPENAI_API_KEY` |
-
-You only need one. The cloud runtime supports all five out of the box.
-
-→ Next: [Your first agent](./your-first-workflow)

package/docs/get-started/run-locally.md

@@ -1,94 +0,0 @@
----
-sidebar_position: 3
-title: 3. Run it locally
-pagination_prev: get-started/your-first-workflow
-pagination_next: get-started/deploy
----
-
-# Run an agent locally
-
-```bash
-zibby agent run my-agent
-```
-
-One-shot: loads `graph.mjs`, instantiates your `WorkflowAgent` class, runs the graph against a real agent, prints results, exits. Output lands in `.zibby/output/sessions/<sessionId>/`:
-
-- `result.json` — the final structured output (Zod-validated)
-- `raw_stream_output.txt` — every byte the agent emitted
-- `events.json` — JSONL execution log: which node ran when, what it received, what it returned, retries
-- `.session-info.json` — session metadata
-
-The flag surface mirrors `zibby agent trigger` (cloud) on purpose: the call you make locally is the same call you make against the cloud, just with the verb flipped.
-
-## Pass input
-
-Most agents take input. Edit `graph.mjs` to define an input schema and reference `state.input`:
-
-```js
-graph.addNode('plan', {
-  prompt: ({ input }) => `Triage this ticket: ${input.ticket}`,
-  outputSchema: z.object({ tasks: z.array(z.string()) }),
-  agent: 'claude',
-});
-```
-
-Then pass input via `--input`:
-
-```bash
-zibby agent run my-agent --input '{"ticket":"BUG-123"}'
-```
-
-Or `--param key=value` (repeatable, dot-notation supported):
-
-```bash
-zibby agent run my-agent -p ticket=BUG-123 -p priority=high
-zibby agent run my-agent -p user.name=Alice -p user.role=admin
-```
-
-Or `--input-file payload.json` for larger payloads.
-
-Precedence: `--param` > `--input` > `--input-file`. Same as `trigger`.
-
-## Iterating
-
-Each run is a fresh process — re-edit `graph.mjs` or any node file and re-run. There's no daemon to restart; tool errors and crashes don't leave a server hanging on port 3848.
-
-If you want auto-rerun on file change, run it under `nodemon`:
-
-```bash
-npx nodemon --ext mjs,js --exec "zibby agent run my-agent -p ticket=BUG-123"
-```
-
-Or add it to your agent's `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "nodemon --ext mjs,js --exec \"zibby agent run my-agent\""
-  }
-}
-```
-
-Then `npm run dev`.
-
-## Inspect a run
-
-After a run finishes, the CLI prints the session ID. Open the session folder to inspect every step:
-
-```bash
-ls .zibby/output/sessions/<sessionId>/
-cat .zibby/output/sessions/<sessionId>/result.json | jq
-```
-
-## Studio (long-lived server, optional)
-
-Studio is a desktop UI for browsing live + past runs. It connects to a local HTTP server, so when you use Studio you start that instead:
-
-```bash
-zibby agent start my-agent   # long-lived server on :3848 (Studio talks to this)
-zibby studio                       # launch the desktop app
-```
-
-For CLI-only iteration, stick with `zibby agent run`.
-
-→ Next: [Deploy to cloud](./deploy)

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

@@ -1,90 +0,0 @@
----
-sidebar_position: 5
-title: 5. Trigger & tail logs
-pagination_prev: get-started/deploy
----
-
-# Run a deployed agent and watch logs
-
-## Trigger
-
-```bash
-zibby agent 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 agent logs 2b1ea07f-... 
-    zibby agent logs 2b1ea07f-... -t
-```
-
-Pass input the same way as locally:
-
-```bash
-zibby agent trigger <uuid> -p ticket=BUG-123
-zibby agent trigger <uuid> --input '{"ticket":"BUG-123"}'
-zibby agent trigger <uuid> --input-file ./input.json
-```
-
-If you omit the UUID, the CLI shows an interactive picker over your deployed agents.
-
-## Tail logs (Heroku-style)
-
-```bash
-zibby agent 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.4.x
-────────────────────────────────────────────────────────────
- Workflow:  my-agent
- 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-agent completed in 19.4s
-```
-
-The stream covers the full execution end-to-end — agent reasoning, tool calls, schema validation, completion summary.
-
-## Multiple executions
-
-Agent UUIDs follow the agent, not a single run. After one execution finishes, `logs -t` waits for the next trigger of the same agent 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 agents 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 an agent. 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/use-from-agents.md

@@ -1,153 +0,0 @@
----
-sidebar_position: 6
-title: 6. Use from your AI agent
-pagination_prev: get-started/trigger-and-logs
----
-
-# Use Zibby from Claude Code, Cursor, Codex, or Gemini
-
-Zibby ships an MCP (Model Context Protocol) server — [`@zibby/mcp-cli`](../packages/mcp-cli). Add it once to your agent's config and Zibby becomes a first-class tool the agent can call directly from chat. Deploy agents, trigger runs, tail logs — all without leaving your editor.
-
-```
-You:    Deploy the browser-test template to my Playhouse project, then run it.
-Agent:  → zibby_scaffold_agent
-        → zibby_deploy_agent
-        → zibby_trigger_agent
-        → "Done. Job a23e… completed in 47s, 0 failures."
-```
-
-The MCP server runs **locally** as a subprocess of your agent — no Zibby-hosted endpoint, no credentials shared with us, no proxy in the middle. Your existing `~/.zibby/config.json` session is reused if you've already run `zibby login`.
-
-## Install
-
-Pick your agent. All flavors run the same npm package via `npx -y` — no global install.
-
-### Claude Code
-
-Add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### OpenAI Codex CLI
-
-Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.zibby]
-command = "npx"
-args = ["-y", "@zibby/mcp-cli"]
-```
-
-### Gemini CLI
-
-Add to `~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### Windows note
-
-If your agent on Windows can't find `npx`, wrap with `cmd /c`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-## First-time login
-
-If you haven't run `zibby login` yet in a terminal, just tell the agent:
-
-```
-You:    Log in to Zibby.
-Agent:  → zibby_login
-        (browser opens to the Zibby login page)
-        → "Logged in as you@yourcompany.com (3 projects cached)."
-```
-
-Login state lives in `~/.zibby/config.json` (mode `0600`) — the same file the CLI writes. Subsequent agent sessions reuse it.
-
-## What the agent can do
-
-| Read-only | Write |
-|---|---|
-| List projects | Scaffold an agent from an official template |
-| List official templates | Deploy an agent to a project |
-| List agents (local + remote) | Trigger a deployed agent |
-| Show login status | Run an agent locally (debug) |
-| Fetch logs from a run | Download a deployed agent (with explicit user confirmation) |
-| Static-validate an agent | |
-
-**Destructive operations stay out of the agent's hands** — agent delete, env-var changes, schedule mutation, and credential management require you to run `zibby` in a terminal. Two-stage authorization for anything that could surprise you.
-
-See the [`@zibby/mcp-cli` package reference](../packages/mcp-cli) for the full tool list and security model.
-
-## Example session
-
-```
-You:    What templates are available?
-
-Agent:  → zibby_list_templates
-        "Three official templates:
-         - browser-test-automation: Playwright preflight + live execution + script gen
-         - code-analysis: Jira ticket → analyze → generate code → emit tests
-         - generate-test-cases: code diff → prioritized AI-runnable test specs"
-
-You:    Scaffold generate-test-cases into a new agent called "release-tests" in my Playhouse project.
-
-Agent:  → zibby_list_projects                       (resolves "Playhouse" → projectId)
-        → zibby_scaffold_agent name=release-tests template=generate-test-cases
-        → zibby_validate_agent name=release-tests
-        "Scaffolded and validated. Ready to deploy."
-
-You:    Deploy it.
-
-Agent:  → zibby_deploy_agent name=release-tests projectId=…
-        "Deployed v1 — UUID 33039db5-2f32-4094-9841-317bc56a88c9."
-
-You:    Run it against this PR diff: ‹pastes diff›
-
-Agent:  → zibby_trigger_agent uuid=33039db5… input={diff: "...", changedFiles: [...]}
-        → zibby_agent_logs jobId=c62e97a4… lines=100
-        "Run completed in 1m 23s. Generated 7 test specs (4 Critical, 2 High, 1 Medium)."
-```
-
-→ Full tool reference: [`@zibby/mcp-cli`](../packages/mcp-cli)

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

@@ -1,69 +0,0 @@
----
-sidebar_position: 2
-title: 2. Your first agent
-pagination_prev: get-started/install
-pagination_next: get-started/run-locally
----
-
-# Scaffold your first agent
-
-An **Agent** is a deployed automation. Scaffold one with the CLI with the `zibby agent` CLI:
-
-```bash
-zibby agent new my-agent
-# zibby agent new my-agent   # alias — identical
-```
-
-This creates:
-
-```
-.zibby/workflows/my-agent/
-├── graph.mjs         # the workflow definition (entry point)
-├── nodes/
-│   └── example.mjs   # a sample node
-├── package.json      # agent's own deps (each agent 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 agents (default: `.zibby/workflows`). The CLI also runs `npm install` inside the new agent 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 agent falls back to the project default (set in `.zibby.config.mjs` or `AGENT_TYPE` env var).
-
-→ Next: [Run it locally](./run-locally)

package/docs/getting-started.md

@@ -1,108 +0,0 @@
----
-sidebar_position: 2
-title: Getting Started
----
-
-# Getting Started
-
-Get up and running with Zibby in under 5 minutes.
-
-## 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/installation.md

@@ -1,127 +0,0 @@
----
-sidebar_position: 3
-title: Installation
----
-
-# Installation
-
-## Install the CLI
-
-```bash
-npm install -g @zibby/cli
-```
-
-Verify:
-
-```bash
-zibby --version
-```
-
-Or use without installing:
-
-```bash
-npx @zibby/cli run test.txt --agent cursor
-```
-
-## Project Setup (Optional)
-
-`zibby test` works without any project setup — it uses a built-in workflow. To customize:
-
-```bash
-cd your-project
-zibby init --agent cursor
-```
-
-**Options:**
-
-| Flag | Description |
-|---|---|
-| `--agent <type>` | `cursor` or `claude` |
-| `--cloud-sync` | Enable cloud sync and configure API |
-| `--headless` | Run browser in headless mode |
-| `--headed` | Run browser in headed mode (visible) |
-| `--skip-install` | Skip `npm install` |
-| `-f, --force` | Overwrite existing config |
-
-This creates:
-
-```
-.zibby.config.js           # Project configuration
-.zibby/
-├── graph.js                # Workflow graph (entry point → nodes → END)
-├── nodes/
-│   ├── preflight.js        # Extract title + assertions from spec
-│   ├── execute-live.js     # AI drives browser
-│   └── generate-script.js  # Generate Playwright script
-└── result-handler.js       # Save artifacts after execution
-```
-
-## Configuration
-
-`.zibby.config.js` in your project root (ESM format):
-
-```javascript
-export default {
-  agent: {
-    cursor: {
-      model: 'auto',
-    },
-    // OR:
-    // claude: {
-    //   model: 'auto',
-    //   maxTokens: 4096,
-    // },
-  },
-
-  paths: {
-    specs: 'test-specs',
-    generated: 'tests',
-    output: '.zibby/output',
-  },
-
-  video: 'on',
-  viewport: { width: 1280, height: 720 },
-  playwrightArtifacts: true,
-  cloudSync: false,
-};
-```
-
-## Environment Setup
-
-Copy the generated `.env.example` to `.env` and add your keys:
-
-```bash
-cp .env.example .env
-```
-
-Then edit `.env` with your values:
-
-```bash
-# For Cursor agent in CI/CD
-CURSOR_API_KEY=your-cursor-api-key
-
-# For Claude agent
-ANTHROPIC_API_KEY=sk-ant-...
-
-# For cloud sync (optional)
-ZIBBY_API_KEY=zby_your_api_key_here
-```
-
-## Playwright Setup
-
-Zibby uses Playwright for browser automation. If you don't have it:
-
-```bash
-zibby setup-playwright
-```
-
-This configures the Playwright MCP server for Zibby.
-
-## Verify Setup
-
-```bash
-echo "Go to example.com and verify the page title" > test.txt
-zibby test test.txt --agent cursor
-```
-
-You should see a browser open, the AI navigate to example.com, and a Playwright script generated in `tests/`.