@zibby/skills 0.1.27 → 0.1.28

package/dist/package.json

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

package/docs/apps/agent-ops.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 4
+title: Agent operator
+---
+
+# The agent-ops sidecar
+
+Every Zibby Managed App ships with **agent-ops**, an autonomous daemon sidecar that runs alongside the app container. It does what a human operator would do — checks health, restarts on crash, prunes disk, rolls upgrades — only it does it every hour, never sleeps, and never forgets to file a runbook.
+
+This is the structural difference between "deploy button on a VM" and **Zibby**.
+
+## What it does
+
+| Task | Cadence | What happens |
+|---|---|---|
+| **Hourly health check** | every 60 min | HTTP probe + container state + EFS usage. Recorded as a structured run record. |
+| **Self-heal on OOM** | event-driven | Container exits with OOMKilled → agent-ops triggers an ECS restart, records the recovery. |
+| **Disk-pressure prune** | when EFS > 90% | Removes safe-to-delete caches (e.g. n8n execution history older than 30 days). Configurable. |
+| **Upgrade orchestration** | on schedule | When a new app version lands in the catalog, agent-ops can run the in-place upgrade on a cron you set. |
+| **Activity log** | every action | One row in the app's "Agent activity" tab, with structured fields you can grep / chart. |
+
+Every action lands in DynamoDB as an `app-runs` record — queryable by anything from a workflow node to a Grafana dashboard.
+
+## See it in action
+
+```bash
+zibby app activity a1b2c3d4
+```
+
+```
+Time         Action                      Status   Duration   Notes
+14:00:01     hourly_health_check         ok       1.2s
+13:00:01     hourly_health_check         ok       1.1s
+12:04:38     oom_recovery                ok       4.8s       restarted container after OOMKilled
+12:00:01     hourly_health_check         warn     2.1s       container restarting
+11:00:01     hourly_health_check         ok       1.3s
+10:00:01     hourly_health_check         ok       1.0s
+```
+
+The dashboard's "Agent activity" tab shows the same records with extra context (HTTP status codes, container logs at failure time, recovery diff).
+
+## Run records ≠ logs
+
+A run record is **structured metadata** about something agent-ops did:
+
+```json
+{
+  "instanceId": "a1b2c3d4",
+  "runId": "01J9KZQF...",
+  "action": "hourly_health_check",
+  "status": "ok",
+  "startedAt": "2026-05-30T14:00:01Z",
+  "duration_ms": 1234,
+  "httpStatus": 200,
+  "containerState": "RUNNING"
+}
+```
+
+Logs are unstructured text. Run records are queryable, chartable, and aggregatable — that's why the Agent activity tab can show a 30-day uptime % without you running grep.
+
+The CLI exposes them:
+
+```bash
+zibby app activity a1b2c3d4 --since 7d
+zibby app activity a1b2c3d4 --action oom_recovery
+zibby app activity a1b2c3d4 --json | jq '.[] | select(.status == "warn")'
+```
+
+## Why a sidecar, not a centralized controller?
+
+Three properties only this shape gives you:
+
+1. **No noisy-neighbor failure mode** — your instance's agent-ops can't be blocked by another instance's slow health check
+2. **Per-instance customization without a central feature flag** — env vars (`AGENT_OPS_CHECK_INTERVAL_MIN=15`, `AGENT_OPS_PRUNE_THRESHOLD=80`) live on your instance and just work
+3. **Egress identity matches the app** — outbound calls from agent-ops use the same ENI / NAT path as the app itself, so when the app has a dedicated egress IP, agent-ops's webhook callbacks come from the same IP
+
+## Customize via env
+
+Per-instance agent-ops behavior is tunable via env vars (set on the app instance — Apps → ENV tab — or via `zibby app env set`):
+
+| Env var | Default | What it controls |
+|---|---|---|
+| `AGENT_OPS_CHECK_INTERVAL_MIN` | 60 | Minutes between hourly health checks |
+| `AGENT_OPS_PRUNE_THRESHOLD` | 90 | EFS usage % that triggers disk-pressure prune |
+| `AGENT_OPS_AUTO_UPGRADE` | `false` | If `true`, upgrade automatically when catalog publishes a new version |
+| `AGENT_OPS_NOTIFY_WEBHOOK` | — | URL to POST run records to (any HTTPS endpoint — your own backend, n8n, etc.) |
+
+`AGENT_OPS_NOTIFY_WEBHOOK` is how you wire agent-ops into your existing observability stack — fire every run record into your team's #ops Slack via a workflow trigger, into Datadog via their webhook receiver, or into your own database.
+
+## Hooking agent-ops into a workflow
+
+The most powerful pattern: a Zibby workflow that runs **on agent-ops events**.
+
+Example: when an `oom_recovery` fires, run a workflow that pulls the container's last-100-lines, classifies the crash, and pages whoever owns this app:
+
+```bash
+zibby app env set a1b2c3d4 \
+  AGENT_OPS_NOTIFY_WEBHOOK=https://api-prod.zibby.app/v1/workflows/<wf-uuid>/trigger
+```
+
+The workflow receives the run record as `input`, can call back to `zibby app logs` / `zibby app status`, and decides what to do. Agent-ops + workflows compose into a self-operating fleet — humans only get pinged for genuinely novel failure modes.
+
+## Upgrade orchestration
+
+When you `zibby app upgrade <id>` manually, agent-ops watches the rollout and rolls back if the new task fails health checks twice in a row. With `AGENT_OPS_AUTO_UPGRADE=true` set, the upgrade fires on a cron (default: weekly, Sunday 04:00 UTC) — agent-ops runs the same flow:
+
+1. Register new task definition revision (catalog's latest)
+2. Update service, watch the rollout
+3. If 2 consecutive health checks pass on the new revision → keep it
+4. If 2 fail → roll back to the previous revision, log a `failed_upgrade` run record
+
+The activity log shows the full attempted upgrade timeline so you can see why a rollback happened.
+
+→ Done with apps. See [Workflows](../get-started/your-first-workflow) for the agent-pipeline counterpart, or [CLI Reference](../cli-reference#app-commands) for the full `zibby app` command surface.

package/docs/apps/deploy.md

@@ -0,0 +1,120 @@
+---
+sidebar_position: 2
+title: Deploy your first app
+---
+
+# Deploy your first app
+
+A complete walk-through — from `zibby app templates` to a running n8n instance behind a stable URL — in 30 seconds.
+
+## Prerequisites
+
+You'll need the CLI installed and authenticated:
+
+```bash
+npm install -g @zibby/cli
+zibby login                # OAuth in browser, saves session to ~/.zibby/config.json
+```
+
+You also need a project. If you don't have one yet, deploy a workflow first or create one in the [Zibby dashboard](https://studio.zibby.dev) — apps are scoped to projects so per-instance EFS volumes can be isolated per team.
+
+## Browse the catalog
+
+```bash
+zibby app templates
+```
+
+```
+ID            Display name              Tier      Rate         Description
+n8n           n8n                       Light     $0.05/hr     Workflow automation. 200+ integrations.
+grafana       Grafana                   Light     $0.05/hr     Dashboards for metrics, logs, traces.
+gastown       Gas Town                  Light     $0.05/hr     Multi-agent workspace. Coordinate Claude, Codex, Cursor, Gemini.
+drawio        draw.io                   Light     $0.05/hr     Client-side diagram editor. Flowcharts, UML, ER, network.
+open-webui    Open WebUI                Heavy     $0.25/hr     ChatGPT-style UI for Ollama / OpenAI-compatible endpoints.
+```
+
+## Deploy
+
+```bash
+zibby app deploy n8n --project <project-id> --name automations
+```
+
+On success:
+
+```
+↑ Provisioning n8n on Fargate…
+  ECS service + EFS volume + ALB target group
+  agent-ops sidecar starting…
+✔ Deployed (instanceId: a1b2c3d4)
+→ Public URL: https://a1b2c3d4.apps.zibby.dev
+```
+
+`--project` is interactive-prompted if omitted (CLI walks you through your project list).
+`--name` controls the **display name** — what shows in `zibby app list` and the dashboard. The subdomain is a separate opaque identifier (the instance ID), stable for the life of the instance.
+
+The provisioning steps:
+
+1. **Allocate an instance ID** — short hex token used as the subdomain
+2. **Create EFS access point** — per-instance volume, encrypted at rest, AZ-pinned
+3. **Register task definition** — pinned to the catalog entry's image + your resource tier
+4. **Spin up ECS service** — desired count 1, agent-ops sidecar bundled alongside the app container
+5. **Wire the ALB** — listener rule routes `<id>.apps.zibby.dev` to the new target group
+6. **Health-check loop** — the first agent-ops tick fires once the container is up
+
+Wall-clock: ~45-90 seconds. The CLI streams progress and prints the public URL the moment the ALB is responsive.
+
+## Verify
+
+```bash
+zibby app status a1b2c3d4
+```
+
+```
+● automations (n8n v1.97.1)
+┌ status    running (1/1) ✓
+├ resources 0.5 vCPU · 1 GB RAM ✓
+└ hourly    $0.05/hr ✓
+
+Public URL: https://a1b2c3d4.apps.zibby.dev
+
+Last agent-ops run: 14:00:01  hourly_health_check  ok (1.2s)
+```
+
+Open the URL in a browser — n8n's setup screen renders, you create the admin account, and the instance is private to you. The data sits on the EFS volume, encrypted and isolated; no other Zibby customer can reach it.
+
+## Watch logs while it warms up
+
+If the app behaves oddly on first launch, tail logs:
+
+```bash
+zibby app logs a1b2c3d4 -t
+```
+
+Logs cover both the app container **and** the agent-ops sidecar. Container logs are color-coded by source:
+
+```
+14:00:00.122 [n8n]        Listening on port 5678
+14:00:01.044 [agent-ops]  hourly_health_check: HTTP 200 in 1.2s
+14:00:01.061 [agent-ops]  ✓ instance healthy — next tick in 60m
+```
+
+`Ctrl+C` exits tail mode; logs persist in CloudWatch with 30-day retention.
+
+## What's actually private vs shared
+
+Mental model that lines up with what the bill shows:
+
+| Resource | Per-instance? |
+|---|---|
+| Subdomain (`<id>.apps.zibby.dev`) | ✅ Yours |
+| EFS volume | ✅ Yours, encrypted |
+| ALB target group | ✅ Yours |
+| ECS task definition | ✅ Yours (revisions tracked) |
+| Fargate task | ✅ Yours |
+| ALB itself | Shared — pooled across all tenants |
+| ECS cluster | Shared |
+| EFS file system | Shared, but per-instance access points enforce isolation |
+
+The shared bits are why per-minute pricing can be $0.05/hr instead of $30/mo — economies of scale on the platform side.
+
+→ Next: [Manage instances](./managing)

package/docs/apps/index.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+title: Apps overview
+---
+
+# Managed Apps
+
+One-click hosted instances of open-source tools (n8n, Grafana, Open WebUI, draw.io, Gas Town, …), each private to your project — with an **autonomous agent-ops sidecar** that handles health checks, self-healing, and upgrades on its own.
+
+```bash
+zibby app templates              # browse the catalog
+zibby app deploy n8n              # one-click — ECS service + EFS volume + ALB target group
+zibby app logs <id> -t            # tail logs, SSE auto-reconnect
+zibby app status <id>             # uptime, cost, version, agent-ops activity
+```
+
+## Why apps (not workflows)
+
+Both are pillars of Zibby Cloud. Pick by **how long the thing needs to run**:
+
+| | **Workflow** | **App** |
+|---|---|---|
+| Lifetime | Per-trigger (seconds to minutes) | Long-lived (24/7 or paused) |
+| Surface | A graph of agent CLI calls | A whole open-source application |
+| Billing | Per execution | Per minute, while running |
+| Persistence | Session JSONL + S3 artifacts | Encrypted-at-rest EFS volume |
+| Best for | "When ticket lands, classify it" | "Host n8n for the team" |
+
+If you find yourself wanting to **run an open-source web app behind a stable URL**, that's an App. If you want **agent-driven business logic that fires on events**, that's a Workflow.
+
+## What you get with every app
+
+- **Private subdomain** — `<instance-id>.apps.zibby.dev`, TLS by default
+- **Dedicated EFS volume** — encrypted-at-rest, persists across container restarts and upgrades
+- **Per-instance ALB target group** — your traffic doesn't share a load balancer with other tenants
+- **Per-minute Fargate billing** — including the agent-ops sidecar, pause-to-stop billing
+- **agent-ops sidecar** (see [Agent operator](./agent-ops)) — hourly health checks, self-healing, upgrades
+- **SSE log streaming** — `zibby app logs -t` tails any container from anywhere
+- **Dedicated egress IP addon** — pin outbound HTTPS through one whitelistable IP for self-hosted GitLab / Salesforce / Oracle Cloud
+
+## The catalog
+
+Each marketplace entry is a curated bundle: container image, EFS volume layout, ALB wiring, secrets pattern, resource defaults. Today's catalog:
+
+| App | Category | Tier | Rate |
+|---|---|---|---|
+| **n8n** | Workflow automation | Light | $0.05/hr |
+| **Grafana** | Metrics + dashboards | Light | $0.05/hr |
+| **Gas Town** | Multi-agent workspace | Light | $0.05/hr |
+| **draw.io** | Diagrams + flowcharts | Light | $0.05/hr |
+| **Open WebUI** | ChatGPT-style UI for Ollama | Heavy | $0.25/hr |
+
+`zibby app templates` is the canonical, always-up-to-date list — the table above is a snapshot.
+
+## How tiers work
+
+The catalog groups apps into three resource tiers:
+
+| Tier | CPU | RAM | Rate |
+|---|---|---|---|
+| **Light** | 0.5 vCPU | 1 GB | $0.05/hr |
+| **Standard** | 1 vCPU | 2 GB | $0.12/hr |
+| **Heavy** | 2 vCPU | 4 GB | $0.25/hr |
+
+Per-instance resource overrides are supported when you need to bump CPU / memory for one specific deployment without forking the catalog entry. See [Managing instances → resource overrides](./managing#resource-overrides).
+
+## Pricing model
+
+- **Per-minute Fargate billing** while the instance is running, scoped to the tier above
+- **No flat platform fee** for apps — you pay only for what's running
+- **Pause to stop the meter** — `zibby app destroy` immediately stops billing; redeploy when you need it back (data is gone after destroy; pause-without-destroy is on the roadmap)
+- **Free tier**: $10 in credits on signup, enough to run a Light app for ~8 days
+
+→ Next: [Deploy your first app](./deploy)

package/docs/apps/managing.md

@@ -0,0 +1,121 @@
+---
+sidebar_position: 3
+title: Manage instances
+---
+
+# Operating instances
+
+Every lifecycle action — restart, scale, upgrade, rotate credentials, tear down — is one CLI call. All operations are scoped by **instance ID** (`a1b2c3d4`-style); `zibby app list` shows the ID alongside the display name.
+
+## Inventory
+
+```bash
+zibby app list                            # all instances under your account
+zibby app list --project <project-id>     # scope to one project
+```
+
+```
+ID         Name         App         Tier    Status    Hourly    Uptime
+a1b2c3d4   automations  n8n@1.97.1  Light   running   $0.05/hr  7d 14h
+a8f7e6d5   metrics      grafana     Light   running   $0.05/hr  21d 3h
+b2c3d4e5   webui        open-webui  Heavy   paused    —         —
+```
+
+`paused` instances are not billed; `running` are. `status` is updated every 60s by the agent-ops sidecar.
+
+## Single-instance status
+
+```bash
+zibby app status a1b2c3d4
+```
+
+A one-screen summary: status, resources, hourly rate, public URL, last agent-ops run.
+
+## Logs
+
+```bash
+zibby app logs a1b2c3d4                   # last 200 lines, both containers
+zibby app logs a1b2c3d4 -t                # tail mode, polls every 3s
+zibby app logs a1b2c3d4 --lines 1000      # bigger window
+zibby app logs a1b2c3d4 --json            # raw JSON lines
+zibby app logs a1b2c3d4 --verbose         # full body, no parsing
+```
+
+Logs include both the **app** container and the **agent-ops** sidecar, prefixed by source. Tail mode reconnects automatically on network blips.
+
+## Upgrade (zero-downtime)
+
+```bash
+zibby app upgrade a1b2c3d4
+zibby app upgrade a1b2c3d4 --version 0.1.16   # pin a specific agent-ops version
+```
+
+Behind the scenes:
+
+1. Register a new task definition revision (same image, same volume, same env)
+2. Update the ECS service with the new revision
+3. ALB drains old tasks while new ones come up; the listener serves the new tasks once they pass health checks
+4. Old tasks shut down
+
+A load-bearing n8n stays serving traffic the whole time. `--yes` skips the confirmation prompt for automation.
+
+## Restart
+
+```bash
+zibby app restart a1b2c3d4
+```
+
+Forces the ECS service to roll the current tasks — useful when an app gets wedged on a stuck connection and you don't want a full upgrade.
+
+## Rotate credentials
+
+For BYOK apps (e.g. open-webui pointing at Anthropic via your own key):
+
+```bash
+zibby app update-credential a1b2c3d4
+```
+
+This picks up whatever's currently in your workspace credentials (set via [Settings → Workspace credentials](https://studio.zibby.dev/settings/workspace) or `zibby creds set`) and rolls the task with the new secret env. EFS data is preserved; the task restarts in ~30s.
+
+## ENV vars
+
+Every app instance has a per-instance encrypted env-var bag, same shape as workflow env. Use it for per-instance config (e.g. `N8N_ENCRYPTION_KEY`, `DATABASE_URL` pointing at an external RDS).
+
+Set via the dashboard (Apps → instance → ENV tab) or via CLI:
+
+```bash
+zibby app env list a1b2c3d4
+zibby app env set a1b2c3d4 N8N_HOST=automations.acme.com
+zibby app env unset a1b2c3d4 OLD_FLAG
+```
+
+Changes apply on the next task restart. Use `zibby app restart` to roll immediately.
+
+## Resource overrides
+
+Default resources come from the catalog entry's tier. To bump CPU / memory for one instance:
+
+```bash
+zibby app deploy n8n --project <id> --cpu 1024 --memory 2048   # 1 vCPU / 2 GB
+```
+
+Per-instance overrides survive upgrades; the upgrade flow re-registers the task definition with the same override values unless `--reset-resources` is passed.
+
+## Destroy
+
+```bash
+zibby app destroy a1b2c3d4
+zibby app destroy a1b2c3d4 --yes          # skip confirmation
+```
+
+This:
+
+1. Drains the ECS service (in-flight requests finish)
+2. Deletes the service + task definition revision
+3. Removes the ALB listener rule + target group
+4. Releases the EFS access point — **destroys the volume data permanently**
+5. Stops the billing meter immediately
+
+There's no soft-delete. If you might want the data later, snapshot it externally first (or wait for the pause-without-destroy feature on the roadmap).
+
+→ Next: [Agent operator](./agent-ops)

package/docs/cli-reference.md

@@ -265,6 +265,111 @@ Templates are starter workflow scaffolds. `add` overwrites existing files in pla
 Options on `add`:
 - `--skip-memory` — strip `SKILLS.MEMORY` from copied `execute-live.mjs` (browser-test template only)
 
+## App commands {#app-commands}
+
+`zibby app` manages [Managed App instances](./apps/) — hosted open-source tools (n8n, Grafana, …) with an autonomous agent-ops sidecar. Each verb is keyed by **instance ID** (`a1b2c3d4`-style); `zibby app list` shows IDs alongside display names.
+
+| Command | What it does |
+|---|---|
+| [`zibby app templates`](#app-templates) | Browse the catalog (n8n, grafana, gas-town, drawio, open-webui, …) |
+| [`zibby app list`](#app-list) | List deployed instances under your account |
+| [`zibby app deploy <appType>`](#app-deploy) | Deploy an app from the catalog |
+| [`zibby app status <id>`](#app-status) | One-screen summary: status, resources, URL, last agent-ops run |
+| [`zibby app logs <id>`](#app-logs) | Logs from app + agent-ops, with `-t` tail mode |
+| [`zibby app upgrade <id>`](#app-upgrade) | Zero-downtime roll to the catalog's current image |
+| [`zibby app restart <id>`](#app-restart) | Force ECS service to roll the running tasks |
+| [`zibby app update-credential <id>`](#app-update-credential) | Rotate a BYOK credential and restart |
+| [`zibby app destroy <id>`](#app-destroy) | Tear down service + volume (data permanently deleted) |
+
+### app templates {#app-templates}
+
+```bash
+zibby app templates
+```
+
+Print the live catalog — id, display name, tier, hourly rate, one-line description.
+
+### app list {#app-list}
+
+```bash
+zibby app list                        # all instances under your account
+zibby app list --project <id>         # scope to one project
+```
+
+Options:
+- `--project <id>` — project to scope the listing to (default: all projects your account owns)
+- `--api-key <key>` — API key (or `ZIBBY_API_KEY` env)
+
+### app deploy {#app-deploy}
+
+```bash
+zibby app deploy n8n --project <project-id> --name automations
+```
+
+Options:
+- `--project <id>` — interactive picker if omitted
+- `--name <name>` — display name in the dashboard / `zibby app list` (defaults to `appType`)
+- `--cpu <units>` — Fargate CPU units (e.g. `1024` for 1 vCPU; default from tier)
+- `--memory <mb>` — Fargate memory in MB (e.g. `2048` for 2 GB; default from tier)
+- `--api-key <key>` — API key (or `ZIBBY_API_KEY` env)
+
+Returns an `instanceId` and the public URL.
+
+### app status {#app-status}
+
+```bash
+zibby app status a1b2c3d4
+```
+
+Prints status, resources, hourly rate, public URL, and the latest agent-ops run summary.
+
+### app logs {#app-logs}
+
+```bash
+zibby app logs a1b2c3d4                       # last 200 lines
+zibby app logs a1b2c3d4 -t                    # tail mode, polls every 3s, SSE auto-reconnect
+zibby app logs a1b2c3d4 --lines 1000          # bigger window
+zibby app logs a1b2c3d4 --json                # raw JSON lines
+zibby app logs a1b2c3d4 --verbose             # full line including JSON body
+```
+
+Logs cover **both** containers — the app and the agent-ops sidecar — prefixed by source. Default output is the parsed `<time>  <msg>` summary.
+
+### app upgrade {#app-upgrade}
+
+```bash
+zibby app upgrade a1b2c3d4
+zibby app upgrade a1b2c3d4 --version 0.1.16   # pin a specific agent-ops version
+zibby app upgrade a1b2c3d4 --yes              # skip confirmation
+```
+
+Registers a new task definition revision, updates the ECS service, and lets the ALB drain old tasks before they exit. Zero-downtime for HTTP traffic.
+
+### app restart {#app-restart}
+
+```bash
+zibby app restart a1b2c3d4
+```
+
+Forces the ECS service to roll the current tasks without changing the task definition. Useful when the app gets wedged on a stuck connection.
+
+### app update-credential {#app-update-credential}
+
+```bash
+zibby app update-credential a1b2c3d4
+```
+
+Picks up whatever's currently in your workspace credentials and rolls the task with the new secret env. EFS data is preserved; the task restarts in ~30s. Used by BYOK apps (e.g. Open WebUI pointing at Anthropic via your own key).
+
+### app destroy {#app-destroy}
+
+```bash
+zibby app destroy a1b2c3d4               # interactive confirm
+zibby app destroy a1b2c3d4 --yes         # skip the confirmation prompt
+```
+
+Drains the ECS service, deletes the task definition revision, removes the ALB listener rule + target group, releases the EFS access point (**destroying the volume data permanently**), and stops the billing meter immediately. No soft delete.
+
 ## Environment variables
 
 | Var | Purpose |

package/docs/intro.md

@@ -56,8 +56,20 @@ zibby template add <name>                  # add a template later (overwrites =
 - **Run anywhere** — local with hot reload, or cloud with Heroku-style bundles (~3s cold start).
 - **Session replay** — every run lands as on-disk JSONL + artifacts. Re-run any node via `--session <id> --node <name>`.
 - **Cloud-native** — SSE log streaming, dedicated egress IPs for firewalled GitLab / GitHub Enterprise / Salesforce.
+- **Hosted apps too** — [Managed Apps](./apps/) host open-source tools (n8n, Grafana, Open WebUI, draw.io) with an autonomous agent-ops sidecar that handles health checks, self-healing, and upgrades.
 - **Drive it from your AI agent** — [`@zibby/mcp-cli`](./packages/mcp-cli) exposes deploy / trigger / logs / debug as MCP tools. Add one snippet to Claude Code, Cursor, Codex, or Gemini and they call Zibby directly from chat. See [Use from your AI agent](./get-started/use-from-agents).
 
+## Two product surfaces
+
+| | **Workflows** | **Apps** |
+|---|---|---|
+| Lifetime | Per trigger (seconds-minutes) | Long-lived |
+| Surface | Graph of agent CLI calls | A whole open-source application |
+| Billing | Per execution | Per minute, while running |
+| Best for | "When ticket lands, classify it" | "Host n8n for the team" |
+
+Pick by how long the thing needs to run — see [Apps overview](./apps/) for the decision tree.
+
 ## How it compares
 
 | | Zibby | Claude Code Agent Teams | Devin | Mastra / LangGraph / CrewAI |

package/docs/recipes/index.md

@@ -30,6 +30,7 @@ You don't have to use the recipes. You can build whatever pipeline you want with
 | Recipe | What it does | Best for |
 |---|---|---|
 | [`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 |

package/docs/recipes/sentry-triage.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 3
+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.
+
+```
+fetch_issues  →  classify  →  dispatch_alerts
+(deterministic    (LLM —      (LLM —
+ + Sentry API)    severity)    Slack/Lark, agent-driven routing)
+```
+
+## What it does
+
+1. **fetch_issues** — calls Sentry's REST API for issues unresolved + unassigned + `lastSeen:-60m`. Hydrates each with `suspectCommits[]` (author email from Sentry's GitHub integration) for downstream routing.
+2. **classify** — labels each issue `NOISE | LOW | MEDIUM | HIGH | CRITICAL` based on a configurable rubric (impact metric, surface area, payment paths, security tags). Skips below-threshold issues.
+3. **dispatch_alerts** — the routing brain. Three layers of decisioning:
+   - **Free-form `DISPATCH_RULES`** in env (highest priority) — natural language like *"send to Sam for billing issues"*
+   - **Structured env vars** — `SLACK_CHANNEL`, `ROUTING_PREFER_AUTHOR`, `ROUTING_HIGH_SEVERITY_GROUP`
+   - **Defaults** — channel-only post, threshold `MEDIUM`
+
+The agent uses [`slack_lookup_user_by_email`](../skills/slack), [`slack_list_usergroups`](../skills/slack), [`slack_search_users`](../skills/slack) (or the Lark equivalents) to resolve names → IDs, then `slack_post_message` / `lark_send_message` to deliver. Channel post, user DM, usergroup mention — same agent decides per-issue based on what you wrote in the rules.
+
+## Deploy from the marketplace
+
+```bash
+zibby workflow templates deploy sentry-triage --project <project-id>
+```
+
+Or via the dashboard: `/marketplace/workflows` → Sentry Triage → Deploy.
+
+After deploy, configure ENV (Apps → workflow → ENV tab):
+
+| Env var | Required? | Default | What it does |
+|---|---|---|---|
+| `SLACK_CHANNEL` *or* `LARK_RECEIVE_ID` | Yes (one of) | — | Channel id (Slack `C…`) / chat id (Lark `oc_…`) for fallback posts |
+| `SEVERITY_THRESHOLD` | No | `MEDIUM` | Skip anything below: `NOISE` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` |
+| `ROUTING_PREFER_AUTHOR` | No | `false` | If `true`, when a suspect commit author is known, DM them |
+| `ROUTING_HIGH_SEVERITY_GROUP` | No | — | Slack usergroup handle (`@oncall`) mentioned on CRITICAL/HIGH |
+| `SLACK_MENTIONS` *or* `LARK_MENTIONS` | No | `[]` | JSON array of mentions prepended on CRITICAL only |
+| `DISPATCH_RULES` | No | — | Free-form natural-language override (see below) |
+
+## DISPATCH_RULES — natural-language routing
+
+When you set `DISPATCH_RULES`, the agent treats it as **authoritative**; the structured env vars become fallbacks for things the rules don't cover.
+
+```
+DISPATCH_RULES="
+- CRITICAL bugs in /payment/ → DM Sam and post to #incidents
+- HIGH severity → DM the suspect commit author if known, else post to #engineering
+- Anything mentioning 'security' → also mention the @security usergroup
+- Frontend bugs (zibby-frontend project) → only Sarah, never page on-call
+- NOISE → skip entirely
+"
+```
+
+The agent reads issue metadata (severity, message, tags, suspectCommit author email, project name) and applies rules in order. **Same rule + same issue is deterministic** — temperature 0, schema-enforced output, every dispatch records who got it and why under `dispatched[].recipient.{kind,id,label}`.
+
+## Author-DM path
+
+When `ROUTING_PREFER_AUTHOR=true` and Sentry has a `suspectCommits[0].author.email`:
+
+```
+1. agent reads issue.suspectCommits[0].authorEmail
+2. → slack_lookup_user_by_email(email)
+3a. ✓ returns {id, name}  → slack_post_message(channel: <user-id>, text: …)
+3b. ✗ users_not_found     → channel fallback
+```
+
+Requires the [Sentry → GitHub integration](https://sentry.io/settings/integrations/github/) installed and Code Mappings configured. Without it, `suspectCommits[]` is empty and the agent falls back to channel-only routing automatically.
+
+If you deployed your backend with `RELEASE_SHA` Sentry release-tracking on, suspect commits populate within ~minutes of new issues being created. (The platform-side wiring — `Sentry.init({release})` + `sentry-cli releases set-commits --auto` at deploy time — is what makes per-issue blame work; without it, every issue lands with `suspectCommits: []`.)
+
+## Customize the prompts
+
+Each node's prompt lives in its own module — fork the template, edit, redeploy:
+
+```bash
+zibby workflow download <uuid>
+# edit nodes/dispatch-node.js
+zibby workflow 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).
+
+→ Next: [`zibby test`](./test) (the browser-testing recipe) or [Build your own workflow](../get-started/your-first-workflow).