@starlove/orbit 1.2.1 → 1.3.1

package/Dockerfile

@@ -4,7 +4,7 @@ FROM node:22-slim AS runtime
 WORKDIR /app
 
 ENV NODE_ENV=production \
-    PORT=3337 \
+    PORT=13701 \
     DATA_DIR=/data
 
 COPY package.json ./
@@ -14,7 +14,7 @@ COPY src ./src
 COPY dist/full ./dist/full
 
 VOLUME ["/data"]
-EXPOSE 3337
+EXPOSE 13701
 
 ENTRYPOINT ["node", "/app/src/cli/orbit.js"]
 CMD ["serve", "--cwd", "/workspace"]

package/README.md

@@ -51,28 +51,28 @@ 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, refreshes managed SKILL-ORBIT.md copies
+orbit run     # host runtime, uses ~/.orbit, refreshes managed SKILL-ORBIT.md copies
 # 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.
+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 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.
+`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.
 
-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*.
+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:
 
 ```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                 # 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
 ```
 
 `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 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.
+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.
 
 ## Use with AI
 
@@ -80,7 +80,7 @@ Orbit ships with everything an agent needs to claim work, read tickets, and writ
 
 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, Cursor, Codex, OpenCode, OpenClaw, and other MCP-capable clients — pick your OS + client and paste the command into your agent's MCP config.
+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.
 
@@ -115,7 +115,7 @@ Dispatch validates the local board, ticket, blockers, and Hermes availability be
 
 ## 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.
+- **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.
 
 Bun is not used as the Orbit runtime because Orbit depends on Node's built-in `node:sqlite` module.
@@ -124,9 +124,9 @@ 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, 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.
+- **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 → 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.
 
@@ -139,7 +139,7 @@ pnpm test
 pnpm run build
 ```
 
-Open `http://localhost:3337`.
+Open the URL printed by `orbit run` (normally `http://localhost:13701`).
 
 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).
 
@@ -209,8 +209,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.
+- **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.
 
 ## Data
 
@@ -223,12 +222,12 @@ Orbit stores each board in the repo it belongs to:
 Override runtime data with:
 
 ```bash
-DATA_DIR=/path/to/data orbit serve
+DATA_DIR=/path/to/data orbit run
 orbit docker --data-dir /path/to/data
 ```
 
 ```powershell
-$env:DATA_DIR="C:\path\to\data"; orbit serve
+$env:DATA_DIR="C:\path\to\data"; orbit run
 ```
 
 The UI exposes **Export** and **Import** from **Settings → Repository**.

package/SKILL-ORBIT.md

@@ -2,7 +2,7 @@
 
 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.
+This file is managed by Orbit and may be overwritten by `orbit init` or refreshed by `orbit run`. Put repo/team-specific agent rules in `AGENTS.md` or board `agent_instructions`, not here.
 
 ## MCP, cwd, and this file
 

package/dist/full/index.html

@@ -33,14 +33,14 @@
             } catch (e) {}
         </script>
         <link rel="preload" as="image" href="./orbits-logo.png" />
-        <link rel="stylesheet" href="styles.b7c19a07.css" />
+        <link rel="stylesheet" href="styles.65b79f8a.css" />
         <!-- Boot splash — the canonical ss-ui loading screen (see the package's
              components/loader.css). Inline critical CSS so it paints before
              /js/main.js loads. The logo grows in then breathes; no spinner.
-             Keyframes namespaced `ss-loader-*`. Under reduced motion the grow-in
+             Keyframes namespaced `starscape-loader-*`. Under reduced motion the grow-in
              is dropped and the dot grid stops; the gentle breathe stays. -->
         <style>
