@zibby/skills 0.1.8 → 0.1.9

package/docs/custom-workflows.md

@@ -0,0 +1,358 @@
+---
+sidebar_position: 5
+title: Custom Workflows
+---
+
+# Custom Workflows
+
+Build, test, and deploy your own AI workflows using Zibby's graph-based framework. Custom workflows let you define multi-step AI pipelines that run locally or in Zibby Cloud, triggered via API or subdomain URL.
+
+## Quick Start
+
+```bash
+# 1. Scaffold a new workflow
+zibby g workflow ticket-triage
+
+# 2. Test locally
+zibby start ticket-triage
+
+# 3. Deploy to cloud
+zibby deploy ticket-triage --project <project-id>
+
+# 4. Trigger via API
+curl -X POST https://ticket-triage-6af9.workflows.zibby.app \
+  -H "Authorization: Bearer $ZIBBY_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"ticket": "BUG-123"}}'
+
+# 5. Tail logs
+zibby logs --workflow ticket-triage --project <project-id>
+```
+
+## Scaffolding
+
+```bash
+zibby g workflow <name>
+```
+
+If you omit the name, Zibby generates a random one (like Heroku app names).
+
+This creates:
+
+```
+.zibby/workflows/<name>/
+├── graph.mjs          # Workflow class (entry point)
+├── nodes/
+│   ├── index.mjs      # Barrel export
+│   └── example.mjs    # Starter node with prompt + schema
+└── workflow.json       # Manifest (metadata, triggers)
+```
+
+### Workflow Structure
+
+**`graph.mjs`** — Defines the workflow class that extends `WorkflowAgent`:
+
+```javascript
+import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
+import { exampleNode } from './nodes/index.mjs';
+
+export class TicketTriageWorkflow extends WorkflowAgent {
+  buildGraph() {
+    const graph = new WorkflowGraph();
+
+    graph.addNode('example', exampleNode);
+    graph.setEntryPoint('example');
+    graph.addEdge('example', 'END');
+
+    return graph;
+  }
+
+  async onComplete(result) {
+    console.log(`Workflow complete — success: ${result.success !== false}`);
+  }
+}
+```
+
+**`nodes/example.mjs`** — Each node has a prompt function and a Zod output schema:
+
+```javascript
+import { z } from '@zibby/core';
+
+const ExampleOutputSchema = z.object({
+  summary: z.string().describe('A short summary of the result'),
+  status: z.enum(['ok', 'warn', 'error']).describe('Overall status'),
+});
+
+export const exampleNode = {
+  name: 'example',
+  prompt: (state) => `You are a helpful workflow node.
+
+Input:
+${JSON.stringify(state.input || {}, null, 2)}
+
+Analyze the input and return a summary with a status.`,
+  outputSchema: ExampleOutputSchema,
+};
+```
+
+**`workflow.json`** — Manifest with metadata:
+
+```json
+{
+  "name": "ticket-triage",
+  "triggers": { "api": true }
+}
+```
+
+## Adding Nodes
+
+Create a new file in `nodes/` and wire it into the graph:
+
+```javascript
+// nodes/classify.mjs
+import { z } from '@zibby/core';
+
+const ClassifySchema = z.object({
+  priority: z.enum(['critical', 'high', 'medium', 'low']),
+  category: z.string(),
+  assignTo: z.string().optional(),
+});
+
+export const classifyNode = {
+  name: 'classify',
+  prompt: (state) => `Given this ticket summary:
+${state.example.summary}
+
+Classify the priority, category, and suggested assignee.`,
+  outputSchema: ClassifySchema,
+};
+```
+
+Then add it to `graph.mjs`:
+
+```javascript
+import { classifyNode } from './nodes/classify.mjs';
+
+// In buildGraph():
+graph.addNode('classify', classifyNode);
+graph.addEdge('example', 'classify');  // instead of example → END
+graph.addEdge('classify', 'END');
+```
+
+### Conditional Edges
+
+Route to different nodes based on output:
+
+```javascript
+graph.addConditionalEdges('classify', (state) => {
+  return state.classify.priority === 'critical' ? 'escalate' : 'notify';
+});
+```
+
+## Local Development
+
+### Start a dev server
+
+```bash
+zibby start ticket-triage
+zibby start ticket-triage --port 3850
+```
+
+This starts a local HTTP server that loads your workflow and exposes a trigger endpoint:
+
+```bash
+curl -X POST http://localhost:3848/trigger \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"ticket": "BUG-456"}}'
+```
+
+The dev server uses your local `.zibby.config.mjs` for agent configuration (model, API keys, etc.) — the same config used by `zibby test`.
+
+## Deploying to Cloud
+
+### Prerequisites
+
+1. **Authenticated**: Run `zibby login` (or set `ZIBBY_API_KEY`)
+2. **Project**: Have a project ID (run `zibby list` to see yours)
+
+### Deploy
+
+```bash
+zibby deploy ticket-triage --project <project-id>
+```
+
+This:
+1. Loads and serializes the workflow graph
+2. Bundles all source files (`.mjs`, `.js`, `.json`)
+3. Uploads to Zibby Cloud
+4. Registers a unique subdomain
+
+Output:
+
+```
+  Workflow "ticket-triage" deployed to version 1
+
+  Trigger URL (API):
+    POST https://api-prod.zibby.app/projects/<id>/workflows/ticket-triage/trigger
+
+  Trigger URL (subdomain):
+    POST https://ticket-triage-6af9.workflows.zibby.app
+
+  Tail logs:
+    zibby logs <jobId> --project <id>
+```
+
+### Subdomain URLs
+
+Each deployed workflow gets a globally unique subdomain:
+
+```
+https://<workflow-name>-<hash>.workflows.zibby.app
+```
+
+The hash is a short (4-char) deterministic suffix derived from your project ID, ensuring uniqueness across all projects.
+
+### Authentication
+
+Both trigger URLs require authentication via the `Authorization` header:
+
+- **JWT token** — from `zibby login` session
+- **Personal Access Token (PAT)** — from your project settings (`zby_xxx`)
+
+```bash
+curl -X POST https://ticket-triage-6af9.workflows.zibby.app \
+  -H "Authorization: Bearer zby_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"ticket": "BUG-789"}}'
+```
+
+### How Cloud Execution Works
+
+When triggered, the workflow runs in an isolated ECS Fargate container:
+
+1. Lambda receives the trigger request
+2. Workflow sources are loaded from DynamoDB and uploaded to S3
+3. A Fargate task is launched with the workflow code
+4. The container downloads sources, rebuilds the graph, and executes it
+5. Agent configuration (model, API keys) comes from your project settings
+
+Each run is fully isolated — no shared state between runs.
+
+## Cloning Repositories
+
+Custom workflows can clone your project's configured repositories using the `cloneRepo()` helper:
+
+```javascript
+import { cloneRepo } from '@zibby/core';
+
+// In a node's preProcess function
+const repoPaths = await cloneRepo();
+// Returns: { 'myorg/backend': '/workspace/repos/myorg-backend', ... }
+```
+
+This gives your workflow access to your actual codebase for analysis, testing, or deployment tasks.
+
+**[See the full Cloning Repositories guide →](./cloning-repositories.md)**
+
+## Tailing Logs
+
+### Tail a specific job
+
+The trigger API returns a `jobId`. Use it to tail logs:
+
+```bash
+zibby logs <jobId> --project <project-id>
+```
+
+### Tail the latest run
+
+```bash
+zibby logs --workflow ticket-triage --project <project-id>
+```
+
+This lists recent runs and automatically tails the latest one.
+
+### All runs (interleaved)
+
+```bash
+zibby logs --workflow ticket-triage --all --project <project-id>
+```
+
+Shows logs from all past runs of the workflow, sorted chronologically with job ID separators:
+
+```
+  ── wfj-1713157331-a3 ──
+2026-04-15 14:02:11  🚀 Starting ticket-triage workflow...
+2026-04-15 14:02:18  ✅ Workflow complete
+
+  ── wfj-1713157522-b7 ──
+2026-04-15 14:05:22  🚀 Starting ticket-triage workflow...
+2026-04-15 14:05:30  Running node: example
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--project <id>` | Project ID (or `ZIBBY_PROJECT_ID` env) |
+| `--workflow <name>` | Workflow name (tails latest run) |
+| `--all` | Interleaved logs from all runs (requires `--workflow`) |
+| `--no-follow` | Fetch logs once, don't stream |
+| `--lines <n>` | Max lines per fetch (default: 200) |
+
+## Agent Configuration
+
+### Local
+
+Local execution uses your `.zibby.config.mjs`:
+
+```javascript
+export default {
+  agent: {
+    cursor: { model: 'auto' },
+    // claude: { model: 'sonnet-4.6' },
+  },
+};
+```
+
+API keys come from environment variables (`CURSOR_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`).
+
+### Cloud
+
+Cloud execution uses your **project settings** (configured in the Zibby dashboard):
+
+- **AI Agent** — which agent to use (Cursor, Claude, Codex, Gemini)
+- **Model** — model override
+- **API Key** — stored encrypted, injected into the container at runtime
+
+No config files are needed in the cloud — everything is read from project settings.
+
+## Self-Hosting
+
+You can run workflows on your own infrastructure without Zibby Cloud. Your server just needs:
+
+1. `@zibby/core` and `@zibby/cli` npm packages
+2. Environment variables for agent configuration:
+
+```bash
+AGENT_TYPE=cursor          # or claude, codex, gemini
+MODEL=auto
+CURSOR_API_KEY=sk-xxx      # or ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY
+```
+
+Then trigger the workflow programmatically:
+
+```javascript
+import { WorkflowGraph } from '@zibby/core';
+import { TicketTriageWorkflow } from './.zibby/workflows/ticket-triage/graph.mjs';
+
+const agent = new TicketTriageWorkflow();
+const graph = agent.buildGraph();
+const result = await graph.run(agent, { input: { ticket: 'BUG-123' } });
+```
+
+Or use the CLI:
+
+```bash
+zibby start ticket-triage --port 8080
+```

