@zibby/skills 0.2.22 → 0.2.24

package/docs/packages/agent-workflow.md

@@ -1,88 +0,0 @@
----
-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` | Internal node class (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,73 +0,0 @@
----
-sidebar_position: 3
-title: '@zibby/cli'
----
-
-# @zibby/cli
-
-[![npm](https://img.shields.io/npm/v/@zibby/cli.svg)](https://www.npmjs.com/package/@zibby/cli)
-
-The user-facing entry point — the `zibby` command. Install once globally; it pulls in `@zibby/core`, `@zibby/agent-workflow`, `@zibby/skills` automatically.
-
-```bash
-npm install -g @zibby/cli
-zibby --version
-```
-
-## What it does
-
-- **Scaffolds** agents: `zibby agent new <name>`
-- **Runs** agents locally (one-shot): `zibby agent run <name>`
-- **Deploys** to Zibby Cloud (Heroku-style bundles): `zibby agent deploy <name>`
-- **Triggers** deployed agents: `zibby agent trigger <uuid>`
-- **Tails** logs: `zibby agent logs <uuid> -t`
-- **Manages** auth: `zibby login`, `zibby logout`, `zibby status`
-
-The full command catalog lives at [CLI Reference](../cli-reference).
-
-## Self-contained agent projects
-
-`zibby agent new` creates an agent as a **self-contained npm project** — its own `package.json`, its own `node_modules`. So an agent can pull in arbitrary deps (PDF libraries, custom MCP servers, your own SDK) without polluting the parent project.
-
-```
-my-app/
-├── package.json
-├── src/
-└── .zibby/
-    └── workflows/
-        └── my-agent/
-            ├── package.json     # agent's own deps
-            ├── node_modules/
-            ├── graph.mjs
-            └── nodes/
-```
-
-The cloud bundle build does the same — `npm install` runs *inside* the agent folder, scoped to its own package.json.
-
-## Configuration
-
-The CLI reads `.zibby.config.mjs` at the project root for defaults:
-
-```js
-// .zibby.config.mjs
-export default {
-  paths: {
-    workflows: '.zibby/workflows',   // override if you want a different folder
-    output: '.zibby/output',
-  },
-  agent: {
-    default: 'cursor',                // fallback agent when no per-node override
-  },
-  models: {
-    default: 'auto',
-    execute_live: 'claude-opus-4.6', // per-node model override
-  },
-};
-```
-
-`zibby agent 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-agent env vars](../cloud/env-vars).
-
-## Source
-
-- 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,72 +0,0 @@
----
-sidebar_position: 2
-title: '@zibby/core'
----
-
-# @zibby/core
-
-[![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 agent new` scaffolds agents against.
-
-```bash
-npm install @zibby/core
-```
-
-## What's in it
-
-### Built-in agent strategies
-
-| Strategy | Backed by |
-|---|---|
-| `CursorAgentStrategy` | `cursor-agent` CLI |
-| `ClaudeAgentStrategy` | `@anthropic-ai/claude-agent-sdk` |
-| `CodexAgentStrategy` | `@openai/codex` CLI |
-| `GeminiAgentStrategy` | `@google/gemini-cli` |
-| `AssistantStrategy` | OpenAI Assistants API |
-
-Importing `@zibby/core` registers all five into the `@zibby/agent-workflow` strategy registry automatically. So:
-
-```js
-import { WorkflowGraph } from '@zibby/core';
-
-const graph = new WorkflowGraph()
-  .addNode('plan', { prompt, outputSchema, agent: 'cursor' })   // already registered
-  .setEntryPoint('plan');
-```
-
-### Re-exports from agent-workflow
-
-So you can do `import { WorkflowGraph, z, AgentStrategy } from '@zibby/core'` without separately importing the engine:
-
-- `WorkflowGraph`, `WorkflowAgent`, `Node`, `WorkflowState`
-- `AgentStrategy`, `registerStrategy`, `getAgentStrategy`, `invokeAgent`
-- `registerSkill`, `getSkill`, `getAllSkills`
-- `compileGraph`, `validateGraphConfig`
-- `timeline`, session helpers, constants
-
-### z (Zod)
-
-Re-exports `zod/v3` so you don't need a separate Zod dep:
-
-```js
-import { z } from '@zibby/core';
-
-const Plan = z.object({ tasks: z.array(z.string()) });
-```
-
-### Cloud-runtime helpers
-
-Functions used by the cloud executor and Studio integration — `ZibbyRuntime`, `StableIdRuntime`, `resolveIntegrationToken`, `cloneRepo`, `patchCursorAgentForCI`, `runPlaywrightTestTool`. Most users don't import these directly.
-
-## When to depend on this vs. agent-workflow
-
-| Goal | Pick |
-|---|---|
-| Build an agent with built-in strategies (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) |
-
-## Source
-
-- npm: [`@zibby/core`](https://www.npmjs.com/package/@zibby/core)

package/docs/packages/mcp-browser.md

@@ -1,110 +0,0 @@
----
-sidebar_position: 4
-title: "@zibby/mcp-browser"
----
-
-# @zibby/mcp-browser
-
-Wrapper around [`@playwright/mcp`](https://github.com/anthropics/playwright-mcp) with stable ID injection, event recording, and session-aware video capture.
-
-```bash
-npm install @zibby/mcp-browser
-```
-
-> Installed automatically as a dependency of `@zibby/core`.
-
-## Why a Wrapper?
-
-The official `@playwright/mcp` provides standard browser automation tools. `@zibby/mcp-browser` adds:
-
-| Feature | Description |
-|---|---|
-| **Stable IDs** | Injects deterministic `data-zibby-id` attributes into the DOM, so selectors survive page re-renders |
-| **Event Recording** | Captures every MCP tool call (navigate, click, type) with timestamps for the action timeline |
-| **Session Awareness** | Reads `ZIBBY_SESSION_INFO` to know which session and node is active — saves videos and events to the right directory |
-| **Video Capture** | Records browser sessions as video with configurable resolution |
-
-## Usage
-
-### As an MCP Server (standalone)
-
-```bash
-npx mcp-browser-zibby --save-video=1280x720 --viewport-size=1280x720 --output-dir=./output
-```
-
-### Via the Browser Skill (recommended)
-
-The browser skill in `@zibby/skills` resolves to `@zibby/mcp-browser` automatically:
-
-```javascript
-import { SKILLS } from '@zibby/core';
-
-export const myNode = {
-  name: 'my_node',
-  skills: [SKILLS.BROWSER],
-  // The framework starts @zibby/mcp-browser as an MCP server
-  // and wires it to whichever agent is active
-};
-```
-
-### Programmatic
-
-```javascript
-import { startServer } from '@zibby/mcp-browser';
-
-const server = await startServer({
-  saveVideo: '1280x720',
-  viewportSize: '1280x720',
-  outputDir: './test-results',
-});
-```
-
-## Stable IDs
-
-Standard CSS selectors break when the DOM changes between renders. Stable IDs solve this by injecting deterministic attributes based on element role, position, and content:
-
-```html
-<!-- Before stable ID injection -->
-<button class="btn-primary sc-fEOsli">Submit</button>
-
-<!-- After stable ID injection -->
-<button class="btn-primary sc-fEOsli" data-zibby-id="form-submit-button">Submit</button>
-```
-
-The stable ID algorithm considers:
-- Element tag and ARIA role
-- Accessible name and label
-- Position relative to landmarks
-- Content hash for disambiguation
-
-This gives the AI and generated Playwright scripts more reliable selectors.
-
-## Event Recording
-
-Every MCP tool call is recorded as a structured event:
-
-```json
-{
-  "timestamp": 1710784523000,
-  "node": "execute_live",
-  "tool": "browser_click",
-  "arguments": { "element": "Submit button", "ref": "s1e45" },
-  "result": "Clicked",
-  "duration": 234
-}
-```
-
-Events are saved to `{sessionPath}/{nodeName}/events.json` and used by:
-- The **action timeline** in the Zibby dashboard
-- The **generate_script** node to produce accurate Playwright scripts
-- The **memory** system to record selector usage
-
-## CLI Options
-
-| Flag | Default | Description |
-|---|---|---|
-| `--save-video=WxH` | — | Record video at specified resolution |
-| `--viewport-size=WxH` | `1280x720` | Browser viewport size |
-| `--output-dir=PATH` | `test-results/` | Where to save video and event files |
-| `--headed` | `false` | Show the browser window |
-| `--headless` | `true` | Run without a visible window |

package/docs/packages/mcp-cli.md

@@ -1,176 +0,0 @@
----
-sidebar_position: 7
-title: "@zibby/mcp-cli"
----
-
-# @zibby/mcp-cli
-
-A Model Context Protocol (MCP) server that exposes the Zibby CLI surface — deploy, run, debug, trigger — to any MCP-aware AI agent. Install once, drive Zibby from Claude Code / Cursor / OpenAI Codex / Gemini CLI / Continue / Cline / Aider / Goose without leaving chat.
-
-```bash
-# Not installed manually — the agent's `npx` invocation handles it.
-# See "Install" below for per-agent config.
-```
-
-## What it exposes
-
-13 MCP tools, all wrapping the underlying `@zibby/cli`:
-
-| Tool | What it does |
-|---|---|
-| `zibby_login` | Opens the user's browser for device-code OAuth. Saves session to `~/.zibby/config.json`. |
-| `zibby_logout` | Clears the saved session. |
-| `zibby_status` | Who is logged in, how many projects are cached, whether the session is still valid. |
-| `zibby_list_projects` | List the Zibby projects the user has access to. |
-| `zibby_list_templates` | List official agent templates (browser-test-automation, code-analysis, generate-test-cases, …). |
-| `zibby_scaffold_agent` | Scaffold `.zibby/workflows/<name>/` from an official template. |
-| `zibby_validate_agent` | Static-check a local agent (~30 ms, no API call). |
-| `zibby_list_agents` | List agents: local, remote, or both. |
-| `zibby_deploy_agent` | Deploy a local agent to a project. |
-| `zibby_trigger_agent` | Trigger a deployed agent by UUID. Returns `jobId`. |
-| `zibby_agent_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
-| `zibby_run_agent_local` | Run an agent on the user's machine one-shot, for debugging. No cloud. |
-| `zibby_download_agent` | Pull a deployed agent back to local. Requires explicit `confirm: true` from the agent. |
-
-**Destructive operations are intentionally not exposed.** Agent deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.
-
-## Install
-
-`@zibby/mcp-cli` ships as a stdio MCP server. The agent's host process spawns it via `npx -y` — no global install needed. The user just needs **Node.js ≥ 18** on their machine.
-
-### Claude Code
-
-`~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### Cursor
-
-`~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### OpenAI Codex CLI
-
-`~/.codex/config.toml`:
-
-```toml
-[mcp_servers.zibby]
-command = "npx"
-args = ["-y", "@zibby/mcp-cli"]
-```
-
-### Gemini CLI
-
-`~/.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### Claude Desktop (macOS)
-
-`~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "zibby": {
-      "command": "npx",
-      "args": ["-y", "@zibby/mcp-cli"]
-    }
-  }
-}
-```
-
-### Windows
-
-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"]
-    }
-  }
-}
-```
-
-## A typical agent chat
-
-```
-User:  Deploy the browser-test template to my "playhouse" project.
-Agent: → zibby_list_projects
-       → zibby_scaffold_agent (browser-test-automation → .zibby/workflows/playhouse-tests/)
-       → zibby_validate_agent
-       → zibby_deploy_agent
-       → "Deployed v1 of playhouse-tests. UUID 988…"
-
-User:  Run it against staging.zibby.dev.
-Agent: → zibby_trigger_agent (input: { url: "https://staging.zibby.dev" })
-       → zibby_agent_logs (lines: 200, jobId: "abc-123")
-       → "Run completed. Found 0 errors."
-```
-
-## Auth model
-
-Two-stage by design (mirrors how the `zibby` CLI works):
-
-1. **Session token** (`zibby_login`) — device-code OAuth via browser. Identifies the user.
-2. **Per-project API tokens** — fetched at login time and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_agent`.
-
-All credentials live in `~/.zibby/config.json` (mode `0600`). The same file `zibby login` writes — so if you've already done `zibby login` from a terminal, the MCP server picks up that session.
-
-The user's password never touches the MCP server: login is OAuth in the browser, and only the resulting session token comes back to the local file.
-
-## Security guarantees
-
-- **No shell interpolation** — every CLI invocation uses `execFile` with argv arrays.
-- **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` reach the child CLI process.
-- **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only, read server-side per call.
-- **Destructive ops excluded** — see the table above.
-- **`zibby_download_agent` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.
-
-## Troubleshooting
-
-| Problem | Likely cause |
-|---|---|
-| `Not logged in` on every call | `~/.zibby/config.json` missing or corrupted. Call `zibby_login`. |
-| `No API token cached for project` | Project list out of date. Call `zibby_list_projects` to refresh. |
-| `npx -y` hangs on first install | First-time download. Subsequent invocations are cached by npm. |
-| Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal to see live output. |
-
-## Versioning
-
-`@zibby/mcp-cli` pins a specific `@zibby/cli` version in its `dependencies`. Upgrading the MCP package upgrades the bundled CLI in lockstep. Users get the right CLI automatically — no need to coordinate two installs.
-
-## Source
-
-[github.com/ZibbyHQ/zibby-agent → packages/mcps/cli](https://github.com/ZibbyHQ/zibby-agent/tree/main/packages/mcps/cli)