@zibby/skills 0.1.32 → 0.1.34

package/docs/packages/skills.md

@@ -17,7 +17,7 @@ npm install @zibby/skills
 
 ## 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 workflow nodes and external capabilities like browser automation, Jira, GitHub, Slack, and test memory.
+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.
 
@@ -46,7 +46,7 @@ export const executeLiveNode = {
 };
 ```
 
-When the workflow runs:
+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

package/docs/packages/ui-memory.md

@@ -13,7 +13,7 @@ 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.
+> 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
 
@@ -51,7 +51,7 @@ zibby memory init
 
 Creates `.zibby/memory/.dolt/` with the schema for runs, selectors, page model, navigation, and insights.
 
-### 3. Enable memory in your workflow
+### 3. Enable memory in your agent
 
 Add `SKILLS.MEMORY` to any node that should have memory access:
 

package/docs/recipes/bug-autofix.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 4
+title: Bug-autofix agent
+---
+
+# `bug-autofix` — ticket → fix PR → tracker writeback
+
+The flagship orchestrator agent. It polls a tracker for new bugs, classifies each one, opens a fix PR for the autofixable ones, and writes the result back to the tracker — chaining three reusable building-block agents via **sub-graph dispatch**.
+
+```
+poll (this graph)
+  ↓ found a ticket?
+triage     → sub-graph: ticket-triage      → { severity, shouldAutofix, summary }
+  ↓ severity ≥ AUTOFIX_MIN_SEVERITY AND shouldAutofix AND repo configured?
+  ├─ yes → code_fix → sub-graph: code-fix  → { pr_url, branch }
+  │            ↓
+  └─ no ───────────────────────────────────────────┐
+                                                     ↓
+writeback  → sub-graph: tracker-writeback   (runs on BOTH branches)
+  ↓
+ END
+```
+
+High-severity, concrete, autofixable bugs get a fix PR opened and the Jira ticket moved to *In Review*. Everything else (noise, vague, too-big, below threshold, or no repo configured) is triaged and a human is notified — no PR.
+
+## The three building-block agents
+
+`bug-autofix` is an orchestrator: each step is a separate, independently deployable agent it dispatches as a sub-graph. Deploy all four in the same project.
+
+| Step | Building block | Input | Output |
+|---|---|---|---|
+| `triage` | `ticket-triage` | `{ ticket }` | severity (`CRITICAL…NOISE`), `shouldAutofix`, summary |
+| `code_fix` | `code-fix` | `{ ticket, repo }` | `{ pr_url, branch }` — clones, fixes with an inline test-gate, opens a PR |
+| `writeback` | `tracker-writeback` | `{ ticket, pr_url?, branch?, result }` | transitions the issue, comments the PR link, posts to Slack/Lark |
+
+Each block is usable on its own — `ticket-triage` is a fine standalone classifier; `code-fix` is a standalone clone→fix→PR agent.
+
+## Sub-graph dispatch
+
+A child step is declared with `{ workflow }` on the node:
+
+```js
+graph.addNode('triage', {
+  workflow: 'ticket-triage',                  // child deploy slug
+  input:  (state) => ({ ticket: state.poll.ticket }),
+  output: 'classify',                         // dot-path on the child's final state
+});
+```
+
+The engine spawns the child as a **separate execution** (its own run row + Fargate task, or in-process when runtime tags match), links it to the parent for the Activity-tab tree and cancellation cascade, polls until terminal, and extracts `output` back into the parent state under the node name.
+
+## Trigger
+
+Cron poll (default) or per-ticket webhook. Each run processes ONE ticket; the next tick/webhook handles the next.
+
+```json
+{ "jql": "issuetype = Bug AND statusCategory != Done ORDER BY updated DESC" }   // cron
+{ "ticketKey": "PROJ-123" }                                                      // webhook
+```
+
+## Config (ENV tab)
+
+| Var | Meaning |
+|---|---|
+| `REPO_URL` | Repo the fix targets. Unset → no autofix, notify-only. |
+| `REPO_NAME` | Short repo name (default: derived from `REPO_URL`). |
+| `REPO_BRANCH` | Base branch (default `main`). |
+| `AUTOFIX_MIN_SEVERITY` | Routing floor for code-fix (default `MEDIUM`). |
+
+Plus the children's own config: Jira connected (triage/poll/writeback), GitHub connected (code-fix), and `SLACK_CHANNEL` / `LARK_RECEIVE_ID` (writeback).
+
+## Scope (v1)
+
+- **In:** poll → triage → (autofix?) → code-fix → writeback, end-to-end to "PR opened + Jira written back".
+- **Out:** deploy / verify / rollback; an auto re-dispatch loop; in-engine approval. The open PR is the human gate.
+- **Tracker seam:** Jira is implemented; GitHub / Linear are extension points in the child templates.
+
+## Deploy
+
+```bash
+zibby agent templates                         # browse the marketplace
+zibby agent new bug-autofix -t bug-autofix    # scaffold the orchestrator
+# ...also scaffold + deploy ticket-triage, code-fix, tracker-writeback in the same project
+zibby agent deploy bug-autofix
+```

package/docs/recipes/github-ai-scout.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 5
+title: GitHub AI scout
+---
+
+# `github-ai-scout` — daily AI-project radar
+
+A daily scout agent that finds **new/trending AI projects on GitHub**, scores them against **your** rubric with an LLM, and posts a shortlist to Slack for a human to review. It proposes — it never stars, forks, or adds anything.
+
+```
+scan   (this graph) → GitHub search REST API: your query + created:> + stars:>=
+  ↓
+score  (LLM)        → rank + filter candidates against your rubric → shortlist
+  ↓
+digest (this graph) → render a report-object → sub-graph: notify-slack
+  ↓
+ END
+```
+
+Everything that defines *what* it scouts is a deploy-time input — the search query, the recency/star thresholds, and the scoring rubric. Point it at a different topic and a different rubric and it scouts that domain instead.
+
+## Inputs
+
+| Input | Default | What it does |
+|---|---|---|
+| `query` | `topic:ai topic:llm topic:agents topic:rag` | GitHub search query, WITHOUT date/stars filters (scan appends those). |
+| `daysBack` | `30` | Only repos created within this many days. |
+| `minStars` | `30` | Minimum stars. |
+| `maxCandidates` | `30` | How many repos to fetch (max 100). |
+| `shortlistSize` | `8` | How many to surface in Slack. |
+| `rubric` | generic quality rubric | Plain-English scoring instruction — describe *your* taste. |
+| `excludeRepos` | `[]` | `owner/repo` names to skip — dedup against repos you already track. |
+| `slackChannel` | **required** | Channel id (`C012345`) or `#name` where the shortlist lands. |
+
+## GitHub auth (optional)
+
+The scan works **unauthenticated** for public search. To raise the rate limit, set a `GITHUB_TOKEN` env var on the project — the scan sends it as a Bearer token. No scopes needed; public read is enough.
+
+## Slack setup
+
+The digest dispatches to the **notify-slack** building-block agent (in-process sub-graph), which renders the shortlist as a native Block-Kit card. Deploy `notify-slack` in the same project, connect Slack, and set `slackChannel`.
+
+## Trigger
+
+Cron — typically **daily**. Each run is a fresh scan over the trailing `daysBack` window; use `excludeRepos` to keep the shortlist to NEW finds.
+
+```json
+{ "slackChannel": "#ai-radar" }
+```
+
+## What it does NOT do
+
+It **proposes a shortlist for human review — never auto-adds.** No starring, no forking, no writing anywhere except the Slack post. A person decides what to do with each find.
+
+## Deploy
+
+```bash
+zibby agent templates                                 # browse the marketplace
+zibby agent new github-ai-scout -t github-ai-scout    # scaffold (also deploy notify-slack)
+zibby agent deploy github-ai-scout
+```