package/docs/getting-started.md

@@ -0,0 +1,108 @@
+---
+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

@@ -0,0 +1,127 @@
+---
+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/`.

package/docs/integrations/github.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 1
+title: GitHub Integration
+---
+
+# GitHub Integration
+
+Connect your GitHub repositories so Zibby can analyze your codebase and create pull requests from AI-generated code.
+
+## How It Works
+
+Zibby uses a **GitHub App** to access your repositories. The app requests read access to your code and write access to create pull requests.
+
+When you run an analysis, Zibby:
+
+1. Clones the repository into a secure container
+2. Analyzes the codebase alongside the Jira ticket
+3. Generates code changes as a diff
+4. Optionally creates a pull request with the suggested changes
+
+## Connect GitHub
+
+1. Go to your project's **Settings** page in the Zibby dashboard
+2. Under **Integrations**, click **Connect GitHub**
+3. You'll be redirected to GitHub to install the Zibby App
+4. Select the repositories you want to grant access to
+5. Click **Install & Authorize**
+6. You'll be redirected back to Zibby
+
+## Permissions
+
+The Zibby GitHub App requests:
+
+| Permission | Level | Purpose |
+|---|---|---|
+| Repository contents | Read | Clone and analyze your code |
+| Pull requests | Write | Create PRs from generated code |
+| Metadata | Read | List repositories |
+
+## Select Repositories
+
+After connecting, go to **Settings > Repositories** to select which repos are available for analysis. You can choose:
+
+- **Primary repository** — the main codebase for analysis
+- **Additional repositories** — supporting repos that provide context
+
+## Creating Pull Requests
+
+After an analysis generates code changes:
+
+1. Go to the **Analysis** page for the ticket
+2. Review the code diff in the **Code Changes** tab
+3. Click **Create Pull Request**
+4. Zibby creates a PR on your repository with the suggested changes
+5. Review and merge through your normal GitHub workflow
+
+## Token Management
+
+Zibby uses GitHub App installation tokens that automatically refresh. You don't need to manage tokens manually. If you need to reconnect:
+
+1. Go to **Settings > Integrations**
+2. Click **Disconnect** next to GitHub
+3. Click **Connect GitHub** to re-authorize
+
+## Troubleshooting
+
+**"Repository not found" during analysis**
+
+Make sure the repository is selected in your project settings and the GitHub App has access to it.
+
+**"Permission denied" when creating PR**
+
+Verify the GitHub App installation has write access to pull requests for the target repository.