@zibby/skills 0.1.27 → 0.1.29

package/docs/apps/goal-mode.md

@@ -0,0 +1,175 @@
+---
+sidebar_position: 6
+title: Goal-mode deploys
+---
+
+# Goal-mode deploys
+
+**Describe what you want. Get a deployment.**
+
+Goal-mode is `zibby app deploy --goal "..."` — a free-form natural-language install path for any app not in the catalog. Claude writes the bash, agent-ops runs and supervises it inside the container, and you get back a stable HTTPS URL pointing at a running app, encrypted EFS volume and all.
+
+```bash
+zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence" \
+  --project <project-id> \
+  --name automations
+```
+
+That's it. ~5 minutes wall-clock on a healthy run, $0.05-$0.30 in Claude tokens, and you have n8n.
+
+## When goal-mode works well
+
+- The install fits in **30 min wall-clock and 8 GB RAM**. (Most things: anything pip / npm / cargo / apt / single Docker run. Not things that need to compile LLVM from source.)
+- The app exposes a **single HTTP port** for verification. (Multi-port apps work — agent-ops just verifies the main one.)
+- You're OK with the app running on a fresh ephemeral EFS volume. (No "restore from my existing database" — start the customer's data flow yourself, post-deploy.)
+- The upstream has a **documented install path**. Random unmaintained GitHub repos with no README work less well than mainstream projects.
+
+If your install needs more than that — long compile steps, custom kernel modules, a 50 GB pre-trained model download — bring your own host. Goal-mode isn't trying to replace EC2.
+
+## How it works
+
+```
+zibby app deploy --goal "Install n8n on port 5678 ..."
+       │
+       ▼
+backend POST /apps:
+  - extracts verify port from "on port NNNN" (sniffs goal text)
+  - splices AGENT_OPS_BOOTSTRAP_MODE=agent_script
+  - splices BOOTSTRAP_PROMPT=<your goal text>
+  - splices customer's BYOK Claude token (env or --anthropic-token)
+  - splices model / max-turns / timeout / token-budget flags
+  - splices AGENT_OPS_BOOTSTRAP_SYSTEM_RULES (curated house rules)
+  - defaults to 4 vCPU / 8 GB Fargate (heavier than the catalog tiers,
+    because installs are CPU-spiky)
+       │
+       ▼
+container starts. agent-ops runs the agent_script loop:
+
+  ┌── Phase 1: PLAN ─────────────────────────────────────────────┐
+  │ Claude with Write+Read tools only — no Bash, no Edit.        │
+  │ Reads your goal + house rules. Writes one complete bash      │
+  │ script to /tmp/install.sh. ~2 turns, ~$0.05.                 │
+  └──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+  ┌── Phase 2: SUPERVISE LOOP ───────────────────────────────────┐
+  │ agent-ops execs /bin/bash /tmp/install.sh in a process group │
+  │ (so we can kill the whole tree on intervene).                │
+  │                                                               │
+  │ Every 30s:                                                   │
+  │   - snapshot stdout/stderr tail + proc status + idle time    │
+  │   - send to Claude (text-only, no tools)                     │
+  │   - Claude returns one JSON line:                            │
+  │       {"verdict":"continue","note":"..."}                    │
+  │       {"verdict":"done","note":"app responding on :5678"}    │
+  │       {"verdict":"intervene","reason":"...","note":"..."}    │
+  │                                                               │
+  │ continue: log progress, keep polling                         │
+  │ done:     write success, leave the nohup'd app running       │
+  │ intervene: SIGTERM the pgroup, 5s grace, SIGKILL, replan     │
+  │                                                               │
+  │ Auto-short-circuit: if proc EXITED with code 0 AND verify    │
+  │ port returns 2xx-499, agent-ops declares done without        │
+  │ asking the supervisor. Stops false-positive intervenes when  │
+  │ the app went into the background and Claude can't see its    │
+  │ "startup logs" in the snapshot anymore.                      │
+  └──────────────────────────────────────────────────────────────┘
+                              │
+              intervene? ───→ back to Phase 1, with stderr +
+                              stdout + exit code as new context.
+                              Claude REWRITES the script (not patches).
+                              Phase 2 starts fresh.
+                              │
+                              ▼
+  Hard caps (whichever hits first):
+    - 5 iterations
+    - 30 min wall-clock (configurable via --timeout-min)
+    - $1.00 token budget
+```
+
+Every iteration's script + supervisor turns + final status are persisted under `/var/lib/agent-ops/agent_script-state/` on the per-instance EFS volume. `zibby app logs <id>` surfaces the supervisor verdicts in real time; the persisted state is there for post-mortems.
+
+## CLI flags
+
+The flags that matter for goal-mode:
+
+| Flag | What |
+|---|---|
+| `--goal "<text>"` | Free-form install description. Mutually exclusive with `[appType]`. |
+| `--model <name>` | Claude model — `claude-sonnet-4-6` (default), `claude-opus-4-8` (heavier installs), `claude-haiku-4-5-20251001` (cheaper). |
+| `--max-turns <n>` | Claude subprocess max turns, 1-200 (default 25). Bump for heavy installs (n8n, OpenHands) that need many supervisor checks. |
+| `--timeout-min <n>` | Bootstrap wall-clock minutes, 1-120 (default 30). |
+| `--anthropic-token <token>` | Per-deploy Claude credential override. Starts `sk-ant-oat01-` (OAuth) or `sk-ant-api03-` (API key). Also accepts `ZIBBY_ANTHROPIC_TOKEN` env. Falls back to workspace credentials if absent. |
+| `--name <name>` | Display name for `zibby app list` / dashboard. |
+| `--auth-type / --auth-user / --auth-password / --auth-token` | Optional Caddy auth sidecar in front of the installed app. See [Auth proxy](./auth). |
+
+Goal-mode tasks default to **4 vCPU / 8 GB** Fargate — heavier than catalog tiers — because `npm install -g n8n` and friends are CPU/memory spiky. You can still pass `--cpu` / `--memory` to override.
+
+## Cost expectations
+
+Per goal-mode deploy:
+
+- **Compute** — 5-15 min of 4 vCPU / 8 GB Fargate at standard Fargate pricing. Single-digit cents per deploy.
+- **Claude tokens** — typically $0.05-$0.30 on Sonnet (the default). Opus-4-8 can hit $1.00 if the install takes 4-5 intervene iterations. Hard-capped at $1.00 by agent-ops — beyond that the deploy fails.
+- **Ongoing** — once the app is running, the deploy is exactly like any catalog app: per-minute Fargate billing at the resource tier you ended up with. No Claude tokens spent after the install converges.
+
+Practical: budget $0.20 - $0.50 per goal-mode deploy attempt, including failed ones. Re-runs after a fix are cheaper because the planner gets shorter context.
+
+## When it converges, when it loops
+
+It converges fast when:
+
+- The install is a single package manager call + a config file + a port to listen on.
+- The app's own README has the exact install steps in a copy-pasteable block.
+- You include the port in your goal (`"on port 5678"`) — saves the planner a guess.
+
+It loops or fails when:
+
+- The install needs interactive prompts and the planner forgets to `apt-get install -y` / `DEBIAN_FRONTEND=noninteractive`.
+- The app needs a sister service (Postgres + Redis + web) and you didn't tell it. Goal-mode does one task; for multi-service, prefer a [catalog multi-service entry](./index#multi-service-entries) or split into multiple deploys.
+- The download is huge (multi-GB models) and times out the 30-min wall-clock. Use `--timeout-min 60` if you know that's coming.
+
+If it fails, the supervisor verdicts in the logs tell you exactly what went wrong on each iteration — paste the goal + the failure output back into the next `--goal "..."` with a hint and it usually converges.
+
+## License responsibility
+
+Goal-mode is intentionally a different licensing posture from the catalog:
+
+- **Catalog apps** — Zibby pre-cleared the license. We're confident we can ship that bundle as a paid host.
+- **Goal-mode** — **you** are directing the install. You named the upstream project, you accepted whatever license terms apply, you decided to run it on infrastructure you're paying for. Same model as deploying it on your own EC2 instance — Zibby is the compute provider, not the redistributor.
+
+This is why n8n (Sustainable Use License — forbids paid commercial hosting by a third party) isn't in the catalog but **can** be installed via goal-mode: when you direct the install, you're the operator. The SUL is between you and n8n GmbH, not between Zibby and them.
+
+If you're unsure whether your install is fine for goal-mode, read the upstream license. If it requires you-as-the-operator to accept terms before running it, you're the one accepting — make sure that's a thing you're allowed to do for your use case.
+
+## Worked example: n8n
+
+```bash
+zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence" \
+  --project <project-id> \
+  --name automations \
+  --max-turns 40
+```
+
+Streaming output (abbreviated):
+
+```
+↑ Goal-mode deploy: "Install n8n on port 5678 with sqlite persistence"
+  Fargate task: 4 vCPU / 8 GB
+  model: claude-sonnet-4-6, max-turns: 40, timeout: 30 min
+  phase 1: planning install script…
+    plan turn 1/40: reading house rules
+    plan turn 2/40: wrote /tmp/install.sh (47 lines)
+  phase 2: executing /tmp/install.sh under supervision…
+    [30s ] supervisor: continue — apt-get update in progress
+    [60s ] supervisor: continue — installing nodejs 20 from nodesource
+    [120s] supervisor: continue — npm install -g n8n (compiling sqlite3)
+    [240s] supervisor: continue — n8n starting, binding to :5678
+    [270s] auto-short-circuit: process exit 0, port 5678 returns 200
+✔ Deployed (instanceId: f1e2d3c4)
+→ Public URL: https://f1e2d3c4.apps.zibby.dev
+```
+
+Total: ~4.5 min, 1 iteration, $0.07 in Claude tokens. Open the URL, set up your n8n admin account, you're done.
+
+→ Next: [Auth proxy](./auth) (put basic auth in front of the install you just did) or [Agent operator](./agent-ops) (how the supervise loop works in detail)

