@starlove/orbit 1.0.6 → 1.1.0

package/dist/full/version.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "edition": "full",
-  "builtAt": "2026-05-20T07:25:07.448Z"
+  "builtAt": "2026-05-26T04:59:52.730Z"
 }

package/docs/AGENT_PROTOCOL.md

@@ -4,6 +4,8 @@ The board is intentionally agent-first. Agents should not scrape the UI. They sh
 
 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`
@@ -70,7 +72,19 @@ Returns the first schedulable `AI Ready` ticket. The scheduler skips tickets blo
 
 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, full `comments`, and the `board_manual`). For the heavier ticket pack with relations, blockers, and child cards, call `GET /api/tickets/:id/context` (or MCP `board_get_ticket_context`).
+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 heavier ticket pack with relations, blockers, implementation fields, and child cards, call `GET /api/tickets/:id/context` (or MCP `board_get_ticket_context`).
+
+### 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 Context Pack
 
@@ -82,14 +96,20 @@ Returns:
 
 - Ticket, board, state, labels.
 - The board manual (`board_manual`), including `agent_instructions` and `project_notes`.
-- Full comments for the assigned ticket.
 - Dedicated implementation fields: `ai_plan`, `implementation_summary`, and `implementation_updates`.
 - Parent epic/story ticket when present.
 - Child feature cards when the ticket is an epic/story.
 - Related tickets.
-- Recent comments from directly related tickets.
 - Blockers and blocking tickets.
 
+Ticket comments are intentionally omitted from this default agent context. Explicit comment/chat consumers should call:
+
+```http
+GET /api/tickets/:id/comments
+```
+
+MCP equivalent: `board_read_comments`.
+
 ### Get Ticket Relations
 
 ```http
@@ -212,10 +232,10 @@ Content-Type: application/json
 ### Export Board Snapshot
 
 ```http
-GET /api/boards/:board_id/export
+GET /api/boards/:board_id/export?include_attachments=true
 ```
 
-Returns a JSON snapshot of the board, states, tickets, comments, relations, board entries, and relevant event history.
+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
 
@@ -298,6 +318,8 @@ Over MCP these are exposed as `board_archive_ticket`, `board_restore_ticket`, `b
 
 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

package/docs/MCP_SETUP.md

@@ -13,7 +13,7 @@ Orbit generates neutral template paths for Windows, macOS, and Linux. Replace th
 
 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 a copy of **`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.
+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 serve`.
 
 The generated format changes by app:
 
@@ -29,11 +29,13 @@ The checked-in example file is not read automatically by Starscape Orbit. It exi
 3. Replace the path to `src/mcp-server.js` with the absolute path on your machine.
 4. Restart the MCP client.
 
-The MCP server 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. **`AGENTS.md` / `SKILL-ORBIT.md`** are unrelated to MCP transport: agents open them via the workspace file tree, and `orbit init` keeps a terse Orbit pointer section in `AGENTS.md`.
+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 serve` refreshes managed `SKILL-ORBIT.md` copies for registered repos.
 
 Typical use:
 
