@starlove/orbit 1.4.0 → 2.0.0

package/docs/AGENT_PROTOCOL.md

@@ -1,424 +0,0 @@
-# Agent Protocol
-
-The board is intentionally agent-first. Agents should not scrape the UI. They should call the API and ask for narrow context packs.
-
-If an MCP client is available, use the MCP server instead of rebuilding these HTTP calls yourself. The MCP tools map directly to the same core operations.
-
-Never edit `.orbit/board.db` directly to create or mutate cards. The SQLite file is Orbit's storage detail; use the HTTP API or MCP tools so validation, events, search indexing, backups, and cross-process locking all run.
-
-## Core Flow
-
-1. `POST /api/agent/claim-next`
-2. Implement using the returned context pack.
-3. Add progress comments with `POST /api/tickets/:id/comments`.
-4. If blocked by human judgment, call `POST /api/agent/checkpoint`.
-5. When ready for review, call `POST /api/agent/complete`.
-
-### End-to-end example
-
-```http
-POST /api/agent/claim-next
-Content-Type: application/json
-
-{ "board": "your-board-slug" }
-```
-
-The response includes the claimed `ticket` and a `context` pack. After working the ticket:
-
-```http
-POST /api/tickets/abc123/comments
-Content-Type: application/json
-
-{ "body": "Wired the new endpoint and added a smoke test.", "kind": "agent_note" }
-```
-
-```http
-POST /api/agent/complete
-Content-Type: application/json
-
-{
-  "ticket_id": "abc123",
-  "summary": "Implemented the new endpoint with input validation and tests.",
-  "updates": "Hit a flaky test on Windows; pinned timeouts to 5s.",
-  "pr_url": "https://github.com/you/repo/pull/42"
-}
-```
-
-## Endpoints
-
-### List boards (thin)
-
-```http
-GET /api/boards
-```
-
-Returns `{ "boards": [ ... ] }` with registry metadata only (`id`, `slug`, `name`, `repo_path`, `repo_url`, `default_branch`, `db_path`, `last_active_at`). Does not load tickets or lanes. MCP equivalent: `board_list`.
-
-For the web UI’s full default-board snapshot (tickets, states, labels, entries), the SPA calls `GET /api/bootstrap`. Agents over MCP should use `board_list`, `board_set_active`, `board_context`, and ticket-scoped tools instead—there is no MCP mirror of bootstrap.
-
-### Claim Next
-
-```http
-POST /api/agent/claim-next
-Content-Type: application/json
-
-{
-  "board": "your-board-slug",
-  "type": "feature"
-}
-```
-
-Returns the first schedulable `AI Ready` ticket. The scheduler skips tickets blocked by unresolved `blocked_by` relations.
-
-By default, `claim-next` skips `epic` cards because they are index/planning cards. To claim an epic for planning, pass `"type": "epic"` or `"include_epics": true`.
-
-The response shape is `{ claimed: true, ticket_id, context }` where `context` is the lightweight `board_read_ticket` pack (`ticket` with title/description/labels/state and the `board_manual`). Ticket comments are not included in the default claim context; call `GET /api/tickets/:id/comments` (or MCP `board_read_comments`) when an explicit chat/comment surface needs them. For the lean ticket relationship pack, call `GET /api/tickets/:id/context` (or MCP `board_get_ticket_context`). For the historical heavy pack with board manual/journal attached, call `GET /api/tickets/:id/context/full` (or MCP `board_get_ticket_context_full`).
-
-### Read Lightweight Ticket
-
-```http
-GET /api/tickets/:id
-GET /api/tickets/lookup?board=your-board-slug&number=42
-GET /api/tickets/lookup?board=your-board-slug&title=Exact%20Title
-```
-
-MCP equivalent: `board_read_ticket`.
-
-Returns the lightweight agent read shape: `ticket` with identity, title, description, labels, state/type/priority, plus `board_manual`. Ticket comments, relations, blockers, child cards, and implementation fields are intentionally omitted. Use this for quick orientation and claim context. The `lookup` form is exact by per-board ticket number or exact title; it does not use fuzzy search or comment/implementation indexes.
-
-### Get Lean Ticket Context Pack
-
-```http
-GET /api/tickets/:id/context?depth=1
-```
-
-Returns:
-
-- Ticket, board identity, state, labels.
-- Human-visible card fields: terse AI Plan (`ai_plan`), terse Work Summary (`implementation_summary`), and Revisions (`implementation_updates`); full handoffs/reports live in linked markdown artifact paths. Board Journal decisions/lessons carry the most important code/pattern/project context loaded for every agent on the board.
-- Parent epic/story ticket when present.
-- Child feature cards when the ticket is an epic/story.
-- Related tickets.
-- Blockers and blocking tickets.
-
-Project manual/journal (`agent_instructions` and board entries) and ticket comments are intentionally omitted from this default agent context. Human-only `project_notes` are not part of agent context surfaces. Fetch project context and comments explicitly when needed:
-
-```http
-GET /api/boards/:board_id/context?include_struck=false
-GET /api/tickets/:id/comments
-```
-
-MCP equivalents: `board_context` and `board_read_comments`.
-
-### Get Full Ticket Context Pack
-
-```http
-GET /api/tickets/:id/context/full?depth=1
-```
-
-MCP equivalent: `board_get_ticket_context_full`.
-
-Returns the historical heavy context shape: everything in the lean ticket context plus the full board row and `board_manual` / journal. Comments are still intentionally omitted; explicit comment/chat consumers should call:
-
-```http
-GET /api/tickets/:id/comments
-```
-
-MCP equivalent: `board_read_comments`.
-
-### Get Ticket Relations
-
-```http
-GET /api/tickets/:id/relations
-```
-
-Returns every link touching the ticket. Each entry has `type`, `direction` (`outgoing` / `incoming`), `source`, and a compact `other_ticket` summary.
-
-- `source: "relation"` — peer rows from the relations table (`relates_to` / `blocks` / `blocked_by`). These have a real `id` and are mutated via `POST /api/relations` and `DELETE /api/relations/:id`.
-- `source: "hierarchy"` — read-only synthetic entries surfacing epic ownership: `child_of` pointing at the parent epic, `parent_of` pointing at each child. `id` is `null`. Mutate via `PATCH /api/tickets/:id` setting `parent_ticket_id`; the relations endpoints reject `child_of` / `parent_of` writes (`hierarchy_uses_parent_ticket_id`).
-
-### Get Ticket Blockers
-
-```http
-GET /api/tickets/:id/blockers
-```
-
-Returns:
-
-```json
-{
-  "ticket_id": "...",
-  "can_start": false,
-  "blockers": [
-    { "id": "...", "number": 12, "title": "...", "state_name": "In Progress", "state_role": "in_progress" }
-  ]
-}
-```
-
-**Source of truth.** Blocker dependencies are defined exclusively by per-card `blocked_by` (and the inverse `blocks`) rows in the relations table — see `POST /api/tickets/:id/relations`. If a row exists, the blocker is unresolved. Rows are removed two ways: a user deletes the relation manually in the UI, or the *blocking* ticket moves into the Done lane (state role `done`) and the server auto-deletes every relation that named it as a blocker. `can_start` is `false` whenever any `blocked_by` row remains. Agents must not move a `can_start: false` ticket into a started state. The `claim-next` scheduler enforces this automatically.
-
-**Epic expansion.** When a `blocked_by` target is an epic, the epic itself is not treated as a blocker — its open children are. A child counts as "open" while it sits in any lane whose role is not `done` (and isn't archived). Each expanded blocker carries `via_epic_id` pointing at the epic that brought it into the list, so reports can explain the dependency.
-
-### Create / Delete Relation
-
-```http
-POST /api/relations
-Content-Type: application/json
-
-{
-  "source_ticket_id": "...",
-  "target_ticket_id": "...",
-  "type": "blocked_by"
-}
-```
-
-```http
-DELETE /api/relations/:id
-```
-
-Rejected with HTTP 400 if the pair already has a `parent_ticket_id` link in either direction (`relation_redundant_with_parent`) or if source equals target (`relation_self`). Use `parent_ticket_id` for epic ↔ direct-child ownership; use relations only for cross-cutting links.
-
-### Search
-
-```http
-GET /api/search?q=auth%20middleware&board=your-board-slug
-```
-
-Searches ticket titles, descriptions, and comments.
-
-### Board context (settings + journal)
-
-```http
-GET /api/boards/:board_id/context?include_struck=false
-```
-
-Returns the same shape as MCP `board_context`: agent-safe board metadata (`agent_instructions`, repository paths, default branch), `entries` (journal / decisions / lessons), and `deployment` paths. Human-only `project_notes` are intentionally excluded. Use `include_struck=true` to include struck journal rows (default off).
-
-MCP: `board_context` with optional `board_id` / `board_slug` / `board` and optional `include_struck`.
-
-### Update Board
-
-```http
-PATCH /api/boards/:board_id
-Content-Type: application/json
-
-{
-  "name": "...",
-  "repo_url": "https://github.com/you/repo",
-  "system_path": "C:/path/to/repo",
-  "default_branch": "main",
-  "agent_instructions": "How agents should work here..."
-}
-```
-
-Each board carries a `repo_url` and `system_path` (both optional). They surface in Settings → Repository and travel with the board through export/import.
-
-### Add Board Memory Entry
-
-```http
-POST /api/boards/:board_id/entries
-Content-Type: application/json
-
-{
-  "type": "decision",
-  "title": "Use journal entries as agent-facing project memory",
-  "body": "Record Decisions for UX and architecture choices agents should follow. Record Lessons for mistakes or discoveries distilled as 'do X instead of Y when working with Z.'"
-}
-```
-
-Allowed entry types:
-
-- `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."
-
-Entries with `struck_at` set are retained for human review but omitted from board manual/context responses unless the REST client explicitly requests `include_struck=true`.
-
-### Strike Or Restore Board Memory Entry
-
-```http
-PATCH /api/board-entries/:entry_id
-Content-Type: application/json
-
-{
-  "struck": true
-}
-```
-
-### Export Board Snapshot
-
-```http
-GET /api/boards/:board_id/export?include_attachments=true
-```
-
-Returns a JSON snapshot of the board, states, tickets, comments, relations, image attachment metadata, board entries, and relevant event history. Image bytes are excluded by default; pass `include_attachments=true` (or `include_images=true`) to embed present attachment files as base64. Missing attachment files are marked in metadata instead of failing the export.
-
-### Import Board Snapshot
-
-```http
-POST /api/admin/import
-Content-Type: application/json
-
-{
-  "snapshot": { "...": "export payload" },
-  "replace_existing": true
-}
-```
-
-Replaces the current board with a previously exported snapshot. Export first if you want a rollback point.
-
-### Add Comment
-
-```http
-POST /api/tickets/:id/comments
-Content-Type: application/json
-
-{
-  "body": "Implementation note...",
-  "kind": "agent_note"
-}
-```
-
-Comments are for discussion and event breadcrumbs. Use the dedicated fields below for durable implementation records.
-
-### Ticket Field Contract
-
-```http
-PATCH /api/tickets/:id
-Content-Type: application/json
-
-{
-  "ai_plan": "Next: implement the sync queue, add conflict tests, verify with pnpm test.",
-  "plan_artifact_path": ".orbit/dispatch-runs/.../handoff.md",
-  "implementation_summary": "Shipped sync queue + conflict tests. pnpm test passed. Risk: mobile offline smoke remains human-owned.",
-  "implementation_artifact_path": ".orbit/dispatch-runs/.../report.md",
-  "implementation_updates": "Revision: narrowed conflict retry to failed operations only."
-}
-```
-
-Field intent:
-
-- `ai_plan`: existing AI Plan field. Store a terse visible plan summary for humans. Use `plan_artifact_path` for full markdown/text handoffs or plan docs.
-- `plan_artifact_path`: human-editable local/repo-relative or hosted-readable markdown/text path, for example `docs/plan.md` or `./docs/plan.md`. The UI resolves it when opening the artifact; if it cannot resolve, the human can edit the path.
-- `implementation_summary`: existing Work Summary field. Store a terse visible result summary for humans. Use `implementation_artifact_path` for full reports/evidence.
-- `implementation_artifact_path`: human-editable local/repo-relative or hosted-readable markdown/text path to the full report/evidence artifact, for example `docs/report.md` or `./docs/report.md`.
-- `implementation_updates`: Revisions. Use only for terse later changes/corrections after initial implementation. Leave blank for normal first completion; do not store chronology, command logs, run receipts, or durable project lessons here.
-- Comments are for compact run receipts, transient breadcrumbs, and discussion.
-- Board Journal entries are for durable reusable project decisions/lessons.
-
-Direct `PATCH /api/tickets/:id` updates the fields exactly. For normal completion, prefer `/api/agent/complete`: its `summary` writes Work Summary (`implementation_summary`), `implementation_artifact_path` links the full report, and optional `updates` writes Revisions only when the run is a later correction/change.
-
-### Archive, Restore, and Delete
-
-Removing a card is a two-step contract: archive first (soft-delete), then optionally permanently delete. Restore reverses an archive.
-
-```http
-POST /api/tickets/:id/archive
-```
-
-Soft-deletes the ticket: sets `archived_at` to the current time and bumps `updated_at`. Archived tickets are filtered out of `GET /api/bootstrap`, `GET /api/search`, `POST /api/agent/claim-next`, `GET /api/tickets/:id/blockers`, `GET /api/tickets/:id/relations`, and child-of-epic listings. Their data, comments, labels, and relations are preserved. Idempotent — archiving an already-archived ticket is a no-op.
-
-```http
-POST /api/tickets/:id/restore
-```
-
-Clears `archived_at`. The ticket reappears on the kanban in its previous lane (the `state_id` is preserved across archive/restore).
-
-```http
-DELETE /api/tickets/:id
-```
-
-Permanently removes the ticket. Returns `409 ticket_not_archived` if the ticket is not currently archived. Cascades delete all comments, ticket-label rows, and relations. Events for the ticket are kept but their `ticket_id` is set to `NULL`. Response: `{ "ok": true, "deleted_id": "..." }`.
-
-```http
-GET /api/boards/:board_id/archive
-```
-
-Returns `{ "tickets": [...] }` — all archived tickets for the board, ordered by `archived_at` descending (most recent first). Each ticket carries the same fields as `bootstrap.tickets`.
-
-Over MCP these are exposed as `board_archive_ticket`, `board_restore_ticket`, `board_delete_ticket`, and `board_list_archive`. Always archive when intent is "remove"; only delete when intent is "delete forever and you have already confirmed."
-
-### Create Epic With Feature Cards
-
-Ticket types are `epic`, `feature`, `task`, and `bug`.
-
-MCP equivalent: `board_create_ticket`. Use it for new cards instead of modifying `.orbit/board.db`.
-
-Create the epic/story parent first:
-
-```http
-POST /api/tickets
-Content-Type: application/json
-
-{
-  "board_id": "board-id",
-  "type": "epic",
-  "title": "Build offline-first sync",
-  "description": "High-level vision and outcome.",
-  "ai_plan": "Feature 1: schema. Feature 2: queue. Feature 3: conflict UI.",
-  "labels": ["ai-eligible"]
-}
-```
-
-Then create feature cards with `parent_ticket_id`:
-
-```http
-POST /api/tickets
-Content-Type: application/json
-
-{
-  "board_id": "board-id",
-  "type": "feature",
-  "parent_ticket_id": "epic-ticket-id",
-  "title": "Feature 1: sync schema",
-  "ai_plan": "Implement the local operation log and migration.",
-  "labels": ["ai-eligible"]
-}
-```
-
-### Checkpoint
-
-```http
-POST /api/agent/checkpoint
-Content-Type: application/json
-
-{
-  "ticket_id": "ticket-id",
-  "message": "CHECKPOINT: Option A vs B..."
-}
-```
-
-Moves the ticket to `Review` (same lane as `/api/agent/complete`) and adds a **`checkpoint`** comment with `message`—use it for mid-flight forks; use `complete` when work is done.
-
-### Complete
-
-```http
-POST /api/agent/complete
-Content-Type: application/json
-
-{
-  "ticket_id": "ticket-id",
-  "summary": "Implemented the requested change. Tests pass.",
-  "updates": "Important implementation notes and lessons.",
-  "pr_url": "https://github.com/you/repo/pull/123"
-}
-```
-
-Moves the ticket to `Review` by default and writes `summary` into Work Summary (`implementation_summary`). If `updates` is present, it is appended to Revisions (`implementation_updates`) without timestamp headings; omit `updates` for normal first completion notes.
-
-## Ticket Writing Contract
-
-Agents perform best when tickets include:
-
-- Clear requirements.
-- Acceptance criteria.
-- Relations for dependencies, especially `blocked_by`. Use `parent_ticket_id` for epic ownership, not relations.
-- Pointers to previous related tickets or comments.
-
-## Two Relationship Models
-
-The board separates structural ownership from cross-cutting links. Treat these as non-overlapping:
-
-- **Hierarchy (`parent_ticket_id`)** — set on the ticket row. Only epics can own children; non-epics carry the parent id. Detach by `PATCH`-ing `parent_ticket_id: null`. The dispatcher and context pack walk this link to surface parent / child cards.
-- **Relations table** — typed links between any two tickets with `relates_to`, `blocks`, or `blocked_by`. The server rejects relation rows that mirror a `parent_ticket_id` link or point a ticket at itself, so the two models stay disjoint.
-
-A ticket is workable only when its `can_start` is `true` (no unresolved `blocked_by`). Use `GET /api/tickets/:id/blockers` for a status check, or read the context pack which already embeds blockers and relations.

package/docs/MCP_SETUP.md

@@ -1,54 +0,0 @@
-# MCP Setup
-
-Use `mcp-client.example.json` in this folder as a copy-editable starting point for any MCP-capable client, including VS Code, Cursor, Claude Desktop, Claude Code, Codex, OpenCode, and similar tools.
-
-The easiest path is **Settings -> AI** in the web app:
-
-1. Confirm or change the detected operating system.
-2. Choose the AI app or agent harness.
-3. Copy the generated setup snippet.
-4. Paste it into that app's MCP settings or run the generated CLI command.
-
-Orbit generates neutral template paths for Windows, macOS, and Linux. Replace those placeholders with the real path to **`src/mcp-server.js`** inside your Orbit checkout. That tells the AI client **how to spawn the MCP helper**; it does not ship markdown or project context—the agent reads files (like `SKILL-ORBIT.md`) from whichever repo/workspace you opened.
-
-Board data lives under each tracked repo at `.orbit/board.db` (flat file or `.orbit/boards/<slug>/` for extra boards)—not beside the MCP script.
-
-After installing Orbit as a package, run **`orbit init`** in (or with `--cwd` pointing at) the repo where you want `.orbit/`, **`AGENTS.md`**, and the managed **`SKILL-ORBIT.md`** so agents and MCP line up with that tree. Orbit enables the AI Ready / In Progress / Review agent lanes by default. Add `--no-ai` if you want AI collaboration disabled, and add `--example` if you want the onboarding example tickets. Keep repo-specific agent customization in `AGENTS.md` or board *Agent Instructions*; `SKILL-ORBIT.md` is Orbit-managed and may be overwritten by `orbit init` or refreshed by `orbit run`.
-
-The generated format changes by app:
-
-- Cursor, Claude Desktop, and generic MCP clients get `mcpServers` JSON.
-- VS Code gets an `mcp.json` snippet with a top-level `servers` object.
-- Claude Code gets a `claude mcp add ... -- node ...` command.
-- Codex gets a `[mcp_servers.starscape-orbit]` TOML snippet.
-- OpenCode gets an `opencode.json` snippet under `mcp`.
-
-The checked-in example file is not read automatically by Starscape Orbit. It exists so a user can:
-
-1. Open the example.
-2. Copy the `minimal-agent-board` server block into their own MCP client config.
-3. Replace the path to `src/mcp-server.js` with the absolute path on your machine.
-4. Restart the MCP client.
-
-By default MCP runs in local mode. It finds a board from an explicit project root first: pass `orbit mcp --cwd <repo>` or set `PROJECT_ROOT=<repo>` in persistent MCP configs. If neither is set, it falls back to the process cwd and walks upward to the first ancestor with `.orbit/board.db`. Prefer explicit roots for long-lived agent configs so launching the agent from another folder does not attach the wrong board.
-
-For a shared/deployed board, run MCP in remote mode instead: set `ORBIT_MODE=remote`, `ORBIT_API_URL=<server origin>`, and usually `ORBIT_DEFAULT_BOARD=<slug-or-id>`. Remote mode calls the HTTP API and does not open or auto-create local `.orbit` databases; it fails at startup if `ORBIT_API_URL` is missing. **`AGENTS.md` / `SKILL-ORBIT.md`** are unrelated to MCP transport: agents open them via the workspace file tree, `orbit init` keeps a terse Orbit pointer section in `AGENTS.md`, and `orbit run` refreshes managed `SKILL-ORBIT.md` copies for registered repos.
-
-Typical use:
-
-- Keep the web UI running with `orbit run` (`node src/server.js` is fine for source-tree development, but `orbit run` is the package command that refreshes managed `SKILL-ORBIT.md` copies).
-- Point the MCP client at `node src/cli/orbit.js mcp --cwd /absolute/project`, set `PROJECT_ROOT=/absolute/project` with `node src/mcp-server.js`, or paste the generated setup from Settings -> AI.
-- Use the MCP tools to claim tickets, read context, update implementation fields, and write project memory.
-
-## System Impact
-
-Running the MCP server starts a small local helper process. It reads and updates the same local board data as the web app, does not publish the board to the internet, and can be removed from your AI app's MCP settings whenever you want.
-
-On Windows, that helper process can keep `.orbit/board.db` and its WAL/SHM sidecar files locked while the AI client is running. Before deleting or recloning a repo that has an Orbit board, close or restart the AI client, stop any Orbit runtime terminal, and prefer `orbit reset --cwd <repo>` for cleanup.
-
-The MCP server is only the bridge. Your AI app is still the part that decides what to do, and that app may send ticket context to its AI provider when you ask it to work on cards. Only connect AI apps you trust with this project.
-
-Important:
-
-- Run the MCP helper and web server against the **same Orbit checkout and `DATA_DIR`** (default `~/.orbit`, override with `DATA_DIR=/path`) so they share one `registry.db` and agree on paths to `.orbit/board.db` files—but remember **`AGENTS.md` / `SKILL-ORBIT.md` are plain repo text**, not streamed over MCP.
-- The generated setup assumes local/open mode. Protected deployments can still add MCP auth manually later.