<!-- zibby-template-version: 4 -->
---
description: Help the user build, test, and deploy Zibby agents + browser tests
globs:
  - "**/.zibby/workflows/**"
  - ".zibby.config.mjs"
  - "**/agent.json"
  - "**/graph.mjs"
  - "test-specs/**"
  - ".zibby/memory/**"
alwaysApply: false
---

# Zibby — agents + tests

This project uses **Zibby**. Two surfaces share `.zibby.config.mjs` at the project root.

## Agents

A graph of AI-agent-driven steps that runs in a sandboxed container.

```
<workflowsBasePath>/<workflow-name>/
├── agent.json    # name, entryClass, triggers, schemas (manifest)
├── graph.mjs        # exports the graph (nodes + edges)
├── nodes/           # one .mjs file per node, plus index.mjs barrel
└── package.json     # deps bundled at deploy time
```

Each node exports `{ id, description, async run(ctx) }`. `ctx` provides `input`, `agent({prompt, schema})`, `shell(cmd)`, `log(...)`.

### Common dev loop

```
zibby agent new <name>          # scaffold
zibby agent run <name>          # one-shot local run (preferred for the dev loop)
zibby agent deploy <name>       # build + push to cloud
zibby agent trigger <uuid>      # invoke the cloud agent
zibby agent logs <uuid> -t      # tail live logs (docker-compose-style for concurrent runs)
zibby agent list                # local + cloud
zibby agent download <uuid>     # pull cloud source back to .zibby/workflows/
zibby agent delete <uuid>       # remove a deployed agent
```

`run` (one-shot) vs `start` (long-lived dev server, port 3848 — Studio integration). For plain CLI iteration always use `run`.

`run` and `trigger` accept the same input flags: `-p key=value` (highest precedence, repeatable), `--input '<json>'`, `--input-file path.json` (lowest precedence).

### Adding a new node

1. Create `<workflow>/nodes/<name>.mjs` (mirror existing `example.mjs` pattern)
2. Register in `<workflow>/nodes/index.mjs`
3. Wire into `<workflow>/graph.mjs` (add to `nodes` array and connect via edges)
4. `zibby agent run <name>` to test locally; `zibby agent deploy` to push

### Per-agent env vars

Each deployed agent has its own encrypted env-var bag; agent env wins over project secrets on conflict.

```
zibby agent env list  <uuid>                          # show key names (values never returned)
zibby agent env set   <uuid> ANTHROPIC_API_KEY=sk-…    # add or rotate one
zibby agent env unset <uuid> OLD_KEY                   # remove one
zibby agent env push  <uuid> --file .env [--file .env.prod]   # bulk replace
```

Fast path on first deploy: `zibby agent deploy my-pipeline --env .env` deploys, then auto-pushes the .env into the new UUID.

## Tests (`zibby test`)

Plain-language `.txt` specs at `test-specs/`. The runner drives a real browser via MCP, generates Playwright, produces a video.

```
zibby test test-specs/<name>.txt        # run a spec
zibby test "go to example.com and ..."  # inline, no file
zibby test <spec> --agent claude        # override agent (claude|cursor|codex|gemini)
zibby test --sources <ids> --execution <id>   # cloud test cases
```

When debugging, `test-results/<spec>/video.webm` usually tells you what went wrong faster than logs.

### Test memory (`.zibby/memory/.dolt/`)

Local-first Dolt SQL DB that learns selectors, page model, navigation, history from every run. Keyed **per-domain** (cross-spec). Auto-pulls before runs, auto-pushes after passing runs.

When `zibby test` runs and `.dolt/` exists, the agent gets 5 MCP tools auto-exposed:
- `memory_get_test_history` — recent runs (filter by spec-path substring)
- `memory_get_selectors` — known selectors per page with stability metrics
- `memory_get_page_model` — page elements, roles, accessible names
- `memory_get_navigation` — page-to-page transitions
- `memory_save_insight` — save observations (`selector_tip | timing | navigation | workaround | flaky | general`)

**After completing a test, the agent MUST call `memory_save_insight` at least once** — record reliable selectors, timing quirks, workarounds.

Local CLI: `zibby memory stats | cost | compact | reset`.

Team sync (BYO or hosted):
```
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)
```
Set `memorySync.remote` in `.zibby.config.mjs` (`'hosted'` or `'aws://...'`) so teammates running `zibby init` plug into the same memory automatically.

## Reference

Canonical, evolving docs: **https://docs.zibby.app/workflows**

Topics:
- Node SDK (ctx.agent / ctx.shell / ctx.log): https://docs.zibby.app/workflows/sdk
- Deploying & bundling: https://docs.zibby.app/workflows/deploying
- Triggering & inputs: https://docs.zibby.app/workflows/triggers
- Per-workflow env vars: https://docs.zibby.app/cloud/env-vars
- Live log streaming: https://docs.zibby.app/workflows/logs
- Egress proxy / static IPs: https://docs.zibby.app/workflows/egress
- Security & secrets: https://docs.zibby.app/workflows/security
- Test memory: https://docs.zibby.app/tests/memory
- Tests — running: https://docs.zibby.app/tests/running

Prefer the docs URL for anything you're unsure about — they're updated more frequently than these rules.