-- Keep the web UI running with `node src/server.js`.
+- Keep the web UI running with `orbit serve` (`node src/server.js` is fine for source-tree development, but `orbit serve` 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.
 
@@ -41,6 +43,8 @@ Typical use:
 
 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 serve` 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:

package/docs/ORBIT_DISPATCH.md

@@ -0,0 +1,185 @@
+# Orbit Dispatch
+
+`orbit dispatch` is the local Orbit-to-Hermes handoff command. It turns a local Orbit ticket into a bounded agent run without relying on a temporary prompt file as the source of truth.
+
+The design intent is simple:
+
+- Git remains canonical for code.
+- Orbit remains canonical for planning, handoff, run records, and implementation notes.
+- The ticket becomes the shared communication surface between the human, orchestrator, and dispatched agent.
+
+## Current remote-board contract
+
+`orbit dispatch` is intentionally local-board only right now. It resolves boards through the local Orbit registry and mutates the local SQLite board file.
+
+Because of that, `--server-url` and `--remote` are refused before side effects. They do not silently target a hosted board.
+
+For hosted/remote boards, use remote MCP/manual orchestration or run `orbit dispatch` on the board host without `--server-url`/`--remote`.
+
+## Basic use
+
+From the code repository you are working in, target the local Orbit board explicitly:
+
+```bash
+orbit dispatch \
+  --board my-app \
+  --ticket 12 \
+  --profile agent \
+  --worktree
+```
+
+Common variants:
+
+```bash
+# Preview only. No files, worktrees, ticket fields, comments, or agents change.
+orbit dispatch --board my-app --ticket 12 --dry-run
+
+# Prepare the handoff/comment/worktree, but do not spawn Hermes and do not move the card to In Progress.
+orbit dispatch --board my-app --ticket 12 --profile agent --worktree --no-spawn
+
+# Attach the Hermes child process to the current terminal instead of detaching it.
+orbit dispatch --board my-app --ticket 12 --profile agent --worktree --foreground
+
+# Use an explicit branch/worktree name.
+orbit dispatch --board my-app --ticket 12 --profile agent --worktree \
+  --branch orbit/my-app-12-search \
+  --worktree-path .worktrees/my-app-12-search
+```
+
+## Preflight order
+
+Before any filesystem writes, worktree creation, ticket mutation, or agent spawn, dispatch now:
+
+1. Refuses `--server-url` / `--remote`.
+2. Resolves the local board from `--board` or from `--cwd` / the current repo.
+3. Resolves the ticket from `--ticket` by number or id.
+4. Refuses archived tickets.
+5. Refuses blocked tickets unless `--force` is passed.
+6. For spawn mode, checks that the Hermes binary exists and the requested profile is plausible.
+7. Handles `--dry-run` as a true no-write preview.
+
+Only after those checks does dispatch create run artifacts/worktrees, write the handoff/comment, move the ticket, or spawn Hermes.
+
+## What dispatch does
+
+In normal spawn mode:
+
+1. Builds a run id such as `orbit-12-agent-abc123def0`.
+2. Creates `.orbit/dispatch-runs/<run-id>/` for run metadata and policy wrappers.
+3. Creates and preserves a git worktree/branch when `--worktree` is used.
+4. Generates a full agent handoff and writes the canonical copy to the ticket's **AI Written-Plan** (`ai_plan`) field.
+5. Moves the ticket to **In Progress**.
+6. Starts Hermes.
+7. Comments a run record back onto the ticket.
+
+In `--no-spawn` mode, dispatch writes the handoff and run-record comment but leaves the ticket in its current lane.
+
+The run record includes profile, policy, ticket, branch, worktree, policy-bin path, child process id, command, and mode. This makes the card the visible cockpit for the run.
+
+## The AI Written-Plan handoff
+
+Dispatch stores the generated handoff in the ticket's AI Written-Plan field. It includes:
+
+- mission and ticket metadata
+- repository root, worktree, branch, and run id
+- required reading order: `AGENTS.md`, `SKILL-ORBIT.md`, then the handoff
+- ticket description
+- implementation fields (`ai_plan`, `implementation_summary`, `implementation_updates`)
+- board-level agent instructions and notes
+- board journal lessons/decisions
+- parent/child ticket context
+- unresolved blockers
+- scope boundaries
+- autonomous policy
+- completion protocol
+
+The short prompt passed to `hermes chat -q` is intentionally small. The ticket is the source of truth; the CLI argument is only a bootstrap pointer.
+
+## Preserved worktrees
+
+Use `--worktree` when the agent will edit code. Dispatch creates a normal git worktree under `.worktrees/` by default and gives the agent that directory as its working directory.
+
+This solves the ephemeral-agent problem: humans can test the branch/worktree before cleanup.
+
+Default shape:
+
+```text
+.worktrees/<board>-<ticket>-<profile>-<shortid>
+orbit/<board>-<ticket>-<profile>-<shortid>
+```
+
+`.worktrees/` is ignored by git.
+
+## Safe autonomous policy
+
+The default policy prepends `.orbit/dispatch-runs/<run-id>/policy-bin` to the child agent's `PATH`. That directory contains wrappers for commands that should be restricted during an autonomous run.
+
+Allowed:
+
+- file reads/searches and local edits
+- `git status`, `git diff`, `git log`, `git show`, `git add`, local `git commit`, safe branch inspection/creation
+- package test/build/lint/check/typecheck scripts
+
+Blocked or requiring human approval:
+
+- Docker
+- `git push`
+- destructive git commands such as reset, clean, rebase, merge, checkout/switch/restore, tag, cherry-pick, worktree mutation
+- package install/publish/version/deploy/release commands
+- recursive or force `rm`
+- SSH/SCP/rsync
+- GitHub CLI
+- direct curl/wget network calls
+- cloud/deploy CLIs
+- `sudo`
+
+Use `--policy none` only when you intentionally want to dispatch without wrappers.
+
+## Agent completion protocol
+
+The dispatched agent should:
+
+1. Run relevant tests and focused manual/API checks.
+2. Commit locally on the dispatch branch.
+3. Update **AI Implementation Summary** (`implementation_summary`) with what changed, commit SHA, branch/worktree, verification, and manual checks still needed.
+4. Add **Implementation Updates/Lessons** (`implementation_updates`) for pitfalls, remediation, and reusable guidance.
+5. Add a completion comment/run record.
+6. Move the card to **Review**, not Done, unless the human explicitly asked for auto-completion.
+
+## Installing / enabling the command
+
+For source installs:
+
+```bash
+cd /path/to/ss-orbit
+pnpm install
+pnpm run build:full
+pnpm link --global
+```
+
+Then from a project repo with an Orbit board:
+
+```bash
+orbit init            # if the repo does not have a board yet
+orbit dispatch --board my-app --ticket 12 --profile agent --worktree --no-spawn
+```
+
+For support, bug reports, and reproducibility notes, human users can print the installed CLI version with either form:
+
+```bash
+orbit -v
+orbit --version
+```
+
+## Operator notes for orchestrators
+
+- Prefer `orbit dispatch` over writing a temporary handoff prompt file when targeting a local board.
+- Use `--dry-run` when you want proof of what would happen without any side effects.
+- Use `--no-spawn` when you want to inspect the generated handoff/worktree/comment before starting an agent.
+- Use `--worktree` for code edits so the human can test before cleanup.
+- Treat the ticket fields as durable surfaces:
+  - AI Written-Plan: generated handoff
+  - AI Implementation Summary: final summary of completed work
+  - Implementation Updates/Lessons: pitfalls, remediation, future-agent guidance
+  - Comments: run records and transient breadcrumbs
+- Do not push, deploy, or open PRs from the dispatched agent unless the human explicitly asked for that run to do so.

package/docs/setup/orbit-init-wizard.md

@@ -0,0 +1,174 @@
+# Orbit init wizard
+
+Status: focused implementation spec for ticket #61.
+
+This replaces the older Mission Control-shaped setup-mode design from Orbit tickets #26 and #27. Keep the useful lesson: `orbit init` should make the first board choice clear. Cut the rest. Orbit setup creates a project board and, optionally, the agent-ready affordances around that board. Suite and Sync concerns stay out.
+
+## Goal
+
+`orbit init` supports two first-pass modes:
+
+1. Local board / no AI
+2. AI-assisted board
+
+Anything beyond those modes belongs to Starscape Suite, Starscape Sync, or an app-specific integration ticket.
+
+## Command contract
+
+These commands must work:
+
+```bash
+orbit init
+orbit init --ai
+orbit init --no-ai
+```
+
+| Command | Mode | Contract |
+| --- | --- | --- |
+| `orbit init` | AI-assisted board | Backwards-compatible default. |
+| `orbit init --ai` | AI-assisted board | Explicit alias for the default. |
+| `orbit init --no-ai` | Local board / no AI | No AI collaboration assumptions. |
+
+Keep existing init flags:
+
+- `--cwd <dir>` selects the project root.
+- `--example` creates onboarding example tickets.
+
+`SKILL-ORBIT.md` is managed Orbit guidance: `orbit init` writes it, and `orbit serve` refreshes registered repo copies on startup. Repo/team customization belongs in `AGENTS.md` or board `agent_instructions`, not in `SKILL-ORBIT.md`.
+
+Do not add `--multi-ai`, `--output=starlog-authored`, `--starlog`, `--suite`, `--forge`, `--sync`, hosted-service flags, agent-guidance refresh flags, or remote-sync flags in this pass.
+
+## Wizard rules
+
+The first implementation should be clear without breaking scripts:
+
+- If `--ai` or `--no-ai` is present, do not prompt.
+- If running non-interactively, default to AI-assisted board.
+- If an interactive prompt is added, Enter chooses AI-assisted board.
+- Ask only for local/no-AI vs AI-assisted. Do not ask about Starlog, Suite dashboard, Nebula, Forgejo, Auth, hosted service, Sync links, artifacts, events, or remote sync.
+
+Suggested prompt:
+
+```text
+Initialize Orbit for this repo
+
+Orbit keeps a project board next to your code. Git stays the truth for code;
+Orbit becomes the truth for tickets, planning state, handoff, and implementation notes.
+
+Choose a first-run mode:
+
+  1. Local board / no AI
+     A local kanban board. No AI Ready lane or MCP setup step.
+
+  2. AI-assisted board (recommended)
+     Adds AI Ready, agent handoff fields, generated agent instructions, and MCP setup guidance.
+
+Select a mode [2]:
+```
+
+## Mode behavior
+
+### Local board / no AI
+
+Triggered by `orbit init --no-ai`.
+
+Behavior:
+
+- Create or repair the board database and registry row for the selected project root.
+- Persist `ai_enabled = 0`.
+- Do not create the `AI Ready` lane.
+- Keep ordinary lanes: `Backlog`, `Todo`, `In Progress`, `Review`, `Done`, `Cancelled`.
+- Keep Orbit usable for human planning, ticket history, blockers, comments, and implementation notes.
+- Generate `AGENTS.md` and `SKILL-ORBIT.md`, but do not present MCP connection as a required next step.
+- If `--example` is used, keep example tickets out of AI Ready.
+
+Success copy should say the board path returned by init, the selected mode, and the next `orbit serve` step. It should not imply AI is required.
+
+### AI-assisted board
+
+Triggered by `orbit init` and `orbit init --ai`.
+
+Behavior:
+
+- Create or repair the board database and registry row for the selected project root.
+- Persist `ai_enabled = 1`.
+- Ensure `AI Ready`, `In Progress`, and `Review` exist for agent flow.
+- Create/update `AGENTS.md` as the repo-owned pointer and write the managed `SKILL-ORBIT.md` so agents know to read board context, respect blockers, use MCP/API tools, and update `ai_plan`, `implementation_summary`, and `implementation_updates`.
+- Print MCP setup guidance after init, including project-root-specific `orbit mcp --cwd <repo>` / `PROJECT_ROOT=<repo>` guidance or the generated client snippet.
+- If `--example` is used, stage the stable MCP exercise ticket in `AI Ready`.
+
+Success copy should say AI collaboration lanes are present and the next step is connecting an agent through MCP.
+
+## Generated guidance files
+
+`orbit init` preserves generation of:
+
+- `AGENTS.md`
+- `SKILL-ORBIT.md`
+
+`AGENTS.md` should stay terse and repo-owned: when work mentions Orbit/tickets/boards, read `SKILL-ORBIT.md` first. `SKILL-ORBIT.md` is Orbit-managed durable protocol and may be overwritten by `orbit init` or refreshed by `orbit serve`; it tells agents to read board context, check blockers, use Orbit API/MCP instead of editing SQLite directly, update implementation fields, and hand off through Review.
+
+For local/no-AI boards, these files are still useful if an agent later opens the repo, but init output should not frame MCP as mandatory.
+
+## MCP setup guidance
+
+For AI-assisted boards, keep the current guidance:
+
+- MCP config tells the AI client how to spawn Orbit's helper.
+- `AGENTS.md` and `SKILL-ORBIT.md` are normal repo files, not streamed through MCP.
+- Persistent MCP configs should use explicit `--cwd <repo>` / `PROJECT_ROOT=<repo>` so the helper attaches to the right board.
+
+For local/no-AI boards, omit MCP guidance or label it optional later setup.
+
+## Board mode metadata
+
+First pass can keep `boards.ai_enabled` as the source of truth:
+
+```text
+ai_enabled = 0 -> local board / no AI
+ai_enabled = 1 -> AI-assisted board
+```
+
+If a mode field is added, keep it deliberately small:
+
+```json
+{
+  "setup_mode": "ai-assisted",
+  "setup_schema_version": 1
+}
+```
+
+Allowed `setup_mode` values: `local`, `ai-assisted`.
+
+Compatibility:
+
+```text
+missing setup_mode + ai_enabled = 0 -> local
+missing setup_mode + ai_enabled = 1 -> ai-assisted
+```
+
+Do not persist Starlog output mode, Suite profile, Forge mode, Sync mode, hosted Auth state, or remote-sync configuration in Orbit setup metadata.
+
+## Explicitly out of scope
+
+| Deferred concern | Route |
+| --- | --- |
+| Starscape Suite dashboard, module/plugin setup, unified launcher, ecosystem settings | `ss-suite` #1 |
+| Nebula / whiteboard setup | `ss-suite` #1 or the Nebula board |
+| Starlog output/reporting mode, authored HTML outputs, templates | Suite/app integration work, not Orbit init |
+| Forgejo/Gitea suite mode, local forge provisioning, themed forge navigation | `ss-suite` #1 |
+| Starscape Auth, hosted service, cloud accounts, managed hosting | `ss-suite` #1 / hosted-service follow-up |
+| Cross-app registry, object identity, links/backrefs, artifacts, activity/events, export/import, remote sync | `ss-sync` #1 |
+| Mission Briefs, named agent ecology, wave execution, multi-agent orchestration | Later Orbit Mission Control work, not this wizard |
+
+Mapping note: Orbit keeps local project boards, generated agent guidance, agent-ready lanes, MCP setup, and ticket implementation records. Suite composition maps to `ss-suite` #1. Registry/link/artifact/event/sync semantics map to `ss-sync` #1.
+
+## Implementation checklist for the next build ticket
+
+- `orbit init`, `orbit init --ai`, and `orbit init --no-ai` all work.
+- `orbit init --ai` is an explicit alias for the default AI-assisted path.
+- Local/no-AI mode creates no `AI Ready` lane and does not require MCP setup.
+- AI-assisted mode keeps AI lanes, generated guidance files, MCP guidance, and example-ticket staging behavior.
+- Generated `AGENTS.md` / `SKILL-ORBIT.md` keep agents on Orbit API/MCP rather than direct SQLite edits.
+- Setup metadata is limited to `local` / `ai-assisted` plus schema version, or remains derived from `ai_enabled`.
+- No Suite, Sync, Starlog, Nebula, Forgejo, Auth, hosted service, artifact, link, event, or remote-sync setup enters Orbit init.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.6",
-  "description": "Starscape Orbit — SQLite-backed, agent-first task board (Starscape suite).",
+  "version": "1.1.0",
+  "description": "Starscape Orbit ??? zero-dependency, pretty, human-ai-first kanban system.",
   "license": "AGPL-3.0",
   "type": "module",
   "packageManager": "pnpm@10.20.0",

package/public/js/actor-labels.js

@@ -0,0 +1,65 @@
+// Human-facing actor labels for ticket activity. The storage layer keeps
+// compact/internal identifiers such as "local" and "local-agent"; the drawer
+// should translate those into labels that explain who acted without exposing
+// implementation details or blaming agent actions on the current user.
+
+const INTERNAL_LOCAL_NAMES = new Set(["local", "local-owner", "owner"]);
+const GENERIC_AGENT_NAMES = new Set(["agent", "local-agent", "orbit-agent"]);
+const AGENT_COMMENT_KINDS = new Set(["agent_note", "checkpoint", "completion"]);
+
+function clean(value) {
+  return String(value || "").trim();
+}
+
+function humanizeIdentifier(value) {
+  const raw = clean(value);
+  if (!raw) return "";
+  return raw
+    .replace(/^@+/, "")
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function agentNameFrom({ actor, actorId } = {}) {
+  const name = clean(actor);
+  const id = clean(actorId);
+  const lowerName = name.toLowerCase();
+  const lowerId = id.toLowerCase();
+
+  if (name && !INTERNAL_LOCAL_NAMES.has(lowerName) && !GENERIC_AGENT_NAMES.has(lowerName)) {
+    return humanizeIdentifier(name);
+  }
+  if (id && !INTERNAL_LOCAL_NAMES.has(lowerId) && !GENERIC_AGENT_NAMES.has(lowerId)) {
+    return humanizeIdentifier(id);
+  }
+  return "";
+}
+
+export function formatActorLabel({ actor, actorType, actorId } = {}) {
+  const type = clean(actorType).toLowerCase();
+  const name = clean(actor);
+  const lowerName = name.toLowerCase();
+
+  if (type === "agent") {
+    const agentName = agentNameFrom({ actor: name, actorId });
+    return agentName ? `Agent · ${agentName}` : "Agent";
+  }
+
+  if (!name || INTERNAL_LOCAL_NAMES.has(lowerName)) return "You";
+  return humanizeIdentifier(name);
+}
+
+export function formatCommentAuthor(comment = {}) {
+  const kind = clean(comment.kind).toLowerCase();
+  const author = clean(comment.author);
+  const isAgentKind = AGENT_COMMENT_KINDS.has(kind) || (kind && kind !== "human_comment");
+
+  if (isAgentKind) {
+    const agentName = agentNameFrom({ actor: author });
+    return agentName ? `Agent · ${agentName}` : "Agent";
+  }
+
+  return formatActorLabel({ actor: author, actorType: "human" });
+}

package/public/js/api.js

@@ -9,7 +9,11 @@ import { request } from "./transport.js";
 
 /** Bootstrap for the currently selected board (server opens the right DB). */
 export function bootstrapPath() {
-  const q = state.boardId ? `?board_id=${encodeURIComponent(state.boardId)}` : "";
+  const q = state.boardId
+    ? `?board_id=${encodeURIComponent(state.boardId)}`
+    : state.boardSlug
+      ? `?board=${encodeURIComponent(state.boardSlug)}`
+      : "";
   return `/api/bootstrap${q}`;
 }
 

package/public/js/app.js

@@ -4,7 +4,7 @@
 
 import { state, syncBoardSelection } from "./state.js";
 import { api, bootstrapPath } from "./api.js";
-import { renderBoard } from "./kanban.js";
+import { renderBoard, renderBoardSelection } from "./kanban.js";
 import { renderDetail } from "./ticket-detail.js";
 import { closeMenuFlyouts, updateTopbarChips } from "./board-menu.js";
 import { connectEventStream } from "./sse.js";
@@ -33,3 +33,10 @@ export async function render() {
   renderBoard();
   await renderDetail();
 }
+
+export async function renderDetailOnly() {
+  syncBoardSelection();
+  updateTopbarChips();
+  renderBoardSelection();
+  await renderDetail();
+}