@zibby/skills 0.2.22 → 0.2.24

package/docs/apps/deploy.md

@@ -1,207 +0,0 @@
----
-sidebar_position: 2
-title: Deploy your first app
----
-
-# Deploy your first app
-
-A complete walk-through — from `zibby app templates` to a running instance behind a stable URL — in under two minutes.
-
-## 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 an agent 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
-grafana         Grafana                 Light       $0.05/hr      Dashboards for metrics, logs, traces.
-uptime-kuma     Uptime Kuma             Light       $0.05/hr      Self-hosted Pingdom-alt.
-drawio          draw.io                 Light       $0.05/hr      Client-side diagram editor.
-gastown         Gas Town                Light       $0.05/hr      Multi-agent workspace.
-open-webui      Open WebUI              Heavy       $0.25/hr      ChatGPT-style UI for Ollama / OpenAI.
-openhands       OpenHands               Heavy       $0.25/hr      AI software-engineer agent (V1).
-docmost         Docmost                 Heavy       $0.25/hr      Wiki + collaboration (multi-service).
-… (20 entries total — see `zibby app templates` for the full list)
-```
-
-## Deploy from the catalog
-
-```bash
-zibby app deploy grafana --project <project-id> --name metrics
-```
-
-On success:
-
-```
-↑ Provisioning grafana 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(s) + your resource tier; one container per `services[]` entry for multi-service apps
-4. **Spin up ECS service** — desired count 1, agent-ops sidecar bundled alongside the app container(s)
-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 for catalog deploys. The CLI streams progress and prints the public URL the moment the ALB is responsive.
-
-## Verify
-
-```bash
-zibby app status a1b2c3d4
-```
-
-```
-● metrics (grafana v10.4.2)
-┌ 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 — Grafana's login screen renders, you sign in with the default `admin / admin` (and immediately rotate it — or better, follow the next section and put basic auth in front of the whole thing). The data sits on the EFS volume, encrypted and isolated; no other Zibby customer can reach it.
-
-## Deploying with auth from day one
-
-Most self-hosted dashboards (Grafana, Uptime Kuma, n8n on the free tier) either have weak default credentials or no app-level auth at all. The fix is the **auth proxy** — opt in at deploy time and a Caddy sidecar fronts the ALB:
-
-```bash
-zibby app deploy grafana \
-  --project <project-id> \
-  --name metrics \
-  --auth-type basic \
-  --auth-user admin \
-  --auth-password 'S0me-long-passphrase!'
-```
-
-Verify it sticks:
-
-```bash
-curl -I https://a1b2c3d4.apps.zibby.dev
-# HTTP/2 401  ← unauthenticated request is bounced by Caddy
-
-curl -I -u 'admin:S0me-long-passphrase!' https://a1b2c3d4.apps.zibby.dev
-# HTTP/2 302  ← Grafana sees the request and redirects to /login
-```
-
-Token-based auth is also supported (for webhook receivers, machine-to-machine access):
-
-```bash
-zibby app deploy gotify --project <id> --name notify --auth-type token
-# Backend auto-generates a 32-char URL-safe token and prints it ONCE.
-```
-
-You can also pass `--auth-token <yours>` to use your own value. Full details + the password-rotation flow are in [Auth proxy](./auth).
-
-## Deploying anything else (goal-mode)
-
-If the app you want isn't in the catalog — or its license forbids us shipping a one-click bundle — use **goal-mode**. You describe the install in plain English, Claude writes a bash script, agent-ops runs and supervises it inside the container until the app is responding on a port.
-
-```bash
-zibby app deploy --goal "Install n8n on port 5678 with sqlite persistence" \
-  --project <project-id> \
-  --name automations \
-  --max-turns 40 \
-  --timeout-min 30
-```
-
-Output streams the planner's progress + the supervisor's verdicts every ~30s:
-
-```
-↑ Goal-mode deploy: "Install n8n on port 5678 with sqlite persistence"
-  phase 1: planning install script (Claude write+read tools)…
-  phase 2: executing /tmp/install.sh under supervision…
-    [30s ] supervisor: continue — npm install in progress
-    [60s ] supervisor: continue — npm install complete, starting n8n
-    [90s ] auto-short-circuit: process exit 0, port 5678 returns 200
-✔ Deployed (instanceId: f1e2d3c4)
-→ Public URL: https://f1e2d3c4.apps.zibby.dev
-```
-
-License terms of whatever you install are yours, not Zibby's — same model as deploying on your own EC2. Full architecture + cost expectations: [Goal-mode deploys](./goal-mode).
-
-## Choosing your model
-
-Goal-mode deploys (and the cheatsheet-mode catalog entries that have a planner step) call Claude inside the container. You can pick which model:
-
-```bash
-zibby app deploy --goal "..." --model claude-sonnet-4-6
-zibby app deploy --goal "..." --model claude-opus-4-8     # heavier installs
-zibby app deploy --goal "..." --model claude-haiku-4-5-20251001  # cheaper, faster
-```
-
-Rule of thumb:
-
-- **Sonnet** (default) — most installs fit. Good speed/cost balance.
-- **Opus** — bump up for installs that hit lots of intervene loops (heavy native compilation, weird init systems, anything where the first plan tends to be wrong).
-- **Haiku** — fine for installs you've already run once and know are reliable.
-
-Token spend per deploy is typically $0.05 - $0.30 on Sonnet. Opus can go to ~$1.00 on a deploy that takes 5 intervene iterations.
-
-## 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 [grafana]    Listening on port 3000
-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
-```
-
-For multi-service apps (e.g. docmost), scope to one container with `--service`:
-
-```bash
-zibby app logs <id> -t --service db        # just the postgres container
-zibby app logs <id> -t --service web       # just the docmost web container
-```
-
-`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/goal-mode.md

@@ -1,175 +0,0 @@
----
-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. An Anthropic API key (`sk-ant-api03-…`). 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

@@ -1,149 +0,0 @@
----
-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 22-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 agents)
-
-Both are pillars of Zibby Cloud. Pick by **how long the thing needs to run**:
-
-| | **Agent** | **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 an [Agent](../recipes/).
-
-## 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 **22 apps**. Run `zibby app templates` for the canonical, always-up-to-date list with live tier + hourly rate — the sample below is a snapshot, grouped by what each app is for.
-
-### AI
-
-| App | What it does |
-|---|---|
-| **Open WebUI** | ChatGPT-style UI for Ollama / OpenAI-compatible endpoints |
-| **OpenHands** | AI software-engineer agent — drives the repo end-to-end, GitHub PR workflows |
-| **Gas Town** | Multi-agent workspace — coordinate Claude, Codex, Cursor, Gemini |
-| **Open Design** | Local-first design-artifact generator via your installed coding-agent CLIs |
-| **Plane** | Self-hosted Jira / Linear alternative — issues, cycles, modules, pages |
-
-### Automation
-
-| App | What it does |
-|---|---|
-| **Activepieces** | Open-source Zapier alternative — visual automation, 400+ MCP servers |
-| **ChangeDetection.io** | Watch any web page for changes — notifies on diff |
-| **Gotify** | Self-hosted push-notification + webhook server |
-
-### Data + APIs
-
-| App | What it does |
-|---|---|
-| **PostgREST** | Serverless REST API on top of any Postgres schema |
-| **Mathesar** | Spreadsheet-style web UI for Postgres |
-| **PocketBase** | Single-file backend — SQLite + REST + realtime + auth + admin UI |
-
-### Productivity + docs
-
-| App | What it does |
-|---|---|
-| **Docmost** | Real-time collaborative wiki (multi-service: web + Postgres + Redis) |
-| **SiYuan** | Privacy-first, block-based note-taking / PKM, local-first |
-| **draw.io** | Client-side diagram editor (flowcharts, UML, ER, network) |
-| **Glance** | Self-hosted homepage / dashboard with a feed of RSS, GitHub, monitors |
-| **Homepage** | Self-hosted dashboard with service integrations + bookmarks |
-
-### Observability
-
-| App | What it does |
-|---|---|
-| **Grafana** | Dashboards for metrics, logs, traces |
-| **OpenObserve** | Petabyte-scale logs + metrics + traces in one binary |
-| **Uptime Kuma** | Self-hosted uptime monitor + status page |
-| **Beszel** | Lightweight server monitor with historical charts |
-
-### Identity
-
-| App | What it does |
-|---|---|
-| **Authentik** | Self-hosted SSO / IdP (OAuth/SAML/LDAP) |
-| **ZITADEL** | Cloud-native identity + access management (OAuth2/OIDC/SAML/LDAP) |
-
-`zibby app templates` is the canonical, always-up-to-date list — the tables above are a snapshot, and the live command is the source of truth for each app's tier and hourly rate.
-
-### 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

@@ -1,121 +0,0 @@
----
-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 agent 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)