@zibby/skills 0.1.13 → 0.1.15

package/dist/memory.js

@@ -1,4 +1,4 @@
-import{createRequire as s}from"module";import{execFileSync as n}from"child_process";import{join as o}from"path";import{existsSync as a}from"fs";var c=s(import.meta.url);function m(){if(process.env.MCP_MEMORY_PATH)return process.env.MCP_MEMORY_PATH;try{return c.resolve("@zibby/memory/mcp-server")}catch{return null}}var d={id:"memory",serverName:"memory",allowedTools:["mcp__memory__*"],envKeys:[],description:"Zibby Memory MCP Server (test history, selectors, page model)",async middleware(){try{let{createMemoryMiddleware:e}=await import("@zibby/memory");return e()}catch{return null}},promptFragment:`BEFORE executing browser actions:
+import{createRequire as s}from"module";import{execFileSync as n}from"child_process";import{join as o}from"path";import{existsSync as a}from"fs";var c=s(import.meta.url);function m(){if(process.env.MCP_MEMORY_PATH)return process.env.MCP_MEMORY_PATH;try{return c.resolve("@zibby/ui-memory/mcp-server")}catch{return null}}var d={id:"memory",serverName:"memory",allowedTools:["mcp__memory__*"],envKeys:[],description:"Zibby Memory MCP Server (test history, selectors, page model)",async middleware(){try{let{createMemoryMiddleware:e}=await import("@zibby/ui-memory");return e()}catch{return null}},promptFragment:`BEFORE executing browser actions:
 - Review any test memory/history above. Prefer selectors proven to work.
 - If a previous run failed, avoid the same approach.
 - After setup/login completes, navigate directly to the target page instead of clicking through menus.
@@ -12,8 +12,8 @@ AFTER completing the test, you MUST call memory_save_insight at least once:
 - Category: selector_tip | timing | navigation | workaround | flaky | general
 - Be specific \u2014 future runs will read your insights.`,resolve(){let e=m();if(!e)throw new Error(`\u274C Memory MCP server not found
 
-  Install @zibby/memory:
-    npm install @zibby/memory`);let r=o(process.cwd(),".zibby","memory");if(!a(o(r,".dolt")))throw new Error(`\u274C Memory database not initialized
+  Install @zibby/ui-memory:
+    npm install @zibby/ui-memory`);let r=o(process.cwd(),".zibby","memory");if(!a(o(r,".dolt")))throw new Error(`\u274C Memory database not initialized
 
   Run:
     zibby init --mem`);try{let t=n("dolt",["sql","-q","SELECT COUNT(*) AS cnt FROM test_runs","-r","json"],{cwd:r,encoding:"utf-8",timeout:5e3}),i=JSON.parse(t.trim()).rows||[];if(!i[0]||i[0].cnt===0)return console.log("[memory] Database empty \u2014 memory tools activate after first completed run"),null}catch(t){throw new Error(`\u274C Dolt not found or memory database error

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",

package/docs/cli-reference.md

@@ -22,14 +22,23 @@ Every command lives under `zibby workflow <verb>` for consistency. The bare top-
 | [`zibby workflow start <name>`](#workflow-start) | Long-lived dev server (Studio integration). Most users want `run`. |
 | [`zibby workflow env <verb>`](#workflow-env) | Manage per-workflow encrypted env vars: `list`, `set`, `unset`, `push`. |
 
-Plus auth + admin:
+Plus the test recipe + memory + project setup:
+
+| Command | What it does |
+|---|---|
+| [`zibby test [spec]`](#test) | Run a test spec (or inline string). Drives the browser via Cursor / Claude / Codex / Gemini. |
+| [`zibby memory <verb>`](#memory) | Local + remote test-memory DB: `init`, `stats`, `cost`, `compact`, `reset`, `pull`, `push`, `remote …`. |
+| [`zibby init [project]`](#init) | Bootstrap a Zibby project (config + creds). `-t <template>` to also scaffold a workflow. |
+| [`zibby template <verb>`](#template) | List or add workflow templates: `list`, `add <name>`. |
+
+Auth + admin:
 
 | Command | What it does |
 |---|---|
 | `zibby login` | OAuth in browser. Writes session to `~/.zibby/config.json`. |
 | `zibby logout` | Clear session. |
 | `zibby status` | Show current auth state. |
-| `zibby project list` | List projects you have access to. |
+| `zibby list` | List projects + API tokens you have access to. |
 
 ## workflow new {#workflow-new}
 
@@ -176,6 +185,86 @@ zibby workflow delete <uuid>
 
 Removes the workflow from cloud (and its trigger URL). Local files are not touched.
 
+## test {#test}
+
+```bash
+zibby test [spec-path]
+zibby test "go to example.com and verify the title is 'Example Domain'"   # inline
+```
+
+Built-in browser-test recipe. Reads a `.txt` spec (or inline string), drives a real browser via the configured agent, generates a Playwright script + verification video. See [Recipes → Test](./recipes/test) for the long form.
+
+Common options:
+- `--agent <claude|cursor|codex|gemini>` — override the configured agent for this run
+- `--workflow <name>` — use a non-default workflow (e.g. `QuickSmokeWorkflow`)
+- `--headless` — run headless (default is headed)
+- `-m, --mem` — enable test memory (Dolt-backed knowledge from prior runs)
+- `--sources <ids> --execution <id>` — run cloud-stored test cases (comma-separated IDs)
+- `--node <name> --session <id|last>` — re-execute one phase from a prior session
+- `--sync` / `--no-sync` — force / skip cloud upload
+- `--collection <id|name>` and `--folder <path>` — categorize the run on the cloud dashboard
+- `--verbose` / `--debug` — escalate log levels
+- `-o, --open` — open results in browser after completion
+- `--auto-approve` — auto-approve MCP tools (CI/CD)
+
+## memory {#memory}
+
+Test memory is a local-first Dolt SQL DB at `.zibby/memory/.dolt/` that learns selectors, page model, navigation, and run history from every `zibby test` run. See [Test memory](./tests/memory) for the deeper explainer.
+
+```bash
+zibby memory init        # initialize the local DB (auto-runs on first `zibby test -m`)
+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 (default: --max-runs 50, --max-age 90)
+zibby memory reset -f    # wipe the DB
+```
+
+Optional team sync:
+
+```bash
+zibby memory remote add <url>           # BYO: aws://, gs://, https://, file:///
+zibby memory remote use --hosted        # Zibby-managed S3 (signed-in users only)
+zibby memory remote info                # show current remote
+zibby memory remote remove [name]       # drop the remote (default: origin)
+
+zibby memory pull                       # pull from remote (auto on test start when configured)
+zibby memory push                       # push to remote (auto after passing tests)
+```
+
+When `memorySync.remote` is set in `.zibby.config.mjs` (`'hosted'` or an `aws://...` URL), `zibby init` auto-wires the remote on first run — teammates clone, run init, and they're plugged in.
+
+## init {#init}
+
+```bash
+zibby init [project-name]
+zibby init -t browser-test-automation   # also scaffold the test recipe
+```
+
+Bare init by default — writes `.zibby.config.mjs`, sets up agent credentials, configures memory. Pass `-t <template>` to also scaffold a workflow template into `.zibby/`.
+
+Common options:
+- `-t, --template <name>` — workflow template to scaffold (see `zibby template list`). Default: none (config + creds only).
+- `--agent <claude|cursor|codex|gemini>` — pick the agent up front instead of prompting
+- `--memory-backend <dolt|mem0>` — memory backend (default: `dolt`; `mem0` is experimental)
+- `--skip-install` / `--skip-memory` — skip `npm install` / skip memory setup
+- `-f, --force` — overwrite existing config
+- `--api-key <key>` — non-interactive Zibby API key (for `--cloud-sync`)
+- `--cloud-sync` — enable cloud sync and install the Zibby MCP
+
+## template {#template}
+
+```bash
+zibby template list             # see what's available
+zibby template add <name>       # copy template into .zibby/ (overwrites = doubles as update)
+```
+
+Templates are starter workflow scaffolds. `add` overwrites existing files in place — use it to upgrade an outdated agent helpers block, or to grab a recipe you didn't pick at `init` time.
+
+`zibby template add zibby-workflow-claude` (or `-cursor`, `-codex`) refreshes the per-agent guidance files emitted by this template — the `<!-- zibby-template-version: N -->` markers make the upgrade idempotent.
+
+Options on `add`:
+- `--skip-memory` — strip `SKILLS.MEMORY` from copied `execute-live.mjs` (browser-test template only)
+
 ## Environment variables
 
 | Var | Purpose |

package/docs/cloud/triggering.md

@@ -18,6 +18,20 @@ Auth: set `ZIBBY_API_KEY` in the environment, or run `zibby login` once on a wor
 
 The flag surface is identical to `zibby workflow run` (local) — same `-p / --input / --input-file`, plus `--idempotency-key` for the cloud-only dedup case below. Flip the verb and the same call shape goes from local to remote.
 
+### Input precedence
+
+When more than one input source is provided, they merge with this **precedence (highest → lowest)**:
+
+1. `-p key=value` (repeatable) — wins over everything; great for shell-friendly tweaks on top of a base payload
+2. `--input '<json>'` — full JSON payload as a string
+3. `--input-file path.json` — full JSON/YAML payload from a file (lowest precedence)
+
+This means the common pattern of "load a base payload from disk, override a few keys for this run" works without manual merging:
+
+```bash
+zibby workflow trigger <uuid> --input-file payload.json -p priority=urgent
+```
+
 ## CI / cron
 
 Anywhere you can shell out, call the CLI. Don't hand-roll an HTTP client — you'll just rebuild what the CLI already does (project lookup from UUID, idempotency, quota error messages, retries).

package/docs/intro.md

@@ -29,12 +29,22 @@ graph
 
 ```bash
 npm install -g @zibby/cli
-zibby workflow new my-pipeline      # scaffold
+zibby init                          # bare init (config + creds; no template)
+zibby workflow new my-pipeline      # scaffold a custom workflow
 zibby workflow run my-pipeline      # run locally (one-shot)
 
 zibby login
 zibby workflow deploy my-pipeline   # ship to cloud
-zibby workflow trigger <uuid> -t    # fire + tail logs
+zibby workflow trigger <uuid>       # fire it
+zibby workflow logs <uuid> -t       # tail logs
+```
+
+Want a starter recipe instead of a blank slate? Use `-t`:
+
+```bash
+zibby init -t browser-test-automation     # scaffold the test recipe at init time
+zibby template list                        # see what's available
+zibby template add <name>                  # add a template later (overwrites = doubles as update)
 ```
 
 → Next: [Install](./get-started/install)

package/docs/legacy/test-automation.md

@@ -5,7 +5,9 @@ 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.
+> **Deprecated landing page.** The `zibby test` flow predates the workflow engine. The current canonical pages are [`zibby test` recipe](/recipes/test), [Test memory](/tests/memory), and [CLI Reference → test](/cli-reference#test). This page is kept for users following old links; everything below still works, but **new users should start with [Get Started](/get-started/install)**.
+
+> Notably, `zibby init --mem` referenced below is now `zibby init` (memory is set up by default) plus optionally `-t browser-test-automation` to scaffold the test recipe. The current commands are documented in the [CLI Reference](/cli-reference#init).
 
 Drive a real browser from a plain-text spec, get a Playwright script back.
 

package/docs/packages/ui-memory.md

@@ -0,0 +1,245 @@
+---
+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. The chat-style memory backend (mem0) is dormant and not documented as a usable feature here.
+
+## 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 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.
+
+## 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

package/docs/recipes/test.md

@@ -77,6 +77,42 @@ zibby test test-specs/login.txt              # headed (default — see the brows
 zibby test test-specs/login.txt --headless   # headless mode (for CI)
 ```
 
+**Cloud-stored test cases (run a saved execution):**
+```bash
+zibby test --sources <id1>,<id2> --execution <executionId>
+```
+
+## Test memory
+
+The recipe ships with a learning loop: every run reads from and writes to a local Dolt DB at `.zibby/memory/.dolt/` (cross-spec, **per-domain**). Selectors that worked, page-element fingerprints, navigation transitions, and free-form insights are all persisted — the agent's 100th run on a site is sharper and cheaper than its first.
+
+When `zibby test` runs and the DB exists, the agent gets 5 MCP tools auto-exposed:
+
+- `memory_get_test_history` — recent runs (pass/fail/timing)
+- `memory_get_selectors` — known selectors with stability metrics
+- `memory_get_page_model` — page elements / roles / accessible names
+- `memory_get_navigation` — known page-to-page transitions
+- `memory_save_insight` — save observations (categories: `selector_tip | timing | navigation | workaround | flaky | general`). **Required at least once per run.**
+
+```bash
+zibby memory stats        # what's in the DB
+zibby memory cost         # real LLM token spend per spec / per domain
+zibby memory compact      # prune old runs + GC
+```
+
+**Team sync.** Point the DB at a remote and teammates' learnings flow back to you on the next test run:
+
+```bash
+zibby memory remote add aws://my-bucket/team/proj/main   # BYO (S3 / GCS / DoltHub / file:///)
+zibby memory remote use --hosted                         # OR Zibby-managed S3 (signed-in only)
+```
+
+Or commit `memorySync.remote: 'hosted'` (or an `aws://` URL) into `.zibby.config.mjs` and `zibby init` auto-wires it for every teammate.
+
+Auto-pull on test start, auto-push on test pass. Failing runs don't pollute team memory.
+
+→ Full guide: [Test memory](../tests/memory). Schema and SDK: [`@zibby/ui-memory`](../packages/ui-memory).
+
 ## Forking the recipe
 
 If the built-in recipe doesn't fit your case, scaffold a custom workflow and copy the structure:

package/docs/tests/memory.md

@@ -0,0 +1,131 @@
+---
+sidebar_position: 1
+title: Test memory
+---
+
+# Test memory
+
+Zibby's `zibby test` runner has a local-first **memory database** at `.zibby/memory/.dolt/` that learns from every run — selectors that worked, page-element fingerprints, navigation transitions, timing quirks, recorded insights. Cross-spec via per-domain keying, optionally synced across the team.
+
+The package powering this is [`@zibby/ui-memory`](../packages/ui-memory) — read that for the schema and SDK. This page is a **usage walkthrough**.
+
+## What's in the box
+
+- **Local DB** — `.zibby/memory/.dolt/` (Dolt SQL, version-controlled like git)
+- **5 MCP tools** auto-exposed when `zibby test` runs and the DB exists
+- **Auto-pull / auto-push** before and after each test run when a remote is configured
+- **CLI** — `zibby memory <verb>` for stats, cost, compact, reset, pull, push, remote management
+
+## Why per-domain keying matters
+
+Memory is keyed on the **domain**, not the spec file. Selectors learned by `login.txt` for `myapp.com/login` are immediately available when `checkout.txt` lands on `myapp.com/checkout` and asks "what's a stable selector for the email field on this site?"
+
+In practice this means a multi-spec suite gets sharper with every run — the agent's Nth run on a domain is meaningfully cheaper and more reliable than its first.
+
+## The 5 MCP tools
+
+When `zibby test` runs and `.zibby/memory/.dolt/` exists, the agent gets these auto-exposed:
+
+| Tool | What it does |
+|---|---|
+| `memory_get_test_history` | Recent runs (filter by spec-path substring) — pass/fail and timing |
+| `memory_get_selectors` | Known selectors per page with success/fail counts |
+| `memory_get_page_model` | Page elements (URL, ARIA role, accessible name, best-known selector) |
+| `memory_get_navigation` | Known transitions (from URL → to URL via what trigger) |
+| `memory_save_insight` | Save an observation: `selector_tip | timing | navigation | workaround | flaky | general` |
+
+> **The agent must call `memory_save_insight` at least once per run.** It's required by the memory skill's prompt fragment. Without insights, only the structural data (selectors / runs) compounds; insights are how the system learns "the site shows a banner on Tuesdays" or "this button needs a 200ms wait after focus".
+
+## CLI commands
+
+```bash
+zibby memory init               # initialize (auto-runs on first `zibby test -m`)
+zibby memory stats              # row counts, last commit, per-spec breakdown
+zibby memory cost               # real LLM token spend per spec / per domain (input/output/cache)
+zibby memory compact            # prune old runs + Dolt GC (--max-runs 50, --max-age 90d)
+zibby memory reset -f           # wipe the DB (destructive — confirm)
+```
+
+`compact` is the maintenance lever once the DB grows. `cost` is the most-asked-after view — it answers "which spec is the expensive one?" with real numbers.
+
+## Team sync
+
+Memory is local-first by default. Opt into a shared remote so teammates' learnings flow back to you:
+
+```bash
+# Option A: bring your own bucket
+zibby memory remote add aws://my-bucket/team/proj/main      # S3
+zibby memory remote add gs://bucket/team/proj/main          # GCS
+zibby memory remote add https://www.dolthub.com/repositories/<owner>/<repo>
+zibby memory remote add file:///abs/path/to/local-shared    # filesystem
+
+# Option B: Zibby-managed S3 (signed-in users only)
+zibby memory remote use --hosted
+
+# Inspect / disconnect
+zibby memory remote info
+zibby memory remote remove [name]   # default: origin
+```
+
+Once a remote is configured:
+
+- `zibby test` auto-pulls before each run
+- `zibby test` auto-pushes after each **passing** run (failing runs don't pollute team memory)
+- `zibby memory pull` / `zibby memory push` for manual override
+
+### Auto-wire teammates with `memorySync.remote`
+
+Drop this into `.zibby.config.mjs` and commit it:
+
+```js
+export default {
+  agent: { claude: { model: 'auto' } },
+  memorySync: {
+    remote: 'hosted',                       // or 'aws://my-bucket/team/proj/main' or null
+  },
+};
+```
+
+Now when a teammate clones the repo and runs `zibby init`, the CLI reads `memorySync.remote` and auto-configures the matching remote. For `'hosted'`, init prompts for `zibby login` if they're not signed in but never blocks the init itself.
+
+### Hosted vs BYO at a glance
+
+| | Hosted (`--hosted`) | BYO |
+|---|---|---|
+| Setup time | One command | Provision bucket + IAM (+ KMS if you want) |
+| Where data lives | Zibby-managed AWS account | Your account |
+| Access | Anyone with Zibby project access | Whoever your IAM grants |
+| Compliance / data residency | Limited regions | Wherever you want |
+| Cost | Included in plan | Your S3 bill |
+
+If you have any data-residency requirement or a regulated workload, prefer BYO. Otherwise hosted is the path of least resistance.
+
+## Run-level controls
+
+`zibby test` exposes one memory-relevant flag:
+
+```bash
+zibby test test-specs/login.txt -m            # enable test memory (auto-init if needed)
+zibby test test-specs/login.txt --no-sync     # don't push to cloud (does not affect memory remote)
+```
+
+Memory is independent of the cloud-results sync (`--sync` / `--no-sync` controls run upload to the Zibby dashboard; memory sync is its own remote).
+
+## Inspecting the DB by hand
+
+It's just Dolt:
+
+```bash
+cd .zibby/memory
+dolt log
+dolt sql -q "SELECT spec_path, passed, duration_ms FROM test_runs ORDER BY created_at DESC LIMIT 20"
+dolt diff HEAD~1 HEAD
+```
+
+Branching works too — `dolt branch experiment` to try out a memory mutation in isolation.
+
+## See also
+
+- [`@zibby/ui-memory` package](../packages/ui-memory) — schema, SDK, middleware
+- [`zibby test` recipe](../recipes/test) — the primary consumer
+- [CLI reference: memory](../cli-reference#memory) — full command list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zibby/skills",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Built-in skill definitions for Zibby test automation framework",
   "type": "module",
   "main": "dist/index.js",