@starlove/orbit 1.4.1 → 2.0.0

package/Dockerfile

@@ -1,21 +1,23 @@
 # syntax=docker/dockerfile:1
+# Build the web app and the server first, as npm pack does:
+#   node build.mjs --edition=full && npx tsc -p tsconfig.build.json
+# The image installs only Orbit's runtime libraries (package.json dependencies).
 
-FROM node:22-slim AS runtime
+FROM node:24-slim AS runtime
 WORKDIR /app
 
 ENV NODE_ENV=production \
     PORT=13701 \
-    DATA_DIR=/data \
-    ORBIT_USE_DIST=1
+    DATA_DIR=/data
 
-COPY package.json ./
-COPY SKILL-ORBIT.md ./SKILL-ORBIT.md
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN corepack enable && pnpm install --prod --frozen-lockfile --ignore-scripts
 COPY docs ./docs
-COPY src ./src
+COPY lib ./lib
 COPY dist/full ./dist/full
 
 VOLUME ["/data"]
 EXPOSE 13701
 
-ENTRYPOINT ["node", "/app/src/cli/orbit.js"]
-CMD ["serve", "--cwd", "/workspace"]
+ENTRYPOINT ["node", "/app/lib/cli/orbit.js"]
+CMD ["run"]

package/README.md

@@ -2,239 +2,221 @@
 
 *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.
+**Tell your agent to use Orbit.** Your agent keeps the tickets, plans, and decisions. You get a calm, beautiful board to watch the work move.
 
-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.
+Orbit is a local-first kanban board for people and their AI agents. Boards stand alone; a code repository is optional. Each board has its own SQLite database, and Orbit keeps every board together in one data folder on your computer or your own server. Agents work the board through one small command language, the same in a shell, over MCP and over HTTP; you watch it live in the browser.
 
-- 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.
+## Quick start
 
-## Screenshots
+Say this to your AI agent (Claude Code, Codex, Cursor, Hermes, or any MCP client):
 
-These screenshots show Orbit in dark and light mode. They were captured before the `AI Ready` lane was added to the board.
+> Install Starscape Orbit and use it to manage this project. Setup: orbit.starscape.app/llms.txt
 
-![Orbit app in dark mode](docs/SS-Orbit-Dark.png)
-
-![Orbit app in light mode](docs/SS-Orbit-Light.png)
-
-## 🛰️ Zero external runtime dependencies
-
-**Orbit's server, CLI, and MCP layer run with zero external runtime dependencies.** They use Node.js built-ins: `node:sqlite`, `node:http`, `node:crypto`, and friends.
-
-Build-time packages include Starscape's own `@starlove/ui` styling and [`esbuild`](https://esbuild.github.io/) for bundling the web UI. They are not needed by initialized project boards at runtime.
-
-## 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:bundle
-pnpm link --global
-```
-
-From the repo you want a board for:
+Or do it yourself:
 
 ```bash
-cd path/to/your-app
-orbit init            # creates .orbit/board.db + managed SKILL-ORBIT.md + AGENTS.md
-orbit init --example  # optional: add onboarding example tickets
-orbit init --no-ai    # optional: create or update the board with AI disabled
+npm i -g @starlove/orbit && orbit run -d         # starts Orbit at http://localhost:13701
+claude mcp add --scope user orbit --env ORBIT_AGENT_NAME=claude -- orbit mcp   # connect your agent (other apps: Help, Connect your agents)
 ```
 
-Start one runtime and keep using it:
-
-```bash
-orbit run     # host runtime, uses ~/.orbit, refreshes managed SKILL-ORBIT.md copies
-# or
-orbit docker  # Docker runtime, uses <repo>/.orbit/docker-data
-```
+**For AI agents:** full setup steps for every client, including running Orbit on a private server, are at [orbit.starscape.app/llms.txt](https://orbit.starscape.app/llms.txt). Orbit speaks one small command language everywhere: `orbit view`, `orbit take`, `orbit finish 12 -m "..."` in a shell, or the same lines through the `orbit_read` and `orbit_write` MCP tools. `help` lists them all.
 
-Both runtimes serve from `http://localhost:13701` by default; `orbit run` auto-increments if that port is busy. Use `--port <n>` to force an exact port and `--cwd path/to/repo` to bind a specific repo. Use `orbit run -d` to start the host runtime in the background.
+![Orbit in dark mode](docs/SS-Orbit-Dark.png)
+![Orbit in light mode](docs/SS-Orbit-Light.png)
 
