@starlove/orbit 1.0.1

package/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.claude
+.orbit
+data
+dist
+node_modules
+npm-debug.log*
+pnpm-debug.log*
+*.db
+*.db-shm
+*.db-wal
+.env
+.DS_Store

package/Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-slim AS build
+WORKDIR /app
+
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+
+RUN corepack enable && corepack prepare pnpm@10.20.0 --activate
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile
+
+COPY build.mjs ./
+COPY public ./public
+RUN pnpm run build:full
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production \
+    PORT=3337 \
+    DATA_DIR=/data
+
+COPY package.json ./
+COPY SKILL-ORBIT.md ./SKILL-ORBIT.md
+COPY docs ./docs
+COPY src ./src
+COPY --from=build /app/dist/full ./dist/full
+
+VOLUME ["/data"]
+EXPOSE 3337
+
+ENTRYPOINT ["node", "/app/src/cli/orbit.js"]
+CMD ["serve", "--cwd", "/workspace"]

package/README.md

@@ -0,0 +1,216 @@
+# Starscape Orbit
+
+*Spin up an Orbit to track the motion of your project.*
+
+**Orbit** by ***Starscape*** is a lightweight, kanban-style project management solution for human-agent collaboration.
+
+Use it when you want the board to live with the code: one SQLite file, one small service, one human UI, and one agent-first API.
+
+- Human UI for creating, editing, and moving tickets kanban-style.
+- Agent API/MCP for claiming work, reading context, updating implementation notes, commenting, and writing project memory.
+
+## 🛰️ Zero runtime dependencies
+
+**Orbit installs with zero third-party runtime dependencies.** The server, CLI, and MCP layer use Node.js built-ins: `node:sqlite`, `node:http`, `node:crypto`, and friends.
+
+The single dev-only dependency is [`esbuild`](https://esbuild.github.io/), used to bundle the web UI at build time. It never ships and is not needed to run the server, CLI, or MCP.
+
+## Install and use Orbit
+
+Install the CLI:
+
+```bash
+corepack enable
+pnpm add -g @starlove/orbit
+
+# or, from source:
+git clone git@github.com:brucestarlove/ss-orbit.git
+cd ss-orbit
+pnpm install
+pnpm run build:full
+pnpm link --global
+```
+
+From the repo you want a board for:
+
+```bash
+cd path/to/your-app
+orbit init            # creates .orbit/board.db + SKILL-ORBIT.md + AGENTS.md
+orbit init --example  # optional: add onboarding example tickets
+```
+
+Start one runtime and keep using it:
+
+```bash
+orbit serve   # host runtime, uses ~/.orbit
+# or
+orbit docker  # Docker runtime, uses <repo>/.orbit/docker-data
+```
+
+Both serve `http://localhost:3337`. Use `--port 3400` to change ports and `--cwd path/to/repo` to bind a specific repo.
+
+`orbit serve` and `orbit docker` run the same app but use different registries by default. A board registered in one mode will not appear in the other unless you share `DATA_DIR`, re-register it, or import a snapshot.
+
+For multiple boards, run your chosen runtime once. In another terminal, `cd` into another repo and run `orbit init`; the board joins that runtime's board picker without a restart.
+
+Docker options:
+
+```bash
+orbit docker                 # builds starscape-orbit:local, then serves http://localhost:3337
+orbit docker --port 3400     # same container flow on a different port
+orbit docker --no-build      # reuse an existing starscape-orbit:local image
+```
+
+`orbit docker` mounts the selected project into the container. Board data still lives in `.orbit/board.db`; Docker-only registry, exports, and backups live under `<repo>/.orbit/docker-data` by default.
+
+Wipe a single board and start over with `orbit reset` (deletes `.orbit/`, `SKILL-ORBIT.md`, and the registry row), then `orbit init` again.
+
+## Use with AI
+
+Orbit ships with everything an agent needs to claim work, read tickets, and write back implementation notes — but it stays out of your way until you turn it on.
+
+1. **Enable AI on the board.** Open Settings (gear icon) → **AI** tab → toggle **Enable AI**. Orbit provisions the `AI Ready`, `In Progress`, and `Review` lanes if they're missing, surfaces the agent-context fields, and reveals the MCP setup snippet.
+2. **Fill in agent context.** Settings → AI → *Agent Instructions* is the project-level briefing every agent reads before touching a ticket. Describe what the project is, who it serves, the stack, and any rules of the road.
+3. **Register the MCP server with your agent.** The AI tab generates copy-pasteable snippets for Claude Code, Cursor, Codex, OpenCode, OpenClaw, and other MCP-capable clients — pick your OS + client and paste the command into your agent's MCP config.
+4. **Restart the agent.** On its next boot it discovers the Orbit MCP tools (`board_claim_next`, `board_get_ticket_context`, `board_update_ticket`, etc.).
+5. **Point the agent at a ticket.** From inside the repo, ask the agent to read `SKILL-ORBIT.md` and then work on a ticket via the Orbit MCP — e.g., *"Use the Orbit MCP to claim the next AI-ready card and start work."* It pulls a focused context pack, claims the ticket, and updates the board as it goes.
+
+If you initialized with `--example`, ticket #12 (`Try Orbit MCP on this ticket`) is a good first exercise once MCP is connected.
+
+## Vocabulary
+
+- **Board** — one repo's planning surface. Each board carries its own `agent_instructions`, lanes, tickets, and memory entries.
+- **Lane** — a column. Lanes are user-defined and freely named/reordered. The seed gives you `Backlog`, `Todo`, `In Progress`, `Review`, `Done`, `Cancelled`; turning on AI also pins `AI Ready`, `In Progress`, and `Review` as anchor lanes the agent flow keys off.
+- **Ticket types**:
+  - `epic` — index card for a multi-feature initiative. Owns child tickets via `parent_ticket_id`.
+  - `feature` — a standalone capability or new behavior.
+  - `task` — a smaller, scoped unit of work.
+  - `bug` — defect, regression, or broken behavior.
+- **Checkpoint** — mid-work human judgment: call `checkpoint` with your question. The ticket moves to `Review`; the `checkpoint` comment marks the blocking fork. Use `complete` when work is finished.
+- **Two relationship models** — hierarchy (`parent_ticket_id`, set on the row, only epics own children) is separate from the relations table (`relates_to`, `blocks`, `blocked_by`). The server keeps them disjoint.
+- **Blockers** — a per-card `blocked_by` row in the relations table is the single source of truth. If the row exists, the ticket is blocked. Rows are removed two ways: the user deletes the relation manually in the UI, **or** the *blocking* ticket lands in the **Done** lane and the server auto-deletes every relation row that named it as a blocker. (Epic targets expand to their open children — see `GET /api/tickets/:id/blockers`.)
+
+## Requirements
+
+- **Node.js 22+**. The server uses the built-in `node:sqlite` module (an experimental Node feature). On boot you'll see a Node experimental-feature warning — that's expected.
+- **pnpm 10+ for development**. The repo pins pnpm through `packageManager`; use Corepack (`corepack enable`) to get the right version.
+
+Bun is not used as the Orbit runtime because Orbit depends on Node's built-in `node:sqlite` module.
+
+## How it works
+
+Each repo gets its own board database. Orbit keeps a small central registry that maps repo paths to their board files; the CLI, web app, and MCP server use explicit project roots when provided, then fall back to walking upward to find `.orbit/board.db`.
+
+- **Per-repo board** — `.orbit/board.db` lives in the repo it tracks. `orbit init` creates it, drops `SKILL-ORBIT.md` at the repo root, and creates/updates `AGENTS.md` with a terse pointer so agents load the full Orbit protocol only when relevant. Add `--example` to create onboarding cards.
+- **Central registry** — `registry.db` records each board's path, slug, and last-active timestamp. Host `orbit serve` uses `~/.orbit`; `orbit docker` uses `<repo>/.orbit/docker-data`. Keep one mode unless you intentionally share `DATA_DIR`, re-register boards, or import snapshots.
+- **Project-root discovery** — `orbit serve`, `orbit mcp`, and MCP-attached agents resolve a board from an explicit `--cwd` / `PROJECT_ROOT` first, then fall back to walking up from process cwd to find `.orbit/board.db`. Persistent MCP configs should use an explicit root so the right board attaches even when the agent launches elsewhere.
+- **Two channels for AI** — `AGENTS.md` is the auto-loaded briefing, with an Orbit-managed pointer to `SKILL-ORBIT.md`; the *MCP config* tells the agent runtime how to launch Orbit's MCP server for the right project. The briefing travels with the repo; the MCP registration is per-agent-install.
+- **Snapshot-portable** — Settings → Repository → Export downloads a `.orbit.json` snapshot. Import on another install (or in the browser preview at [orbit.starscape.app/app](https://orbit.starscape.app/app)) to restore the same board.
+
+## Developing Orbit
+
+```bash
+pnpm install
+pnpm run dev
+pnpm test
+pnpm run build
+```
+
+Open `http://localhost:3337`.
+
+If you want an AI agent to work this board, point it at [SKILL-ORBIT.md](SKILL-ORBIT.md). Agent-facing HTTP/MCP details live in [docs/AGENT_PROTOCOL.md](docs/AGENT_PROTOCOL.md).
+
+**Two channels:** MCP config tells your AI app where `mcp-server.js` lives. `SKILL-ORBIT.md` is the repo-local briefing the agent reads before working.
+
+## Typical Workflow
+
+A normal day on a shared board:
+
+1. **Human** creates an epic for a new initiative and fills in card description with the high-level breakdown.
+2. **Human** or **Agent** breaks it into `feature` / `task` / `bug` cards under the epic and moves the workable ones to the `AI Ready` lane.
+3. **Human** directs **Agent** to find a ticket by number or name, or tell it to call `claim-next` to get one from the `AI Ready` column, which gets context for the ticket and important project notes, and starts work. Blocked tickets are skipped automatically.
+4. **Agent** either:
+  - calls `complete` with a summary and PR link, moving the card to `Review`; or
+  - calls `checkpoint` with a question if it is blocked mid-flight. Orbit moves the card to `Review` and records a checkpoint comment.
+5. **Human** reviews, merges, and moves the card to the `Done` lane (or sends it back with comments).
+
+## MCP
+
+Orbit ships a stdio MCP server for agents that prefer tools over raw HTTP. You don't normally start it yourself; your agent runtime spawns it from the snippet in **Settings → AI**. To run it standalone:
+
+```bash
+orbit mcp
+# equivalent: node src/mcp-server.js
+```
+
+MCP uses the same registry and board databases when launched with the same `DATA_DIR` and `--cwd` as the web runtime.
+
+A copy-editable client config lives at [docs/mcp-client.example.json](docs/mcp-client.example.json). The web app also generates setup snippets from **Settings → AI**. More detail is in [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
+
+### MCP tools
+
+
+| Purpose       | Tool                                                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Index         | `board_list` (tiny registry), `board_set_active`                                                                                                                                |
+| Board context | `board_context` (settings + journal + deployment; optional board + `include_struck`)                                                                                            |
+| Read          | `board_read_ticket`, `board_read_comments`, `board_get_ticket_context` (heavy), `board_get_ticket_relations`, `board_get_ticket_blockers`, `board_search`, `board_list_archive` |
+| Agent flow    | `board_claim_next`, `board_checkpoint`, `board_complete`                                                                                                                        |
+| Write         | `board_update_ticket`, `board_add_comment`, `board_add_board_entry`, `board_archive_ticket`, `board_restore_ticket`, `board_delete_ticket`                                      |
+| Admin         | `board_export_board`, `board_update_settings`                                                                                                                                   |
+
+
+## First-Run Seed
+
+`orbit init` (or first server start in a repo without a board) creates a universal board seed in the new `.orbit/board.db`:
+
+- **Board**: name from `BOARD_NAME` env var, otherwise inferred from `package.json` `name` or the repo folder name. Slug from `BOARD_SLUG` or derived from the name.
+- **Repo metadata**: `REPO_URL` env var or `git config --get remote.origin.url`; `SYSTEM_PATH` env var or the repo path passed to `orbit init`.
+- **Default branch**: `DEFAULT_BRANCH` env var, otherwise the current git branch.
+- **Lanes (6)**: `Backlog`, `Todo` (default), `In Progress`, `Review`, `Done`, `Cancelled`.
+- **Labels (7)**: `human-only`, `needs-human-input`, `needs-decomposition`, `needs-followup`, `tech-debt`, `security`, `onboarding`.
+- **Onboarding cards (optional)**: pass `--example` to create an epic `#1` plus children `#2`, `#3`, and `#12 — Try Orbit MCP on this ticket`.
+- **Free-form fields**: `project_notes` (Notes tab) and `agent_instructions` (AI tab) get placeholder text you should replace.
+
+Set env vars before `orbit init` or first runtime start to skip the placeholders:
+
+```powershell
+$env:BOARD_NAME="My App"; $env:BOARD_SLUG="my-app"; $env:REPO_URL="https://github.com/you/my-app"; orbit init
+```
+
+```bash
+BOARD_NAME="My App" BOARD_SLUG=my-app REPO_URL=https://github.com/you/my-app orbit init
+```
+
+## Troubleshooting
+
+- **UI loads but lanes are blank** — usually a cached `app.js`. Hard-refresh the page (Ctrl+Shift+R) and check the browser console.
+- **`node:sqlite` is not a known module** — you're on Node < 22. Upgrade to Node 22+.
+- **Port 3337 already in use** — run `orbit serve --port 3340` or `orbit docker --port 3340`.
+
+## Data
+
+Orbit stores each board in the repo it belongs to:
+
+- Board data: `.orbit/board.db`
+- Host registry and backups: `~/.orbit` by default
+- Docker registry and backups: `<repo>/.orbit/docker-data` by default
+
+Override runtime data with:
+
+```bash
+DATA_DIR=/path/to/data orbit serve
+orbit docker --data-dir /path/to/data
+```
+
+```powershell
+$env:DATA_DIR="C:\path\to\data"; orbit serve
+```
+
+The UI exposes **Export** and **Import** from **Settings → Repository**.
+
+**Export** downloads a portable `.orbit.json` file you can move to another computer or import later.
+
+**Automatic backups** are separate from Export. Orbit quietly saves local backup copies after you make changes, waiting about two minutes after your last edit so it does not create a file for every click. Orbit also makes an immediate backup before risky actions like deleting a board, resetting Orbit, or replacing a board during import.
+
+Backups are stored under the active runtime data dir's `backups/` folder. They are for local recovery; Export is still the easiest way to intentionally save or share a board.

package/SKILL-ORBIT.md

@@ -0,0 +1,94 @@
+# SKILL-ORBIT.md
+
+Read this before repo work. This board is the repo-local memory and execution layer.
+
+## MCP, cwd, and this file
+
+These are separate concerns; mixing them causes confusion:
+
+- **Where Orbit is installed** — Your MCP client stores an **absolute path** to Orbit's `src/mcp-server.js` (the generated snippet under **Settings → AI**). Claude Code / Codex / Cursor keep that registration. Starting your agent **from another folder** does not change that path.
+
+- **Which board MCP tools use** — The MCP helper uses the explicit project root passed by `orbit mcp --cwd <repo>` or `PROJECT_ROOT`; without either, it falls back to the process current working directory and walks upward until it finds a repo with `.orbit/board.db` (details in [`docs/MCP_SETUP.md`](docs/MCP_SETUP.md)). Prefer explicit `--cwd` / `PROJECT_ROOT` in persistent MCP configs so the right board attaches even when the agent launches elsewhere.
+
+- **This file** — Coding agents resolve `SKILL-ORBIT.md` through normal **filesystem / workspace search**, not through MCP tools. Keep a copy **in each repo** where you run an agent against that board—usually the repo that contains `.orbit/board.db`. If you edit in a multi-root workspace with more than one `SKILL-ORBIT.md`, name the repo or path explicitly in your prompt.
+
+## Use The Board
+
+- Read `agent_instructions` on the board first, then the ticket context pack.
+- Respect blockers and parent epics.
+- Use comments for discussion and breadcrumbs.
+- Use ticket fields for durable implementation records: `ai_plan`, `implementation_summary`, `implementation_updates`.
+- Add a project entry when the context should outlive one ticket.
+
+## Historical Backfill
+
+If asked to create historical tickets from logs, docs, commit history, notes, or conversations, reconstruct planning structure instead of making a flat list.
+
+- `epic`: multi-phase chunk or large initiative.
+- `feature`: standalone capability or one coherent stage of an epic.
+- `task`: smaller scoped unit of work, including maintenance, cleanup, config, refactor, or repo hygiene.
+- `bug`: defect, regression, incident, or broken behavior.
+
+Rules:
+
+- Prefer fewer, clearer epics with named feature cards underneath.
+- Preserve source references in descriptions or comments.
+- Mark uncertainty with `Inferred from...` or `Source suggests...`.
+- Put implementation facts in `implementation_summary`.
+- Put chronology, pitfalls, and lessons in `implementation_updates`.
+- Keep future work open unless the source clearly supports `Done`.
+- Do not invent acceptance criteria.
+
+## Board Context Model
+
+The board is the unit of organization. Each board is tied to one repo and carries:
+
+- `repo_url`, `system_path`, `default_branch`: where the code lives.
+- `agent_instructions`: project-level context for agents (purpose, surface area, stack, constraints, operating rules — included in ticket context packs). Edited under Settings → AI.
+- `project_notes`: Notes For You — personal reminders on the board (Settings → Notes).
+
+Use board-level memory entries for durable history:
+
+- `decision`: UX or architecture choices agents should follow instead of defaulting to generic codegen.
+- `lesson`: mistakes or discoveries distilled as "do X instead of Y when working with Z."
+
+## Ticket Relationships
+
+Two distinct, non-overlapping mechanisms:
+
+- **Hierarchy** — `parent_ticket_id` on the ticket row. One epic owns many features/tasks/bugs. Set on create or via `PATCH /api/tickets/:id`. Only epics can have children; pass `null` to detach. Do not duplicate this link in `relations`.
+- **Relations** — rows in the `relations` table with `type` of `relates_to`, `blocks`, or `blocked_by`. Use these for cross-cutting connections that aren't ownership: another team's ticket relates to mine, ticket A blocks ticket B, etc. The board rejects relations between a ticket and its direct parent epic (`relation_redundant_with_parent`) and self-relations (`relation_self`).
+
+Before working a ticket, check blockers. A ticket is **not workable** while it has any `blocked_by` relation row. The relation row is the source of truth — it gets removed when the blocking ticket moves into the Done lane (state role `done`, server auto-deletes) or when a user removes the link manually in the UI. If a `blocked_by` target is an epic, the rule expands to *the epic's open children* — the ticket only becomes workable once every child sits in a Done-role lane (or is archived). The `claim-next` scheduler skips blocked tickets automatically; for ad-hoc checks call `GET /api/tickets/:id/blockers` (returns `can_start` + the unresolved blockers list, with `via_epic_id` on entries that came from epic expansion).
+
+For a full picture of cross-cutting links call `GET /api/tickets/:id/relations`. The context pack (`GET /api/tickets/:id/context`) already includes both relations and blockers, so this dedicated endpoint is mostly for status-style queries that don't need the full pack.
+
+## Common API Actions
+
+- `GET /api/boards/:board_id/context`
+- `GET /api/boards/:board_id/archive`
+- `GET /api/tickets/:ticket_id/context?depth=1`
+- `GET /api/tickets/:ticket_id/relations`
+- `GET /api/tickets/:ticket_id/blockers`
+- `POST /api/agent/claim-next`
+- `PATCH /api/tickets/:ticket_id`
+- `POST /api/tickets/:ticket_id/archive`
+- `POST /api/tickets/:ticket_id/restore`
+- `DELETE /api/tickets/:ticket_id`
+- `POST /api/relations` / `DELETE /api/relations/:id`
+- `POST /api/boards/:board_id/entries`
+
+## Archive and Delete
+
+Removing a card is a two-step process:
+
+1. **Archive** (`POST /api/tickets/:ticket_id/archive`) — soft-deletes the card. Archived tickets are excluded from `bootstrap`, `search`, `claim-next`, blockers, relations, and the kanban view, but their data and comments are preserved. Reversible via `POST /api/tickets/:ticket_id/restore`.
+2. **Delete** (`DELETE /api/tickets/:ticket_id`) — permanently removes the card. The ticket MUST already be archived; calling DELETE on a live card returns `409 ticket_not_archived`. Comments, labels, and relations are removed via cascade. Events for the ticket are kept but their `ticket_id` becomes `NULL`.
+
+`GET /api/boards/:board_id/archive` returns `{ tickets: [...] }` listing archived tickets ordered by archive time (most recent first).
+
+The same flow is exposed over MCP as `board_archive_ticket`, `board_restore_ticket`, `board_delete_ticket`, and `board_list_archive`. Always archive before deleting; archive when in doubt — restore is cheap, deletion is not.
+
+## Current Rule
+
+Board is canonical for planning state. Git repo is canonical for code.

package/build.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// Two-edition static build. Bundles public/js/main.js with esbuild, copies
+// HTML/CSS/images alongside, and rewrites the script tag to point at the
+// hashed bundle. Edition is selected via `--edition=full|preview`; preview
+// substitutes `__ORBIT_EDITION__` so config.js reports edition="preview".
+
+import { build } from "esbuild";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(fileURLToPath(import.meta.url), "..");
+const PUBLIC_DIR = join(ROOT, "public");
+const DIST_DIR = join(ROOT, "dist");
+
+function parseArgs(argv) {
+  const args = { edition: "full" };
+  for (const a of argv.slice(2)) {
+    if (a.startsWith("--edition=")) args.edition = a.slice("--edition=".length);
+  }
+  if (!["full", "preview", "site"].includes(args.edition)) {
+    throw new Error(`--edition must be "full", "preview", or "site" (got "${args.edition}")`);
+  }
+  return args;
+}
+
+// "site" output combines the marketing landing at / with the preview app
+// at /app/ — the layout Vercel deploys for orbit.starscape.app.
+function assembleSite() {
+  const previewDir = join(DIST_DIR, "preview");
+  const siteDir = join(DIST_DIR, "site");
+  if (!existsSync(previewDir)) {
+    throw new Error("dist/preview missing — run `npm run build:preview` first");
+  }
+  rmSync(siteDir, { recursive: true, force: true });
+  mkdirSync(siteDir, { recursive: true });
+
+  // Marketing assets live at the repo root (the landing page references
+  // public/orbits-logo.png etc., which we mirror under public/ at the site
+  // root so existing href values keep resolving).
+  const marketingHtml = readFileSync(join(ROOT, "index.html"), "utf8")
+    .replace(/href="public\/index\.html"/g, 'href="/app/"');
+  writeFileSync(join(siteDir, "index.html"), marketingHtml);
+  writeFileSync(join(siteDir, "install.html"), marketingHtml);
+  writeFileSync(join(siteDir, "support.html"), marketingHtml);
+
+  for (const file of ["apple-touch-icon.png", "favicon-32x32.png", "orbits-favicon.png"]) {
+    const src = join(ROOT, file);
+    if (existsSync(src)) cpSync(src, join(siteDir, file));
+  }
+  const faviconSrc = join(ROOT, "favicon-32x32.png");
+  if (existsSync(faviconSrc)) cpSync(faviconSrc, join(siteDir, "favicon.ico"));
+
+  // Marketing references public/orbits-logo.png etc. — mirror the public/
+  // image set at the site root so we don't have to rewrite every img src.
+  mkdirSync(join(siteDir, "public"), { recursive: true });
+  for (const entry of readdirSync(join(ROOT, "public"))) {
+    if (!entry.endsWith(".png")) continue;
+    cpSync(join(ROOT, "public", entry), join(siteDir, "public", entry));
+  }
+  const cursorsSrc = join(ROOT, "public", "cursors");
+  if (existsSync(cursorsSrc)) {
+    cpSync(cursorsSrc, join(siteDir, "public", "cursors"), { recursive: true });
+  }
+
+  // Preview app at /app/.
+  cpSync(previewDir, join(siteDir, "app"), { recursive: true });
+  const appIndexPath = join(siteDir, "app", "index.html");
+  let appHtml = readFileSync(appIndexPath, "utf8");
+  appHtml = appHtml
+    .replace(/href="\.\/(apple-touch-icon\.png|favicon-32x32\.png)"/g, 'href="/app/$1"')
+    .replace(/href="(styles\.[^"]+\.css)"/g, 'href="/app/$1"')
+    .replace(/src="\.\/([^"]+\.png)"/g, 'src="/app/$1"')
+    .replace(/src="(js\/app\.[^"]+\.js)"/g, 'src="/app/$1"');
+  writeFileSync(appIndexPath, appHtml);
+
+  console.log(`✓ site → ${siteDir}`);
+  console.log(`  /         marketing landing`);
+  console.log(`  /app/     preview kanban (IndexedDB)`);
+  return;
+}
+
+function hashContent(buffer) {
+  return createHash("sha256").update(buffer).digest("hex").slice(0, 8);
+}
+
+// Preview build replaces api.js's transport import with the IndexedDB
+// backend. Filter matches the literal `./transport.js` import string only —
+// other imports keep their normal resolution.
+function previewTransportPlugin() {
+  return {
+    name: "preview-transport",
+    setup(build) {
+      build.onResolve({ filter: /^\.\/transport\.js$/ }, (args) => ({
+        path: resolve(args.resolveDir, "local-backend.js")
+      }));
+    }
+  };
+}
+
+async function run() {
+  const { edition } = parseArgs(process.argv);
+  if (edition === "site") {
+    return assembleSite();
+  }
+  const outDir = join(DIST_DIR, edition);
+
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+
+  // 1. Bundle JS. Single entry → single file, ESM, minified, tree-shaken.
+  const bundleResult = await build({
+    entryPoints: [join(PUBLIC_DIR, "js", "main.js")],
+    bundle: true,
+    format: "esm",
+    target: "es2022",
+    minify: true,
+    sourcemap: true,
+    write: false,
+    outfile: "app.js",
+    define: {
+      __ORBIT_EDITION__: JSON.stringify(edition)
+    },
+    legalComments: "none",
+    plugins: edition === "preview" ? [previewTransportPlugin()] : []
+  });
+
+  const jsFile = bundleResult.outputFiles.find((f) => f.path.endsWith(".js") && !f.path.endsWith(".map"));
+  const mapFile = bundleResult.outputFiles.find((f) => f.path.endsWith(".map"));
+  const jsHash = hashContent(jsFile.contents);
+  const jsName = `app.${jsHash}.js`;
+  mkdirSync(join(outDir, "js"), { recursive: true });
+  writeFileSync(join(outDir, "js", jsName), jsFile.contents);
+  if (mapFile) writeFileSync(join(outDir, "js", `${jsName}.map`), mapFile.contents);
+
+  // 2. Hash + copy CSS.
+  const cssSrc = join(PUBLIC_DIR, "styles.css");
+  const cssBuf = readFileSync(cssSrc);
+  const cssHash = hashContent(cssBuf);
+  const cssName = `styles.${cssHash}.css`;
+  writeFileSync(join(outDir, cssName), cssBuf);
+
+  // 3. Copy static assets (images, favicons) — anything in public/ that
+  // isn't HTML/CSS/JS source. Hashing not necessary; long-cache via headers.
+  for (const entry of readdirSync(PUBLIC_DIR)) {
+    const src = join(PUBLIC_DIR, entry);
+    if (entry === "js" || entry === "styles.css") continue;
+    if (entry.endsWith(".html")) continue;
+    if (statSync(src).isDirectory()) {
+      cpSync(src, join(outDir, entry), { recursive: true });
+    } else {
+      cpSync(src, join(outDir, entry));
+    }
+  }
+
+  // 4. Render index.html with rewritten asset references.
+  const htmlSrc = join(PUBLIC_DIR, "index.html");
+  if (!existsSync(htmlSrc)) {
+    throw new Error(`Missing ${htmlSrc}`);
+  }
+  let html = readFileSync(htmlSrc, "utf8");
+  // Use relative paths so the bundle works whether the build is mounted at
+  // "/" or "/app/" (preview on Vercel).
+  html = html.replace(/"\/?js\/main\.js"/g, `"js/${jsName}"`);
+  html = html.replace(/"\/?styles\.css"/g, `"${cssName}"`);
+  writeFileSync(join(outDir, "index.html"), html);
+
+  // 5. version.json — consumed by support/debug, also lets a status check
+  // confirm which bundle a host is serving.
+  const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+  writeFileSync(
+    join(outDir, "version.json"),
+    JSON.stringify(
+      {
+        name: pkg.name,
+        version: pkg.version,
+        edition,
+        builtAt: new Date().toISOString()
+      },
+      null,
+      2
+    ) + "\n"
+  );
+
+  const ext = extname(jsName);
+  console.log(`✓ ${edition} build → ${outDir}`);
+  console.log(`  js:  js/${jsName} (${(jsFile.contents.length / 1024).toFixed(1)} KB${ext === ".js" ? " min" : ""})`);
+  console.log(`  css: ${cssName} (${(cssBuf.length / 1024).toFixed(1)} KB)`);
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});