@zibby/skills 0.1.96 → 0.2.0

package/dist/workflow-builder.d.ts

@@ -1,245 +1,11 @@
-export namespace workflowBuilderSkill {
-    export let id: string;
-    export let description: string;
-    export let envKeys: any[];
-    export { PROMPT_FRAGMENT as promptFragment };
-    export let tools: ({
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                name: {
-                    type: string;
-                    description: string;
-                };
-                description: {
-                    type: string;
-                    description: string;
-                };
-                nodes: {
-                    type: string;
-                    items: {
-                        type: string;
-                        properties: {
-                            name: {
-                                type: string;
-                                description: string;
-                            };
-                            description: {
-                                type: string;
-                                description: string;
-                            };
-                            inputFields: {
-                                type: string;
-                                items: {
-                                    type: string;
-                                };
-                                description: string;
-                            };
-                            outputFields: {
-                                type: string;
-                                items: {
-                                    type: string;
-                                };
-                                description: string;
-                            };
-                        };
-                        required: string[];
-                    };
-                    description: string;
-                };
-                edges: {
-                    type: string;
-                    items: {
-                        type: string;
-                        properties: {
-                            from: {
-                                type: string;
-                                description: string;
-                            };
-                            to: {
-                                type: string;
-                                description: string;
-                            };
-                            condition: {
-                                type: string;
-                                description: string;
-                            };
-                        };
-                        required: string[];
-                    };
-                    description: string;
-                };
-                spec?: undefined;
-                workflowName?: undefined;
-                nodeName?: undefined;
-                inputFields?: undefined;
-                outputFields?: undefined;
-                projectId?: undefined;
-                topic?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                name: {
-                    type: string;
-                    description: string;
-                };
-                spec: {
-                    type: string;
-                    description: string;
-                    properties: {
-                        name: {
-                            type: string;
-                        };
-                        description: {
-                            type: string;
-                        };
-                        nodes: {
-                            type: string;
-                            items: {
-                                type: string;
-                            };
-                        };
-                        edges: {
-                            type: string;
-                            items: {
-                                type: string;
-                            };
-                        };
-                    };
-                };
-                description?: undefined;
-                nodes?: undefined;
-                edges?: undefined;
-                workflowName?: undefined;
-                nodeName?: undefined;
-                inputFields?: undefined;
-                outputFields?: undefined;
-                projectId?: undefined;
-                topic?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                workflowName: {
-                    type: string;
-                    description: string;
-                };
-                nodeName: {
-                    type: string;
-                    description: string;
-                };
-                description: {
-                    type: string;
-                    description: string;
-                };
-                inputFields: {
-                    type: string;
-                    items: {
-                        type: string;
-                    };
-                    description: string;
-                };
-                outputFields: {
-                    type: string;
-                    items: {
-                        type: string;
-                    };
-                    description: string;
-                };
-                name?: undefined;
-                nodes?: undefined;
-                edges?: undefined;
-                spec?: undefined;
-                projectId?: undefined;
-                topic?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                name: {
-                    type: string;
-                    description: string;
-                };
-                projectId: {
-                    type: string;
-                    description: string;
-                };
-                description?: undefined;
-                nodes?: undefined;
-                edges?: undefined;
-                spec?: undefined;
-                workflowName?: undefined;
-                nodeName?: undefined;
-                inputFields?: undefined;
-                outputFields?: undefined;
-                topic?: undefined;
-            };
-            required: string[];
-        };
-    } | {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                name?: undefined;
-                description?: undefined;
-                nodes?: undefined;
-                edges?: undefined;
-                spec?: undefined;
-                workflowName?: undefined;
-                nodeName?: undefined;
-                inputFields?: undefined;
-                outputFields?: undefined;
-                projectId?: undefined;
-                topic?: undefined;
-            };
-            required?: undefined;
-        };
-    } | {
-        name: string;
-        description: string;
-        input_schema: {
-            type: string;
-            properties: {
-                topic: {
-                    type: string;
-                    description: string;
-                };
-                name?: undefined;
-                description?: undefined;
-                nodes?: undefined;
-                edges?: undefined;
-                spec?: undefined;
-                workflowName?: undefined;
-                nodeName?: undefined;
-                inputFields?: undefined;
-                outputFields?: undefined;
-                projectId?: undefined;
-            };
-            required?: undefined;
-        };
-    })[];
-    export function handleToolCall(name: any, args: any, context: any): Promise<string>;
-    export function resolve(): any;
-}
-declare const PROMPT_FRAGMENT: "## Workflow Builder\n\nYou can help users build custom AI workflows using the Zibby workflow framework.\n\n### What makes Zibby workflows different\nEach node invokes a **real AI agent** (Cursor, Claude, Codex, or Gemini) \u2014 not a thin LLM API wrapper.\nThat means every node has full agent capabilities: tool use, MCP servers (browser, GitHub, Jira, Slack),\nmulti-turn reasoning, and structured output validation via Zod schemas.\n\nKey differentiators:\n- **Agent-powered nodes** \u2014 each step runs a full AI agent (cursor-agent, claude, codex, gemini CLI) with tool access and MCP skills, not a simple chat completion call.\n- **Structured output** \u2014 every node declares a Zod schema; the framework validates and parses the agent's response automatically.\n- **Conditional routing** \u2014 edges can branch on agent-produced fields (e.g., `state.triage.priority === 'critical'`), enabling intelligent decision graphs.\n- **MCP skill injection** \u2014 nodes declare `skills: [SKILLS.BROWSER, SKILLS.GITHUB]` and the framework spins up the right MCP servers automatically.\n- **Deploy anywhere** \u2014 `zibby deploy` pushes to Zibby Cloud with an API trigger; or self-host with `zibby start`.\n- **State accumulation** \u2014 each node's validated output is stored under its name in `state` (e.g., `state.classify_ticket`), so downstream nodes can reference upstream results.\n\n### What is a workflow?\nA directed graph of nodes (AI agent steps) connected by edges. Each node has:\n- `name` \u2014 unique identifier (snake_case)\n- `prompt` \u2014 function that receives state and returns the prompt string sent to the agent\n- `outputSchema` \u2014 Zod schema defining the structured output the agent must return\n- `skills` (optional) \u2014 array of MCP skill IDs the node needs (e.g., `SKILLS.BROWSER`, `SKILLS.GITHUB`)\n- `timeout` (optional) \u2014 max execution time in ms (default: 300000)\n- `model` (optional) \u2014 override the model for this node (e.g., `'claude-opus-4'`)\n\n### File structure\n```\n.zibby/workflows/<name>/\n\u251C\u2500\u2500 graph.mjs          \u2014 WorkflowAgent subclass with buildGraph()\n\u251C\u2500\u2500 nodes/\n\u2502   \u251C\u2500\u2500 index.mjs      \u2014 barrel export for all nodes\n\u2502   \u2514\u2500\u2500 <node>.mjs     \u2014 one file per node\n\u2514\u2500\u2500 workflow.json       \u2014 manifest (name, description, triggers)\n```\n\n### Node pattern\n```javascript\nimport { z, SKILLS } from '@zibby/core';\n\nconst OutputSchema = z.object({\n  summary: z.string().describe('Brief summary'),\n  items: z.array(z.string()).describe('List of extracted items'),\n  needsReview: z.boolean().describe('Whether a human should review this'),\n});\n\nexport const myNode = {\n  name: 'my_node',\n  skills: [SKILLS.GITHUB],  // optional \u2014 framework injects MCP servers\n  timeout: 120000,           // optional \u2014 2 min timeout\n  prompt: (state) => \\`You are analyzing a pull request.\n\nInput:\n\\${JSON.stringify(state.input || {}, null, 2)}\n\nReturn a JSON object matching the schema.\\`,\n  outputSchema: OutputSchema,\n};\n```\n\n### Graph pattern\n```javascript\nimport { WorkflowAgent, WorkflowGraph } from '@zibby/core';\nimport { classifyNode, routeNode } from './nodes/index.mjs';\n\nexport class MyWorkflow extends WorkflowAgent {\n  buildGraph() {\n    const graph = new WorkflowGraph();\n    graph.addNode('classify', classifyNode);\n    graph.addNode('route', routeNode);\n    graph.setEntryPoint('classify');\n    graph.addEdge('classify', 'route');\n    graph.addEdge('route', 'END');\n    return graph;\n  }\n\n  async onComplete(result) {\n    // Post-execution hook \u2014 save artifacts, notify, etc.\n    console.log('Workflow complete:', result.success);\n  }\n}\n```\n\nConditional edges: `graph.addConditionalEdges('node', (state) => state.node.priority === 'high' ? 'escalate' : 'notify')`\n\n### Available SKILLS constants\nImport from `@zibby/core`: `SKILLS.BROWSER`, `SKILLS.MEMORY`, `SKILLS.GITHUB`, `SKILLS.JIRA`, `SKILLS.SLACK`, `SKILLS.RUNNER`\n\n### Deep documentation\nCall `explore_framework_docs` to read detailed framework docs on demand. Use it for:\n- Advanced patterns (middleware, parallel nodes, state schemas)\n- Deployment & cloud triggers\n- CLI commands reference\n- Integration details (Jira, GitHub, etc.)\nCall with no arguments to see all available topics.\n\n### How to use the builder tools\n1. For complex workflows, call `explore_framework_docs(\"custom-workflows\")` first to learn advanced patterns.\n2. Ask the user what their workflow should do, what input it receives, and what steps are needed.\n3. Call `design_workflow` with the structured spec for the user to review.\n4. Once approved, call `build_workflow` to generate real code on disk (uses the configured agent for high-quality code generation).\n5. Remind the user: `zibby start <name>` to test locally, `zibby deploy <name> --project <id>` to deploy to cloud, `zibby logs --workflow <name>` to tail logs.\n\n### Important\n- Each node prompt should be detailed and specific \u2014 tell the AI agent exactly what to do and what format to return.\n- Zod schemas MUST use .describe() on every field so the agent knows what each field means.\n- Node names must be snake_case (e.g., classify_ticket, generate_report).\n- Workflow names must be kebab-case (e.g., ticket-triage, pr-review).\n- State flows through: each node's validated output is stored under its name in state (e.g., state.classify_ticket).\n- Downstream nodes reference upstream outputs in their prompt function (e.g., \\`\\${JSON.stringify(state.classify_ticket, null, 2)}\\`).\n- Nodes can declare skills to get MCP tool access \u2014 the framework handles server lifecycle automatically.";
-export {};
+/**
+ * Workflow Builder Skill
+ *
+ * Guides users through designing and building custom AI workflows
+ * via conversation. The chat agent (assistant) handles the dialog;
+ * this skill provides tools that generate real workflow code by
+ * delegating to the user's configured agent (cursor/claude/codex/gemini).
+ *
+ * No MCP server needed — all handlers run locally.
+ */
+export declare const workflowBuilderSkill: any;