package/docs/recipes/index.md

@@ -1,63 +1,68 @@
 ---
 sidebar_position: 1
-title: Recipes overview
+title: Agent Marketplace
 ---
 
-# Built-in workflow recipes
+# Agent Marketplace
 
-Zibby ships with a few **vertical slice workflows** — production-ready pipelines you can run today, demonstrating what the platform does. Each recipe is a real Zibby workflow under the hood, eating its own dog food.
+Zibby ships a set of **ready-made agents** — production-ready automations you can deploy today. Each one is a real Zibby agent, eating its own dog food. Browse them, deploy with one command, and tune them to your project.
+
+> An **Agent** is a deployed automation built on coding-agent CLIs. Build and ship one with the `zibby agent` CLI.
 
 ```
-                       ┌─────────────────────┐
-   ┌──────────────────►│  zibby workflow new │  ◄── Build your own
-   │                   │  zibby workflow ... │
-   │                   └─────────────────────┘
+                       ┌──────────────────┐
+   ┌──────────────────►│  zibby agent new │  ◄── Build your own
+   │                   │  zibby agent ... │
+   │                   └──────────────────┘
    │                              ▲
    │                              │ uses the same primitives
    │                              │
-   │                   ┌─────────────────────┐
-   │  Recipes built ──►│  zibby test         │  ◄── Browser testing
-   │  on top of the    │  zibby analyze      │  ◄── Code analysis
-   │  same platform    │  zibby video        │  ◄── Test playback
-   │                   │  zibby generate     │  ◄── Spec generation
-   │                   └─────────────────────┘
+   │                   ┌──────────────────────┐
+   │  Marketplace ────►│  bug-autofix         │  ◄── Ticket → fix PR → writeback
+   │  agents built     │  github-ai-scout     │  ◄── Daily AI-project radar
+   │  on top of the    │  pipeline-supervisor │  ◄── Zibby managing Zibby
+   │  same platform    │  sentry-triage       │  ◄── Incident routing
+   │                   │  zibby test          │  ◄── Browser testing
+   │                   └──────────────────────┘
 ```
 
