@starlove/orbit 1.0.3 → 1.0.4

package/dist/full/version.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "edition": "full",
-  "builtAt": "2026-05-19T05:38:00.174Z"
+  "builtAt": "2026-05-19T06:06:41.796Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Starscape Orbit — SQLite-backed, agent-first task board (Starscape suite).",
   "license": "MIT",
   "type": "module",

package/public/js/create-card.js

@@ -7,7 +7,7 @@ import {
   createFlyoutInner,
   createFlyoutBackdrop
 } from "./dom.js";
-import { state, statesForProject, ticketsForProject } from "./state.js";
+import { state, visibleStatesForProject, ticketsForProject } from "./state.js";
 import { escapeHtml, ticketLabel } from "./format.js";
 import { api } from "./api.js";
 import { syncUrlFromState } from "./router.js";
@@ -54,7 +54,7 @@ export function closeCreateFlyout() {
 
 /** HTML for the “New” flyout: lane + type + priority on one row, then parent and labels. */
 function renderCreateForm(preselectedLaneId) {
-  const states = statesForProject();
+  const states = visibleStatesForProject();
   const defaultState = states.find((item) => item.is_default) || states[0];
   const effectiveStateId =
     preselectedLaneId && states.some((s) => s.id === preselectedLaneId)

package/public/js/kanban.js

@@ -4,7 +4,7 @@
 // owned by ticket-detail.js.
 
 import { kanban } from "./dom.js";
-import { state, statesForProject, ticketsForProject } from "./state.js";
+import { state, visibleStatesForProject, ticketsForProject } from "./state.js";
 import {
   escapeHtml,
   ticketLabel,
@@ -21,7 +21,7 @@ import { load } from "./app.js";
 import { unreadCount } from "./unread.js";
 
 export function renderBoard() {
-  const states = statesForProject();
+  const states = visibleStatesForProject();
   const tickets = ticketsForProject();
   kanban.innerHTML = states.map((column) => renderColumn(column, tickets)).join("");
 

package/public/js/settings.js

@@ -144,7 +144,7 @@ function renderProjectAiTab(context) {
         </span>
         <span class="orbit-check-label">Enable AI</span>
       </label>
-      <p class="description">Provisions the <strong>AI Ready</strong>, <strong>In Progress</strong>, and <strong>Review</strong> lanes if missing, surfaces agent context fields, and exposes the MCP setup snippet. Disabling AI keeps the lanes in place.</p>
+      <p class="description">Provisions the <strong>AI Ready</strong>, <strong>In Progress</strong>, and <strong>Review</strong> lanes if missing, surfaces agent context fields, and exposes the MCP setup snippet. Disabling AI hides the AI Ready column but keeps its cards in place.</p>
     </div>
     ${aiDivider}
     ${agentContextSetup}
@@ -387,7 +387,7 @@ function renderDeleteBoardSection(project) {
     return `
       <div class="section repository-danger-zone">
         <h3>Delete Board</h3>
-        <p class="description">Delete this board from Orbit and remove its local database. Export a snapshot first if you may need this board again.</p>
+        <p class="description">Delete this board from Orbit and remove its repo-local Orbit files. Export a snapshot first if you may need this board again.</p>
         <div class="repository-delete-actions">
           <button type="button" class="ghost" id="deleteBoardExportFirst">Export first</button>
           <button type="button" class="ghost danger-button" id="deleteBoardSkipExport">Delete without exporting</button>
@@ -421,7 +421,7 @@ function renderDeleteBoardSection(project) {
   return `
     <div class="section repository-danger-zone">
       <h3>Delete Board</h3>
-      <p class="description">Remove this board from Orbit and delete its local database. This cannot be undone without an exported snapshot.</p>
+      <p class="description">Remove this board from Orbit and delete its repo-local Orbit files. This cannot be undone without an exported snapshot.</p>
       <button type="button" class="ghost danger-button" id="deleteBoardStart">Delete Board</button>
     </div>
   `;
@@ -674,7 +674,7 @@ function bindProjectTabHandlers(context, tab) {
       });
       await load();
       state.detailMode = "settings";
-      toast.success(enabled ? "AI features enabled — agent lanes provisioned" : "AI features disabled");
+      toast.success(enabled ? "AI features enabled — agent lanes provisioned" : "AI features disabled — AI Ready hidden");
     });
 
   }
@@ -804,7 +804,8 @@ function renderProjectEntries(entries = []) {
 }
 
 // In Progress and Review are core kanban lanes — undeletable regardless of
-// AI. AI Ready is only locked while AI is enabled; turn AI off to remove it.
+// AI. AI Ready is only locked while AI is enabled; disabling AI hides it from
+// the board without moving its cards.
 const CORE_LANE_ROLES = new Set(["in_progress", "review"]);
 
 /** A lane can't be deleted if it has cards (orphan risk), if it's the default
@@ -831,7 +832,7 @@ function deleteTitle(lane, counts, aiEnabled) {
     return "Cannot delete — core kanban lane";
   }
   if (aiEnabled && lane.role === "ai_ready") {
-    return "Cannot delete — required by agent flow (disable AI in Settings → AI to remove)";
+    return "Cannot delete — required by agent flow while AI is enabled";
   }
   return "Delete lane";
 }
@@ -850,7 +851,7 @@ function renderLaneManager() {
         .map((lane, index) => {
           const isAiReady = lane.role === "ai_ready";
           const nameTitle = isAiReady
-            ? "AI Ready lane name is locked — toggle from Settings → AI to remove this column"
+            ? "AI Ready lane name is locked — disable AI to hide this column"
             : "";
           return `
             <div class="lane-row${isAiReady ? " lane-row--locked" : ""}" data-lane-id="${lane.id}">

package/public/js/state.js

@@ -49,6 +49,22 @@ export function statesForProject() {
   return state.data.states.filter((item) => item.board_id === state.boardId);
 }
 
+export function isAiReadyState(item) {
+  return item?.role === "ai_ready" || item?.name === "AI Ready";
+}
+
+export function visibleStatesForProject() {
+  const states = statesForProject();
+  if (currentBoard()?.ai_enabled !== 0) return states;
+  return states.filter((item) => !isAiReadyState(item));
+}
+
+export function selectableStatesForProject(currentStateId = "") {
+  const states = statesForProject();
+  if (currentBoard()?.ai_enabled !== 0) return states;
+  return states.filter((item) => !isAiReadyState(item) || item.id === currentStateId);
+}
+
 export function ticketsForProject() {
   return state.data.tickets.filter((item) => item.board_id === state.boardId);
 }

package/public/js/ticket-detail.js

@@ -4,7 +4,7 @@
 // related cards. Also owns the small render helpers (status history,
 // comments, detail-card) that are only used inside the drawer.
 
-import { state, ticketsForProject, statesForProject, boardLabelCatalog, currentBoard } from "./state.js";
+import { state, ticketsForProject, selectableStatesForProject, boardLabelCatalog, currentBoard } from "./state.js";
 import { drawerInner, drawer, $ } from "./dom.js";
 import {
   escapeHtml,
@@ -217,7 +217,7 @@ export async function renderDetail() {
   // user doesn't see it lingering until the next full re-render.
   markRead(ticket.id, ticket.updated_at);
   document.querySelector(`.card[data-ticket-id="${CSS.escape(ticket.id)}"] .card-unread-dot`)?.remove();
-  const states = statesForProject();
+  const states = selectableStatesForProject(ticket.state_id);
 
   // Ordered by the canonical hierarchy so the dropdown visually reinforces scale:
   // Epic (biggest) → Feature → Task → Bug.

package/src/cli/orbit.js

@@ -5,9 +5,10 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, rmSync, unlinkSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { removeOrbitAgentsSection, syncAgentsMd } from "../core/agents-md.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -54,12 +55,9 @@ function formatCommand(executable, args) {
   return [executable, ...args].map(commandQuote).join(" ");
 }
 
-const ORBIT_AGENTS_START = "<!-- ORBIT:AGENTS-START -->";
-const ORBIT_AGENTS_END = "<!-- ORBIT:AGENTS-END -->";
-
 async function loadCliCore() {
   const [
-    { enableAiCollaboration },
+    { disableAiCollaboration, enableAiCollaboration },
     { backupBoardDatabase, backupRegistry },
     { createRegistrySchema, openConnection },
     { DATA_DIR, ROOT_DIR },
@@ -83,6 +81,7 @@ async function loadCliCore() {
     backupRegistry,
     createRegistrySchema,
     deleteBoard,
+    disableAiCollaboration,
     enableAiCollaboration,
     getBoardByRepoPath,
     normalizePath,
@@ -91,50 +90,6 @@ async function loadCliCore() {
   };
 }
 
-function orbitAgentsSection() {
-  return `${ORBIT_AGENTS_START}
-When work mentions Orbit, kanban, board, lane, ticket, card, epic, blocker, claim, AI Ready, implementation fields, planning state, project memory, or handoff: read \`SKILL-ORBIT.md\` first and follow it.
-${ORBIT_AGENTS_END}\n`;
-}
-
-function buildAgentsMd() {
-  return `# AGENTS.md
-
-Git is canonical for code. \`SKILL-ORBIT.md\` is canonical for Orbit/kanban/ticket/card workflow.
-
-${orbitAgentsSection()}`;
-}
-
-function syncAgentsMd(projectRoot, options) {
-  const agentsPath = resolve(projectRoot, "AGENTS.md");
-  const section = orbitAgentsSection();
-
-  if (!existsSync(agentsPath)) {
-    writeFileSync(agentsPath, buildAgentsMd(), "utf8");
-    console.log(`Wrote ${agentsPath}`);
-    return;
-  }
-
-  const current = readFileSync(agentsPath, "utf8");
-  const startIndex = current.indexOf(ORBIT_AGENTS_START);
-  const endIndex = current.indexOf(ORBIT_AGENTS_END);
-
-  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
-    if (!options.refreshAgentsMd) {
-      console.log("AGENTS.md already includes Orbit instructions — left unchanged (use --refresh-agents-md to replace).");
-      return;
-    }
-    const before = current.slice(0, startIndex).replace(/\s*$/, "\n\n");
-    const after = current.slice(endIndex + ORBIT_AGENTS_END.length).replace(/^\s*/, "");
-    writeFileSync(agentsPath, `${before}${section}${after}`, "utf8");
-    console.log(`Refreshed Orbit instructions inside ${agentsPath}`);
-    return;
-  }
-
-  writeFileSync(agentsPath, `${current.replace(/\s*$/, "\n\n")}${section}`, "utf8");
-  console.log(`Appended Orbit instructions to ${agentsPath}`);
-}
-
 function enableAiIfEnabled(options, registryRow, core) {
   if (!options.ai || !registryRow) return;
   const { enableAiCollaboration, openConnection } = core;
@@ -146,9 +101,9 @@ function enableAiIfEnabled(options, registryRow, core) {
 
 function disableAiIfRequested(options, registryRow, core) {
   if (options.ai || !registryRow) return;
-  const { openConnection } = core;
+  const { disableAiCollaboration, openConnection } = core;
   const db = openConnection(registryRow.db_path);
-  db.prepare("UPDATE boards SET ai_enabled = 0, updated_at = ? WHERE id = ?").run(new Date().toISOString(), registryRow.id);
+  disableAiCollaboration(db, registryRow.id, { actor: "orbit init" });
   console.log("AI collaboration disabled for this board.");
 }
 
@@ -304,6 +259,12 @@ async function runReset(options) {
     unlinkSync(skillMd);
     removed.push(skillMd);
   }
+  const agentsCleanup = removeOrbitAgentsSection(projectRoot);
+  if (agentsCleanup.removed) {
+    removed.push(`${agentsCleanup.path} Orbit section`);
+  } else if (!agentsCleanup.ok) {
+    console.warn(`Warning: skipped AGENTS.md cleanup (${agentsCleanup.reason}) in ${agentsCleanup.path}`);
+  }
 
   if (registryRow) {
     deleteBoard(registryRow.id);
@@ -447,4 +408,6 @@ async function main() {
   }
 }
 
-main();
+await main();
+await new Promise((resolvePromise) => process.stdout.write("", resolvePromise));
+await new Promise((resolvePromise) => process.stderr.write("", resolvePromise));

package/src/core/agents-md.js

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const ORBIT_AGENTS_START = "<!-- ORBIT:AGENTS-START -->";
+export const ORBIT_AGENTS_END = "<!-- ORBIT:AGENTS-END -->";
+export const ORBIT_AGENTS_CANONICAL_LINE =
+  "Git is canonical for code. `SKILL-ORBIT.md` is canonical for Orbit/kanban/ticket/card workflow.";
+
+export function orbitAgentsSection() {
+  return `${ORBIT_AGENTS_START}
+${ORBIT_AGENTS_CANONICAL_LINE}
+
+When work mentions Orbit, kanban, board, lane, ticket, card, epic, blocker, claim, AI Ready, implementation fields, planning state, project memory, or handoff: read \`SKILL-ORBIT.md\` first and follow it.
+${ORBIT_AGENTS_END}\n`;
+}
+
+export function buildAgentsMd() {
+  return `# AGENTS.md
+
+${orbitAgentsSection()}`;
+}
+
+export function syncAgentsMd(projectRoot, options = {}, logger = console.log) {
+  const agentsPath = resolve(projectRoot, "AGENTS.md");
+  const section = orbitAgentsSection();
+
+  if (!existsSync(agentsPath)) {
+    writeFileSync(agentsPath, buildAgentsMd(), "utf8");
+    logger(`Wrote ${agentsPath}`);
+    return;
+  }
+
+  const current = readFileSync(agentsPath, "utf8");
+  const startIndex = current.indexOf(ORBIT_AGENTS_START);
+  const endIndex = current.indexOf(ORBIT_AGENTS_END);
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    if (!options.refreshAgentsMd) {
+      logger("AGENTS.md already includes Orbit instructions — left unchanged (use --refresh-agents-md to replace).");
+      return;
+    }
+    const before = current.slice(0, startIndex).replace(/\s*$/, "\n\n");
+    const after = current.slice(endIndex + ORBIT_AGENTS_END.length).replace(/^\s*/, "");
+    writeFileSync(agentsPath, `${before}${section}${after}`, "utf8");
+    logger(`Refreshed Orbit instructions inside ${agentsPath}`);
+    return;
+  }
+
+  writeFileSync(agentsPath, `${current.replace(/\s*$/, "\n\n")}${section}`, "utf8");
+  logger(`Appended Orbit instructions to ${agentsPath}`);
+}
+
+function removeExactLegacyIntro(before) {
+  const escaped = ORBIT_AGENTS_CANONICAL_LINE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const legacyIntro = new RegExp(`(?:^|\\n)[ \\t]*${escaped}[ \\t]*(?:\\r?\\n)?[ \\t]*$`);
+  return before.replace(legacyIntro, (match) => (match.startsWith("\n") ? "\n" : ""));
+}
+
+function joinAfterAgentsRemoval(beforeRaw, afterRaw) {
+  const before = removeExactLegacyIntro(beforeRaw).replace(/\s*$/, "");
+  const after = afterRaw.replace(/^\s*/, "");
+  if (before && after) return `${before}\n\n${after}`;
+  if (before) return `${before}\n`;
+  return after;
+}
+
+export function removeOrbitAgentsSection(projectRoot) {
+  const agentsPath = resolve(projectRoot, "AGENTS.md");
+  if (!existsSync(agentsPath)) {
+    return { ok: true, removed: false, path: agentsPath, reason: "agents_md_missing" };
+  }
+
+  const current = readFileSync(agentsPath, "utf8");
+  const startMatches = [...current.matchAll(new RegExp(ORBIT_AGENTS_START, "g"))];
+  const endMatches = [...current.matchAll(new RegExp(ORBIT_AGENTS_END, "g"))];
+  if (startMatches.length === 0 && endMatches.length === 0) {
+    return { ok: true, removed: false, path: agentsPath, reason: "orbit_section_missing" };
+  }
+  if (startMatches.length !== 1 || endMatches.length !== 1 || endMatches[0].index <= startMatches[0].index) {
+    return { ok: false, removed: false, path: agentsPath, reason: "ambiguous_orbit_section" };
+  }
+
+  const startIndex = startMatches[0].index;
+  const endIndex = endMatches[0].index + ORBIT_AGENTS_END.length;
+  const next = joinAfterAgentsRemoval(current.slice(0, startIndex), current.slice(endIndex));
+  if (next !== current) writeFileSync(agentsPath, next, "utf8");
+  return { ok: true, removed: next !== current, path: agentsPath };
+}

package/src/core/boards.js

@@ -188,6 +188,18 @@ export function enableAiCollaboration(db, boardId, options = {}) {
   return boardById(db, boardId);
 }
 
+export function disableAiCollaboration(db, boardId, options = {}) {
+  const innerBoard = boardById(db, boardId);
+  if (!innerBoard) throw httpError(404, "board_not_found");
+
+  const time = now();
+  return tx(db, () => {
+    db.prepare("UPDATE boards SET ai_enabled = 0, updated_at = ? WHERE id = ?").run(time, boardId);
+    recordEvent(db, boardId, "ai_disabled", null, options.actor || "system", { board_id: boardId });
+    return boardById(db, boardId);
+  });
+}
+
 export function updateBoard(boardId, body, ctx) {
   const { db, board, actor } = ctx;
   if (boardId !== board.id) throw httpError(404, "board_not_found");

package/src/core/delete-board.js

@@ -1,9 +1,10 @@
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, rmSync, unlinkSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
+import { removeOrbitAgentsSection } from "./agents-md.js";
 import { requireBoardAccess } from "./auth.js";
 import { backupBoardDatabase, backupRegistry, cancelAutomaticBoardBackup } from "./backups.js";
 import { closeConnection } from "./db.js";
-import { deleteBoard, openBoardDb } from "./registry.js";
+import { deleteBoard, listBoards, openBoardDb } from "./registry.js";
 import { httpError, normalizePath } from "./util.js";
 
 function isInside(parent, child) {
@@ -26,6 +27,24 @@ function boardDbDeleteTargets(boardRow) {
   return [dbPath, `${dbPath}-wal`, `${dbPath}-shm`, `${dbPath}-journal`];
 }
 
+function isLastBoardForRepo(boardRow) {
+  const repoRoot = normalizePath(boardRow.repo_path || "");
+  return !listBoards().some((row) => row.id !== boardRow.id && normalizePath(row.repo_path || "") === repoRoot);
+}
+
+function repoArtifactTargets(boardRow) {
+  const repoRoot = normalizePath(boardRow.repo_path || "");
+  const dbPath = normalizePath(boardRow.db_path || "");
+  const orbitRoot = normalizePath(join(repoRoot, ".orbit"));
+  if (!repoRoot || !dbPath || !isInside(orbitRoot, dbPath) || basename(dbPath) !== "board.db") {
+    throw httpError(409, "unsafe_board_db_path");
+  }
+  return {
+    orbitRoot,
+    skillMd: join(repoRoot, "SKILL-ORBIT.md")
+  };
+}
+
 export function deleteRegisteredBoard(boardRow, body, actor) {
   requireBoardAccess(actor, { slug: boardRow.slug });
 
@@ -33,14 +52,37 @@ export function deleteRegisteredBoard(boardRow, body, actor) {
   if (confirmation !== boardRow.slug) throw httpError(400, "board_slug_confirmation_required");
 
   const deleteFiles = body?.delete_files !== false;
-  const targets = deleteFiles ? boardDbDeleteTargets(boardRow) : [];
+  const removeRepoArtifacts = deleteFiles && isLastBoardForRepo(boardRow);
+  const repoArtifacts = removeRepoArtifacts ? repoArtifactTargets(boardRow) : null;
+  const targets = deleteFiles
+    ? removeRepoArtifacts
+      ? [repoArtifacts.orbitRoot]
+      : boardDbDeleteTargets(boardRow)
+    : [];
+  const artifactResults = [];
   cancelAutomaticBoardBackup(boardRow.id);
   if (deleteFiles) backupBoardDatabase(boardRow, openBoardDb(boardRow), "pre-board-delete");
   backupRegistry("pre-board-delete");
   closeConnection(boardRow.db_path);
 
   for (const target of targets) {
-    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+    if (existsSync(target)) {
+      rmSync(target, { recursive: true, force: true });
+      artifactResults.push({ path: target, removed: true });
+    }
+  }
+  if (repoArtifacts?.skillMd && existsSync(repoArtifacts.skillMd)) {
+    unlinkSync(repoArtifacts.skillMd);
+    artifactResults.push({ path: repoArtifacts.skillMd, removed: true });
+  }
+  if (removeRepoArtifacts) {
+    const agentsCleanup = removeOrbitAgentsSection(boardRow.repo_path);
+    artifactResults.push({
+      path: agentsCleanup.path,
+      removed: agentsCleanup.removed,
+      ok: agentsCleanup.ok,
+      reason: agentsCleanup.reason
+    });
   }
 
   deleteBoard(boardRow.id);
@@ -48,6 +90,8 @@ export function deleteRegisteredBoard(boardRow, body, actor) {
     ok: true,
     deleted_board_id: boardRow.id,
     deleted_board_slug: boardRow.slug,
-    deleted_files: deleteFiles
+    deleted_files: deleteFiles,
+    deleted_repo_artifacts: removeRepoArtifacts,
+    artifacts: artifactResults
   };
 }

package/src/core/seed.js

@@ -100,7 +100,7 @@ export function seedIfEmpty(db, repoPath, options = {}) {
       const firstTicket = insertSeedTicket(db, boardId, 2, {
         title: "Fill agent context & personal notes",
         description:
-          "Open Settings → AI (Agent Instructions) and Settings → Notes, and replace the seed text with real project context plus your own reminders.",
+          "Open Settings → AI (Agent Instructions) and Settings → Notes, and add real project context plus your own reminders.",
         type: "feature",
         parentTicketId: epicTicket,
         stateId: stateIds.get("Todo"),
@@ -193,7 +193,6 @@ export function buildBoardFromRepo(projectRoot) {
     "main";
   const defaultProjectNotes =
     "Personal reminders (Settings → Notes: Notes For You). Point yourself at SKILL-ORBIT.md, runbooks, or nudges for your tools.";
-  const defaultAgentInstructions = `Describe why ${boardName} exists, who it serves, and what success looks like. Add features, stack, constraints, and anything agents should know — this project-level context is provided to agents when they work on tickets.`;
   return {
     boardName,
     boardSlug,
@@ -201,7 +200,7 @@ export function buildBoardFromRepo(projectRoot) {
     systemPath,
     defaultBranch,
     projectNotes: readSeedValue("project_notes") || defaultProjectNotes,
-    agentInstructions: readSeedValue("agent_instructions") || defaultAgentInstructions
+    agentInstructions: readSeedValue("agent_instructions") || ""
   };
 }