-`orbit run` 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.
+## Install and run
 
-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. `SKILL-ORBIT.md` is Orbit-managed guidance and may be overwritten by `orbit init` or refreshed by `orbit run`; keep repo/team-specific agent rules in `AGENTS.md` or board *Agent Instructions*.
-
-Docker options:
+Requires **Node.js 22.16 or newer**; 24 is recommended. (Orbit searches with SQLite's full-text search, which Node's own SQLite has from 22.16; `orbit` says so on an older Node.) Orbit supports Node 22 until Node's own security support for it ends, on April 30, 2027; the first Orbit release after that needs Node 24. Node from [nodejs.org](https://nodejs.org) or a version manager starts each `orbit` command about three times faster than Ubuntu's `nodejs` package. Install once, then start Orbit **from any directory**:
 
 ```bash
-orbit docker                 # builds starscape-orbit:local, then serves http://localhost:13701
-orbit docker --port 13702    # force a different published port
-orbit docker --no-build      # reuse an existing starscape-orbit:local image
+npm install -g @starlove/orbit
+orbit run
 ```
 
-`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. On Windows, close Orbit runtime terminals and restart any AI client using Orbit MCP before deleting or recloning a repo; those helper processes keep SQLite handles open while they are running.
+Open the URL printed in the terminal (normally `http://localhost:13701`). Choose **Create a board** or **Import a board**. Orbit starts with no boards and makes only the ones you choose.
 
-## Use with AI
+The server listens on **127.0.0.1** by default. `orbit run -d` keeps it running in the background (its log: `orbit-run.log` in the data folder); `--port <n>` chooses an exact port, otherwise Orbit takes the first free port from 13701. Set `DATA_DIR` to choose where boards live, and give the server, the CLI and every MCP server the same value.
 
-Orbit ships with everything an agent needs to claim work, read tickets, and write back implementation notes. New boards have AI collaboration enabled by default; pass `orbit init --no-ai` or turn off **Enable AI** in Settings → AI if you want a human-only board.
+**Coming from Orbit 1.x?** Orbit 2.0 keeps its boards in a new folder, `~/.starscape/orbit`, and doesn't open a 1.x data folder. From any 1.x (1.0 to 1.4) or the 2.0 preview:
 
-1. **Confirm AI is enabled.** Open Settings (gear icon) → **AI** tab → toggle **Enable AI** if needed. 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, VS 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.
+1. Stop the old Orbit and its MCP servers, then `npm i -g @starlove/orbit@2`.
+2. `orbit migrate` brings every board, card, comment, image and journal entry from `~/.orbit`, boards 1.x kept inside a project included, checks each against the original, and never changes the old folder. Kept your boards somewhere else? `orbit migrate <old folder>`.
+3. `orbit run`.
+4. Reconnect your agents with `orbit mcp` (Settings, AI). Setups made by 1.x still start until Orbit 3.0.
+5. Remove the `SKILL-ORBIT.md` and `AGENTS.md` block 1.x wrote into your projects.
 
-If you initialized with `--example`, ticket #12 (`Try Orbit MCP on this ticket`) is a good first exercise once MCP is connected.
+[Updating](docs/UPDATING.md) has the details, and the steps for a git checkout, a server and Docker. [The changelog](CHANGELOG.md) has what's new.
 
-### Dispatch a local Hermes run
+**Orbit 1.x stays.** 1.x's server, CLI and MCP run on Node's built-ins alone. It keeps that promise on its own line (`npm i -g @starlove/orbit@1`), and gets its own update after 2.0. Orbit 2.0 takes four runtime libraries, listed below, each for something 1.x wrote by hand.
 
