@zibby/skills 0.1.26 → 0.1.28

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).

package/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",
@@ -8,6 +8,7 @@
     ".": "./dist/index.js",
     "./bin/mcp-sentry.mjs": "./bin/mcp-sentry.mjs",
     "./bin/mcp-lark.mjs": "./bin/mcp-lark.mjs",
+    "./bin/mcp-slack.mjs": "./bin/mcp-slack.mjs",
     "./browser": "./dist/browser.js",
     "./jira": "./dist/jira.js",
     "./github": "./dist/github.js",