-You don't have to use the recipes. You can build whatever pipeline you want with `zibby workflow new`. The recipes just save you from writing the obvious starter graphs for common cases.
+You don't have to use the marketplace. You can build whatever agent you want with `zibby agent new`. The marketplace just saves you from writing the obvious starter graphs for common cases.
 
-## Available recipes
+## Available agents
 
-| Recipe | What it does | Best for |
+| Agent | What it does | Best for |
 |---|---|---|
+| [Bug-autofix](./bug-autofix) | Polls a tracker, triages each bug, opens a fix PR for autofixable ones, writes the result back. Chains three reusable building-block agents (`ticket-triage` → `code-fix` → `tracker-writeback`). | End-to-end bug SDLC, automated remediation |
+| [GitHub AI scout](./github-ai-scout) | Daily scan of new/trending AI projects on GitHub, LLM-scored against your rubric, shortlist posted to Slack | Tracking a fast-moving space without manual triage |
+| [Pipeline supervisor](./pipeline-supervisor) | Watches the project's *other* agents, flags failing/slow ones, posts an improvement proposal to Slack/Lark | Zibby managing Zibby — agent fleet health |
+| [Sentry triage](./sentry-triage) | Hourly: fetch unresolved Sentry issues, classify by severity, route via Slack/Lark (author DM + usergroup mention) | Automated incident routing without a human triager |
 | [`zibby test`](./test) | Drives a browser via Cursor or Claude, runs assertions, generates a Playwright script + verification video | E2E test generation from plain-English specs |
-| [Sentry Triage](./sentry-triage) | Hourly: fetch unresolved Sentry issues, classify by severity, route via Slack/Lark — author DM + usergroup mention | Automated incident routing without a human triager |
-| `zibby analyze` | Reads a Jira/Linear ticket, walks the codebase, produces an implementation plan | Pre-implementation planning, ticket triage |
-| `zibby generate` | Generates test specs from a ticket + codebase | Backfilling test coverage on legacy projects |
-| `zibby video` | Re-records or organizes verification videos for an existing test | Producing demos, regenerating after code changes |
 
-## Why recipes matter
+Plus reusable **building-block agents** that the orchestrators compose via sub-graph dispatch — `ticket-triage`, `code-fix`, `tracker-writeback`, `notify-slack`, `notify-lark`, `notify-notion`. Each is independently deployable and usable on its own.
+
+## Why a marketplace
 
-Three reasons we ship vertical workflows alongside the platform:
+Three reasons we ship ready-made agents alongside the platform:
 