package/docs/apps/index.md

@@ -0,0 +1,146 @@
+---
+sidebar_position: 1
+title: Apps overview
+---
+
+# Managed Apps
+
+Long-lived, per-tenant containers running open-source tools — each behind a stable HTTPS URL, on encrypted EFS, 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 grafana          # 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
+```
+
+## Two paths to a deployment
+
+There are two ways to land a container on the apps fleet, and you pick by **whether the thing you want is in our catalog**:
+
+| | **Catalog** | **Goal-mode** |
+|---|---|---|
+| Trigger | `zibby app deploy <slug>` | `zibby app deploy --goal "..."` |
+| Source | Curated bundle (image + EFS layout + defaults) | Free-form natural-language install |
+| Time-to-live | ~45-90 s | 2-15 min (Claude writes + runs the install script) |
+| Licensing | Pre-cleared by Zibby | You direct the install; you accept the upstream license |
+| Best for | Anything in the 20-app catalog | n8n, random GitHub project, anything not in the catalog |
+
+Both paths land in the same shape — Fargate task, per-instance EFS volume, ALB target group, agent-ops sidecar — and look identical to every downstream `zibby app logs/status/upgrade` command. The only difference is **who wrote the install recipe**.
+
+See [Goal-mode deploys](./goal-mode) for the long form.
+
+## 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 Grafana 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
+- **Optional auth proxy** — `--auth-type basic|token` puts a Caddy sidecar in front of the app (see [Auth proxy](./auth))
+- **Dedicated egress IP addon** — pin outbound HTTPS through one whitelistable IP for self-hosted GitLab / Salesforce / Oracle Cloud
+
+## The catalog
+
+Each catalog entry is a curated bundle: container image, EFS volume layout, ALB wiring, secrets pattern, resource defaults. Today's catalog is **20 apps**, grouped by what they're for:
+
+### AI
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **Open WebUI** | Heavy | $0.25/hr | ChatGPT-style UI for Ollama / OpenAI-compatible endpoints |
+| **OpenHands** | Heavy | $0.25/hr | AI software-engineer agent (V1) |
+| **Gas Town** | Light | $0.05/hr | Multi-agent workspace — coordinate Claude, Codex, Cursor, Gemini |
+
+### Data + APIs
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **PostgREST** | Standard | $0.10/hr | Auto-generated REST API on top of any Postgres schema |
+| **Mathesar** | Heavy | $0.25/hr | Spreadsheet-style front-end for Postgres |
+| **PocketBase** | Light | $0.05/hr | Single-file backend (Auth + DB + file storage + realtime) |
+
+### Knowledge + docs
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **Docmost** | Heavy | $0.25/hr | Wiki + collaboration (multi-service: web + Postgres + Redis) |
+| **SiYuan** | Heavy | $0.25/hr | Notion-like knowledge base, local-first |
+| **draw.io** | Light | $0.05/hr | Diagrams + flowcharts (client-side editor) |
+
+### Monitoring + observability
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **Grafana** | Light | $0.05/hr | Dashboards for metrics, logs, traces |
+| **OpenObserve** | Heavy | $0.25/hr | Unified logs + metrics + traces |
+| **Uptime Kuma** | Light | $0.05/hr | Self-hosted Pingdom-alt |
+| **Beszel** | Light | $0.05/hr | Lightweight single-host server monitor |
+| **ChangeDetection.io** | Standard | $0.10/hr | Web-page change watcher |
+
+### Identity
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **Authentik** | Heavy | $0.25/hr | SSO / IdP |
+| **Zitadel** | Heavy | $0.25/hr | SSO / IdP (alt) |
+
+### Productivity
+
+| App | Tier | Rate | What it does |
+|---|---|---|---|
+| **Glance** | Light | $0.05/hr | Personal dashboard |
+| **Homepage** | Standard | $0.10/hr | Self-hosted homepage / app launcher |
+| **Gotify** | Light | $0.05/hr | Self-hosted push-notification + webhook server |
+
+`zibby app templates` is the canonical, always-up-to-date list — the table above is a snapshot.
+
+### Multi-service entries
+
+A catalog entry can declare more than one container in the same task — useful for apps that need a DB + cache alongside the web tier. **Docmost** is the live example: web + `postgres:16-alpine` + `redis:7-alpine` sharing localhost and per-volume EFS access points. You don't have to think about it — `zibby app deploy docmost` reads identically — but `zibby app logs --service db` lets you scope log tails to one container.
+
+### Not in the catalog? Use goal-mode
+
+The catalog only includes apps whose licenses permit Zibby (a paid host) to ship them as a one-click bundle. Apps under the Sustainable Use License — most famously **n8n** — aren't in the catalog because the SUL forbids paid commercial hosting. They can still be deployed via goal-mode:
+
+```bash
+zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence"
+```
+
+The customer (you) is directing the install — Zibby just provides compute. License terms of whatever you install are between you and the upstream project. See [Goal-mode deploys](./goal-mode).
+
+## 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.10/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). Goal-mode deploys default to 4 vCPU / 8 GB to give the install agent enough headroom.
+
+## 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   wiki         docmost     Heavy   running   $0.25/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 Grafana 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 grafana --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,176 @@ 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 (Grafana, Open WebUI, Docmost, OpenHands, and 16 more in the catalog, plus anything you install via [goal-mode](./apps/goal-mode)) 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 (grafana, uptime-kuma, open-webui, openhands, docmost, …) |
+| [`zibby app list`](#app-list) | List deployed instances under your account |
+| [`zibby app deploy <appType>`](#app-deploy) | Deploy an app from the catalog, or `--goal "..."` for free-form goal-mode |
+| [`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; `--service <name>` to scope multi-service |
+| [`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 set-auth <id>`](#app-set-auth) | Add / rotate / remove the optional Caddy auth proxy |
+| [`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 grafana --project <project-id> --name metrics
+zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence" --project <id> --name automations
+```
+
+Two modes:
+
+- **Catalog**: pass an `appType` (slug from `zibby app templates`).
+- **Goal-mode**: pass `--goal "<install description>"` instead of `appType`. Claude writes the install script and agent-ops runs it under supervision inside the container. See [Goal-mode deploys](./apps/goal-mode).
+
+Options:
+
+- `--project <id>` — interactive picker if omitted
+- `--name <name>` — display name in the dashboard / `zibby app list` (defaults to `appType`)
+- `--provider <name>` — `claude` (default) or `codex` — picks which BYOK credential to inject
+- `--arch <name>` — `x86_64` or `arm64` (defaults to catalog's first listed arch)
+- `--api-key <key>` — Zibby API key (or `ZIBBY_API_KEY` env)
+- `--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)
+
+Goal-mode + planner options (used by `--goal` deploys and cheatsheet-mode catalog entries):
+
+- `--goal "<text>"` — free-form install description. Mutually exclusive with `[appType]`.
+- `--model <name>` — Claude model identifier. E.g. `claude-sonnet-4-6` (default), `claude-opus-4-8`, `claude-haiku-4-5-20251001`. Overrides the agent-ops bootstrap default.
+- `--anthropic-token <token>` — per-deploy Claude credential override. Must start `sk-ant-oat01-` (OAuth) or `sk-ant-api03-` (API key). SENSITIVE. Also accepts `ZIBBY_ANTHROPIC_TOKEN` env. Falls back to workspace credentials if absent.
+- `--max-turns <n>` — Claude subprocess max turns, 1-200 (default 25). Bump for heavy installs.
+- `--timeout-min <n>` — bootstrap wall-clock minutes, 1-120 (default 30).
+
+Auth proxy options (opts into a Caddy sidecar on port 8888 — see [Auth proxy](./apps/auth)):
+
+- `--auth-type <kind>` — `basic`, `token`, or `none` (default `none`).
+- `--auth-user <name>` — required for `--auth-type basic`. Printable ASCII, no spaces, 1-64 chars.
+- `--auth-password <pass>` — required for `--auth-type basic`. SENSITIVE. 8-256 chars. Also accepts `ZIBBY_APP_AUTH_PASSWORD` env.
+- `--auth-token <token>` — optional for `--auth-type token`. If omitted, backend auto-generates a 32-char URL-safe token and returns it ONCE on deploy. Also accepts `ZIBBY_APP_AUTH_TOKEN` env.
+
+Returns an `instanceId` and the public URL. If `--auth-type token` was used without `--auth-token`, the generated token is included in the response and shown ONCE — save it then, you can't retrieve it later.
+
+### 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
+zibby app logs a1b2c3d4 -t --service db       # scope to one container in a multi-service entry
+```
+
+Logs cover **all** containers in the task — the app(s), the agent-ops sidecar, and (if enabled) the Caddy auth proxy — prefixed by source. Default output is the parsed `<time>  <msg>` summary.
+
+Options:
+
+- `-t, --follow` — live tail
+- `--lines <n>` — initial window size (default 200)
+- `--json` / `--verbose` — output format toggles
+- `--service <name>` — scope to one container by name (e.g. `db` on docmost). Useful for multi-service catalog entries.
+
+### 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 set-auth {#app-set-auth}
+
+Add, rotate, or remove the [Caddy auth proxy](./apps/auth) on an existing instance.
+
+```bash
+# Add basic auth to a previously-unauthenticated instance
+zibby app set-auth a1b2c3d4 --auth-type basic --auth-user admin --auth-password 'S0me-long-passphrase!'
+
+# Rotate just the password (basic auth must already be on)
+zibby app set-auth a1b2c3d4 --auth-password 'N3w-passphrase-2026!'
+
+# Switch from basic to token auth (caller-supplied)
+zibby app set-auth a1b2c3d4 --auth-type token --auth-token "$(cat ~/.secrets/bearer.txt)"
+
+# Switch to token auth with a freshly-generated token (returned ONCE in response)
+zibby app set-auth a1b2c3d4 --auth-type token
+
+# Strip auth entirely — Caddy container is removed; ALB routes straight to the app
+zibby app set-auth a1b2c3d4 --off
+```
+
+PATCH semantics: omitted flags preserve current state. Triggers an ECS rolling task replace (~60-90s); the app container keeps its EFS data, only the proxy config / container set changes.
+
+Options:
+
+- `--auth-type <kind>` — `basic`, `token`, or `none`
+- `--auth-user <name>` — required when setting `--auth-type basic`
+- `--auth-password <pass>` — set / rotate the basic-auth password. Also accepts `ZIBBY_APP_AUTH_PASSWORD` env.
+- `--auth-token <token>` — set / rotate the bearer token. If `--auth-type token` is set without this flag, backend generates a 32-char URL-safe token and returns it once. Also accepts `ZIBBY_APP_AUTH_TOKEN` env.
+- `--off` — remove auth entirely. Equivalent to `--auth-type none`.
+- `--yes` — skip confirmation prompt.
+
+### 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 (Grafana, Open WebUI, Docmost, Uptime Kuma, Authentik, …) from a curated catalog, OR deploy anything else via natural-language [goal-mode](./apps/goal-mode). Every instance ships 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 Grafana 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 |