@starlove/orbit 1.0.7 → 1.1.0

package/README.md

@@ -43,7 +43,7 @@ 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            # 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
 ```
@@ -51,7 +51,7 @@ orbit init --no-ai    # optional: create or update the board with AI disabled
 Start one runtime and keep using it:
 
 ```bash
-orbit serve   # host runtime, uses ~/.orbit
+orbit serve   # host runtime, uses ~/.orbit, refreshes managed SKILL-ORBIT.md copies
 # or
 orbit docker  # Docker runtime, uses <repo>/.orbit/docker-data
 ```
@@ -60,7 +60,7 @@ Both serve `http://localhost:3337`. Use `--port 3400` to change ports and `--cwd
 
 `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.
+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 serve`; keep repo/team-specific agent rules in `AGENTS.md` or board *Agent Instructions*.
 
 Docker options:
 
@@ -72,7 +72,7 @@ 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.
+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 serve` 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.
 
 ## Use with AI
 
@@ -86,6 +86,20 @@ Orbit ships with everything an agent needs to claim work, read tickets, and writ
 
 If you initialized with `--example`, ticket #12 (`Try Orbit MCP on this ticket`) is a good first exercise once MCP is connected.
 
+### Dispatch a local Hermes run
+
+For a first-class handoff to a named Hermes profile on a local board, use `orbit dispatch` instead of writing an ad-hoc prompt file:
+
+```bash
+orbit dispatch --board my-app --ticket 12 --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
+```
+
+Dispatch validates the local board, ticket, blockers, and Hermes availability before mutating a ticket. Normal spawn mode writes the generated handoff into the ticket's **AI Written-Plan**, moves the ticket to **In Progress**, optionally preserves a git worktree/branch for review, starts Hermes, and comments a run record back onto the card. `--no-spawn` writes the handoff/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.
+
+`orbit dispatch` is intentionally not a hosted-board client yet: `--server-url` and `--remote` are refused before side effects. Use remote MCP tools for hosted/remote boards, or run dispatch on the board host. Full operator/user guide: [docs/ORBIT_DISPATCH.md](docs/ORBIT_DISPATCH.md).
+
 ## Vocabulary
 
 - **Board** — one repo's planning surface. Each board carries its own `agent_instructions`, lanes, tickets, and memory entries.
@@ -110,11 +124,11 @@ Bun is not used as the Orbit runtime because Orbit depends on Node's built-in `n
 
 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, or `--no-ai` to disable AI collaboration for the board.
+- **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 serve` 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 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.
+- **Snapshot-portable** — Settings → Repository → 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.
 
 ## Developing Orbit
 
@@ -196,6 +210,7 @@ BOARD_NAME="My App" BOARD_SLUG=my-app REPO_URL=https://github.com/you/my-app orb
 - **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`.
+- **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 `orbit serve`, 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.
 
 ## Data
 
@@ -218,7 +233,7 @@ $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.
+**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.
 
 **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.
 

package/SKILL-ORBIT.md

@@ -2,13 +2,15 @@
 
 Read this before repo work. This board is the repo-local memory and execution layer.
 
+This file is managed by Orbit and may be overwritten by `orbit init` or refreshed by `orbit serve`. Put repo/team-specific agent rules in `AGENTS.md` or board `agent_instructions`, not here.
+
 ## 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.
+- **Which board MCP tools use** — Orbit can target either a local board discovered from a repo path or a hosted board by remote URL. For local boards, 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)). For remote/hosted boards, use the explicit board/server URL from the prompt or environment, then `board_list` + `board_set_active` before mutations; repo cwd remains code context, not planning-state authority. Prefer explicit `--cwd` / `PROJECT_ROOT` or explicit remote URL 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.
 
@@ -20,6 +22,27 @@ These are separate concerns; mixing them causes confusion:
 - Use ticket fields for durable implementation records: `ai_plan`, `implementation_summary`, `implementation_updates`.
 - Add a project entry when the context should outlive one ticket.
 
+## Dispatching Agents
+
+`orbit dispatch --board <slug> --ticket <number-or-id> --profile <name> --worktree` is the preferred human/orchestrator entrypoint for starting a Hermes agent on a specific card.
+
+Dispatch responsibilities:
+- Generate the handoff and store the canonical copy in the card's `ai_plan` / AI Written-Plan field.
+- Move the card to In Progress.
+- Preserve a git worktree/branch for human testing when `--worktree` is used.
+- Add a run-record comment with profile, policy, branch, worktree, pid, and command.
+- Apply the default safe PATH policy wrappers unless `--policy none` is explicit.
+
+Agent completion responsibilities remain unchanged:
+- Write final work notes to `implementation_summary`.
+- Write pitfalls, remediation, and reusable future guidance to `implementation_updates`.
+- Add comments for transient breadcrumbs/run events.
+- Move the card to Review unless the human explicitly asked for Done.
+
+## Human CLI Checks
+
+- `orbit -v` / `orbit --version`: print the installed Orbit CLI version for support, bug reports, and reproducibility notes.
+
 ## 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.
@@ -67,6 +90,8 @@ For a full picture of cross-cutting links call `GET /api/tickets/:id/relations`.
 
 - `GET /api/boards/:board_id/context`
 - `GET /api/boards/:board_id/archive`
+- `GET /api/tickets/:ticket_id`
+- `GET /api/tickets/lookup?board=<slug>&number=<n>` / `GET /api/tickets/lookup?board=<slug>&title=<exact-title>`
 - `GET /api/tickets/:ticket_id/context?depth=1`
 - `GET /api/tickets/:ticket_id/relations`
 - `GET /api/tickets/:ticket_id/blockers`

package/dist/full/index.html

@@ -15,7 +15,7 @@
             sizes="180x180"
             href="./apple-touch-icon.png"
         />
-        <link rel="stylesheet" href="styles.14e9dbbd.css" />
+        <link rel="stylesheet" href="styles.836872e7.css" />
     </head>
     <body>
         <div class="grain">
@@ -309,6 +309,6 @@
             </div>
         </dialog>
 
-        <script src="js/app.f4fd5e94.js" type="module"></script>
+        <script src="js/app.a4f045fc.js" type="module"></script>
     </body>
 </html>