-1. **Proof of concept** — every recipe IS a Zibby workflow. If `zibby test` works, the platform works. You can see the actual graph definition and adapt it.
-2. **Faster onboarding** — you don't need to design a full graph on day one. Run a recipe, see the output, then build your own.
-3. **Demonstrates multi-vendor** — the test recipe runs across Cursor / Claude / Codex / Gemini. Pick the agent that gives you the best results for your use case; the recipe doesn't care.
+1. **Proof of concept** — every marketplace agent IS a Zibby agent. If `bug-autofix` works, the platform works. You can see the actual graph definition and adapt it.
+2. **Faster onboarding** — you don't need to design a full graph on day one. Deploy an agent, see the output, then build your own.
+3. **Composable** — the orchestrators (`bug-autofix`) are built from smaller building-block agents dispatched as sub-graphs, so you can reuse the pieces in your own agents.
 
-## Building your own recipe
+## Building your own agent
 
-If you have a workflow you'd want shipped as a built-in:
+If you have an agent you'd want shipped as a built-in:
 
 ```bash
-zibby workflow new my-recipe          # scaffold
+zibby agent new my-agent          # scaffold
 # ... build it out ...
-zibby workflow run my-recipe          # test locally
-zibby workflow deploy my-recipe       # ship to your cloud account
+zibby agent run my-agent          # test locally
+zibby agent deploy my-agent       # ship to your cloud account
 ```
 
-If it's broadly useful, we may pull it into the official recipes set. Open an issue or PR.
+If it's broadly useful, we may pull it into the official marketplace. Open an issue or PR.
 
 ## Next
 
-- **[`zibby test` recipe](./test)** — the most-used recipe, walked through end-to-end
-- **[Build your own workflow](../get-started/your-first-workflow)** — scaffold and customize
-- **[Concepts: graph](../concepts/graph)** — the primitives every recipe is built on
+- **[Bug-autofix agent](./bug-autofix)** — the flagship orchestrator, walked through end-to-end
+- **[Build your own agent](../get-started/your-first-workflow)** — scaffold and customize
+- **[Concepts: graph](../concepts/graph)** — the primitives every agent is built on

package/docs/recipes/pipeline-supervisor.md

@@ -0,0 +1,57 @@
+---
+sidebar_position: 6
+title: Pipeline supervisor
+---
+
+# `pipeline-supervisor` — Zibby managing Zibby
+
+A scheduled supervisor agent that watches the project's *other* agents, finds the ones that are failing or slow, and posts a human-reviewable improvement proposal to Slack or Lark.
+
+v1 is strictly **READ → PROPOSE → NOTIFY**. It never edits another agent's graph — that's the safe starting point. The auto-PATCH step is a deliberate TODO, not implemented.
+
+```
+scan_pipelines        (deterministic + Zibby REST API, PAT-authed)
+   → propose_improvements (LLM — one proposal per flagged agent)
+   → notify               (LLM + SKILLS.CHAT_NOTIFY — one review card)
+```
+
+If `scan_pipelines` flags nothing, the graph short-circuits straight to `notify` (which posts/skips without an LLM call on the proposer).
+
+## How it reads other agents
+
+A direct authed `GET /executions?projectId=<id>&limit=200` against the Zibby REST API (the same route the dashboard and remote MCP server use), carrying a **user personal access token** in `Authorization: Bearer`.
+
+It must be a USER PAT (`zby_pat_…`), **not** the Fargate-injected `PROJECT_API_TOKEN`: every cross-agent read route requires a `userId` from the authorizer, and a project token carries none — so it 401s.
+
+## Config (ENV tab)
+
+Required:
+
+- `ZIBBY_PAT` — user personal access token the supervisor reads executions with.
+- `SLACK_CHANNEL` **or** `LARK_RECEIVE_ID` — where the review card goes.
+
+Optional:
+
+- `SUPERVISOR_PROJECT_ID` — project to supervise (defaults to the running project).
+- `SLACK_MENTIONS` / `LARK_MENTIONS` — JSON array of mentions on the card.
+
+## Input (per-run dials)
+
+| Field | Default | Meaning |
+|---|---|---|
+| `lookbackHours` | 24 | Hours of execution history to scan |
+| `minFailRate` | 0.4 | Flag an agent failing ≥ this fraction of recent runs |
+| `targetWorkflowTypes` | — | Optional name filter (case-insensitive substring) |
+| `maxPipelines` | 25 | Cap on distinct agents analyzed per run |
+
+## Trigger
+
+Cron — typically daily or hourly, depending on how active the supervised project is.
+
+## Deploy
+
+```bash
+zibby agent templates                                       # browse the marketplace
+zibby agent new pipeline-supervisor -t pipeline-supervisor  # scaffold
+zibby agent deploy pipeline-supervisor
+```

