@zibby/skills 0.2.22 → 0.2.24

package/docs/packages/memory.md

@@ -1,223 +0,0 @@
----
-sidebar_position: 3
-title: "@zibby/memory"
----
-
-# @zibby/memory
-
-Version-controlled test memory database powered by [Dolt](https://www.dolthub.com/). Learns from every test run — selectors that worked, pages that were visited, patterns that failed, workarounds that helped.
-
-```bash
-npm install @zibby/memory
-```
-
-## Why Memory?
-
-Without memory, every test run starts from scratch. The AI has no idea which selectors are stable, which pages have changed, or what workarounds were discovered in previous runs.
-
-With `@zibby/memory`:
-- **Selectors** — the AI knows which CSS/XPath selectors are reliable and which are flaky
-- **Page models** — the AI has a map of page elements, roles, and structure before it even navigates
-- **Navigation patterns** — the AI knows which URL transitions are valid
-- **Test history** — the AI sees pass/fail trends and avoids repeating past failures
-- **Insights** — the AI reads and writes tips (timing quirks, workarounds, selector alternatives)
-
-## Setup
-
-### 1. Install Dolt
-
-Dolt is a version-controlled SQL database (Git for data):
-
-```bash
-# macOS
-brew install dolt
-
-# Linux
-sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
-```
-
-### 2. Initialize Memory Database
-
-```bash
-zibby init --mem
-```
-
-This creates a Dolt database at `.zibby/memory/` with the schema for test runs, selectors, page models, navigation, and insights.
-
-### 3. Enable Memory in Your Workflow
-
-Add `SKILLS.MEMORY` to any node that should have memory access:
-
-```javascript
-import { SKILLS } from '@zibby/core';
-
-export const executeLiveNode = {
-  name: 'execute_live',
-  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
-  // ...
-};
-```
-
-The built-in `execute_live` node already has memory enabled by default.
-
-## How It Works
-
-### During a Test Run
-
-1. **Before execution** — the memory middleware loads relevant history:
-   - Previous runs for this spec (pass/fail, timing)
-   - Known selectors for the target pages
-   - Saved insights and tips
-
-2. **During execution** — the AI can call memory tools:
-   - `memory_get_selectors` to find stable selectors
-   - `memory_get_page_model` to understand page structure
-   - `memory_save_insight` to record a finding
-
-3. **After execution** — the result handler persists new data:
-   - Test result (pass/fail, duration)
-   - Selectors used and their success/failure
-   - Page model updates
-   - Navigation transitions discovered
-
-### Version Control
-
-Every persist operation creates a Dolt commit. You can:
-
-```bash
-# View memory history
-cd .zibby/memory
-dolt log
-
-# Diff between runs
-dolt diff HEAD~1 HEAD
-
-# Branch for experiments
-dolt branch experiment
-dolt checkout experiment
-```
-
-## Database Schema
-
-### `test_runs`
-
-| Column | Type | Description |
-|---|---|---|
-| `session_id` | VARCHAR | Unique session identifier |
-| `spec_path` | VARCHAR | Path to the test spec file |
-| `passed` | BOOLEAN | Whether the test passed |
-| `duration_ms` | INT | Total execution time |
-| `agent_type` | VARCHAR | Which agent ran the test |
-| `created_at` | DATETIME | Timestamp |
-
-### `selectors`
-
-| Column | Type | Description |
-|---|---|---|
-| `page_url` | VARCHAR | URL where this selector was used |
-| `selector` | VARCHAR | The CSS/XPath selector string |
-| `stable_id` | VARCHAR | Zibby stable ID (if available) |
-| `success_count` | INT | Times this selector worked |
-| `fail_count` | INT | Times this selector failed |
-| `last_used` | DATETIME | Last usage timestamp |
-
-### `page_model`
-
-| Column | Type | Description |
-|---|---|---|
-| `url` | VARCHAR | Page URL |
-| `element_role` | VARCHAR | ARIA role |
-| `element_name` | VARCHAR | Accessible name |
-| `selector` | VARCHAR | Best known selector |
-| `updated_at` | DATETIME | Last update |
-
-### `navigation`
-
-| Column | Type | Description |
-|---|---|---|
-| `from_url` | VARCHAR | Source page URL |
-| `to_url` | VARCHAR | Destination page URL |
-| `trigger` | VARCHAR | What caused the navigation (click, submit, etc.) |
-| `count` | INT | Times this transition was observed |
-
-### `insights`
-
-| Column | Type | Description |
-|---|---|---|
-| `category` | ENUM | `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |
-| `content` | TEXT | The insight text |
-| `spec_path` | VARCHAR | Related spec |
-| `session_id` | VARCHAR | Session that created it |
-| `created_at` | DATETIME | Timestamp |
-
-## MCP Tools
-
-The memory MCP server exposes five tools:
-
-```
-memory_get_test_history   — Query recent test runs (filter by spec path)
-memory_get_selectors      — Query selectors with stability metrics (filter by page URL)
-memory_get_page_model     — Query page elements and roles (filter by URL)
-memory_get_navigation     — Query page-to-page transitions (filter by source URL)
-memory_save_insight       — Save a useful observation for future runs
-```
-
-### Example: AI Querying Memory
-
-During execution, the AI might call:
-
-```json
-{
-  "tool": "memory_get_selectors",
-  "input": { "pageUrl": "myapp.com/login", "limit": 10 }
-}
-```
-
-And receive:
-
-```json
-[
-  { "selector": "[data-testid='email']", "success_count": 12, "fail_count": 0 },
-  { "selector": "#login-email", "success_count": 8, "fail_count": 3 },
-  { "selector": "input[name='email']", "success_count": 5, "fail_count": 1 }
-]
-```
-
-The AI then prefers `[data-testid='email']` because it has the highest success rate.
-
-## Middleware Integration
-
-Memory provides automatic middleware that injects history into the node context:
-
-```javascript
-import { createMemoryMiddleware } from '@zibby/memory';
-
-const middleware = createMemoryMiddleware();
-
-const graph = new WorkflowGraph({ middleware: [middleware] });
-```
-
-The memory skill registers this middleware automatically when `SKILLS.MEMORY` is declared on a node.
-
-## CLI Commands
-
-```bash
-# Initialize memory database
-zibby init --mem
-
-# View memory stats
-zibby memory status
-
-# Sync memory (push to Dolt remote)
-zibby memory sync
-```
-
-## Exports
-
-```javascript
-import {
-  createMemoryMiddleware,
-  memoryEndRun,
-  memorySyncPush,
-} from '@zibby/memory';
-```

package/docs/packages/skills.md

@@ -1,218 +0,0 @@
----
-sidebar_position: 2
-title: "@zibby/skills"
----
-
-# @zibby/skills
-
-> Looking for skill-specific docs and examples? See [Skills reference](../skills/index.md).
-
-Built-in skill definitions for Zibby's test automation framework.
-
-```bash
-npm install @zibby/skills
-```
-
-> Installed automatically as a dependency of `@zibby/cli`.
-
-## What Are Skills?
-
-A **skill** is a declarative description of an MCP (Model Context Protocol) server and the tools it exposes. Skills are the bridge between your agent nodes and external capabilities like browser automation, Jira, GitHub, Slack, and test memory.
-
-Skills are **agent-agnostic** — the same skill definition works across Cursor, Claude, and Codex. The framework resolves the skill into the right MCP configuration for whichever agent is active.
-
-## Built-in Skills
-
-| Skill ID | MCP Server | Tools Provided |
-|---|---|---|
-| `browser` | `@zibby/mcp-browser` / `@playwright/mcp` | Browser navigation, clicking, typing, snapshots, video |
-| `memory` | `@zibby/mcp-memory` | Test history, selector stability, page model, save insights |
-| `jira` | `@zibby/mcp-jira` | Read/write Jira tickets |
-| `github` | GitHub MCP server | Repository access, PR creation |
-| `slack` | Slack MCP server | Send notifications, post results |
-
-## Using Skills in Nodes
-
-Declare skills in a node definition:
-
-```javascript
-import { SKILLS } from '@zibby/core';
-
-export const executeLiveNode = {
-  name: 'execute_live',
-  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
-  prompt: (state) => `Execute the test: ${state.testSpec}`,
-  outputSchema: ExecutionSchema,
-};
-```
-
-When the agent runs:
-1. The framework reads the node's `skills` array
-2. For each skill, calls `skill.resolve()` to get the MCP server config
-3. Injects the resolved MCP server into the agent's environment
-4. Appends the skill's `promptFragment` to the prompt (if defined)
-5. Runs skill middleware (if defined)
-
-## Skill Anatomy
-
-Every skill has this shape:
-
-```javascript
-{
-  id: 'browser',                           // Unique identifier
-  type: 'mcp',                             // 'mcp' or 'function'
-  serverName: 'playwright',                // MCP server name
-  allowedTools: ['mcp__playwright__*'],     // Tool patterns for Claude SDK
-  cursorKey: 'playwright-official',         // Key in ~/.cursor/mcp.json
-  sessionEnvKey: 'ZIBBY_SESSION_INFO',     // Env var with session path
-  envKeys: [],                             // Required env vars
-  description: 'Playwright Browser MCP',
-
-  // Prompt text appended to every node that uses this skill
-  promptFragment: 'Execute using browser tools...',
-
-  // Returns MCP server config { command, args, env }
-  resolve({ sessionPath, workspace }) {
-    return {
-      command: 'node',
-      args: ['/path/to/mcp-server.js', '--output-dir', sessionPath],
-    };
-  },
-
-  // Optional: middleware factory (called once per graph run)
-  async middleware() {
-    return async (nodeName, next, stateValues, state) => {
-      // Pre-node logic (e.g., load test history)
-      const result = await next();
-      // Post-node logic (e.g., persist insights)
-      return result;
-    };
-  },
-
-  // Tool schemas for compile-time validation
-  tools: [
-    { name: 'tool_name', description: '...', input_schema: { ... } }
-  ],
-}
-```
-
-## Creating Custom Skills
-
-### MCP Skill (wraps an external MCP server)
-
-```javascript
-import { skill } from '@zibby/skills';
-
-export const linear = skill('linear', {
-  description: 'Linear issue tracker',
-  serverName: 'linear',
-  allowedTools: ['mcp__linear__*'],
-  envKeys: ['LINEAR_API_KEY'],
-  resolve() {
-    if (!process.env.LINEAR_API_KEY) return null;
-    return {
-      command: 'npx',
-      args: ['-y', '@anthropic/linear-mcp-server'],
-      env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY },
-    };
-  },
-});
-```
-
-Use it in a node:
-
-```javascript
-graph.addNode('create_issue', {
-  name: 'create_issue',
-  skills: ['linear'],
-  prompt: (state) => `Create a Linear issue for: ${state.bugReport}`,
-  outputSchema: IssueSchema,
-});
-```
-
-### Function Skill (single tool, auto-bridged to MCP)
-
-For simple tools that don't need a full MCP server:
-
-```javascript
-import { skill } from '@zibby/skills';
-
-export const calculator = skill('calculator', {
-  description: 'Perform arithmetic calculations',
-  input: {
-    expression: 'string',
-  },
-  handler: async ({ expression }) => {
-    const result = eval(expression); // simplified example
-    return { result: String(result) };
-  },
-});
-```
-
-The framework automatically spawns a lightweight MCP bridge server for function skills at runtime.
-
-### Skill with Middleware
-
-Middleware runs before and after every node that uses the skill:
-
-```javascript
-import { skill } from '@zibby/skills';
-
-export const audit = skill('audit', {
-  description: 'Audit logging',
-  resolve() { return null; }, // No MCP server needed
-  async middleware() {
-    return async (nodeName, next, stateValues, state) => {
-      console.log(`[audit] Node ${nodeName} starting`);
-      const startTime = Date.now();
-      const result = await next();
-      console.log(`[audit] Node ${nodeName} completed in ${Date.now() - startTime}ms`);
-      return result;
-    };
-  },
-});
-```
-
-## Browser Skill Details
-
-The browser skill resolves to `@zibby/mcp-browser` if installed, otherwise falls back to `@playwright/mcp`:
-
-```javascript
-// Resolution priority:
-// 1. MCP_BROWSER_PATH env var
-// 2. @zibby/mcp-browser (enhanced: stable IDs, event recording)
-// 3. @playwright/mcp (community fallback)
-```
-
-Default configuration:
-- Video resolution: 1280x720
-- Viewport: 1280x720
-- Output directory: session path or `test-results/`
-
-## Memory Skill Details
-
-The memory skill provides five tools:
-
-| Tool | Description |
-|---|---|
-| `memory_get_test_history` | Query recent test runs with pass/fail results |
-| `memory_get_selectors` | Query known selectors with stability metrics |
-| `memory_get_page_model` | Query page structure — elements, roles, selectors |
-| `memory_get_navigation` | Query known page-to-page transitions |
-| `memory_save_insight` | Save observations for future runs (selector tips, timing, workarounds) |
-
-The memory skill also includes middleware that automatically loads relevant test history before node execution.
-
-## Exports
-
-```javascript
-import { SKILLS } from '@zibby/skills';
-// SKILLS.BROWSER, SKILLS.JIRA, SKILLS.GITHUB, SKILLS.SLACK, SKILLS.MEMORY
-
-import { browserSkill, jiraSkill, githubSkill, slackSkill, memorySkill } from '@zibby/skills';
-
-import { skill, functionSkill } from '@zibby/skills';
-
-// Re-exported from @zibby/core
-import { registerSkill, getSkill, hasSkill, getAllSkills, listSkillIds } from '@zibby/skills';
-```

package/docs/packages/ui-memory.md

@@ -1,245 +0,0 @@
----
-sidebar_position: 5
-title: "@zibby/ui-memory"
----
-
-# @zibby/ui-memory
-
-Version-controlled UI agent memory powered by [Dolt](https://www.dolthub.com/). Learns from every test run — selectors that worked, page-element fingerprints, navigation transitions, timing quirks, recorded insights. Used today by `zibby test`; designed to power any agent that drives a UI.
-
-```bash
-npm install @zibby/ui-memory
-```
-
-Current version: **1.1.0**
-
-> Renamed from `@zibby/memory` to make the per-domain UI focus explicit. This package is the **UI test-memory** store (Dolt-backed, per-domain). For chat-style agent memory — facts, decisions, task history — see the [Chat memory skill](../skills/chat-memory.md), which defaults to a **mem0** semantic backend (with automatic fallback to Dolt) and can be pinned to Dolt explicitly.
-
-## Why memory
-
-Without memory, every test run starts from scratch. The agent has no idea which selectors are stable, which pages have changed, or what workarounds were discovered last week.
-
-With `@zibby/ui-memory`:
-
-- **Selectors** — the agent prefers selectors with high success / low fail counts
-- **Page model** — known elements, ARIA roles, accessible names
-- **Navigation** — known page-to-page transitions (which click produced which URL)
-- **Test history** — pass/fail trends per spec, full timing
-- **Insights** — categorized free-form notes the agent reads + writes (`selector_tip | timing | navigation | workaround | flaky | general`)
-
-Critically, memory is keyed **per domain**, not per spec. A selector that one spec learned for `myapp.com/login` is available to every other spec hitting the same site.
-
-## Setup
-
-Most users get this automatically via `zibby init` — Dolt is bundled, the DB is initialized, and `zibby test` writes to it. The notes below are for direct package consumption.
-
-### 1. Install Dolt (if not bundled)
-
-```bash
-# macOS
-brew install dolt
-
-# Linux
-sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
-```
-
-### 2. Initialize the database
-
-```bash
-zibby memory init
-```
-
-Creates `.zibby/memory/.dolt/` with the schema for runs, selectors, page model, navigation, and insights.
-
-### 3. Enable memory in your agent
-
-Add `SKILLS.MEMORY` to any node that should have memory access:
-
-```javascript
-import { SKILLS } from '@zibby/core';
-
-export const executeLiveNode = {
-  name: 'execute_live',
-  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
-  // ...
-};
-```
-
-The built-in `execute_live` node already has memory enabled.
-
-## How it works
-
-### Before each run
-
-The runner auto-pulls from the configured remote (if any) and loads the relevant slice into the agent's context — selectors for the page, recent failures, applicable insights.
-
-### During the run
-
-The agent has 5 MCP tools auto-exposed:
-
-| Tool | What it does |
-|---|---|
-| `memory_get_test_history` | Recent runs — filter by spec-path substring; returns pass/fail/timing |
-| `memory_get_selectors` | Known selectors per page with success/fail counts |
-| `memory_get_page_model` | Page elements (URL, ARIA role, accessible name, best selector) |
-| `memory_get_navigation` | Known transitions (from URL → to URL via what trigger) |
-| `memory_save_insight` | Save observation: `selector_tip | timing | navigation | workaround | flaky | general` |
-
-### After the run
-
-The result handler persists the new state — selectors used (with success/failure deltas), page-model updates, new navigation transitions discovered, and any insights the agent saved.
-
-> **The agent is required to call `memory_save_insight` at least once at the end of every run.** This is in the memory skill's prompt fragment. Without insights, memory degrades to cached selectors and run rows; with them it compounds.
-
-### Version control
-
-Every persist creates a Dolt commit. You can:
-
-```bash
-cd .zibby/memory
-dolt log
-dolt diff HEAD~1 HEAD
-dolt branch experiment
-dolt checkout experiment
-```
-
-## Database schema
-
-### `test_runs`
-
-| Column | Type | Description |
-|---|---|---|
-| `session_id` | VARCHAR | Unique session identifier |
-| `spec_path` | VARCHAR | Path to the test spec file |
-| `passed` | BOOLEAN | Whether the test passed |
-| `duration_ms` | INT | Total execution time |
-| `agent_type` | VARCHAR | Which agent ran the test |
-| `tokens_input` / `tokens_output` / `tokens_cache_*` | INT | LLM token usage (drives `zibby memory cost`) |
-| `created_at` | DATETIME | Timestamp |
-
-### `selectors`
-
-| Column | Type | Description |
-|---|---|---|
-| `page_url` | VARCHAR | URL where this selector was used |
-| `selector` | VARCHAR | The CSS/XPath selector string |
-| `stable_id` | VARCHAR | Zibby stable ID (if available) |
-| `success_count` | INT | Times this selector worked |
-| `fail_count` | INT | Times this selector failed |
-| `last_used` | DATETIME | Last usage timestamp |
-
-### `page_model`
-
-| Column | Type | Description |
-|---|---|---|
-| `url` | VARCHAR | Page URL |
-| `element_role` | VARCHAR | ARIA role |
-| `element_name` | VARCHAR | Accessible name |
-| `selector` | VARCHAR | Best known selector |
-| `updated_at` | DATETIME | Last update |
-
-### `navigation`
-
-| Column | Type | Description |
-|---|---|---|
-| `from_url` | VARCHAR | Source page URL |
-| `to_url` | VARCHAR | Destination page URL |
-| `trigger` | VARCHAR | What caused the navigation (click, submit, etc.) |
-| `count` | INT | Times this transition was observed |
-
-### `insights`
-
-| Column | Type | Description |
-|---|---|---|
-| `category` | ENUM | `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |
-| `content` | TEXT | The insight text |
-| `spec_path` | VARCHAR | Related spec |
-| `session_id` | VARCHAR | Session that created it |
-| `created_at` | DATETIME | Timestamp |
-
-## Team sync
-
-Memory is local-first. Opt into a shared remote so teammates' learnings flow back:
-
-```bash
-# BYO — your S3 / GCS / DoltHub repo / file path
-zibby memory remote add aws://my-bucket/team/proj/main
-zibby memory remote add gs://bucket/team/proj/main
-zibby memory remote add https://www.dolthub.com/repositories/<owner>/<repo>
-zibby memory remote add file:///abs/path/to/local-shared
-
-# OR Zibby-managed S3 (no plumbing; signed-in users only)
-zibby memory remote use --hosted
-```
-
-Once configured:
-
-- `zibby test` auto-pulls before runs and auto-pushes after passing runs
-- `zibby memory pull` / `zibby memory push` for manual override
-- `zibby memory remote info` to inspect, `zibby memory remote remove` to disconnect
-
-To wire teammates in automatically, set `memorySync.remote` in `.zibby.config.mjs`:
-
-```js
-export default {
-  agent: { claude: { model: 'auto' } },
-  memorySync: {
-    remote: 'hosted',                          // or 'aws://my-bucket/team/proj/main' or null
-  },
-};
-```
-
-`zibby init` reads this — when set to `'hosted'` and the user isn't signed in, init prompts for `zibby login` but never blocks. After login, the remote is wired and the next `zibby test` pulls.
-
-### Hosted vs BYO
-
-| | Hosted (`--hosted`) | BYO |
-|---|---|---|
-| Setup | `zibby memory remote use --hosted` | Provision bucket / IAM / KMS |
-| Storage | Zibby-managed AWS account | Your account |
-| Access | Anyone with project access on Zibby | Whoever your IAM grants |
-| Compliance / data residency | Limited regions | Wherever you want |
-| Cost | Included in plan | Your S3 bill |
-
-## Middleware integration
-
-Memory provides automatic middleware that injects history into the node context:
-
-```javascript
-import { createMemoryMiddleware } from '@zibby/ui-memory';
-
-const middleware = createMemoryMiddleware();
-const graph = new WorkflowGraph({ middleware: [middleware] });
-```
-
-The memory skill registers this middleware automatically when `SKILLS.MEMORY` is declared on a node.
-
-## CLI commands
-
-```bash
-zibby memory init               # initialize the DB
-zibby memory stats              # row counts, last commit, per-spec breakdown
-zibby memory cost               # real LLM token spend per spec / per domain
-zibby memory compact            # prune old runs + Dolt GC
-zibby memory reset -f           # wipe (destructive)
-zibby memory pull / push        # manual sync (auto on test start/end if remote configured)
-zibby memory remote add <url>   # BYO remote
-zibby memory remote use --hosted# Zibby-managed S3
-zibby memory remote info        # show config
-zibby memory remote remove      # drop the remote
-```
-
-## Exports
-
-```javascript
-import {
-  createMemoryMiddleware,
-  memoryEndRun,
-  memorySyncPush,
-} from '@zibby/ui-memory';
-```
-
-## See also
-
-- [`zibby test` recipe](../recipes/test) — the primary consumer of memory
-- [Test memory deep dive](../tests/memory) — usage-oriented walkthrough