package/docs/concepts/designing-agents.md

@@ -0,0 +1,201 @@
+---
+sidebar_position: 7
+title: Designing agents
+---
+
+# Designing agents
+
+Before you build an agent, learn the three patterns that make Zibby agents
+powerful. Almost every good agent is some combination of them:
+
+1. **One agent, many entry points** — a single deployed agent that behaves
+   differently depending on *how* it was triggered (cron vs. a human vs. a
+   webhook), selected by a code **router** node.
+2. **Zero-LLM code nodes that read & write Stores** — deterministic work
+   (fetch, ETL, aggregate, persist) runs as plain code, no model call, and can
+   read/write a Store (SQLite / file / dataset) directly.
+3. **Event-driven agents** — one agent subscribes to several events (PR opened,
+   comment, `@mention`) and routes each to the right branch.
+
+These are not exotic. The shipped **sentry-triage** and **engineering-insights**
+agents use all three at once. Study them — they are the canonical reference for
+"how an agent should be designed."
+
+:::tip Design rule
+**Don't reach for an LLM node when plain code will do.** A model call costs
+tokens, adds latency, and is non-deterministic. Fetching data, transforming
+JSON, running a query, writing to a Store, calling an API — all of that belongs
+in a **code node**. Reserve LLM nodes for judgment: classify, summarize, decide.
+:::
+
+---
+
+## Pattern 1 — one agent, many entry points
+
+The trap beginners fall into is building *two* agents: a "collector" that runs on
+a schedule and a "reporter" a human triggers. Don't. Build **one** agent whose
+**first node is a code router** that inspects the trigger and sends the run down
+the right branch. One bundle, one deployment, one set of env/Store bindings.
+
+```js
+import { WorkflowGraph } from '@zibby/agent-workflow';
+import { z } from '@zibby/core';
+
+// The router is PURE CODE — no model call. It reads the trigger input off state
+// and returns the name of the next node.
+function route(state) {
+  // state.trigger / state.mode / state.action come from the trigger payload,
+  // spread onto the initial state by the runner.
+  return state?.trigger === 'fix' ? 'fix_intake' : 'fetch_issues';
+}
+
+const graph = new WorkflowGraph()
+  .addNode('route', {
+    _isCustomCode: true,
+    description: 'Routes on the trigger: "fix" runs the single-issue auto-fix branch, anything else runs the scheduled triage branch.',
+    outputSchema: z.object({}).passthrough(),
+    execute: async (ctx) => ctx.state.getAll(), // router only decides an edge; it forwards state
+  })
+  // …branch nodes…
+  .setEntryPoint('route')
+  // A conditional edge: run `route`, then take the edge its return value names.
+  .addConditionalEdges('route', route, {
+    labels: { fix_intake: 'auto-fix one issue', fetch_issues: 'scheduled triage' },
+  });
+```
+
+The **same agent** then gets three trigger sources, all landing on `route`:
+
+| Trigger | Payload | Branch it takes |
+|---|---|---|
+| Cron (nightly) | `{ mode: 'collect' }` | collect → persist to Store |
+| Human `zibby agent trigger` | `{ action: 'report' }` | read Store → generate → deliver |
+| Webhook / Lark `@bot` | `{ trigger: 'fix', issueId }` | single-item fix branch |
+
+> **Real reference:** `sentry-triage` routes `state.trigger === 'fix'` to an
+> auto-fix branch and everything else (incl. an absent trigger — the nightly
+> cron) to scheduled triage. `engineering-insights` routes `state.action`
+> between `collect` (meter commits → SQLite) and `report` (aggregate → charts).
+
+---
+
+## Pattern 2 — code nodes read & write Stores (no LLM)
+
+A **code node** (`_isCustomCode: true` + an `execute` function) is a first-class
+citizen. It runs in the same container as the rest of the graph and has the same
+environment — including any **Store** bound to the node. So a deterministic node
+can fetch from a Store, transform, and write results back, entirely without a
+model.
+
+### How a node reaches a Store
+
+When you bind a Store to a node (via `zibby_set_node_stores`, the deploy modal,
+or the CLI), the runtime injects three env vars into that node's container:
+
+| Env var | What it is |
+|---|---|
+| `ZIBBY_STORE__<name>` | the **storeId** of the Store you bound as `<name>` |
+| `ZIBBY_ACCOUNT_API_URL` | the base URL of the datasets API |
+| `PROJECT_API_TOKEN` | a project-scoped bearer token |
+
+The node just `fetch`es the datasets API. No SDK required.
+
+```js
+// A pure-code node: read from a SQLite Store, write to a file Store. Zero LLM.
+const BASE  = process.env.ZIBBY_ACCOUNT_API_URL;
+const TOKEN = process.env.PROJECT_API_TOKEN;
+
+async function ds(storeId, action, body) {
+  const r = await fetch(`${BASE}/datasets/stores/${encodeURIComponent(storeId)}/${action}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${TOKEN}` },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error(`${action} ${r.status}: ${await r.text()}`);
+  return r.json();
+}
+
+graph.addNode('build_report', {
+  _isCustomCode: true,
+  description: 'Reads metrics from a SQLite Store, writes the rendered report to a file Store. Pure code — no model call.',
+  outputSchema: z.object({ topDevs: z.array(z.any()), wrote: z.boolean() }),
+  execute: async (ctx) => {
+    const state      = ctx.state.getAll();
+    const metricsDb  = process.env.ZIBBY_STORE__metrics_db;    // a sqlite Store
+    const reportFile = process.env.ZIBBY_STORE__report_files;  // a file Store
+
+    // ── SQLite READ ── (readOnly:true → read-only guard)
+    const q = await ds(metricsDb, 'sql', {
+      sql: 'SELECT dev, added FROM commits WHERE added > ? ORDER BY added DESC LIMIT 10',
+      params: [100],
+      readOnly: true,
+    });
+    // q = { columns: ['dev','added'], rows: [['alice', 420], …] }
+
+    // ── SQLite WRITE ── (bound params; a brand-new table is created STRICT)
+    await ds(metricsDb, 'sql', {
+      sql: 'INSERT INTO runs (ran_at, top_dev) VALUES (?, ?)',
+      params: [state.ranAt, q.rows[0]?.[0] ?? null],
+    });
+
+    // ── file WRITE / READ ──
+    await ds(reportFile, 'put', { path: 'report.html', content: state.html });
+    const tpl = await ds(reportFile, 'get', { path: 'template.html' });
+
+    return { topDevs: q.rows, wrote: true };
+  },
+});
+```
+
+### The Store data actions
+
+| Store type | Actions | Notes |
+|---|---|---|
+| `sqlite` | `sql` `{ sql, params?, readOnly? }` | a real relational DB — tables, joins, UPDATEs. `readOnly: true` refuses any write. New tables are created **STRICT** so a column's declared type is enforced. |
+| `file` | `put` / `get` / `list` / `delete` `{ path, content? }` | arbitrary blobs by relative path — good for whole-JSON inputs and rendered outputs. |
+| `dataset` | `append` `{ record }` / `query` `{ select?, where?, … }` | append-only records + SQL-style aggregation — good for raw event streams you later `count`/`sum`/`group`. |
+
+:::tip Choosing a Store type by data shape
+- **Whole-blob** (a JSON file a script reads with `readFileSync`, a rendered
+  report) → **file**.
+- **Rows you dedupe / update / join** (git commits keyed by SHA) → **sqlite**.
+- **Append-only events you aggregate later** (MRs, worklogs) → **dataset**.
+- **A tiny cursor** ("where did I get to last time") → **kv-memory** (built into
+  every agent, not a registry Store).
+:::
+
+---
+
+## Pattern 3 — event-driven agents
+
+A single agent can subscribe to **several** events and handle each differently.
+The shipped **github-code-review** / **gitlab-code-review** agents are one agent
+that reacts to *PR opened*, *new commits pushed*, *a comment reply*, and an
+*`@mention`* — the entry router branches on which event fired. The owner even
+chooses **which** events trigger a review (cost control), because the whole thing
+is just an event-subscription subset feeding the same router.
+
+The takeaway: **you rarely need a second agent for a new trigger.** Add an event
+to the subscription, add a branch, extend the router.
+
+---
+
+## Putting it together — a design checklist
+
+When you design a new agent, ask:
+
+1. **How many ways will this be triggered?** More than one → **Pattern 1**: a
+   code `route` node at the entry, one agent, branches per scenario.
+2. **What here is deterministic?** Fetch / transform / query / persist → **code
+   nodes** (Pattern 2), not LLM nodes. Bind the Stores those nodes need.
+3. **What actually needs judgment?** Only *those* steps get an LLM node
+   (`agent: 'claude' | 'codex' | …` + a `prompt` + an `outputSchema`).
+4. **Where does the data live?** Pick a Store type per data shape (blob → file,
+   relational → sqlite, append-only → dataset; cursor → kv-memory).
+5. **Is the split write-side vs. read-side?** Keep it **one agent** — a nightly
+   `collect` branch that writes the Store and an on-demand `report` branch that
+   reads it, selected by the router. Not two agents.
+
+Then read the source of **sentry-triage** and **engineering-insights** and map
+each pattern onto what you see. That is the fastest way to learn what Zibby can
+do.

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

@@ -0,0 +1,52 @@
+---
+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 three 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. **`.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), `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/index.md

@@ -0,0 +1,75 @@
+---
+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

@@ -0,0 +1,50 @@
+---
+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.