-For a first-class handoff to a named Hermes profile, use `orbit dispatch` instead of writing an ad-hoc prompt file:
+### From source
 
 ```bash
-orbit dispatch --board my-app --ticket 12 --profile agent --worktree
-orbit dispatch 'http://orbit.example/#/b/my-app/t/<ticket-id>' --profile agent --worktree
-orbit dispatch --board my-app --ticket 12 --dry-run    # preview only; no writes or spawn
-orbit dispatch --board my-app --ticket 12 --no-spawn   # prepare handoff/comment; leave lane unchanged
+git clone https://github.com/brucestarlove/ss-orbit.git
+cd ss-orbit
+pnpm install
+npm run build:bundle && npm run build:node     # the web app into dist/full, the server into lib/
+node lib/cli/orbit.js run
 ```
 
-Dispatch validates the board, ticket, blockers, and Hermes availability before mutating a ticket. Normal spawn mode writes the generated handoff as a linked markdown artifact, stores only a terse plan summary in AI Plan, moves the ticket to **In Progress**, optionally preserves a git worktree/branch for review, starts Hermes, and comments a compact run record back onto the card. `--no-spawn` writes the handoff artifact/comment but does not move the ticket to In Progress. The default `agent-safe` policy allows local inspection, edits, tests, and commits while blocking Docker, pushes, deploys, package installs, destructive git commands, and common network/cloud escape hatches.
+Node 24 also runs the TypeScript directly: `node src/cli/orbit.ts run`. `npm run verify` is the check before a change (types, lint, the tests and the contract fixtures); [contributing](CONTRIBUTING.md) has the rest.
 
-`orbit dispatch` supports hosted boards through a full Orbit ticket URL or `--server-url <url> --board <slug> --ticket <id-or-number>`. In remote mode, hosted Orbit is the planning-state source of truth while `--cwd` points at the local code checkout/worktree root. Full operator/user guide: [docs/ORBIT_DISPATCH.md](docs/ORBIT_DISPATCH.md).
+## How it's built
 
-## Vocabulary
+Orbit is one core with several doors, over a storage contract any database can implement.
 
