@zibby/skills 0.2.22 → 0.2.24

package/docs/running-tests.md

@@ -1,134 +0,0 @@
----
-sidebar_position: 5
-title: Running Tests
----
-
-# Running Tests
-
-Zibby runs tests locally using an AI agent that drives a real browser. It records video, captures actions, and generates reusable Playwright scripts.
-
-## Basic Usage
-
-```bash
-zibby test test-specs/login.txt --agent cursor
-```
-
-## From a Test Spec File
-
-Create a plain-text file with test steps:
-
-```text title="test-specs/login.txt"
-1. Navigate to the login page
-2. Enter email: test@example.com
-3. Enter password: TestPass123
-4. Click the Sign In button
-5. Verify the dashboard page loads
-6. Verify the user's name appears in the header
-```
-
-Run it:
-
-```bash
-zibby test test-specs/login.txt
-```
-
-## From Cloud Test Cases
-
-After running analysis on a Jira ticket in the dashboard:
-
-```bash
-zibby test --sources TC001,TC002 --execution abc-123-def --sync
-```
-
-## What Happens During a Run
-
-The default workflow executes three nodes:
-
-1. **Preflight** — AI extracts a title and assertions from the test spec
-2. **Execute Live** — AI drives a Playwright browser, following the test steps
-3. **Generate Script** — AI produces a reusable `.spec.js` from recorded actions
-
-```
-Test Spec → Preflight → Execute Live → Generate Script → Done
-```
-
-## Choosing an AI Agent
-
-```bash
-# Cursor Agent (uses Cursor IDE or CURSOR_API_KEY)
-zibby test test-specs/login.txt --agent cursor
-
-# Claude (uses ANTHROPIC_API_KEY)
-zibby test test-specs/login.txt --agent claude
-
-# Codex (uses OPENAI_API_KEY + codex CLI)
-zibby test test-specs/login.txt --agent codex
-```
-
-## Headless Mode
-
-Run without a visible browser (for CI/CD):
-
-```bash
-zibby test test-specs/login.txt --headless
-```
-
-## Cloud Sync
-
-Upload results to the [Zibby dashboard](https://zibby.app):
-
-```bash
-# Upload to dashboard
-zibby test test-specs/login.txt --sync
-
-# Organize into a collection
-zibby test test-specs/login.txt --collection "Auth Tests" --sync
-
-# With subfolder
-zibby test test-specs/login.txt --collection "Auth Tests" --folder "Login" --sync
-
-# Local only (no upload)
-zibby test test-specs/login.txt --no-sync
-```
-
-The `cloudSync` setting in `.zibby.config.js` sets the default. CLI flags override it.
-
-## Running a Single Node
-
-Re-run just one step of the workflow (useful for debugging):
-
-```bash
-# Re-execute the browser test (reusing previous session)
-zibby test test-specs/login.txt --node execute_live --session last
-
-# Only regenerate the Playwright script
-zibby test test-specs/login.txt --node generate_script --session last
-```
-
-## Custom Workflows
-
-If you've created a custom workflow in `.zibby/graph.js`:
-
-```bash
-zibby test test-specs/login.txt --workflow QuickSmokeWorkflow
-```
-
-Supported formats: `QuickSmokeWorkflow`, `QuickSmoke`, `quick-smoke`.
-
-## Opening Results in Browser
-
-```bash
-zibby test test-specs/login.txt --sync --open
-```
-
-The `--open` flag opens the dashboard results page after upload.
-
-## Debugging
-
-```bash
-# Info-level logs
-zibby test test-specs/login.txt --verbose
-
-# Full debug logs
-zibby test test-specs/login.txt --debug
-```

package/docs/self-host/backup-restore.md

@@ -1,53 +0,0 @@
----
-sidebar_position: 3
-title: Backup & restore
----
-
-# Backup & restore
-
-`backup.sh` and `restore.sh` ship next to the compose file in your install directory (the installer drops them there). Together they let a dead VM — or a fat-fingered `docker compose down -v` — never mean "start over and reconnect 50 repos".
-
-## What a backup contains
-
-One timestamped tarball holds the four things that together **are** your install:
-
-1. **ScyllaDB volume** (`scylla-data`) — all metadata: integrations + their encrypted connect tokens, deployed agents (graph/env/schedule/prompts), repo→agent links, projects, members, access tokens, review-memory, execution history, stores.
-2. **Object-store volume** — `seaweed-data` (SeaweedFS, the default) or `minio-data` on a legacy box. Run artifacts + per-node logs, datasets, marketplace icons. The active store is detected from `.env` (`ZIBBY_OBJECT_STORE`) / volume presence; `restore.sh` handles either.
-3. **Sidecar data volumes** (`zibby-sidecar-*-data`) — content that exists **nowhere else** and cannot be re-derived: a knowledge base's indexed documents, a sidecar's encrypted OAuth token store. They are discovered by convention, so a sidecar you add later — including one you brought yourself — is included with no configuration. Skip them with `--skip-sidecar-data` (or `ZIBBY_BACKUP_SIDECAR_DATA=false` for scheduled backups) if the size is a real problem; those sidecars then restore **empty**, and `restore.sh` says so out loud.
-4. **`.env`** — **critical**. It holds `ENCRYPTION_KEY`, without which every encrypted token/secret in ScyllaDB is unrecoverable, plus `JWT_SECRET`, the object-store root creds, and integration tokens. A ScyllaDB restore without the matching `ENCRYPTION_KEY` is useless, so `.env` travels **inside** the backup — which is also why the backup is highly sensitive.
-
-## Take a backup
-
-```bash
-cd zibby-selfhosted
-./backup.sh                         # → ./backups/zibby-selfhosted-<timestamp>.tar.gz
-./backup.sh --out /mnt/backups      # write elsewhere
-./backup.sh --encrypt               # encrypt at rest with age or gpg (prompts for a passphrase)
-./backup.sh --s3 s3://mybucket/zibby   # also upload with YOUR aws creds (nothing goes to Zibby)
-```
-
-Consistency + downtime: for a single-VM box the safe, simple approach wins — the script briefly **stops the writers** (control-plane + datastores + any running sidecars, whose single-writer file databases would otherwise be captured mid-write), `nodetool flush`es Scylla so the commitlog is on disk, tars the volumes read-only from a throwaway helper container, then restarts everything. Downtime is typically seconds to a few minutes (plus Scylla's ~1–2 min cold-boot on restart). A trap guarantees the stack restarts even if the backup errors out. Volume names are compose-project-prefixed and **discovered at runtime**, so it works regardless of your install-dir name.
-
-Copy the tarball **off the box** — it is your only recovery path, and it contains the encryption key.
-
-:::tip
-An upgrade takes its own safety snapshot into `<install-dir>/backups/upgrade-<id>/` before touching anything, and there is an `auto-backup.sh` you can cron for scheduled snapshots.
-:::
-
-## Restore
-
-Onto the same box after data loss, or onto a brand-new VM:
-
-```bash
-./restore.sh zibby-selfhosted-<timestamp>.tar.gz          # interactive confirm
-./restore.sh backup.tar.gz --dir /opt/zibby --force        # scripted
-./restore.sh backup.age                                    # decrypts first (needs age/gpg)
-```
-
-`restore.sh` restores **both** data volumes and the `.env` (so the restored, encrypted data is readable). Volume names are discovered at runtime, or created if this is a fresh box.
-
-:::danger Restore wipes current data
-Restoring **overwrites** this install's volumes. The script refuses to run without an explicit confirmation (interactive `y/N`, or `--force`).
-:::
-
-A MinIO-era bundle restored onto a current (post-SeaweedFS-flip) release comes up on the legacy MinIO override; the next installer run auto-migrates it to SeaweedFS — see [Storage](./storage).

package/docs/self-host/custom-sidecars.md

@@ -1,136 +0,0 @@
----
-sidebar_position: 5
-title: Custom (BYO) sidecars
----
-
-# Bring your own sidecar
-
-A **sidecar** is a long-lived service container the box runs next to your
-agents — the platform's own vector-KB engine and OAuth token broker ship this
-way. On a self-hosted box you can also register **your own** sidecar image.
-That is the standard way to add a custom resident service to the platform —
-most commonly a **thin MCP server that wraps an internal REST API**, so your
-agents and the chat Copilot can call systems that only exist inside your
-network.
-
-No marketplace entry, no platform code change, no third-party registry: you
-push a `docker save` tarball to your own box, the box pins its sha256, and the
-sidecar flows through the exact same launch/health/idle-reap machinery as the
-built-ins.
-
-:::tip Wrapping a REST API? Try the OpenAPI bridge agent first.
-
-If all you need is "my agents should be able to call this internal REST API",
-you probably do **not** need to build an image at all. Deploy the **OpenAPI MCP
-Bridge** agent from the marketplace, put your API's spec URL in its **Env** tab,
-and every operation in the spec becomes an MCP tool — no code, no upload.
-
-```json
-OPENAPI_APIS = {"billing":{"specUrl":"https://internal/v2/api-docs","root":"https://internal"}}
-```
-
-It is a marketplace agent that carries its own sidecar, so deploying it is the
-whole installation. Build your own image (below) when you need logic the bridge
-can't express — a non-HTTP protocol, a stateful session, custom auth.
-:::
-
-## Push one
-
-```bash
-# 1. Build your image however you like; it must serve HTTP on one port.
-docker build -t report-mcp:0.1.0 .
-docker save report-mcp:0.1.0 | gzip > report-mcp.tar.gz
-
-# 2. Push it to the box. Needs an OPERATOR access token
-#    (a restricted per-user token is refused).
-zibby sidecar push report-mcp.tar.gz \
-  --name report-mcp --port 8080 \
-  --health-path /health \
-  --warm \
-  --api-url https://your-box.example.com --token $OPERATOR_PAT
-```
-
-`push` streams the tarball up (`POST /selfhost/sidecars/artifacts`), then
-registers the declaration (`PUT /selfhost/sidecars/report-mcp`) pinned to the
-sha256 the server computed from the uploaded bytes. The image is verified and
-`docker load`ed **before** anything is persisted — a corrupt or tampered
-tarball can never become a registered sidecar.
-
-Manage what's registered:
-
-```bash
-zibby sidecar list             # custom sidecars + the reserved built-in names
-zibby sidecar remove <name>    # unregister + stop (image reclaimed; data volume kept) (data volumes are kept)
-```
-
-## Reach it
-
-- **From the control plane / the chat Copilot** — the container listens on the
-  box's infra network at `http://zibby-sidecar-<name>:<port>`. Agent run
-  containers deliberately **cannot** dial it directly (they are isolated on the
-  run network); access is brokered by the platform.
-- **From a browser / third-party client** — every `--public-path` prefix is
-  served at `https://<box-origin>/sidecars/<name>/<path>` through the
-  control-plane reverse proxy. Anything not declared public stays
-  infra-network-only.
-
-:::warning `--public-path` is opt-in, and most sidecars don't need it
-A declared public path is reachable **anonymously** — the platform adds no auth
-and no identity; your app owns that surface entirely. Agents and the chat
-Copilot reach a sidecar over the infra network, so an MCP server for them needs
-**no** public path. It exists for browser flows (an OAuth callback a provider
-redirects to). Registering one is therefore refused unless the box opts in with
-`SIDECAR_BYO_PUBLIC_PATHS=1` in its `.env` (then restart the control-plane).
-:::
-
-### Wire it into the Copilot
-
-For the "internal API → MCP → chat" use case, register the sidecar and then
-attach its MCP endpoint to the Copilot (in chat):
-
-> connect yourself to the MCP at `http://zibby-sidecar-report-mcp:8080/mcp`
-
-The Copilot can also drive the whole flow itself with the owner-only tools
-`zibby_add_sidecar` (takes a downloadable `url` + pinned `sha256` instead of a
-file upload), `zibby_list_sidecars`, and `zibby_remove_sidecar`.
-
-## Declaration reference
-
-| Flag | Meaning |
-|---|---|
-| `--name` | `[a-z][a-z0-9-]{1,30}`. Built-in names (`gbrain`, `pingcode`, …) are reserved. |
-| `--port` | The HTTP port your app listens on inside the container. Required. |
-| `--version` | Display/tag version (default: first 12 chars of the sha256). |
-| `--health-path` | GET path returning 2xx when ready (default `/health`). |
-| `--public-path` | Repeatable. Path prefix exposed through the public reverse proxy — **anonymously**. Disabled unless the box sets `SIDECAR_BYO_PUBLIC_PATHS=1`; see below. |
-| `--warm` | Keep it always-on (pre-warmed at boot, never idle-reaped). Default: on-demand launch + idle reap. |
-| `--env-key` | Repeatable. A box `.env` variable forwarded into the container when set. |
-| `--request-config-key` | Repeatable. Per-agent config: resolved from the **calling agent's encrypted Env bag** and sent per request — one shared container can serve N projects with different upstream credentials. |
-| `--data-path` | Container path persisted on a named volume (survives restarts; kept on remove). |
-| `--memory-bytes` | Container memory cap. |
-
-## What the box guarantees
-
-- **sha256-pinned, always.** The tarball's hash is computed server-side at
-  upload and re-verified on every subsequent load — including the re-fetch
-  path: the verified tarball is kept in the box's own object store, so if the
-  docker image is ever pruned it is restored automatically without a re-upload.
-- **Operator-only surface.** Upload/register/remove require the box
-  owner/admin token; restricted per-user tokens get `403`.
-- **Isolation unchanged.** Custom sidecars get the same placement as built-in
-  ones: infra network, brokered access, no host mounts — the declaration
-  cannot ask for privileged options.
-- **No shadowing, at BOTH layers.** A custom sidecar can never take over a
-  built-in sidecar's *name*, and its package can never take over a platform or
-  another sidecar's *image tag*: the archive's manifest is read **before**
-  `docker load` runs, and a package declaring `zibby-*` or another sidecar's
-  image is refused outright — even if that image isn't on the box yet.
-- **Uninstall reclaims storage.** Removing a sidecar deletes its image; a
-  superseded image is reclaimed when you push a new version. The declared data
-  volume is **kept** (it holds your content) — the response tells you its name,
-  and `zibby sidecar remove <name> --purge-data` deletes it deliberately.
-
-:::note Cloud
-BYO sidecars are **self-host only** today. On cloud, wrap an external API as a
-remote MCP server and attach it with `zibby_add_mcp` instead.
-:::

package/docs/self-host/index.md

@@ -1,75 +0,0 @@
----
-sidebar_position: 1
-title: Self-host overview
----
-
-# Operating a self-hosted box
-
-Run the entire Zibby agent platform on **one host**, inside your own VPC, with `docker compose`. This section is the **operator runbook** — for the person who holds the box's owner/admin token and is responsible for install, upgrade, backup, and storage. It is not the agent-authoring guide (that's the rest of these docs, and `zibby init` in your repo).
-
-A self-hosted box is the **same codebase as cloud**, assembled differently: the control plane is `backend/server.js` (the Express server that wraps every Lambda handler, including the MCP server), the run executor is the host Docker engine instead of Fargate, and the datastore / object store are ScyllaDB Alternator + SeaweedFS instead of DynamoDB + S3.
-
-## Install
-
-One command, on a Linux/macOS host with **Docker Engine + Compose v2**:
-
-```bash
-curl -fsSL https://dl.zibby.app/selfhosted/latest/install.sh | bash
-```
-
-The installer downloads a signed release (a `docker save` image tarball + compose file + the marketplace-template bundle), **verifies it** (an Ed25519 signature over `SHA256SUMS`, then a per-file checksum — it fails closed on any mismatch and never runs unverified bytes), `docker load`s the images, and `docker compose up -d`s the stack. It is idempotent — re-running it is how you upgrade in place, and cached downloads are checksum-verified.
-
-:::warning Compose v2 is required
-`apt install docker.io` alone gives you the engine but **not** Compose v2. Install both — the installer aborts with a link if `docker compose version` fails. On a headless box also make sure `openssl` is present (the installer needs it to verify the release signature).
-:::
-
-### What comes up
-
-The stack is a handful of containers on the `zibby-selfhosted` docker network:
-
-| Container | Role |
-|---|---|
-| `zibby-control-plane` | the long-lived API + `/mcp` + `/hooks/*` server + the dashboard; drives the host Docker engine as the run executor over the mounted `docker.sock` |
-| `zibby-scylla` | **ScyllaDB Alternator** (`:8000`) — speaks the DynamoDB API, so the backend is unchanged. All metadata: integrations + encrypted tokens, deployed agents, projects, members, executions, stores. |
-| `zibby-minio` | the **object store** (`:9000`) for run sources + artifacts + logs. As of 0.1.126 this is **SeaweedFS** (the service keeps the historical name `minio` so every `S3_ENDPOINT` consumer is unchanged). Legacy boxes still run MinIO until they auto-migrate — see [Storage](./storage). |
-| `zibby-bootstrap` | one-shot: provisions tables + buckets, syncs all marketplace templates, seeds the default project + token, then exits. |
-| run containers | one ephemeral `zibby-agent` container per run, destroyed on exit — the same per-run isolation Fargate gives cloud. |
-
-The control plane mounts `/var/run/docker.sock` — that socket **is** the run executor (no docker-in-docker).
-
-### After install
-
-The installer prints the access info and the seeded credential:
-
-- **Dashboard** — `http://<host>:3001/` (and `/ui`). The self-host dashboard is a single vanilla HTML page served by the control plane; the cloud React app is not shipped on-prem.
-- **API + CLI** — `http://<host>:3001`. Set `ZIBBY_API_URL` + `ZIBBY_API_KEY=<apiToken>` (the seeded `zby_…` project token printed at the end, or recover it with `docker logs zibby-bootstrap`).
-- **MCP** — `http://<host>:3001/mcp`, `Authorization: Bearer <PAT>`. MCP needs a **user PAT** (`zby_pat_…`), minted with `zibby self-host token` — not the project token.
-- **Health** — `http://<host>:3001/health`.
-
-AI model keys are **per-project**, set in the dashboard (Settings → AI); the deploy modal collects a missing one. The box comes up keyless — there is deliberately no box-global model credential.
-
-## Install knobs
-
-Set these as environment variables or flags on the install command (they persist into `.env`, which is the runtime source of truth and is **reused untouched on upgrade**):
-
-| Knob | Default | Effect |
-|---|---|---|
-| `--dir <path>` / `ZIBBY_DIR` | `./zibby-selfhosted` | install + data directory |
-| `--url <u>` / `ZIBBY_DIST_URL` | `https://dl.zibby.app/selfhosted/latest` | release base URL |
-| `--reconfigure` | — | re-run the external-URL / domain prompt |
-| `CONTROL_PLANE_PORT` (`.env`) | `3001` | host port the control plane binds |
-| `CONTROL_PLANE_BIND` (`.env`) | `0.0.0.0` | set to `127.0.0.1` to restrict the dashboard/API to loopback and front it with the bundled Caddy TLS proxy |
-| `ZIBBY_EXTERNAL_URL` (`.env`/prompt) | unset | a domain → automatic Let's Encrypt HTTPS; an IP → self-signed HTTPS; `http://…` → plain HTTP via Caddy. Blank → plain HTTP on `CONTROL_PLANE_PORT`. |
-| `MAX_CONCURRENT_RUNS` (`.env`) | `5` | run containers executing in parallel; the rest queue |
-| `ZIBBY_SKIP_OBJECT_STORE_MIGRATION` | `0` | `1` opts a legacy MinIO box out of the auto-migration to SeaweedFS |
-
-:::warning Plain-HTTP default binds in cleartext
-With no external URL the dashboard/API bind to `0.0.0.0:3001` unencrypted — the operator token and login passcode cross the network in the clear. Either set `ZIBBY_EXTERNAL_URL` (→ auto-TLS via Caddy), firewall the port to trusted IPs, or set `CONTROL_PLANE_BIND=127.0.0.1`.
-:::
-
-## The runbook
-
-- **[Upgrade & rollback](./upgrade)** — check the running version, the owner-only remote upgrade, and how auto-rollback works.
-- **[Backup & restore](./backup-restore)** — snapshot the whole install to one tarball; restore onto the same or a fresh box.
-- **[Storage](./storage)** — the object store, and the automatic MinIO → SeaweedFS migration.
-- **[Troubleshooting](./troubleshooting)** — reading logs and the failure signatures worth recognizing.

package/docs/self-host/storage.md

@@ -1,50 +0,0 @@
----
-sidebar_position: 4
-title: Storage
----
-
-# Storage
-
-A self-hosted box keeps two stateful stores, both as single-box containers on named docker volumes:
-
-- **ScyllaDB Alternator** (`zibby-scylla`, volume `scylla-data`) — the DynamoDB-compatible metadata store. All accounts, projects, agents, integrations, executions, and stores live here.
-- **Object store** (`zibby-minio`, volume `seaweed-data` or legacy `minio-data`) — run sources, artifacts, per-node logs, datasets, and marketplace icons, over the S3 API.
-
-Both survive `docker compose restart` / `down` (they're on named volumes) but **not** `down -v`. Back them up — see [Backup & restore](./backup-restore).
-
-## MinIO → SeaweedFS
-
-MinIO's upstream was archived in 2026-04, so as of **0.1.126** the object store is **SeaweedFS**. The service is still *named* `minio` in compose and DNS so every `S3_ENDPOINT` consumer is unchanged — only the engine behind it changed. (Full evaluation: `strategy/object-store-replacement.md` in the root repo.)
-
-- **New installs** come up on SeaweedFS (volume `seaweed-data`). Nothing to do.
-- **Upgrades from a MinIO box auto-migrate.** When the installer upgrades a legacy (pre-flip, `minio-data`) box, it keeps MinIO running for that `up`, then — once the upgraded stack is healthy — runs the migration automatically.
-
-### How the auto-migration works
-
-It is designed to **auto-attempt, never auto-brick** — MinIO's data is never modified, so every failure path rolls back to a working box:
-
-1. **backup** — a full `backup.sh` snapshot first; it refuses to migrate without one.
-2. **quiesce** — stop the S3 writers (control-plane + copilot-runtime) so the copy is consistent.
-3. **copy + verify** — `migrate-object-store.sh` mirrors every bucket into a throwaway SeaweedFS container writing to the `seaweed-data` volume, then verifies per-bucket **object count + total bytes must match exactly**, plus a sha256 comparison of sampled objects (always including the largest). It never deletes anything.
-4. **flip** — record `ZIBBY_OBJECT_STORE=seaweedfs` in `.env` and bring up the default (SeaweedFS) stack.
-5. **health-gate** — the new control plane must become healthy **and** pass an authenticated S3 list against the migrated store.
-6. **rollback** — any failure at any stage rolls back to MinIO (whose data was never touched) with a loud status line.
-
-The **old `minio-data` volume is retained** as a rollback safety net. After a few days of verified operation you can reclaim it:
-
-```bash
-docker volume rm <project>_minio-data   # irreversible — only after you trust SeaweedFS
-```
-
-### Controlling / retrying the migration
-
-- **Opt out** (stay on MinIO for now): run the installer with `ZIBBY_SKIP_OBJECT_STORE_MIGRATION=1`.
-- **Retry** after a failed auto-migration: re-run the installer, or manually —
-  ```bash
-  cd zibby-selfhosted
-  docker compose stop control-plane copilot-runtime
-  bash migrate-object-store.sh --yes
-  # then flip: set ZIBBY_OBJECT_STORE=seaweedfs + COMPOSE_FILE=docker-compose.yml in .env
-  docker compose -f docker-compose.yml up -d
-  ```
-- **MinIO emergency fallback image** (if a legacy box lost its local MinIO image): the pinned tarball is at `https://dl.zibby.app/selfhosted/infra/` — verify the `.sha256`, then `docker load -i`. The box only ever pulls images from our own CDN, never a third-party registry.

package/docs/self-host/troubleshooting.md

@@ -1,48 +0,0 @@
----
-sidebar_position: 5
-title: Troubleshooting
----
-
-# Troubleshooting
-
-A self-hosted box is **one VM** — control-plane container + Scylla + object store + ephemeral run containers. When something is slow or failing, diagnose from the box's own logs; the reflex "it doesn't scale / the VM is overloaded" is almost always wrong (a `top` usually shows the box near-idle).
-
-## First moves
-
-```bash
-top                                          # CPU / memory — usually reveals it's idle
-docker ps -a                                 # are containers Up? did a run container Exit?
-docker logs zibby-control-plane --tail 100   # the executor + reaper + API
-docker logs zibby-bootstrap                  # first-boot template sync + the seeded token
-curl -s http://localhost:3001/health         # control-plane health
-curl -s http://localhost:3001/selfhost/version   # the running release (baked, authoritative)
-```
-
-To query the box's own API, use its `PROJECT_API_TOKEN` from `.env`:
-
-```bash
-curl -H "Authorization: Bearer <zby_...>" \
-  "http://localhost:3001/executions?projectId=selfhosted-project"
-```
-
-A failed run's `reapedReason` field tells you why it was reaped. (The cloud Zibby MCP/CLI talks to the *cloud* backend — it cannot reach a self-host box; you need the box's own token.)
-
-## Failure signatures worth recognizing
-
-**Runs "fail" with empty steps + `pull access denied for zibby-agent … repository does not exist`.** An agent-image tag mismatch after an upgrade — the executor is launching a tag the reused `.env` doesn't have. Fixed at the root in installer 0.1.53+; immediate unblock:
-
-```bash
-docker tag zibby-agent:slim zibby-agent:local
-```
-
-**The dashboard shows the new version but the API still behaves like the old one.** `docker compose up -d` can judge a service "up to date" when only the image *content* changed. The installer force-recreates the control-plane container to avoid this; if you hit it, re-run the installer (or `docker compose up -d --no-deps --force-recreate control-plane`). Because `/selfhost/version` reads the **baked** file, a genuine version mismatch is *visible* rather than hidden behind a lying env-var label.
-
-**Control plane won't become healthy right after boot.** Scylla cold-boots slowly (~1–2 min). The installer waits up to ~5 min; if it's still unhealthy, read `docker logs zibby-control-plane` — a broken data path shows up there, not in `top`.
-
-**An upgrade ended at `rolled_back`.** The box is safe (back on the prior version). Read `GET /selfhost/upgrade/status` `logTail` for the failing phase, and check `docker logs zibby-control-plane`. Re-attempt with a **pinned** version (see [Upgrade & rollback](./upgrade)).
-
-## Where things live
-
-- **Data** — docker volumes `scylla-data` + the object store volume. Back them up (see [Backup & restore](./backup-restore)); they survive restarts but not `down -v`.
-- **`.env`** — the runtime source of truth (`JWT_SECRET`, `ENCRYPTION_KEY`, tokens, `MAX_CONCURRENT_RUNS`, `AGENT_IMAGE`). Reused untouched on upgrade.
-- **Upgrade backups + logs** — `<install-dir>/backups/upgrade-<id>/`.

package/docs/self-host/upgrade.md

@@ -1,81 +0,0 @@
----
-sidebar_position: 2
-title: Upgrade & rollback
----
-
-# Upgrade & rollback
-
-## Check the running version
-
-```bash
-curl -s http://<host>:3001/selfhost/version
-# {"version":"0.1.126"}
-```
-
-This reads the **immutable file `/app/SELFHOST_VERSION`**, baked into the image at build time from `selfhosted/package.json`. It ships inside the image layer, so it **always matches the code actually running** and cannot be spoofed by a runtime env / compose `.env` override. That is the point: if an upgrade did not actually swap the control-plane image (a silent-upgrade failure), the baked file still reports the old version — you *see* the mismatch instead of trusting a lying label.
-
-The dashboard renders this same value as a small `v0.1.126` label in the sidebar, so the running release is always visible. (The dashboard has no upgrade button — upgrades are driven by the API endpoint or by re-running the installer, below.)
-
-The latest published version is in the release manifest:
-
-```bash
-curl -s https://dl.zibby.app/selfhosted/latest/manifest.env
-# ZIBBY_SELFHOSTED_VERSION=0.1.126
-# IMAGE_TARBALL=zibby-selfhosted-0.1.126.tar.gz
-# ...
-```
-
-## Two ways to upgrade
-
-### 1. Re-run the installer (in place)
-
-The installer is idempotent — re-running it pulls a newer release, verifies + `docker load`s the new images, re-pins `AGENT_IMAGE`, and **force-recreates** the control-plane container from the freshly loaded image:
-
-```bash
-curl -fsSL https://dl.zibby.app/selfhosted/latest/install.sh | bash
-# or, from the install dir:  cd zibby-selfhosted && bash install.sh
-```
-
-Your `.env` (JWT_SECRET, ENCRYPTION_KEY, tokens) and data volumes are preserved.
-
-### 2. The owner-only remote upgrade (recommended)
-
-`POST /selfhost/upgrade` runs a **safe, self-driving upgrade** with an automatic backup and rollback — you can trigger it remotely and it survives the control-plane restart. It is **owner-only**: the endpoint requires the workspace-owner PAT/session or the admin project token (a run token or a non-owner member is refused `403`).
-
-```bash
-curl -s -X POST http://<host>:3001/selfhost/upgrade \
-  -H "Authorization: Bearer <owner-or-admin-token>" \
-  -H "Content-Type: application/json" \
-  -d '{"version":"0.1.126"}'
-# → 202 { "upgradeId": "...", "phase": "starting", ... }
-```
-
-Because a container can't recreate itself, the control plane launches a **detached helper** container (with the host docker socket) that outlives the control-plane bounce and drives the upgrade end to end:
-
-1. **backup** — flush Scylla, tar the Scylla + object-store volumes, copy `.env`, into `<install-dir>/backups/upgrade-<id>/`.
-2. **anchor** — pin the current control-plane image as `zibby-control-plane:rollback-<id>` so the new `docker load` can't garbage-collect the rollback target.
-3. **download → install** — fetch the target release's `install.sh` (Ed25519 + checksum verified), `docker load`, re-pin `AGENT_IMAGE`, force-recreate.
-4. **healthcheck** — poll the new control plane until container-healthy **and** `GET /selfhost/version` returns the target version.
-5. **rollback** — on an unhealthy new control plane (or an installer that exited non-zero), re-tag the anchor back to `:local` and force-recreate → back to the working version.
-
-Poll the status (owner-only, read-only):
-
-```bash
-curl -s http://<host>:3001/selfhost/upgrade/status \
-  -H "Authorization: Bearer <owner-or-admin-token>"
-# { "upgrade": { "phase": "install", ... }, "logTail": "...", "history": [...] }
-```
-
-Phases progress `starting → backup → anchor → download → install → healthcheck → success`. A failed upgrade ends at `rolled_back` (the box is back on the prior, healthy version) or, if even rollback fails, `rollback_failed` (manual restore needed — the backup dir and rollback-anchor tag are named in the status). The control plane restarts mid-upgrade, so the poll may briefly fail to connect — that is expected.
-
-:::warning Pin the exact version, not `latest`
-`{"version":"latest"}` resolves through the CDN, which can serve a **stale cached** `latest` for a while after a publish. For a deterministic upgrade, pass the exact version you verified against `manifest.env` (e.g. `{"version":"0.1.126"}`). The helper also treats "healthy but the version didn't advance to the pinned target" as a failure and rolls back — a guard you only get with a pinned version.
-:::
-
-## If a run fails with empty steps after an upgrade
-
-Symptom: reviews/runs "fail" with `steps: []` and the control-plane log shows `pull access denied for zibby-agent … repository does not exist`. That is an **agent-image tag mismatch** — the executor is trying to launch a tag the reused `.env` points at but the tarball loaded a different one. Installer 0.1.53+ fixes this at the root (it pins `AGENT_IMAGE` to the loaded tag and aliases `zibby-agent:local`). Immediate operator unblock:
-
-```bash
-docker tag zibby-agent:slim zibby-agent:local
-```