@starlove/orbit 1.0.2 → 1.0.4

package/dist/full/version.json

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

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. Add `--ai` to enable the AI Ready / In Progress / Review agent lanes immediately, 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 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.
 
 The generated format changes by app:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.0.2",
+  "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)), "..", "..");
 
@@ -23,7 +24,7 @@ Options (init / reset / serve / docker / mcp):
   --cwd <dir>           Project root (default: process.cwd())
 
 Options (init only):
-  --ai                  Enable AI collaboration lanes
+  --no-ai               Create the board with AI collaboration disabled
   --example             Create example onboarding tickets
   --refresh-agents-md   Overwrite SKILL-ORBIT.md and refresh Orbit section in AGENTS.md
 
@@ -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,66 +90,30 @@ 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 enableAiIfRequested(options, registryRow, core) {
+function enableAiIfEnabled(options, registryRow, core) {
   if (!options.ai || !registryRow) return;
   const { enableAiCollaboration, openConnection } = core;
   const db = openConnection(registryRow.db_path);
-  enableAiCollaboration(db, registryRow.id, { stageOnboardingTicket: options.example, actor: "orbit init --ai" });
+  enableAiCollaboration(db, registryRow.id, { stageOnboardingTicket: options.example, actor: "orbit init" });
   const suffix = options.example ? "; example ticket #12 is staged in AI Ready." : ".";
   console.log(`AI collaboration enabled — AI Ready, In Progress, and Review lanes are present${suffix}`);
 }
 
+function disableAiIfRequested(options, registryRow, core) {
+  if (options.ai || !registryRow) return;
+  const { disableAiCollaboration, openConnection } = core;
+  const db = openConnection(registryRow.db_path);
+  disableAiCollaboration(db, registryRow.id, { actor: "orbit init" });
+  console.log("AI collaboration disabled for this board.");
+}
+
 function parseArgs(argv) {
   const args = {
     command: null,
     cwd: process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : process.cwd(),
     cwdProvided: false,
     refreshAgentsMd: false,
-    ai: false,
+    ai: true,
     example: false,
     port: null,
     image: "starscape-orbit:local",
@@ -169,7 +132,7 @@ function parseArgs(argv) {
   for (let i = 1; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--refresh-agents-md") args.refreshAgentsMd = true;
-    else if (a === "--ai") args.ai = true;
+    else if (a === "--no-ai") args.ai = false;
     else if (a === "--example") args.example = true;
     else if (a === "--cwd" && rest[i + 1]) {
       args.cwdProvided = true;
@@ -217,7 +180,7 @@ async function runInit(options) {
   mkdirSync(DATA_DIR, { recursive: true });
   createRegistrySchema();
 
-  const result = provisionRepoBoard(projectRoot, { includeExamples: options.example });
+  const result = provisionRepoBoard(projectRoot, { enableAi: options.ai, includeExamples: options.example });
   const skillSrc = resolve(ROOT_DIR, "SKILL-ORBIT.md");
   const skillDest = resolve(projectRoot, "SKILL-ORBIT.md");
 
@@ -235,7 +198,8 @@ async function runInit(options) {
     syncAgentsMd(projectRoot, options);
   }
 
-  enableAiIfRequested(options, result.registryRow, core);
+  enableAiIfEnabled(options, result.registryRow, core);
+  disableAiIfRequested(options, result.registryRow, core);
 
   if (result.message && result.status === "skipped") {
     console.log(result.message);
@@ -254,7 +218,7 @@ ${mcpLine}
 --- Next: agent prompt (from this repo) ---
 Read AGENTS.md in this repository, then use the Orbit MCP tools. Use board_list, board_set_active, and ticket context tools per docs/AGENT_PROTOCOL.md before claiming or updating work.
 
-${options.example ? (options.ai ? "Example ticket #12 is \"Try Orbit MCP on this ticket\" in AI Ready — good first exercise after MCP is connected." : "Example tickets were created. Add `--ai` to also create AI collaboration lanes and stage ticket #12 in AI Ready.") : "No example tickets were created. Rerun on a fresh board with `orbit init --example` if you want the onboarding examples."}
+${options.example ? (options.ai ? "Example ticket #12 is \"Try Orbit MCP on this ticket\" in AI Ready — good first exercise after MCP is connected." : "Example tickets were created. AI collaboration was disabled with `--no-ai`, so ticket #12 remains in Backlog.") : "No example tickets were created. Rerun on a fresh board with `orbit init --example` if you want the onboarding examples."}
 `);
 
   if (result.registryRow) {
@@ -295,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);
@@ -438,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

@@ -1,5 +1,5 @@
 import { getRegistry, tx } from "./db.js";
-import { boardById } from "./queries.js";
+import { boardById, compactStatePositions } from "./queries.js";
 import {
   computeNewBoardDbPath,
   ensureBoardDbFileAndSchema,
@@ -33,14 +33,23 @@ export function createBoard(body, ctx) {
   const time = now();
   const sniff = buildBoardFromRepo(repoPath);
 
-  const defaultStates = body.states || [
+  const aiEnabled = body.ai_enabled === undefined ? true : Boolean(body.ai_enabled);
+  const defaultStates = body.states || (aiEnabled ? [
     ["Backlog", null],
     ["Todo", null],
+    ["AI Ready", "ai_ready"],
     ["In Progress", "in_progress"],
     ["Review", "review"],
     ["Done", "done"],
     ["Cancelled", null]
-  ];
+  ] : [
+    ["Backlog", null],
+    ["Todo", null],
+    ["In Progress", "in_progress"],
+    ["Review", "review"],
+    ["Done", "done"],
+    ["Cancelled", null]
+  ]);
 
   // Board row + lanes + creation event land atomically in the board DB. The
   // registry insert below is a different database (can't share this
@@ -49,8 +58,8 @@ export function createBoard(body, ctx) {
   tx(db, () => {
     db.prepare(
       `INSERT INTO boards
-       (id, slug, name, repo_url, system_path, default_branch, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+       (id, slug, name, repo_url, system_path, default_branch, ai_enabled, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
     ).run(
       boardId,
       slug,
@@ -58,6 +67,7 @@ export function createBoard(body, ctx) {
       body.repo_url || sniff.repoUrl || "",
       repoPath,
       body.default_branch || sniff.defaultBranch || "main",
+      aiEnabled ? 1 : 0,
       time,
       time
     );
@@ -70,6 +80,7 @@ export function createBoard(body, ctx) {
       ).run(id(), boardId, stateName, position, stateName === "Todo" ? 1 : 0, role || null, time);
     });
 
+    if (aiEnabled) ensureAgentLanes(db, boardId);
     recordEvent(db, boardId, "board_created", null, actor.name, { board_id: boardId, slug });
   });
 
@@ -95,24 +106,58 @@ const AGENT_LANES = [
   { name: "Review", role: "review" }
 ];
 
-/** Ensure the three role-bearing lanes that agent flow depends on
- *  (ai_ready / in_progress / review) exist on the board. Missing lanes are
- *  appended at the end of the lane order. Idempotent. */
+function desiredAgentLanePosition(db, boardId, role) {
+  if (role === "ai_ready") {
+    const todo = db.prepare("SELECT position FROM states WHERE board_id = ? AND name = 'Todo'").get(boardId);
+    if (todo) return Number(todo.position) + 1;
+    const inProgress = db.prepare("SELECT position FROM states WHERE board_id = ? AND role = 'in_progress'").get(boardId);
+    if (inProgress) return Number(inProgress.position);
+  }
+  const maxPosition = db
+    .prepare("SELECT MAX(position) AS value FROM states WHERE board_id = ?")
+    .get(boardId).value;
+  return Number(maxPosition ?? -1) + 1;
+}
+
+function openStateSlot(db, boardId, position, exceptStateId = null) {
+  db.prepare(
+    `UPDATE states
+     SET position = position + 1
+     WHERE board_id = ?
+       AND position >= ?
+       AND (? IS NULL OR id != ?)`
+  ).run(boardId, position, exceptStateId, exceptStateId);
+}
+
+/** Ensure the role-bearing lanes that agent flow depends on exist on the
+ *  board. AI Ready is kept directly after Todo so claim-next has a predictable
+ *  handoff column. Idempotent. */
 export function ensureAgentLanes(db, boardId) {
   const time = now();
   for (const lane of AGENT_LANES) {
     const existing = db
-      .prepare("SELECT id FROM states WHERE board_id = ? AND role = ?")
+      .prepare("SELECT id, position FROM states WHERE board_id = ? AND role = ?")
       .get(boardId, lane.role);
-    if (existing) continue;
-    const maxPosition = db
-      .prepare("SELECT MAX(position) AS value FROM states WHERE board_id = ?")
-      .get(boardId).value;
+    if (existing) {
+      if (lane.role === "ai_ready") {
+        let desiredPosition = desiredAgentLanePosition(db, boardId, lane.role);
+        if (Number(existing.position) !== desiredPosition) {
+          db.prepare("UPDATE states SET position = -1 WHERE id = ?").run(existing.id);
+          compactStatePositions(db, boardId);
+          desiredPosition = desiredAgentLanePosition(db, boardId, lane.role);
+          openStateSlot(db, boardId, desiredPosition, existing.id);
+          db.prepare("UPDATE states SET position = ? WHERE id = ?").run(desiredPosition, existing.id);
+        }
+      }
+      continue;
+    }
+    const position = desiredAgentLanePosition(db, boardId, lane.role);
+    openStateSlot(db, boardId, position);
     db.prepare(
       `INSERT INTO states
        (id, board_id, name, position, is_default, role, created_at)
        VALUES (?, ?, ?, ?, 0, ?, ?)`
-    ).run(id(), boardId, lane.name, Number(maxPosition || 0) + 1, lane.role, time);
+    ).run(id(), boardId, lane.name, position, lane.role, time);
   }
 }
 
@@ -143,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");