-- **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 default seed gives you `Backlog`, `Todo`, `AI Ready`, `In Progress`, `Review`, `Done`, `Cancelled`; `AI Ready`, `In Progress`, and `Review` are anchor lanes the agent flow keys off. `AI Ready` is inserted between `Todo` and `In Progress` when AI is enabled.
-- **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`.)
+- **The core** (`src/core/`) holds every rule: boards, cards, lanes, the journal, search, imports and exports. It runs on Node and in a browser alike, and touches storage only through the **storage port** (`src/store/types.ts`), an async interface with a conformance suite every adapter passes.
+- **Three adapters** implement the port: SQLite on a computer or server (`node:sqlite`, a database per board), IndexedDB in the browser, and memory for tests and embedding.
+- **The command language** (`src/commands/`) is what agents speak: `view`, `take`, `finish #12` and the rest, as short text answers built for models. The CLI, the MCP server and `POST /api/cmd` all run it.
+- **The doors:** `orbit run` serves the JSON API and the web app; `orbit mcp` is a stdio MCP server with two tools, `orbit_read` and `orbit_write`; the `orbit` CLI runs commands in a shell. Each works on the data folder directly or, with `ORBIT_MODE=remote`, against a server.
+- **The web app** (`web/`) is React with zustand, built by Vite. The full edition talks to `orbit run`; the browser edition at [orbit.starscape.app/app/](https://orbit.starscape.app/app/) runs the whole core in the page over IndexedDB, offline once loaded.
 
-## Requirements
+[Architecture](docs/ARCHITECTURE.md) has the map, the contracts and how to write an adapter of your own.
 
-- **Node.js 22.13+**. The server uses the built-in `node:sqlite` module, which is available without an experimental flag starting in 22.13 (or 23.4+). You'll still see an experimental-feature warning on boot — that's expected until the module stabilizes.
-- **pnpm 10+ for development**. The repo pins pnpm through `packageManager`; use Corepack (`corepack enable`) to get the right version.
+### Runtime libraries
 
-Bun is not used as the Orbit runtime because Orbit depends on Node's built-in `node:sqlite` module.
+What `npm install` brings, and what each is for:
 
-## How it works
+| Library | For |
+| --- | --- |
+| [`hono`](https://hono.dev) | The JSON API's routes. The same app answers `orbit run`'s requests and, in the browser edition, the page's own. |
+| [`@hono/node-server`](https://github.com/honojs/node-server) | Serves that app on Node's HTTP server for `orbit run`. |
+| [`@modelcontextprotocol/server`](https://github.com/modelcontextprotocol/typescript-sdk) | The MCP protocol for `orbit mcp`: the handshake, the tool list and the calls. |
+| [`zod`](https://zod.dev) | Checks an imported board's file before anything is written. Loaded only when an import runs. |
 
-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`.
+React, zustand and the web app's other code are compiled into the bundle Orbit ships (`dist/full`), so they aren't installed at runtime. SQLite is Node's own `node:sqlite`.
 
-- **Per-repo board** — `.orbit/board.db` lives in the repo it tracks. `orbit init` creates it, writes the managed `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. `orbit run` refreshes managed `SKILL-ORBIT.md` copies for registered repos on startup. Add `--example` to create onboarding cards, or `--no-ai` to disable AI collaboration for the board.
-- **Central registry** — `registry.db` records each board's path, slug, and last-active timestamp. Host `orbit run` 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 run`, `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 → Data → Export downloads a `.orbit.json` snapshot, with an option to embed attached images. Import on another install (or in the browser preview at [orbit.starscape.app/app](https://orbit.starscape.app/app)) to restore the same board.
+## Boards
 
-## Developing Orbit
-
-```bash
-pnpm install
-pnpm run dev
-pnpm test
-pnpm run build
-```
+Make a board in **Board → New**, or let a connected agent run `boards new <name>` (`orbit boards new <name>` in a shell). A board's slug is its stable name. Every board lives in Orbit's data folder, whatever folder you or your agent work in.
 
-Open the URL printed by `orbit run` (normally `http://localhost:13701`).
+Orbit never writes files into your repo. Agents learn Orbit from Orbit itself: the MCP instructions, `help`, and the guide. Put a project's rules for agents in the board's Agent Instructions (**Settings → AI**). Delete a board in **Settings → Data**; Orbit backs it up first.
 
-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).
+### Agent use
 
-**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.
+AI is on by default (**Settings → AI**), where you also write Agent Instructions and copy the setup for your agent's app. Agents work the board through one command language, the same in every client: a shell runs `orbit view`, MCP clients get two tools (`orbit_read`, `orbit_write`) that take the same command lines, and other programs `POST /api/cmd`. Answers are short text built for models: one line per card, cards as `#12`, lanes by name. An agent learns the loop from the server: short instructions on connect, the board's rules and next steps with every card it takes, `help`, and the full guide ([`docs/AGENT_GUIDE.md`](docs/AGENT_GUIDE.md)). Set `ORBIT_AGENT_NAME` so the board shows who did what.
 
-## Typical Workflow
+Day to day, move a card to **AI Ready** (the agent's `take` picks it up) or say "work on ticket 12" (`take #12`). The agent checks the card has enough context, asks if it doesn't, and hands finished work back in **Review**.
 
-A normal day on a shared board:
+An agent picks a board by its slug. Starting MCP **makes no board**. With one board, commands use it; with several, name one (`view <board>`, `board#12`), let the repo name it (`orbit boards link <board>` writes a one-line `orbit.json` to commit, so every agent in the repo lands on it), or set a default with `orbit boards use <board>` in a terminal (for every folder on this computer) or `ORBIT_BOARD`. Over MCP, `boards use` chooses a board for that session only. See [MCP setup](docs/MCP_SETUP.md) and [the agent protocol](docs/AGENT_PROTOCOL.md).
 
-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).
+## Storage, backup, and moving machines
 
-## MCP
+By default Orbit uses `~/.starscape/orbit` (each Starscape product keeps its own folder under `~/.starscape`), made readable by you alone when Orbit creates it:
 
-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
+```text
+DATA_DIR/
+  registry.db                         the boards: ids, slugs, and each board's folder
+  boards/<slug>/board.db              one SQLite database per board
+  boards/<slug>/attachments/          image bytes, beside the database
+  boards/<slug>/artifacts/            a card's markdown files (plans, handoffs)
+  backups/boards/<board id>/          a copy of a board before it is replaced or deleted, and one a day
+                                      after writes; the newest 30 are kept, each made of:
+    <time>-<reason>-<slug>.board.db     the database
+    <time>-<reason>-<slug>.files/       its attachments/ and artifacts/, beside the database
+    <time>-<reason>-<slug>.board.db.json  what it holds
+  backups/registry/                   the same for the list of boards
+  exports/                            saved exports
 ```
 
-MCP uses the same registry and board databases when launched with the same `DATA_DIR` and `--cwd` as the web runtime.
+A board keeps its folder when its slug changes, and a new board whose folder name is taken gets `<slug>-2`. The registry names folders, not full paths, so a whole data folder can move.
 
-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).
+To move boards between machines, choose **Board → Export → Include attached images → Export All** to download a ZIP of `.orbit.json` snapshots. **Settings → Data → Version and updates → Back up all boards** downloads the same ZIP, images included. Import the ZIP on the other machine with **Import a board** on an empty install (or Board → Export → Import boards later). A single `.orbit.json` works too. **Matching slugs replace existing boards**, so take a backup before importing into an Orbit that has boards. Snapshots made without images keep the images' names but not their bytes. After importing, check the board and card counts and a few images.
 
-### MCP tools
+Orbit's own copies hold a board's database and its images and markdown files together, so a deleted or replaced board comes back whole. A copy's files are hard links to the board's files, so an image that never changes takes no more disk in thirty copies than in one; where links aren't possible (another disk, a file system without them) the files are copied, and the copy's `.json` says which (`how`: linked, copied or mixed). The files folder of a copy goes with its database when old copies are cleaned up. If a copy's files couldn't be kept, Orbit logs it and keeps the database copy anyway. These copies sit on the same disk as the boards: they cover a mistake, not a dead disk. Back up the **whole data folder**, `backups/` and the images included, somewhere else too, and copy it with a tool that keeps hard links (`rsync -aH`, `tar`) or accept that each linked image is stored once per copy. If you change the data folder, give it to the server and MCP alike (`DATA_DIR=/path/to/data orbit run` on Unix; `$env:DATA_DIR='C:\path\to\data'; orbit run` in PowerShell).
 
+### Restoring a copy
 
-| 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` (lean), `board_get_ticket_context_full` (manual/journal), `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`                                                                                                                                   |
+Restoring is putting a copy back, with Orbit stopped (`orbit run`, and any `orbit mcp` or CLI process):
 
+1. Open `backups/boards/<board id>/` and pick a copy: `<time>-<reason>-<slug>.board.db`, with a `.files/` folder of the same name beside it.
+2. Copy the database to the board's folder as `boards/<folder>/board.db` (the folder is the board's own under `boards/`; the slug it was made with, unless that was taken). Delete `board.db-wal` and `board.db-shm` there if they exist.
+3. Copy what is inside the `.files/` folder (`attachments/` and `artifacts/`) into the same board folder, beside `board.db`. Copy, don't move: the files in the copy stay as they are.
+4. Start Orbit and open the board.
 
-## First-Run Seed
+A board that was deleted is also off the list. Orbit copied the list before it deleted the board: put `backups/registry/<time>-pre-board-delete.registry.db` back as `registry.db` (delete `registry.db-wal` and `registry.db-shm`), then do steps 2 and 3 in a new `boards/<folder>/`. That puts the list back as it was then, so first copy the whole data folder, and expect boards made after it to leave the list. To keep them, export them first.
 
-`orbit init` (or first server start in a repo without a board) creates a universal board seed in the new `.orbit/board.db`:
+## On a server
 
-- **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 (7)**: `Backlog`, `Todo` (default), `AI Ready`, `In Progress`, `Review`, `Done`, `Cancelled`. Pass `--no-ai` to seed without `AI Ready` and leave AI collaboration disabled.
-- **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.
+Orbit is one Node process and its data folder, so the simplest reliable way to run it on a VPS is as a system service. Linux's service manager, systemd, starts it at boot, restarts it if it stops, keeps its logs, and locks it down nearly as tightly as a container would.
 
-Set env vars before `orbit init` or first runtime start to skip the placeholders:
+### As a service (recommended)
 
-```powershell
-$env:BOARD_NAME="My App"; $env:BOARD_SLUG="my-app"; $env:REPO_URL="https://github.com/you/my-app"; orbit init
-```
+As root, with Node installed:
 
-```bash
-BOARD_NAME="My App" BOARD_SLUG=my-app REPO_URL=https://github.com/you/my-app orbit init
+```sh
+npm install -g @starlove/orbit
+useradd --system --home-dir /var/lib/orbit --shell /usr/sbin/nologin orbit
+command -v orbit    # the path for ExecStart below
 ```
 
-## Troubleshooting
+Save this as `/etc/systemd/system/orbit.service`, with that path in `ExecStart`:
+
+```ini
+[Unit]
+Description=Starscape Orbit
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=orbit
+ExecStart=/usr/local/bin/orbit run --port 13701
+Environment=NODE_ENV=production
+Environment=DATA_DIR=/var/lib/orbit
+StateDirectory=orbit
+StateDirectoryMode=0700
+Restart=on-failure
+RestartSec=5
+MemoryMax=512M
+# Locked down: a read-only system, no home folders, no new privileges.
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+RestrictNamespaces=yes
+RestrictRealtime=yes
+LockPersonality=yes
+ProtectClock=yes
+ProtectHostname=yes
+ProtectProc=invisible
+CapabilityBoundingSet=
+SystemCallArchitectures=native
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target
+```
 
-- **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+.
-- **Windows says `.orbit/board.db` is busy during cleanup** - an Orbit web server, MCP helper, editor, or terminal still has the SQLite file open. Stop the Orbit runtime, close or restart AI clients with Orbit MCP enabled, then retry delete from Settings or run `orbit reset --cwd <repo>` before recloning or deleting the folder.
+Then run `systemctl enable --now orbit` and check it with `curl http://127.0.0.1:13701/api/health`. Its logs are in `journalctl -u orbit`. Boards live in `/var/lib/orbit`: back up that whole folder.
 
-## Data
+Orbit listens on 127.0.0.1 only. Reach it through a private tunnel, never a public address: `ssh -N -L 13701:127.0.0.1:13701 you@server`, then open `http://localhost:13701`; or, on a tailnet, `tailscale serve --bg --https=13701 http://127.0.0.1:13701` (never Funnel). Agents on the server talk to it over HTTP: `ORBIT_MODE=remote ORBIT_API_URL=http://127.0.0.1:13701 orbit mcp`, or the same variables for the `orbit` command.
 
-Orbit stores each board in the repo it belongs to:
+To update Orbit, run `npm install -g @starlove/orbit@latest`, then `systemctl restart orbit`. Take Node's security releases as they come, the same way you installed Node, then restart the service.
 
-- Board data: `.orbit/board.db`
-- Host registry and backups: `~/.orbit` by default
-- Docker registry and backups: `<repo>/.orbit/docker-data` by default
+### Docker (optional)
 
-Override runtime data with:
+Orbit ships a `Dockerfile`, and Starscape's own Orbit runs in a locked-down container. From a source checkout, build the web app and the server first, then the image, and publish it only on **127.0.0.1**, with data kept on the host (`/data` in the container):
 
 ```bash
-DATA_DIR=/path/to/data orbit run
-orbit docker --data-dir /path/to/data
+npm run build:bundle && npm run build:node && docker build --pull -t orbit .
+docker run -d --name orbit --restart unless-stopped -p 127.0.0.1:13701:13701 -e HOST=0.0.0.0 -v ~/orbit-docker-data:/data orbit
 ```
 
-```powershell
-$env:DATA_DIR="C:\path\to\data"; orbit run
-```
+`HOST=0.0.0.0` lets Docker's port mapping reach the server inside the container; the `127.0.0.1` in `-p` keeps it off your network. Behind a reverse proxy with its own domain, add `-e ORBIT_ALLOWED_HOSTS=orbit.example.com`: Orbit answers only names it knows (IP addresses, `localhost`, full `*.ts.net` names and `HOST`'s), and 421 to the rest, a short tailnet name or a `.local` name included, which go in `ORBIT_ALLOWED_HOSTS` too. Orbit on the host and Orbit in Docker have separate data folders this way; share one only if you understand what two processes on one folder mean for your file system. The image carries its own Node, so rebuild it with `--pull` when Node ships a security release.
+
+### Security
 
-The UI exposes **Export** and **Import** from **Settings → Data**.
+Orbit's HTTP API serves **one trusted person and their agents**; it has no accounts. Keep Orbit's address private, the one agents on other computers use included: Orbit doesn't sign in remote clients, so anyone who reaches it owns your boards. Do **not** put it on a public address, rely on separate SQLite files to keep people apart, or treat a login page in front of it as hosted-service authorization. `HOST=0.0.0.0` deliberately opts into listening on the network; use it only inside a protected network. The API sends no CORS headers and refuses browser requests that come from another site (Fetch Metadata, falling back to `Origin`), so a web page you visit can't read or drive your boards through your browser; that adds to keeping the server private, it doesn't replace it. The app also refuses to be framed by other sites, sends a script policy that runs only its own scripts, and never shows an attachment as a page: images are PNG, JPEG, GIF, WebP or AVIF, and anything else (an SVG a shared board brought) is offered as a download. `orbit run` answers only a browser that reached it by an IP address, `localhost`, a full tailnet name (`*.ts.net`) or the name in `HOST`; any other name goes in `ORBIT_ALLOWED_HOSTS` (comma-separated), or Orbit answers 421: a reverse proxy's own domain, and also a short tailnet name (`http://mybox:13701`), a `.local` name or a name your LAN's DNS gives. That stops a DNS rebinding, where another site's name is pointed at your computer. Agents never see the server's folders, the board's private notes, or comments a person hid from AI. Accounts, board-scoped agent tokens and hosted multi-user Orbit are future work, not part of this setup.
 
-**Export** downloads a portable `.orbit.json` file you can move to another computer or import later. By default it stores image attachment records without image bytes; enable **Include attached images** to embed the images in the snapshot.
+For updates and moving from 1.x, see [updating](docs/UPDATING.md).
 
-**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.
+## License
 
-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.
+AGPL-3.0. See [LICENSE](LICENSE).

package/dist/full/csp.txt

@@ -0,0 +1 @@
+default-src 'self'; script-src 'self' 'sha256-kLYwoO3pLfw/PQENSuRkD8x0mBkQrv1A5fhVedYez3M=' 'sha256-UmjJBwGq+DKi5mG+H5TrVRzCLdnf+3YwUUV8EK/F77Y='; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'

package/dist/full/fonts/JetBrains_Mono/README.txt

@@ -77,3 +77,8 @@ commercial or otherwise.
 
 This isn't legal advice, please consider consulting a lawyer and see the full
 license for all details.
+
+JetBrainsMono-subset.woff2 is the same face (OFL.txt beside it) cut to
+Starscape's subset, the file starscape.biz and Nebula serve: upright, weight
+400 to 500, Basic Latin, Latin-1 and common punctuation. Orbit's landing sets
+its commands and paths in it.