package/docs/recipes/sentry-triage.md

@@ -5,7 +5,7 @@ title: Sentry triage recipe
 
 # `sentry-triage` — agent-driven Sentry triage
 
-An hourly Sentry triage workflow that fetches unresolved issues, classifies them by severity, and **routes them to the right human**. Three nodes, end-to-end agent-driven, deployed from the marketplace in one click.
+An hourly Sentry triage agent that fetches unresolved issues, classifies them by severity, and **routes them to the right human**. Three nodes, end-to-end agent-driven, deployed from the marketplace in one click.
 
 ```
 fetch_issues  →  classify  →  dispatch_alerts
@@ -27,12 +27,12 @@ The agent uses [`slack_lookup_user_by_email`](../skills/slack), [`slack_list_use
 ## Deploy from the marketplace
 
 ```bash
-zibby workflow templates deploy sentry-triage --project <project-id>
+zibby agent templates deploy sentry-triage --project <project-id>
 ```
 
 Or via the dashboard: `/marketplace/workflows` → Sentry Triage → Deploy.
 
-After deploy, configure ENV (Apps → workflow → ENV tab):
+After deploy, configure ENV (Apps → agent → ENV tab):
 
 | Env var | Required? | Default | What it does |
 |---|---|---|---|
@@ -79,15 +79,15 @@ If you deployed your backend with `RELEASE_SHA` Sentry release-tracking on, susp
 Each node's prompt lives in its own module — fork the template, edit, redeploy:
 
 ```bash
-zibby workflow download <uuid>
+zibby agent download <uuid>
 # edit nodes/dispatch-node.js
-zibby workflow deploy ./sentry-triage   # same UUID, new version
+zibby agent deploy ./sentry-triage   # same UUID, new version
 ```
 
 Or fork the whole template repo if you want long-term divergence — it's just a `@zibby/workflow-templates/sentry-triage/` directory in the published package.
 
 ## Cadence
 
-Default: hourly cron, fires `sinceMinutes=60`. Change in the trigger config (Apps → workflow → Triggers) — keep the SQL safe `since` between 5 and 1440 minutes (`inputSchema` enforces this).
+Default: hourly cron, fires `sinceMinutes=60`. Change in the trigger config (Apps → agent → Triggers) — keep the SQL safe `since` between 5 and 1440 minutes (`inputSchema` enforces this).
 
-→ Next: [`zibby test`](./test) (the browser-testing recipe) or [Build your own workflow](../get-started/your-first-workflow).
+→ Next: [`zibby test`](./test) (the browser-testing recipe) or [Build your own agent](../get-started/your-first-workflow).

package/docs/recipes/test.md

@@ -7,7 +7,7 @@ title: Browser test recipe (zibby test)
 
 The browser-test recipe takes a plain-English spec, drives a real browser via a coding agent (Cursor / Claude / Codex / Gemini), runs the assertions, and produces a Playwright script + verification video.
 
-It's a worked example of what the Zibby platform does — every step is a regular workflow node with Zod-validated handoff. You can read the source, fork it, or build your own variation.
+It's a worked example of what the Zibby platform does — every step is a regular agent node with Zod-validated handoff. You can read the source, fork it, or build your own variation.
 
 ## Quick start
 