-            .ss-loader {
+            .loader {
                 position: fixed;
                 inset: 0;
                 z-index: 99999;
@@ -60,7 +60,7 @@
                 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
                     Roboto, "Helvetica Neue", Arial, sans-serif;
             }
-            .ss-loader::before {
+            .loader::before {
                 content: "";
                 position: absolute;
                 width: 200%;
@@ -72,24 +72,28 @@
                 );
                 background-size: 50px 50px;
                 will-change: transform;
-                animation: ss-loader-drift 20s linear infinite;
+                animation: starscape-loader-drift 20s linear infinite;
             }
-            .ss-loader.is-hiding {
+            .loader.is-hiding {
                 opacity: 0;
                 pointer-events: none;
             }
-            .ss-loader__logo {
+            .loader__logo {
                 width: 120px;
                 height: 120px;
                 object-fit: contain;
                 filter: drop-shadow(0 0 20px rgba(255, 255, 255, 0.3));
                 transform-origin: center;
+                /* translateZ in the keyframes + backface-visibility keep the star
+                   on a stable GPU layer, so it doesn't snap ~1px as the grow
+                   starts. Keep in sync with the package components/loader.css. */
+                backface-visibility: hidden;
                 will-change: transform;
                 animation:
-                    ss-loader-grow 0.6s cubic-bezier(0.22, 1, 0.36, 1) both,
-                    ss-loader-breathe 3s ease-in-out 0.6s infinite;
+                    starscape-loader-grow 0.6s cubic-bezier(0.22, 1, 0.36, 1) both,
+                    starscape-loader-breathe 3s ease-in-out 0.6s infinite;
             }
-            .ss-loader__label {
+            .loader__label {
                 margin: 0;
                 color: #fff;
                 font-size: 1.25rem;
@@ -97,45 +101,45 @@
                 letter-spacing: 0.5px;
                 text-shadow: 0 2px 10px rgba(0, 0, 0, 0.3);
             }
-            @keyframes ss-loader-drift {
+            @keyframes starscape-loader-drift {
                 from { transform: translate(0, 0); }
                 to { transform: translate(-50px, -50px); }
             }
-            @keyframes ss-loader-grow {
-                from { transform: scale(0); opacity: 0; }
-                to { transform: scale(1); opacity: 1; }
+            @keyframes starscape-loader-grow {
+                from { transform: scale(0) translateZ(0); opacity: 0; }
+                to { transform: scale(1) translateZ(0); opacity: 1; }
             }
-            @keyframes ss-loader-breathe {
-                0%, 100% { transform: scale(1); }
-                50% { transform: scale(1.06); }
+            @keyframes starscape-loader-breathe {
+                0%, 100% { transform: scale(1) translateZ(0); }
+                50% { transform: scale(1.06) translateZ(0); }
             }
             @media (prefers-reduced-motion: reduce) {
-                :root:not([data-motion="full"]) .ss-loader::before {
+                :root:not([data-motion="full"]) .loader::before {
                     animation: none;
                 }
-                :root:not([data-motion="full"]) .ss-loader__logo {
-                    animation: ss-loader-breathe 3s ease-in-out infinite;
+                :root:not([data-motion="full"]) .loader__logo {
+                    animation: starscape-loader-breathe 3s ease-in-out infinite;
                 }
             }
-            [data-motion="reduce"] .ss-loader::before {
+            [data-motion="reduce"] .loader::before {
                 animation: none;
             }
-            [data-motion="reduce"] .ss-loader__logo {
-                animation: ss-loader-breathe 3s ease-in-out infinite;
+            [data-motion="reduce"] .loader__logo {
+                animation: starscape-loader-breathe 3s ease-in-out infinite;
             }
         </style>
     </head>
     <body>
         <!-- Boot splash - shown immediately, removed once the app is ready. -->
-        <div id="ss-loader" class="ss-loader" role="status" aria-live="polite">
+        <div id="loader" class="loader" role="status" aria-live="polite">
             <img
-                class="ss-loader__logo"
+                class="loader__logo"
                 src="./orbits-logo.png"
                 alt="Orbit"
                 width="120"
                 height="120"
             />
-            <p class="ss-loader__label">Loading Orbit…</p>
+            <p class="loader__label">Loading Orbit…</p>
         </div>
 
         <div class="grain">
@@ -143,9 +147,40 @@
         </div>
         <header class="topbar">
             <div class="brand" aria-label="Orbit">
-                <img class="mark" src="./orbits-logo.png" alt="Orbits logo" />
+                <button
+                    id="brandFocusBtn"
+                    type="button"
+                    class="brand-focus-btn"
+                    data-variant="brand-focus"
+                    aria-label="Show board notes"
+                    aria-expanded="false"
+                    aria-controls="brandFocusPopover"
+                >
+                    <img class="mark" src="./orbits-logo.png" alt="Orbits logo" />
+                </button>
+                <div
+                    id="brandFocusPopover"
+                    class="brand-focus-popover"
+                    role="dialog"
+                    aria-label="Board notes"
+                    hidden
+                >
+                    <div class="brand-focus-popover__eyebrow">Board notes</div>
+                    <div id="brandFocusNotes" class="brand-focus-notes-body">No board notes yet</div>
+                </div>
             </div>
             <div class="controls">
+                <button
+                    id="brandNotesBtn"
+                    type="button"
+                    class="topbar-notes brand-notes-strip"
+                    data-variant="topbar-notes"
+                    aria-label="Show board notes"
+                    aria-expanded="false"
+                    aria-controls="brandFocusPopover"
+                >
+                    <span id="brandNotesText" class="topbar-notes__text"></span>
+                </button>
                 <span class="topbar-controls-gap" aria-hidden="true"></span>
                 <div class="topbar-search" id="topbarSearch">
                     <input
@@ -235,6 +270,32 @@
                         />
                     </svg>
                 </button>
+                <button
+                    id="helpBtn"
+                    type="button"
+                    class="topbar-btn topbar-ctl-shrink"
+                    data-variant="translucent"
+                    aria-haspopup="dialog"
+                    aria-controls="helpDialog"
+                >
+                    <svg
+                        class="topbar-icon"
+                        width="16"
+                        height="16"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        stroke-width="2"
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                        aria-hidden="true"
+                    >
+                        <circle cx="12" cy="12" r="10" />
+                        <path d="M9.09 9a3 3 0 015.83 1c0 2-3 3-3 3" />
+                        <path d="M12 17h.01" />
+                    </svg>
+                    Help
+                </button>
                 <button
                     id="settingsBtn"
                     type="button"
@@ -424,14 +485,149 @@
             </div>
         </dialog>
 
-        <script src="js/app.ccc442f7.js" type="module"></script>
+        <!-- Help & About. Reuses the .orbit-dialog shell + welcome-dialog-*
+             styling so it inherits the modal chrome; opened from the topbar
+             Help button and wired through modal.js (Escape/backdrop close). -->
+        <dialog
+            id="helpDialog"
+            class="orbit-dialog"
+            aria-labelledby="helpDialogTitle"
+        >
+            <div class="welcome-dialog-inner help-dialog-inner">
+                <div class="welcome-dialog-head">
+                    <img
+                        class="welcome-dialog-logo"
+                        src="./orbits-logo.png"
+                        alt=""
+                        aria-hidden="true"
+                    />
+                    <span
+                        class="welcome-dialog-edition-pill"
+                        id="helpDialogVersion"
+                        >Orbit</span
+                    >
+                    <button
+                        type="button"
+                        class="help-dialog-close"
+                        aria-label="Close"
+                        data-modal-close
+                    >
+                        ×
+                    </button>
+                </div>
+                <div class="welcome-dialog-body">
+                    <h2 id="helpDialogTitle" class="welcome-dialog-title">
+                        Starscape Orbit
+                    </h2>
+                    <p class="welcome-dialog-lede">
+                        A developer-first kanban board built for teams working
+                        alongside AI agents. Track the motion of your project —
+                        and hand work to your coding agent through the Orbit MCP
+                        tools.
+                    </p>
+
+                    <section
+                        class="help-dialog-section"
+                        aria-label="Getting started"
+                    >
+                        <h3 class="help-dialog-heading">Getting started</h3>
+                        <ol class="help-dialog-steps">
+                            <li class="help-dialog-step">
+                                <span class="help-dialog-step__index">01</span>
+                                <div>
+                                    <h4>Create a board</h4>
+                                    <p>
+                                        Use the <strong>Board</strong> menu →
+                                        New board. Optionally point it at a
+                                        coding project folder so Orbit can drop
+                                        <code>SKILL-ORBIT.md</code> and
+                                        <code>AGENTS.md</code> for your agent.
+                                    </p>
+                                </div>
+                            </li>
+                            <li class="help-dialog-step">
+                                <span class="help-dialog-step__index">02</span>
+                                <div>
+                                    <h4>Add cards &amp; the AI Ready lane</h4>
+                                    <p>
+                                        Capture work with
+                                        <strong>New Card</strong>. Move cards
+                                        into <strong>AI Ready</strong> to stage
+                                        them for an agent to claim.
+                                    </p>
+                                </div>
+                            </li>
+                            <li class="help-dialog-step">
+                                <span class="help-dialog-step__index">03</span>
+                                <div>
+                                    <h4>Connect your coding agent</h4>
+                                    <p>
+                                        Add the Orbit MCP server from
+                                        <strong>Settings</strong>, then ask your
+                                        agent to read <code>AGENTS.md</code> and
+                                        claim the next ticket.
+                                    </p>
+                                </div>
+                            </li>
+                        </ol>
+                    </section>
+
+                    <section
+                        class="help-dialog-section"
+                        aria-label="Links"
+                    >
+                        <h3 class="help-dialog-heading">Links</h3>
+                        <ul class="help-dialog-links">
+                            <li>
+                                <a
+                                    class="welcome-dialog-link"
+                                    href="https://orbit.starscape.app"
+                                    target="_blank"
+                                    rel="noopener"
+                                    >Documentation</a
+                                >
+                            </li>
+                            <li>
+                                <a
+                                    class="welcome-dialog-link"
+                                    href="https://github.com/brucestarlove/ss-orbit/blob/master/docs/MCP_SETUP.md"
+                                    target="_blank"
+                                    rel="noopener"
+                                    >MCP setup</a
+                                >
+                            </li>
+                            <li>
+                                <a
+                                    class="welcome-dialog-link"
+                                    href="https://orbit.starscape.app/support"
+                                    target="_blank"
+                                    rel="noopener"
+                                    >Support / Tip</a
+                                >
+                            </li>
+                        </ul>
+                    </section>
+                </div>
+                <footer class="welcome-dialog-footer">
+                    <button
+                        type="button"
+                        class="welcome-dialog-cta"
+                        data-modal-close
+                    >
+                        Got it
+                    </button>
+                </footer>
+            </div>
+        </dialog>
+
+        <script src="js/app.b8296a78.js" type="module"></script>
         <!-- Fade out the boot splash once the DOM is ready. The /js/main.js
              module runs before DOMContentLoaded, so theme/motion + wiring are
              already applied by the time this fires. -->
         <script>
             (function () {
                 function hideSplash() {
-                    var splash = document.getElementById("ss-loader");
+                    var splash = document.getElementById("loader");
                     if (!splash) return;
                     // Keep the splash up for a minimum of 786ms (measured from
                     // navigation start) so a fast load doesn't flash it in and out.