@@ -38,7 +38,7 @@ zibby test test-specs/checkout.txt --agent claude
 
 Open the session in [Zibby Studio](https://zibby.app/studio) to scrub through the run, swap the prompt, re-execute any node.
 
-## The graph (this is just a Zibby workflow)
+## The graph (this is just a Zibby agent)
 
 Under the hood, `zibby test` is a 3-node graph:
 
@@ -115,10 +115,10 @@ Auto-pull on test start, auto-push on test pass. Failing runs don't pollute team
 
 ## Forking the recipe
 
-If the built-in recipe doesn't fit your case, scaffold a custom workflow and copy the structure:
+If the built-in recipe doesn't fit your case, scaffold a custom agent and copy the structure:
 
 ```bash
-zibby workflow new my-test-pipeline
+zibby agent new my-test-agent
 ```
 
 Then in `graph.mjs`, define your own nodes:
@@ -170,7 +170,7 @@ That's the platform. The recipe is just a starter.
     npx @zibby/cli test test-specs/checkout.txt --headless
 ```
 
-For workflows triggered remotely (rather than per-CI-run), use [`workflow trigger`](../cloud/triggering) on a deployed graph.
+For agents triggered remotely (rather than per-CI-run), use [`agent trigger`](../cloud/triggering) on a deployed graph.
 
 ## Why this is different from Playwright codegen / a basic LLM script
 
@@ -187,4 +187,4 @@ For workflows triggered remotely (rather than per-CI-run), use [`workflow trigge
 
 - [Recipes overview](./)
 - [Concepts: graph](../concepts/graph) — the primitives this recipe uses
-- [Cloud triggering](../cloud/triggering) — fire workflows from CI/CD
+- [Cloud triggering](../cloud/triggering) — fire agents from CI/CD

package/docs/skills/browser.md

@@ -5,7 +5,7 @@ title: Browser
 
 # Browser skill
 
-Playwright-driven browser automation. Click, type, navigate, snapshot, record video. Used by `zibby test` and by any workflow node that needs to drive a web UI.
+Playwright-driven browser automation. Click, type, navigate, snapshot, record video. Used by `zibby test` and by any agent node that needs to drive a web UI.
 
 - **ID:** `browser`
 - **MCP server:** `playwright` (tools exposed as `mcp__playwright__*`)
@@ -45,7 +45,7 @@ npm install @zibby/mcp-browser
 
 Override the bin path with `MCP_BROWSER_PATH` if you need to point at a local checkout.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/chat-memory.md

@@ -5,7 +5,7 @@ title: Chat memory
 
 # Chat memory skill
 
-Persistent agent memory across sessions — facts, decisions, preferences, task history. Dolt-backed by default; pluggable to mem0 for embedding-based recall.
+Persistent agent memory across sessions — facts, decisions, preferences, task history. **mem0-backed by default** (embedding-based semantic recall, persists across cloud tasks); falls back to the self-contained Dolt backend automatically when the embedding proxy isn't available, or set `dolt` explicitly.
 
 - **ID:** `chat-memory`
 - **Runs in-process** — no MCP spawn
@@ -16,7 +16,7 @@ For test-run history (selectors, page models, prior runs) see [Memory](./memory.
 
 | Tool | What it does |
 |---|---|
-| `memory_store` | Save a fact/decision/preference. Categories: `fact`, `decision`, `context`, `insight`, `preference`, `credential`, `url`, `error`, `workaround`. Tiers: `short` (24h), `mid` (default), `long` (permanent). Optional `memoryKey` for upserts |
+| `memory_store` | Save a fact/decision/preference. Categories: `fact`, `decision`, `context`, `insight`, `preference`, `credential`, `url`, `error`, `workaround`. Tiers: `short` (24h), `mid` (default), `long` (permanent). Optional `memoryKey` for upserts. Optional `infer` (mem0 only — see [the `infer` toggle](#the-infer-toggle)) |
 | `memory_recall` | Search by `query`, `category`, `ticketKey`, or `tier`. Ranked by relevance × recency |
 | `memory_brief` | Compact briefing — recent sessions + top long/mid-tier memories. Call at conversation start |
 | `memory_end_session` | Save a session summary + key facts (semicolon-separated) for future recall |
@@ -25,13 +25,7 @@ For test-run history (selectors, page models, prior runs) see [Memory](./memory.
 
 ## Setup
 
-**Dolt (default).** Install Dolt; the skill auto-creates `.zibby/memory/` on first use.
-
-```bash
-brew install dolt
-```
-
-**mem0 (optional).** Set `ZIBBY_MEMORY_BACKEND=mem0` (or `memory.backend: 'mem0'` in `.zibby.config.mjs`) and `npm install mem0ai` in your workspace. Configure with:
+**mem0 (default).** `zibby init` configures mem0 out of the box and writes the right deps (`mem0ai@npm:@zibby/mem0ai@^3.0.5` + `better-sqlite3`) into your project. In Zibby cloud runs the embedding/LLM calls are proxied and billed through the agent run — no OpenAI key of your own needed. For local runs, point it at any OpenAI-compatible endpoint:
 
 ```bash
 ZIBBY_MEM0_OPENAI_BASE_URL=https://api.openai.com/v1
@@ -41,9 +35,44 @@ ZIBBY_MEM0_EMBEDDER_MODEL=text-embedding-3-small
 ZIBBY_MEM0_EMBEDDING_DIMS=1536
 ```
 
-mem0 mode skips Dolt session/task tables and relies on embedding search; `memory_end_session`, `task_log`, and `task_history` still write to Dolt for cross-session continuity.
+mem0 mode uses embedding search for `memory_store` / `memory_recall`; `memory_end_session`, `task_log`, and `task_history` still write to Dolt for cross-session continuity. mem0's SQLite vector store lives under `.zibby/memory/mem0/` and is carried across ephemeral cloud tasks by the tenant-scoped memory tarball sync.
+
+**Graceful degradation.** If the embedding proxy is unreachable (or a local run has no `ZIBBY_MEM0_API_KEY`), memory ops automatically fall back to the Dolt backend per-op rather than failing the run — you get structured memory instead of an error.
+
+**Dolt (self-contained, no embedding dependency).** Set `ZIBBY_MEMORY_BACKEND=dolt` (or `memory.backend: 'dolt'`, or `zibby init --memory-backend dolt`) to opt out of mem0 entirely. Install Dolt; the skill auto-creates `.zibby/memory/` on first use:
+
+```bash
+brew install dolt
+```
+
+### The `infer` toggle
+
+mem0 can either store memories raw (embed-only, free) or run an LLM fact-extraction pass that distills and dedupes facts before storing (~7.7k tokens per call, costs money). This is the `infer` flag, and it **defaults to `false`** (embed-only).
+
+Resolution precedence (first match wins):
+
+1. **Per-call tool arg** — pass `infer: true` to `memory_store`
+2. **Env toggle** — `ZIBBY_MEM0_INFER=true`
+3. **Project config** — `memory.infer: true` in `.zibby.config.mjs`
+4. Default — `false` (embed-only, no LLM call)
+
+```js
+// .zibby.config.mjs
+export default {
+  memory: {
+    backend: 'mem0',
+    infer: false,        // default — store raw + embed, never call the LLM
+  },
+};
+```
+
+Turn `infer` on when you want mem0 to consolidate noisy inputs into clean facts; leave it off (the default) for free, deterministic embed-and-store.
+
+### Cloud persistence
+
+On Zibby Cloud, mem0 state **persists across Fargate tasks**. mem0's SQLite vector + history stores are rooted under the workspace's tenant-scoped `.zibby/memory/` tree, which is tarball-synced between executions — so a memory written in one run is recallable in the next, even though each run is a fresh, ephemeral container. mem0 user IDs are workspace-scoped (`workspace:<name>`, overridable via `ZIBBY_MEMORY_USER_ID`), keeping each project's memory isolated.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/core-tools.md

@@ -27,7 +27,7 @@ Most Claude/Cursor/Codex nodes get these tools by default from their agent strat
 
 None. The skill has no env keys, no auth, no external dependencies.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/function-skill.md

@@ -34,7 +34,7 @@ export const myTool = skill('my_tool', {
 
 Calling `skill()` both creates and **registers** the skill in the global registry, so just importing the module is enough to make it available.
 
-## Use in a workflow
+## Use in an agent
 
 Once registered, reference by id:
 

package/docs/skills/github.md

@@ -37,11 +37,11 @@ Two options:
 
 **GitHub App (recommended).** In **Settings → Integrations**, click **Connect GitHub**, install the Zibby GitHub App on the orgs/repos you want, and authorize. Tokens auto-refresh; you don't manage them. See the [GitHub Integration page](../integrations/github.md) for the full app permissions list.
 
-**Personal access token.** Set `GITHUB_TOKEN` in your workflow's env (locally) or via **Cloud → Env vars** (cloud runs). Scope `repo` for private read+write, `public_repo` for public-only.
+**Personal access token.** Set `GITHUB_TOKEN` in your agent's env (locally) or via **Cloud → Env vars** (cloud runs). Scope `repo` for private read+write, `public_repo` for public-only.
 
 The skill reads `envKeys: ['GITHUB_TOKEN']` and the official `@modelcontextprotocol/server-github` consumes it directly.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/index.md

@@ -15,8 +15,12 @@ Per-skill reference for everything shipped in `@zibby/skills`. For the mental mo
 | [Sentry](./sentry.md) | `sentry` | `sentry_list_projects`, `sentry_list_issues`, `sentry_get_issue` | OAuth (PKCE) |
 | [Lark](./lark.md) | `lark` | `lark_send_message`, `lark_reply`, `lark_list_chats`, `lark_get_chat_history` | App ID + App Secret |
 | [GitHub](./github.md) | `github` | Repos, PRs, issues, commits, file reads, clone | GitHub App or `GITHUB_TOKEN` |
+| GitLab | `gitlab` | Repos, MRs, issues, pipelines (self-hosted or SaaS) | `GITLAB_TOKEN` (+ base URL) |
 | [Slack](./slack.md) | `slack` | Channels, post/reply, reactions, history, users | Bot token + team ID |
 | [Jira](./jira.md) | `jira` | Issues, sprints, comments, transitions | Atlassian OAuth |
+| Linear | `linear` | `linear_list_issues`, `linear_get_issue`, `linear_add_comment`, `linear_update_state`, `linear_list_teams/states/labels` | `LINEAR_API_KEY` |
+| Plane | `plane` | Projects, work items, cycles, modules, epics, comments (official MCP) | `PLANE_API_KEY` (+ `PLANE_WORKSPACE_SLUG`, `PLANE_BASE_URL`) |
+| Notion | n/a | Not an attachable MCP skill — a [connectable integration](../integrations/notion.md). Agents publish a `report` object to Notion blocks (`reportToNotionBlocks`), e.g. the `notify-notion` template | OAuth (dashboard) / `NOTION_API_KEY` (SDK) |
 | [Memory](./memory.md) | `memory` | Test history, selectors, page model (Dolt) | `zibby init --mem` |
 | [Chat memory](./chat-memory.md) | `chat-memory` | `memory_store`, `memory_recall`, `memory_brief`, `task_log`, `task_history` | None (Dolt or mem0) |
 | [Core tools](./core-tools.md) | `core-tools` | `read_file`, `write_file`, `list_directory`, `run_command`, `open_url`, `wait` | None |

package/docs/skills/jira.md

@@ -40,7 +40,7 @@ See the [Jira Integration page](../integrations/jira.md) for the user-facing set
 
 Under the hood the bin reads `ATLASSIAN_ACCESS_TOKEN` + `ATLASSIAN_CLOUD_ID` (and optional `ATLASSIAN_INSTANCE_URL`), which the backend supplies through `resolveIntegrationToken('jira')`.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/lark.md

@@ -30,7 +30,7 @@ Lark bots authenticate with App ID + App Secret. The bot needs `im:message` and
 
 For self-hosted Lark deployments, set `host` on the integration config; the default is the standard Feishu host.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/memory.md

@@ -30,7 +30,7 @@ Requires [Dolt](https://docs.dolthub.com/introduction/installation) and an initi
 ```bash
 # macOS
 brew install dolt
-# then, in your workflow workspace:
+# then, in your agent workspace:
 zibby init --mem
 ```
 
@@ -40,7 +40,7 @@ Override the bin location for development with `MCP_MEMORY_PATH`.
 
 See [Tests → Memory](../tests/memory.md) for the full memory lifecycle.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';

package/docs/skills/sentry.md

@@ -29,7 +29,7 @@ Sentry uses OAuth 2.0 with PKCE (public client — no client secret).
 
 The backend (`/integrations/sentry/connect` and `/integrations/sentry/callback`) handles the PKCE exchange. Tokens auto-refresh on use; if refresh fails, click **Reconnect** in the same settings panel.
 
-## Use in a workflow
+## Use in an agent
 
 ```js
 import { WorkflowAgent, WorkflowGraph } from '@zibby/core';