@staff0rd/assist 0.372.0 → 0.374.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@staff0rd/assist",
-  version: "0.372.0",
+  version: "0.374.0",
   type: "module",
   main: "dist/index.js",
   bin: {
@@ -27,7 +27,15 @@ var package_default = {
     build: "tsup",
     start: "node dist/index.js",
     "check:types": "tsc --noEmit",
-    test: "vitest run"
+    test: "vitest run",
+    "verify:lint": "oxlint --config .oxlintrc.json src",
+    "verify:format": "oxfmt .",
+    "verify:knip": "knip --no-progress --treat-config-hints-as-errors",
+    "verify:duplicate-code": 'jscpd --format typescript,tsx,python --exitCode 1 --ignore "**/*.test.*,**/.venv/**" -r consoleFull src',
+    "verify:test": "vitest run --changed --passWithNoTests --reporter dot",
+    "verify:config-keys": "tsx src/index.ts verify config-keys",
+    "verify:react-build": "esbuild src/commands/sessions/web/ui/App.tsx --bundle --minify --format=iife --target=es2020 --outfile=dist/commands/sessions/web/bundle.verify.js --jsx=automatic --jsx-import-source=react --define:process.env.NODE_ENV='production'",
+    "verify:circular-deps": "skott --displayMode=raw --showCircularDependencies --exitCodeOnCircularDependencies=1 src/index.ts"
   },
   overrides: {
     lodash: "^4.18.0",
@@ -107,7 +115,9 @@ var package_default = {
     "react-dom": "^19.2.4",
     "react-router": "^7.14.0",
     "semantic-release": "^25.0.2",
+    skott: "^0.35.11",
     tsup: "^8.5.1",
+    tsx: "^4.23.0",
     vitest: "^4.0.18"
   }
 };
@@ -120,8 +130,8 @@ var ITEM_ID_ENV = "ASSIST_BACKLOG_ITEM_ID";
 function resolveSessionItemId() {
   const raw = process.env[ITEM_ID_ENV];
   if (!raw) return null;
-  const id2 = Number.parseInt(raw, 10);
-  return Number.isInteger(id2) && id2 > 0 ? id2 : null;
+  const id = Number.parseInt(raw, 10);
+  return Number.isInteger(id) && id > 0 ? id : null;
 }
 
 // src/shared/db/getDb.ts
@@ -1005,9 +1015,9 @@ async function closeDb() {
 }
 
 // src/shared/db/recordGitRef.ts
-async function recordGitRef(db, itemId, ref) {
+async function recordGitRef(db, itemId2, ref) {
   await db.insert(itemGitRefs).values({
-    itemId,
+    itemId: itemId2,
     kind: ref.kind,
     ref: ref.ref,
     title: ref.title ?? null,
@@ -1025,15 +1035,15 @@ async function recordGitRef(db, itemId, ref) {
 
 // src/shared/db/recordSessionRefs.ts
 async function recordSessionRefs(refs) {
-  const itemId = resolveSessionItemId();
-  if (itemId === null || refs.length === 0) return;
-  await persist(itemId, refs).catch(ignore);
+  const itemId2 = resolveSessionItemId();
+  if (itemId2 === null || refs.length === 0) return;
+  await persist(itemId2, refs).catch(ignore);
   await closeDb().catch(ignore);
 }
-async function persist(itemId, refs) {
+async function persist(itemId2, refs) {
   const db = await getDb();
   for (const ref of refs) {
-    await recordGitRef(db, itemId, ref);
+    await recordGitRef(db, itemId2, ref);
   }
 }
 function ignore() {
@@ -2583,7 +2593,7 @@ function collectHashComments(content, options2) {
 function collectComments(sourceFile) {
   const seen = /* @__PURE__ */ new Set();
   const comments3 = [];
-  const collect5 = (node) => {
+  const collect6 = (node) => {
     for (const range of [
       ...node.getLeadingCommentRanges(),
       ...node.getTrailingCommentRanges()
@@ -2594,8 +2604,8 @@ function collectComments(sourceFile) {
       comments3.push({ pos, text: range.getText() });
     }
   };
-  collect5(sourceFile);
-  sourceFile.forEachDescendant(collect5);
+  collect6(sourceFile);
+  sourceFile.forEachDescendant(collect6);
   return comments3;
 }
 
@@ -2780,6 +2790,104 @@ Total: ${findings.length} comment(s)`);
   process.exit(1);
 }
 
+// src/shared/configHelp.ts
+var documentedKeys = /* @__PURE__ */ new Set();
+function getDocumentedConfigKeys() {
+  return documentedKeys;
+}
+function renderConfigHelp(entries, preamble) {
+  const width = Math.max(...entries.map((entry) => entry.setter.length));
+  const lines = entries.map(
+    (entry) => `  ${entry.setter.padEnd(width)} # ${entry.note}`
+  );
+  const body = preamble ? ["", preamble, "", "Config:", ...lines] : ["", "Config:", ...lines];
+  return body.join("\n");
+}
+function configHelp(command, entries, preamble) {
+  for (const entry of entries) documentedKeys.add(entry.key);
+  return command.addHelpText(
+    "after",
+    () => renderConfigHelp(entries, preamble)
+  );
+}
+
+// src/shared/enumerateConfigLeafKeys.ts
+var WRAPPER_TYPES = /* @__PURE__ */ new Set([
+  "optional",
+  "default",
+  "nullable",
+  "nullish",
+  "readonly",
+  "catch"
+]);
+function unwrap(node) {
+  let current = node;
+  while (current.def && WRAPPER_TYPES.has(current.def.type ?? "") && current.def.innerType) {
+    current = current.def.innerType;
+  }
+  return current;
+}
+function collect(node, prefix2, out) {
+  const unwrapped = unwrap(node);
+  const shape = unwrapped.def?.shape;
+  if (unwrapped.def?.type === "object" && shape) {
+    for (const [key, child] of Object.entries(shape)) {
+      collect(child, prefix2 ? `${prefix2}.${key}` : key, out);
+    }
+    return;
+  }
+  out.push(prefix2);
+}
+function enumerateConfigLeafKeys(schema2) {
+  const out = [];
+  collect(schema2, "", out);
+  return out.sort();
+}
+
+// src/commands/verify/pendingConfigDocumentation.ts
+var pendingConfigDocumentation = /* @__PURE__ */ new Set();
+
+// src/commands/verify/configKeys.ts
+function section(label2, keys) {
+  if (keys.length === 0) return void 0;
+  const list5 = keys.sort().map((key) => `  ${key}`).join("\n");
+  return `${label2}:
+${list5}`;
+}
+function configKeys() {
+  const schemaKeys = new Set(enumerateConfigLeafKeys(assistConfigSchema));
+  const documented = getDocumentedConfigKeys();
+  const pending = pendingConfigDocumentation;
+  const problems = [
+    section(
+      "Config keys documented by no command (surface them with configHelp)",
+      [...schemaKeys].filter(
+        (key) => !documented.has(key) && !pending.has(key)
+      )
+    ),
+    section(
+      "Documented config keys not present in assistConfigSchema",
+      [...documented].filter((key) => !schemaKeys.has(key))
+    ),
+    section(
+      "Keys now documented but still in pendingConfigDocumentation (remove them)",
+      [...pending].filter((key) => documented.has(key))
+    ),
+    section(
+      "pendingConfigDocumentation lists keys not in assistConfigSchema (remove them)",
+      [...pending].filter((key) => !schemaKeys.has(key))
+    )
+  ].filter((problem) => problem !== void 0);
+  if (problems.length > 0) {
+    console.log(problems.join("\n\n"));
+    process.exit(1);
+  }
+  console.log(
+    `All ${schemaKeys.size} config keys are surfaced in --help or pending documentation.`
+  );
+  process.exit(0);
+}
+
 // src/commands/verify/forbiddenStrings/index.ts
 import { existsSync as existsSync12, readFileSync as readFileSync9 } from "fs";
 
@@ -4082,6 +4190,13 @@ function registerBackup(program2) {
   scheduleCommand.command("remove").description(
     "Remove the marked backup schedule block, leaving other crontab lines intact"
   ).action(scheduleRemove);
+  configHelp(backupCommand, [
+    {
+      key: "backup.dir",
+      setter: "assist config set backup.dir ~/.assist/backups",
+      note: "directory dumps are written to (default: ~/.assist/backups)"
+    }
+  ]);
 }
 
 // src/commands/backlog/next.ts
@@ -4120,6 +4235,24 @@ function hasLocalChanges() {
   }
 }
 
+// src/commands/backlog/formatItemId.ts
+var InvalidItemIdError = class extends Error {
+  name = "InvalidItemIdError";
+};
+function formatItemId(id) {
+  return `a${id}`;
+}
+var itemIdPattern = /^a?(\d+)$/;
+function parseItemId(input) {
+  const match = itemIdPattern.exec(input.trim());
+  if (!match) {
+    throw new InvalidItemIdError(
+      `Invalid backlog item id "${input}" (e.g. a574 or 574).`
+    );
+  }
+  return Number.parseInt(match[1], 10);
+}
+
 // src/commands/backlog/acquireLock.ts
 import {
   existsSync as existsSync16,
@@ -4133,8 +4266,8 @@ import { join as join12 } from "path";
 function getLocksDir() {
   return join12(homedir4(), ".assist", "locks");
 }
-function getLockPath(itemId) {
-  return join12(getLocksDir(), `lock-${itemId}.json`);
+function getLockPath(itemId2) {
+  return join12(getLocksDir(), `lock-${itemId2}.json`);
 }
 function isProcessAlive(pid) {
   try {
@@ -4144,8 +4277,8 @@ function isProcessAlive(pid) {
     return false;
   }
 }
-function isLockedByOther(itemId) {
-  const lockPath = getLockPath(itemId);
+function isLockedByOther(itemId2) {
+  const lockPath = getLockPath(itemId2);
   if (!existsSync16(lockPath)) return false;
   try {
     const lock2 = JSON.parse(readFileSync12(lockPath, "utf8"));
@@ -4155,15 +4288,15 @@ function isLockedByOther(itemId) {
     return false;
   }
 }
-function acquireLock(itemId) {
+function acquireLock(itemId2) {
   mkdirSync4(getLocksDir(), { recursive: true });
   writeFileSync14(
-    getLockPath(itemId),
+    getLockPath(itemId2),
     JSON.stringify({ pid: process.pid, timestamp: (/* @__PURE__ */ new Date()).toISOString() })
   );
 }
-function releaseLock(itemId) {
-  const lockPath = getLockPath(itemId);
+function releaseLock(itemId2) {
+  const lockPath = getLockPath(itemId2);
   try {
     unlinkSync2(lockPath);
   } catch {
@@ -4366,27 +4499,27 @@ import { join as join14 } from "path";
 function getControlsDir() {
   return join14(homedir6(), ".assist", "controls");
 }
-function getPausePath(itemId) {
-  return join14(getControlsDir(), `pause-${itemId}.json`);
+function getPausePath(itemId2) {
+  return join14(getControlsDir(), `pause-${itemId2}.json`);
 }
-function requestPause(itemId) {
+function requestPause(itemId2) {
   mkdirSync6(getControlsDir(), { recursive: true });
   writeFileSync16(
-    getPausePath(itemId),
+    getPausePath(itemId2),
     JSON.stringify({ timestamp: (/* @__PURE__ */ new Date()).toISOString() })
   );
 }
-function isPausePending(itemId) {
-  return existsSync17(getPausePath(itemId));
+function isPausePending(itemId2) {
+  return existsSync17(getPausePath(itemId2));
 }
-function clearPause(itemId) {
+function clearPause(itemId2) {
   try {
-    unlinkSync3(getPausePath(itemId));
+    unlinkSync3(getPausePath(itemId2));
   } catch {
   }
 }
-function consumePause(itemId) {
-  const pausePath = getPausePath(itemId);
+function consumePause(itemId2) {
+  const pausePath = getPausePath(itemId2);
   if (!existsSync17(pausePath)) return false;
   try {
     unlinkSync3(pausePath);
@@ -4716,8 +4849,8 @@ function rowToGitRef(r) {
   if (r.createdAt != null) ref.createdAt = new Date(r.createdAt).toISOString();
   return ref;
 }
-function attachGitRefs(item, rel, id2) {
-  const gitRefs = (rel.gitRefs.get(id2) ?? []).map(rowToGitRef);
+function attachGitRefs(item, rel, id) {
+  const gitRefs = (rel.gitRefs.get(id) ?? []).map(rowToGitRef);
   if (gitRefs.length > 0) item.gitRefs = gitRefs;
 }
 
@@ -4730,8 +4863,8 @@ function rowToSubtask(s) {
   if (s.description != null) subtask.description = s.description;
   return subtask;
 }
-function attachSubtasks(item, rel, id2) {
-  const subtasks = (rel.subtasks.get(id2) ?? []).map(rowToSubtask);
+function attachSubtasks(item, rel, id) {
+  const subtasks = (rel.subtasks.get(id) ?? []).map(rowToSubtask);
   if (subtasks.length > 0) item.subtasks = subtasks;
 }
 
@@ -4744,8 +4877,8 @@ function rowToUsage(u) {
     activeMs: u.activeMs
   };
 }
-function attachUsage(item, rel, id2) {
-  const usage = (rel.usage.get(id2) ?? []).map(rowToUsage);
+function attachUsage(item, rel, id) {
+  const usage = (rel.usage.get(id) ?? []).map(rowToUsage);
   if (usage.length > 0) item.phaseUsage = usage;
 }
 
@@ -4804,17 +4937,17 @@ function baseItem(row) {
   assignOptionalColumns(item, row);
   return item;
 }
-function attachComments(item, rel, id2) {
-  const comments3 = (rel.comments.get(id2) ?? []).map(rowToComment);
+function attachComments(item, rel, id) {
+  const comments3 = (rel.comments.get(id) ?? []).map(rowToComment);
   if (comments3.length > 0) item.comments = comments3;
 }
-function attachLinks(item, rel, id2) {
-  const links2 = (rel.links.get(id2) ?? []).map(rowToLink);
+function attachLinks(item, rel, id) {
+  const links2 = (rel.links.get(id) ?? []).map(rowToLink);
   if (links2.length > 0) item.links = links2;
 }
-function attachPlan(item, rel, id2) {
-  const phases = rel.phases.get(id2) ?? [];
-  if (phases.length > 0) item.plan = buildPlan(phases, rel.tasks.get(id2) ?? []);
+function attachPlan(item, rel, id) {
+  const phases = rel.phases.get(id) ?? [];
+  if (phases.length > 0) item.plan = buildPlan(phases, rel.tasks.get(id) ?? []);
 }
 function rowToItem(row, rel) {
   const item = baseItem(row);
@@ -4966,8 +5099,8 @@ async function ensureMigrated(orm, dir, origin) {
 
 // src/commands/backlog/deleteItem.ts
 import { eq as eq4 } from "drizzle-orm";
-async function deleteItem(orm, id2) {
-  const [row] = await orm.delete(items).where(eq4(items.id, id2)).returning({ name: items.name });
+async function deleteItem(orm, id) {
+  const [row] = await orm.delete(items).where(eq4(items.id, id)).returning({ name: items.name });
   return row?.name;
 }
 
@@ -5047,10 +5180,10 @@ function getCurrentOrigin(cwd) {
 
 // src/commands/backlog/loadItem.ts
 import { eq as eq5 } from "drizzle-orm";
-async function loadItem(orm, id2) {
-  const [row] = await orm.select().from(items).where(eq5(items.id, id2));
+async function loadItem(orm, id) {
+  const [row] = await orm.select().from(items).where(eq5(items.id, id));
   if (!row) return void 0;
-  const rel = await loadRelations(orm, [id2], {
+  const rel = await loadRelations(orm, [id], {
     includeUsage: true,
     includeGitRefs: true
   });
@@ -5087,14 +5220,14 @@ async function searchItemIds(orm, query, origin) {
 
 // src/commands/backlog/updateCurrentPhase.ts
 import { eq as eq9 } from "drizzle-orm";
-async function updateCurrentPhase(orm, id2, phase) {
-  await orm.update(items).set({ currentPhase: phase }).where(eq9(items.id, id2));
+async function updateCurrentPhase(orm, id, phase) {
+  await orm.update(items).set({ currentPhase: phase }).where(eq9(items.id, id));
 }
 
 // src/commands/backlog/updateStatus.ts
 import { eq as eq10 } from "drizzle-orm";
-async function updateStatus(orm, id2, status2) {
-  const [row] = await orm.update(items).set({ status: status2 }).where(eq10(items.id, id2)).returning({ name: items.name });
+async function updateStatus(orm, id, status2) {
+  const [row] = await orm.update(items).set({ status: status2 }).where(eq10(items.id, id)).returning({ name: items.name });
   return row?.name;
 }
 
@@ -5126,35 +5259,39 @@ async function searchBacklog(query) {
   const allItems = await loadAllItems(orm, origin);
   return allItems.filter((item) => ids.includes(item.id));
 }
-async function findOneItem(id2) {
-  const numId = Number.parseInt(id2, 10);
+async function findOneItem(id) {
+  const numId = parseItemId(id);
   const { orm } = await getReady();
-  const item = Number.isNaN(numId) ? void 0 : await loadItem(orm, numId);
+  const item = await loadItem(orm, numId);
   if (!item) {
-    console.log(chalk37.red(`Item #${id2} not found.`));
+    console.log(chalk37.red(`Item ${formatItemId(numId)} not found.`));
     return void 0;
   }
   return { orm, item };
 }
-async function setStatus(id2, status2) {
+async function setStatus(id, status2) {
   const { orm } = await getReady();
-  const name = await updateStatus(orm, Number.parseInt(id2, 10), status2);
-  if (name === void 0) console.log(chalk37.red(`Item #${id2} not found.`));
+  const numId = parseItemId(id);
+  const name = await updateStatus(orm, numId, status2);
+  if (name === void 0)
+    console.log(chalk37.red(`Item ${formatItemId(numId)} not found.`));
   return name;
 }
-async function setCurrentPhase(id2, phase) {
+async function setCurrentPhase(id, phase) {
   const { orm } = await getReady();
-  await updateCurrentPhase(orm, Number.parseInt(id2, 10), phase);
+  await updateCurrentPhase(orm, parseItemId(id), phase);
 }
-async function removeItem(id2) {
+async function removeItem(id) {
   const { orm } = await getReady();
-  const name = await deleteItem(orm, Number.parseInt(id2, 10));
-  if (name === void 0) console.log(chalk37.red(`Item #${id2} not found.`));
+  const numId = parseItemId(id);
+  const name = await deleteItem(orm, numId);
+  if (name === void 0)
+    console.log(chalk37.red(`Item ${formatItemId(numId)} not found.`));
   return name;
 }
 
 // src/commands/backlog/handleReviewResult.ts
-async function handleReviewResult(id2, review2) {
+async function handleReviewResult(id, review2) {
   if (review2.kind === "fail" || review2.kind === "abort")
     return { kind: "stop", success: false };
   if (review2.kind === "paused") return { kind: "stop", success: true };
@@ -5164,12 +5301,12 @@ async function handleReviewResult(id2, review2) {
       startPhase: review2.targetPhase,
       plan: review2.plan
     };
-  await ensureDone(id2);
+  await ensureDone(id);
   return { kind: "stop", success: true };
 }
-async function ensureDone(id2) {
+async function ensureDone(id) {
   try {
-    await setStatus(id2, "done");
+    await setStatus(id, "done");
   } catch {
   }
 }
@@ -5191,20 +5328,24 @@ function resolvePlan(item) {
 }
 
 // src/commands/backlog/prepareRun.ts
-async function prepareRun(id2) {
-  const found = await findOneItem(id2);
+async function prepareRun(id) {
+  const found = await findOneItem(id);
   if (!found) return void 0;
   const { item } = found;
   const plan2 = resolvePlan(item);
   const startPhase = (item.currentPhase ?? 1) - 1;
   if (item.status === "done") {
-    console.log(chalk38.green(`Already done: #${id2}: ${item.name}`));
+    console.log(
+      chalk38.green(`Already done: ${formatItemId(item.id)}: ${item.name}`)
+    );
     return void 0;
   }
   if (startPhase > plan2.length) {
-    await setStatus(id2, "done");
+    await setStatus(id, "done");
     console.log(
-      chalk38.green(`All phases already complete for #${id2}: ${item.name}`)
+      chalk38.green(
+        `All phases already complete for ${formatItemId(item.id)}: ${item.name}`
+      )
     );
     return void 0;
   }
@@ -5284,10 +5425,10 @@ function buildCommentLines(comments3) {
   return ["", "Comments:", ...comments3.map(formatPromptComment)];
 }
 function formatPromptComment(entry) {
-  const id2 = entry.id !== void 0 ? `#${entry.id} ` : "";
+  const id = entry.id !== void 0 ? `#${entry.id} ` : "";
   const tag = entry.type === "summary" ? "[summary]" : "[comment]";
   const phase = entry.phase !== void 0 ? ` (phase ${entry.phase})` : "";
-  return `${id2}${tag}${phase} ${entry.timestamp}
+  return `${id}${tag}${phase} ${entry.timestamp}
   ${entry.text}`;
 }
 
@@ -5305,16 +5446,16 @@ function buildAuthoredPhasePrompt(item, phaseNumber, phase) {
     "When you have completed all tasks for this phase, run /verify to check your work.",
     ...buildManualCheckLines(manualChecks),
     "",
-    `Post concise comments for any notable findings or changes using \`assist backlog comment ${item.id} "<text>"\`.`,
+    `Post concise comments for any notable findings or changes using \`assist backlog comment ${formatItemId(item.id)} "<text>"\`.`,
     "",
-    `Once verify passes${confirmSuffix}, run: assist backlog phase-done ${item.id} ${phaseNumber} "<summary>"`,
+    `Once verify passes${confirmSuffix}, run: assist backlog phase-done ${formatItemId(item.id)} ${phaseNumber} "<summary>"`,
     "Replace <summary> with a concise summary of what was done in this phase."
   ].filter((line) => line !== void 0).join("\n");
 }
 function buildContextLines(item, phaseNumber, phase) {
   const ac = item.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
   return [
-    `You are implementing phase ${phaseNumber} of backlog item #${item.id}: ${item.name}`,
+    `You are implementing phase ${phaseNumber} of backlog item ${formatItemId(item.id)}: ${item.name}`,
     "",
     item.description ? `Description: ${item.description}` : "",
     "",
@@ -5355,8 +5496,9 @@ function formatTasks(phase) {
 // src/commands/backlog/buildReviewPrompt.ts
 function buildReviewPrompt(item, phaseNumber) {
   const acLines = item.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join("\n");
+  const itemId2 = formatItemId(item.id);
   return [
-    `You are reviewing backlog item #${item.id}: ${item.name}`,
+    `You are reviewing backlog item ${itemId2}: ${item.name}`,
     "",
     item.description ? `Description: ${item.description}` : "",
     "",
@@ -5369,9 +5511,9 @@ function buildReviewPrompt(item, phaseNumber) {
     "",
     "If any criterion fails, fix the issue and re-verify.",
     "",
-    `Any sub-tasks on this item must all be done before it can be completed: \`assist backlog done\` and completing this Review phase both fail while any sub-task is not done. Check them with \`assist backlog show ${item.id}\` and mark each finished one done via \`assist backlog subtask-status ${item.id} <idx> done\`.`,
+    `Any sub-tasks on this item must all be done before it can be completed: \`assist backlog done\` and completing this Review phase both fail while any sub-task is not done. Check them with \`assist backlog show ${itemId2}\` and mark each finished one done via \`assist backlog subtask-status ${itemId2} <idx> done\`.`,
     "",
-    `Post concise comments for any notable findings or changes using \`assist backlog comment ${item.id} "<text>"\`.`,
+    `Post concise comments for any notable findings or changes using \`assist backlog comment ${itemId2} "<text>"\`.`,
     "",
     "After all criteria pass, ask the user to confirm any manual checks",
     "(e.g. end-to-end behaviour they need to verify themselves).",
@@ -5384,13 +5526,13 @@ function buildReviewPrompt(item, phaseNumber) {
     "",
     "Once the user gives that explicit completion instruction:",
     "1. Run: /commit",
-    `2. Run: assist backlog done ${item.id} "<summary>"`,
-    `3. Run: assist backlog phase-done ${item.id} ${phaseNumber} "done"`,
+    `2. Run: assist backlog done ${itemId2} "<summary>"`,
+    `3. Run: assist backlog phase-done ${itemId2} ${phaseNumber} "done"`,
     "",
     "Precedence rules \u2014 read carefully:",
     "- An explicit completion instruction plus a successful commit means the work is complete. Always finish with done + phase-done; never rewind already-approved, committed work as an automatic response.",
     "- If the implementation has diverged from the recorded acceptance criteria but the user has approved it, the default is still to complete the item. You may optionally offer to update the acceptance criteria, but stale criteria are not a reason to rewind.",
-    `- Rewinding is a confirm-first exception, not the normal path. If you believe a criterion genuinely no longer fits and the work should return to an earlier phase, you must ask the user and get explicit confirmation first. Only after they confirm may you run \`assist backlog rewind ${item.id} <phase> --reason "<reason>"\`. Never rewind silently.`
+    `- Rewinding is a confirm-first exception, not the normal path. If you believe a criterion genuinely no longer fits and the work should return to an earlier phase, you must ask the user and get explicit confirmation first. Only after they confirm may you run \`assist backlog rewind ${itemId2} <phase> --reason "<reason>"\`. Never rewind silently.`
   ].filter((line) => line !== void 0).join("\n");
 }
 
@@ -5525,15 +5667,15 @@ function cleanupSignal() {
     unlinkSync4(statusPath);
   }
 }
-async function isTerminalStatus(itemId) {
+async function isTerminalStatus(itemId2) {
   const { orm } = await getReady();
-  const item = await loadItem(orm, itemId);
+  const item = await loadItem(orm, itemId2);
   return item?.status === "done" || item?.status === "wontdo";
 }
-async function resolvePhaseResult(phaseIndex, itemId) {
+async function resolvePhaseResult(phaseIndex, itemId2) {
   const signalPath = getSignalPath();
   if (!signalPath || !existsSync22(signalPath)) {
-    if (await isTerminalStatus(itemId)) return -1;
+    if (await isTerminalStatus(itemId2)) return -1;
     const action = await handleIncompletePhase();
     if (action === "abort") return -1;
     return action === "skip" ? phaseIndex + 1 : phaseIndex;
@@ -5617,8 +5759,8 @@ async function executePhase(item, phaseIndex, phases, spawnOptions, totalPhases
 }
 
 // src/commands/backlog/reloadPlan.ts
-async function reloadPlan(id2) {
-  const found = await findOneItem(String(id2));
+async function reloadPlan(id) {
+  const found = await findOneItem(String(id));
   if (!found) return void 0;
   return resolvePlan(found.item);
 }
@@ -5690,23 +5832,23 @@ async function runOnce(item, startPhase, plan2, spawnOptions) {
 }
 
 // src/commands/backlog/run.ts
-async function run2(id2, spawnOptions) {
-  const prepared = await prepareRun(id2);
+async function run2(id, spawnOptions) {
+  const prepared = await prepareRun(id);
   if (!prepared) return false;
   await ensureStoryBranch(prepared.item);
-  await setStatus(id2, "in-progress");
+  await setStatus(id, "in-progress");
   discardStalePause(prepared.item.id);
-  logProgress(id2, prepared);
-  return runPrepared(id2, prepared, spawnOptions);
+  logProgress(prepared);
+  return runPrepared(id, prepared, spawnOptions);
 }
-function discardStalePause(itemId) {
-  if (!isPausePending(itemId)) return;
-  clearPause(itemId);
+function discardStalePause(itemId2) {
+  if (!isPausePending(itemId2)) return;
+  clearPause(itemId2);
   appendDaemonLog(
-    `backlog run ${itemId}: discarded stale pause file at run start; this run starts auto-advancing (Continue on) regardless of a prior run's pause`
+    `backlog run ${itemId2}: discarded stale pause file at run start; this run starts auto-advancing (Continue on) regardless of a prior run's pause`
   );
 }
-async function runPrepared(id2, prepared, spawnOptions) {
+async function runPrepared(id, prepared, spawnOptions) {
   const { item } = prepared;
   let { plan: plan2, startPhase } = prepared;
   acquireLock(item.id);
@@ -5714,7 +5856,7 @@ async function runPrepared(id2, prepared, spawnOptions) {
     while (true) {
       const review2 = await runOnce(item, startPhase, plan2, spawnOptions);
       spawnOptions = withoutResumeSession(spawnOptions);
-      const outcome = await handleReviewResult(id2, review2);
+      const outcome = await handleReviewResult(id, review2);
       if (outcome.kind === "stop") {
         return outcome.success;
       }
@@ -5725,8 +5867,10 @@ async function runPrepared(id2, prepared, spawnOptions) {
     releaseLock(item.id);
   }
 }
-function logProgress(id2, { plan: plan2, startPhase, item }) {
-  console.log(chalk42.bold(`Running plan for #${id2}: ${item.name}`));
+function logProgress({ plan: plan2, startPhase, item }) {
+  console.log(
+    chalk42.bold(`Running plan for ${formatItemId(item.id)}: ${item.name}`)
+  );
   const totalPhases = plan2.length + 1;
   if (startPhase > 0) {
     const phaseNumber = startPhase + 1;
@@ -5742,7 +5886,7 @@ function logProgress(id2, { plan: plan2, startPhase, item }) {
 
 // src/commands/backlog/next.ts
 function toChoice(item, items2) {
-  const name = `${typeLabel(item.type)} #${item.id}: ${item.name}`;
+  const name = `${typeLabel(item.type)} ${formatItemId(item.id)}: ${item.name}`;
   return isBlocked(item, items2) ? { name, disabled: chalk43.red("[blocked]") } : { name };
 }
 async function selectItem(todo, items2) {
@@ -5754,20 +5898,24 @@ async function selectItem(todo, items2) {
       choices: todo.map((i) => toChoice(i, items2))
     })
   );
-  return selected.match(/#(\d+)/)?.[1] ?? "";
+  return selected.match(/(a\d+):/)?.[1] ?? "";
 }
 function pickResumable(items2) {
   const resumable = findResumable(items2);
   if (!resumable) return void 0;
   console.log(
-    chalk43.bold(`Resuming in-progress item #${resumable.id}: ${resumable.name}`)
+    chalk43.bold(
+      `Resuming in-progress item ${formatItemId(resumable.id)}: ${resumable.name}`
+    )
   );
-  return String(resumable.id);
+  return formatItemId(resumable.id);
 }
 function autoSelect(unblocked) {
   const item = unblocked[0];
-  console.log(chalk43.bold(`Auto-selecting item #${item.id}: ${item.name}`));
-  return String(item.id);
+  console.log(
+    chalk43.bold(`Auto-selecting item ${formatItemId(item.id)}: ${item.name}`)
+  );
+  return formatItemId(item.id);
 }
 async function pickItem(items2, firstPick = false) {
   const resumable = pickResumable(items2);
@@ -5783,11 +5931,11 @@ async function next(options2, startId) {
   let pendingId = startId;
   let firstPick = true;
   while (true) {
-    const id2 = pendingId ?? await pickItem(await loadBacklog(), firstPick);
+    const id = pendingId ?? await pickItem(await loadBacklog(), firstPick);
     pendingId = void 0;
     firstPick = false;
-    if (id2 === void 0) return;
-    const completed = await run2(id2, options2);
+    if (id === void 0) return;
+    const completed = await run2(id, options2);
     if (!completed || options2?.once) return;
   }
 }
@@ -5797,10 +5945,10 @@ import chalk45 from "chalk";
 
 // src/commands/backlog/appendComment.ts
 import { sql as sql4 } from "drizzle-orm";
-async function appendComment(orm, itemId, text9, opts = {}) {
+async function appendComment(orm, itemId2, text9, opts = {}) {
   await orm.insert(comments).values({
-    itemId,
-    idx: sql4`(SELECT COALESCE(MAX(${comments.idx}) + 1, 0) FROM ${comments} WHERE ${comments.itemId} = ${itemId})`,
+    itemId: itemId2,
+    idx: sql4`(SELECT COALESCE(MAX(${comments.idx}) + 1, 0) FROM ${comments} WHERE ${comments.itemId} = ${itemId2})`,
     text: text9,
     phase: opts.phase ?? null,
     timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -5810,12 +5958,12 @@ async function appendComment(orm, itemId, text9, opts = {}) {
 
 // src/commands/backlog/checkSubtasksComplete.ts
 import chalk44 from "chalk";
-function checkSubtasksComplete(id2, item) {
+function checkSubtasksComplete(item) {
   const pending = (item.subtasks ?? []).filter((s) => s.status !== "done");
   if (pending.length === 0) return true;
   console.log(
     chalk44.red(
-      `Cannot complete item #${id2}: ${pending.length} incomplete sub-task(s):`
+      `Cannot complete item ${formatItemId(item.id)}: ${pending.length} incomplete sub-task(s):`
     )
   );
   for (const subtask of pending) {
@@ -5825,48 +5973,51 @@ function checkSubtasksComplete(id2, item) {
 }
 
 // src/commands/backlog/phaseDone.ts
-async function phaseDone(id2, phase, summary) {
+async function phaseDone(id, phase, summary) {
   const phaseNumber = Number.parseInt(phase, 10);
   const phaseIndex = phaseNumber - 1;
-  const itemId = Number.parseInt(id2, 10);
+  const itemId2 = parseItemId(id);
+  const label2 = formatItemId(itemId2);
   const { orm } = await getReady();
-  const item = await loadItem(orm, itemId);
+  const item = await loadItem(orm, itemId2);
   if (item === void 0) {
-    console.log(chalk45.red(`Item #${id2} not found.`));
+    console.log(chalk45.red(`Item ${label2} not found.`));
     return;
   }
   function signal() {
     writeSignal("phase-done", {
-      itemId,
+      itemId: itemId2,
       phaseIndex,
       completedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
   }
   if (item.status === "done") {
     signal();
-    console.log(chalk45.dim(`Item #${id2} already done, skipping phase advance.`));
+    console.log(
+      chalk45.dim(`Item ${label2} already done, skipping phase advance.`)
+    );
     return;
   }
   const reviewPhaseNumber = resolvePlan(item).length + 1;
-  if (phaseNumber === reviewPhaseNumber && !checkSubtasksComplete(id2, item)) {
+  if (phaseNumber === reviewPhaseNumber && !checkSubtasksComplete(item)) {
     process.exitCode = 1;
     return;
   }
   signal();
-  await appendComment(orm, itemId, summary, {
+  await appendComment(orm, itemId2, summary, {
     phase: phaseNumber,
     type: "summary"
   });
-  await setCurrentPhase(id2, phaseNumber + 1);
+  await setCurrentPhase(id, phaseNumber + 1);
   console.log(
-    chalk45.green(`Phase ${phaseNumber} of item #${id2} marked as complete.`)
+    chalk45.green(`Phase ${phaseNumber} of item ${label2} marked as complete.`)
   );
 }
 
 // src/commands/backlog/plan.ts
 import chalk46 from "chalk";
-async function plan(id2) {
-  const found = await findOneItem(id2);
+async function plan(id) {
+  const found = await findOneItem(id);
   if (!found) return;
   const { item } = found;
   if (!item.plan || item.plan.length === 0) {
@@ -5890,11 +6041,11 @@ import chalk53 from "chalk";
 // src/commands/backlog/formatComment.ts
 import chalk47 from "chalk";
 function formatComment(entry) {
-  const id2 = entry.id !== void 0 ? chalk47.dim(`#${entry.id} `) : "";
+  const id = entry.id !== void 0 ? chalk47.dim(`#${entry.id} `) : "";
   const tag = entry.type === "summary" ? chalk47.magenta("[summary]") : chalk47.cyan("[comment]");
   const phase = entry.phase !== void 0 ? chalk47.dim(` (phase ${entry.phase})`) : "";
   const time = chalk47.dim(entry.timestamp);
-  return `${id2}${tag}${phase} ${time}
+  return `${id}${tag}${phase} ${time}
   ${entry.text}`;
 }
 
@@ -5991,11 +6142,11 @@ async function printLinks(orm, item) {
     const typeLabel2 = link3.type === "depends-on" ? chalk49.red("depends-on") : chalk49.blue("relates-to");
     if (target) {
       console.log(
-        `  ${typeLabel2} #${target.id} ${target.name} ${chalk49.dim(`(${target.status})`)}`
+        `  ${typeLabel2} ${formatItemId(target.id)} ${target.name} ${chalk49.dim(`(${target.status})`)}`
       );
     } else {
       console.log(
-        `  ${typeLabel2} #${link3.targetId} ${chalk49.dim("(not found)")}`
+        `  ${typeLabel2} ${formatItemId(link3.targetId)} ${chalk49.dim("(not found)")}`
       );
     }
   }
@@ -6061,7 +6212,7 @@ function printSubtasks(item) {
 
 // src/commands/backlog/show/index.ts
 function printHeader(item) {
-  console.log(chalk53.bold(`#${item.id} ${item.name}`));
+  console.log(chalk53.bold(`${formatItemId(item.id)} ${item.name}`));
   console.log(
     `${chalk53.dim("Type:")} ${item.type}  ${chalk53.dim("Status:")} ${item.status}`
   );
@@ -6087,8 +6238,8 @@ function printComments(item) {
   }
   console.log();
 }
-async function show(id2) {
-  const found = await findOneItem(id2);
+async function show(id) {
+  const found = await findOneItem(id);
   if (!found) process.exit(1);
   const { orm, item } = found;
   printHeader(item);
@@ -6518,18 +6669,18 @@ async function getBacklogSummary(req, res) {
 
 // src/commands/backlog/deleteComment.ts
 import { and as and4, eq as eq13 } from "drizzle-orm";
-async function deleteComment(orm, itemId, commentId) {
-  const [row] = await orm.select({ type: comments.type }).from(comments).where(and4(eq13(comments.id, commentId), eq13(comments.itemId, itemId)));
+async function deleteComment(orm, itemId2, commentId) {
+  const [row] = await orm.select({ type: comments.type }).from(comments).where(and4(eq13(comments.id, commentId), eq13(comments.itemId, itemId2)));
   if (!row) return "not-found";
   if (row.type === "summary") return "is-summary";
-  await orm.delete(comments).where(and4(eq13(comments.id, commentId), eq13(comments.itemId, itemId)));
+  await orm.delete(comments).where(and4(eq13(comments.id, commentId), eq13(comments.itemId, itemId2)));
   return "deleted";
 }
 
 // src/commands/backlog/updateStarred.ts
 import { eq as eq14 } from "drizzle-orm";
-async function updateStarred(orm, id2, starred) {
-  const [row] = await orm.update(items).set({ starred }).where(eq14(items.id, id2)).returning({ name: items.name });
+async function updateStarred(orm, id, starred) {
+  const [row] = await orm.update(items).set({ starred }).where(eq14(items.id, id)).returning({ name: items.name });
   return row?.name;
 }
 
@@ -6581,50 +6732,50 @@ async function listItems(req, res) {
   const items2 = await loadVisibleItems(req);
   respondJson(res, 200, items2.slice().reverse());
 }
-async function findItemOr404(res, id2) {
+async function findItemOr404(res, id) {
   const { orm } = await getReady();
-  const item = await loadItem(orm, id2);
+  const item = await loadItem(orm, id);
   if (!item) {
     respondJson(res, 404, { error: "Not found" });
     return void 0;
   }
   return { orm, item };
 }
-async function getItemById(res, id2) {
-  const result = await findItemOr404(res, id2);
+async function getItemById(res, id) {
+  const result = await findItemOr404(res, id);
   if (result) respondJson(res, 200, withReviewPhase(result.item));
 }
-async function deleteItem2(res, id2) {
-  const result = await findItemOr404(res, id2);
+async function deleteItem2(res, id) {
+  const result = await findItemOr404(res, id);
   if (!result) return;
-  await deleteItem(result.orm, id2);
+  await deleteItem(result.orm, id);
   respondJson(res, 200, result.item);
 }
-async function patchItemStatus(req, res, id2) {
+async function patchItemStatus(req, res, id) {
   const { status: status2 } = await parseStatusBody(req);
-  const result = await findItemOr404(res, id2);
+  const result = await findItemOr404(res, id);
   if (!result) return;
-  await updateStatus(result.orm, id2, status2);
+  await updateStatus(result.orm, id, status2);
   const updated = { ...result.item, status: status2 };
   respondJson(res, 200, updated);
 }
-async function patchItemStar(req, res, id2) {
+async function patchItemStar(req, res, id) {
   const { starred } = await parseStarBody(req);
-  const result = await findItemOr404(res, id2);
+  const result = await findItemOr404(res, id);
   if (!result) return;
-  await updateStarred(result.orm, id2, starred);
+  await updateStarred(result.orm, id, starred);
   const updated = { ...result.item, starred };
   respondJson(res, 200, updated);
 }
 
 // src/commands/backlog/web/deleteItemComment.ts
-async function deleteItemComment(res, itemId, commentId) {
-  const result = await findItemOr404(res, itemId);
+async function deleteItemComment(res, itemId2, commentId) {
+  const result = await findItemOr404(res, itemId2);
   if (!result) return;
-  const outcome = await deleteComment(result.orm, itemId, commentId);
+  const outcome = await deleteComment(result.orm, itemId2, commentId);
   if (outcome === "not-found") {
     respondJson(res, 404, {
-      error: `Comment #${commentId} not found on item #${itemId}.`
+      error: `Comment #${commentId} not found on item ${formatItemId(itemId2)}.`
     });
     return;
   }
@@ -6634,19 +6785,19 @@ async function deleteItemComment(res, itemId, commentId) {
     });
     return;
   }
-  respondJson(res, 200, await loadItem(result.orm, itemId));
+  respondJson(res, 200, await loadItem(result.orm, itemId2));
 }
 
 // src/commands/backlog/updateSubtaskStatus.ts
 import { and as and5, eq as eq15 } from "drizzle-orm";
-async function updateSubtaskStatus(orm, itemId, idx, status2) {
-  const [row] = await orm.update(itemSubtasks).set({ status: status2 }).where(and5(eq15(itemSubtasks.itemId, itemId), eq15(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
+async function updateSubtaskStatus(orm, itemId2, idx, status2) {
+  const [row] = await orm.update(itemSubtasks).set({ status: status2 }).where(and5(eq15(itemSubtasks.itemId, itemId2), eq15(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
   return row?.title;
 }
 
 // src/commands/backlog/web/patchSubtaskStatus.ts
 var validStatuses = ["todo", "in-progress", "done"];
-async function patchSubtaskStatus(req, res, id2, idx) {
+async function patchSubtaskStatus(req, res, id, idx) {
   const { status: status2 } = await parseStatusBody(req);
   if (!validStatuses.includes(status2)) {
     respondJson(res, 400, {
@@ -6654,16 +6805,18 @@ async function patchSubtaskStatus(req, res, id2, idx) {
     });
     return;
   }
-  const result = await findItemOr404(res, id2);
+  const result = await findItemOr404(res, id);
   if (!result) return;
   const { orm, item } = result;
   const subtasks = item.subtasks ?? [];
   if (idx < 0 || idx >= subtasks.length) {
-    respondJson(res, 400, { error: `Item #${id2} has no sub-task ${idx}.` });
+    respondJson(res, 400, {
+      error: `Item ${formatItemId(id)} has no sub-task ${idx}.`
+    });
     return;
   }
-  await updateSubtaskStatus(orm, id2, idx, status2);
-  respondJson(res, 200, await loadItem(orm, id2));
+  await updateSubtaskStatus(orm, id, idx, status2);
+  respondJson(res, 200, await loadItem(orm, id));
 }
 
 // src/commands/backlog/rewindItemToPhase.ts
@@ -6696,9 +6849,9 @@ async function rewindItemToPhase(orm, item, phaseNumber, reason) {
 }
 
 // src/commands/backlog/web/rewindItemPhase.ts
-async function rewindItemPhase(req, res, id2) {
+async function rewindItemPhase(req, res, id) {
   const { phase, reason } = await parseRewindBody(req);
-  const result = await findItemOr404(res, id2);
+  const result = await findItemOr404(res, id);
   if (!result) return;
   const { orm, item } = result;
   const outcome = await rewindItemToPhase(orm, item, phase, reason);
@@ -6706,46 +6859,47 @@ async function rewindItemPhase(req, res, id2) {
     respondJson(res, 400, { error: outcome.error });
     return;
   }
-  respondJson(res, 200, await loadItem(orm, id2));
+  respondJson(res, 200, await loadItem(orm, id));
 }
 
 // src/commands/backlog/web/handleItemRoute.ts
-var id = (match, group = 1) => Number.parseInt(match[group], 10);
+var itemId = (match, group = 1) => parseItemId(match[group]);
+var subId = (match, group) => Number.parseInt(match[group], 10);
 var routes = [
   {
-    pattern: /^\/api\/items\/(\d+)\/rewind$/,
+    pattern: /^\/api\/items\/(a?\d+)\/rewind$/,
     method: "POST",
-    run: (req, res, m) => rewindItemPhase(req, res, id(m))
+    run: (req, res, m) => rewindItemPhase(req, res, itemId(m))
   },
   {
-    pattern: /^\/api\/items\/(\d+)\/star$/,
+    pattern: /^\/api\/items\/(a?\d+)\/star$/,
     method: "POST",
-    run: (req, res, m) => patchItemStar(req, res, id(m))
+    run: (req, res, m) => patchItemStar(req, res, itemId(m))
   },
   {
-    pattern: /^\/api\/items\/(\d+)\/comments\/(\d+)$/,
+    pattern: /^\/api\/items\/(a?\d+)\/comments\/(\d+)$/,
     method: "DELETE",
-    run: (_req, res, m) => deleteItemComment(res, id(m), id(m, 2))
+    run: (_req, res, m) => deleteItemComment(res, itemId(m), subId(m, 2))
   },
   {
-    pattern: /^\/api\/items\/(\d+)\/subtasks\/(\d+)$/,
+    pattern: /^\/api\/items\/(a?\d+)\/subtasks\/(\d+)$/,
     method: "PATCH",
-    run: (req, res, m) => patchSubtaskStatus(req, res, id(m), id(m, 2))
+    run: (req, res, m) => patchSubtaskStatus(req, res, itemId(m), subId(m, 2))
   },
   {
-    pattern: /^\/api\/items\/(\d+)$/,
+    pattern: /^\/api\/items\/(a?\d+)$/,
     method: "GET",
-    run: (_req, res, m) => getItemById(res, id(m))
+    run: (_req, res, m) => getItemById(res, itemId(m))
   },
   {
-    pattern: /^\/api\/items\/(\d+)$/,
+    pattern: /^\/api\/items\/(a?\d+)$/,
     method: "PATCH",
-    run: (req, res, m) => patchItemStatus(req, res, id(m))
+    run: (req, res, m) => patchItemStatus(req, res, itemId(m))
   },
   {
-    pattern: /^\/api\/items\/(\d+)$/,
+    pattern: /^\/api\/items\/(a?\d+)$/,
     method: "DELETE",
-    run: (_req, res, m) => deleteItem2(res, id(m))
+    run: (_req, res, m) => deleteItem2(res, itemId(m))
   }
 ];
 async function handleItemRoute(req, res, pathname) {
@@ -7816,9 +7970,23 @@ async function web2(options2) {
   });
 }
 
+// src/commands/backlog/backlogConfigHelp.ts
+var backlogConfigHelp = [
+  {
+    key: "database.url",
+    setter: "assist config set database.url postgresql://...",
+    note: "Postgres connection string for backlog storage (or ASSIST_DATABASE_URL)"
+  },
+  {
+    key: "subtasks",
+    setter: 'assist config set subtasks.0.title "Review"',
+    note: "default sub-tasks seeded onto every new backlog item"
+  }
+];
+
 // src/commands/backlog/addActivity.ts
 import chalk60 from "chalk";
-async function addActivity(id2, kind, ref, options2) {
+async function addActivity(id, kind, ref, options2) {
   const parsedKind = gitRefKindSchema.safeParse(kind);
   if (!parsedKind.success) {
     console.log(
@@ -7829,7 +7997,7 @@ async function addActivity(id2, kind, ref, options2) {
     process.exitCode = 1;
     return;
   }
-  const found = await findOneItem(id2);
+  const found = await findOneItem(id);
   if (!found) {
     process.exitCode = 1;
     return;
@@ -7844,7 +8012,9 @@ async function addActivity(id2, kind, ref, options2) {
     state: options2.state
   });
   console.log(
-    chalk60.green(`Attached ${parsedKind.data} "${ref}" to item #${id2}.`)
+    chalk60.green(
+      `Attached ${parsedKind.data} "${ref}" to item ${formatItemId(item.id)}.`
+    )
   );
 }
 
@@ -7890,17 +8060,19 @@ function fetchIssue(issueKey, fields) {
 
 // src/commands/backlog/associate-jira/index.ts
 var JIRA_KEY_PATTERN = /^[A-Z]+-\d+$/;
-async function associateJira(id2, key, options2) {
-  const found = await findOneItem(id2);
+async function associateJira(id, key, options2) {
+  const found = await findOneItem(id);
   if (!found) {
     process.exitCode = 1;
     return;
   }
   const { orm } = found;
-  const itemId = found.item.id;
+  const itemId2 = found.item.id;
   if (options2.clear) {
-    await orm.update(items).set({ jiraKey: null }).where(eq16(items.id, itemId));
-    console.log(chalk62.green(`Cleared Jira association on item #${itemId}.`));
+    await orm.update(items).set({ jiraKey: null }).where(eq16(items.id, itemId2));
+    console.log(
+      chalk62.green(`Cleared Jira association on item ${formatItemId(itemId2)}.`)
+    );
     return;
   }
   if (!key) {
@@ -7918,9 +8090,9 @@ async function associateJira(id2, key, options2) {
   const parsed = fetchIssue(key, "summary");
   const fields = parsed?.fields;
   const summary = fields?.summary;
-  await orm.update(items).set({ jiraKey: key }).where(eq16(items.id, itemId));
+  await orm.update(items).set({ jiraKey: key }).where(eq16(items.id, itemId2));
   console.log(
-    chalk62.green(`Associated ${key} with item #${itemId}.`),
+    chalk62.green(`Associated ${key} with item ${formatItemId(itemId2)}.`),
     summary ? chalk62.dim(`(${summary})`) : ""
   );
 }
@@ -7932,26 +8104,30 @@ function registerAssociateJiraCommand(cmd) {
 
 // src/commands/backlog/comment/index.ts
 import chalk63 from "chalk";
-async function comment(id2, text9) {
-  const found = await findOneItem(id2);
+async function comment(id, text9) {
+  const found = await findOneItem(id);
   if (!found) process.exit(1);
   await appendComment(found.orm, found.item.id, text9);
-  console.log(chalk63.green(`Comment added to item #${id2}.`));
+  console.log(
+    chalk63.green(`Comment added to item ${formatItemId(found.item.id)}.`)
+  );
 }
 
 // src/commands/backlog/comments/index.ts
 import chalk64 from "chalk";
-async function comments2(id2) {
-  const found = await findOneItem(id2);
+async function comments2(id) {
+  const found = await findOneItem(id);
   if (!found) process.exit(1);
   const { item } = found;
   const entries = item.comments ?? [];
   if (entries.length === 0) {
-    console.log(chalk64.dim(`No comments on item #${id2}.`));
+    console.log(chalk64.dim(`No comments on item ${formatItemId(item.id)}.`));
     return;
   }
-  console.log(chalk64.bold(`Comments for #${id2}: ${item.name}
-`));
+  console.log(
+    chalk64.bold(`Comments for ${formatItemId(item.id)}: ${item.name}
+`)
+  );
   for (const entry of entries) {
     console.log(`${formatComment(entry)}
 `);
@@ -7960,22 +8136,29 @@ async function comments2(id2) {
 
 // src/commands/backlog/delete-comment/index.ts
 import chalk65 from "chalk";
-async function deleteCommentCmd(id2, commentId) {
-  const found = await findOneItem(id2);
+async function deleteCommentCmd(id, commentId) {
+  const found = await findOneItem(id);
   if (!found) process.exit(1);
+  const itemId2 = found.item.id;
   const outcome = await deleteComment(
     found.orm,
-    found.item.id,
+    itemId2,
     Number.parseInt(commentId, 10)
   );
   switch (outcome) {
     case "deleted":
       console.log(
-        chalk65.green(`Comment #${commentId} deleted from item #${id2}.`)
+        chalk65.green(
+          `Comment #${commentId} deleted from item ${formatItemId(itemId2)}.`
+        )
       );
       break;
     case "not-found":
-      console.log(chalk65.red(`Comment #${commentId} not found on item #${id2}.`));
+      console.log(
+        chalk65.red(
+          `Comment #${commentId} not found on item ${formatItemId(itemId2)}.`
+        )
+      );
       process.exit(1);
       break;
     case "is-summary":
@@ -8060,7 +8243,7 @@ function parseDump(dump) {
 function validateDump({ header, sections }) {
   const tables = header.tables ?? [];
   const missing = tables.find(({ name }) => !sections.has(name))?.name;
-  const checks = [
+  const checks2 = [
     [
       header.format === DUMP_FORMAT,
       `Unrecognised dump format "${header.format}" (expected "${DUMP_FORMAT}").`
@@ -8072,7 +8255,7 @@ function validateDump({ header, sections }) {
     [tables.length > 0, "Dump header lists no tables; cannot restore."],
     [!missing, `Invalid dump: missing data section for "${missing}".`]
   ];
-  const failure = checks.find(([ok]) => !ok);
+  const failure = checks2.find(([ok]) => !ok);
   if (failure) throw new Error(failure[1]);
 }
 
@@ -8220,37 +8403,37 @@ import { count as count2, eq as eq18 } from "drizzle-orm";
 
 // src/commands/backlog/shiftPhasesUp.ts
 import { and as and6, desc as desc3, eq as eq17, gte } from "drizzle-orm";
-async function shiftPhasesUp(db, itemId, fromIdx) {
-  const toShift = await db.select({ idx: planPhases.idx }).from(planPhases).where(and6(eq17(planPhases.itemId, itemId), gte(planPhases.idx, fromIdx))).orderBy(desc3(planPhases.idx));
+async function shiftPhasesUp(db, itemId2, fromIdx) {
+  const toShift = await db.select({ idx: planPhases.idx }).from(planPhases).where(and6(eq17(planPhases.itemId, itemId2), gte(planPhases.idx, fromIdx))).orderBy(desc3(planPhases.idx));
   for (const p of toShift) {
-    await db.update(planTasks).set({ phaseIdx: p.idx + 1 }).where(and6(eq17(planTasks.itemId, itemId), eq17(planTasks.phaseIdx, p.idx)));
-    await db.update(planPhases).set({ idx: p.idx + 1 }).where(and6(eq17(planPhases.itemId, itemId), eq17(planPhases.idx, p.idx)));
+    await db.update(planTasks).set({ phaseIdx: p.idx + 1 }).where(and6(eq17(planTasks.itemId, itemId2), eq17(planTasks.phaseIdx, p.idx)));
+    await db.update(planPhases).set({ idx: p.idx + 1 }).where(and6(eq17(planPhases.itemId, itemId2), eq17(planPhases.idx, p.idx)));
   }
 }
 
 // src/commands/backlog/insertPhaseAt.ts
-async function insertPhaseAt(orm, itemId, phaseIdx, name, tasks, manualChecks, currentPhase) {
+async function insertPhaseAt(orm, itemId2, phaseIdx, name, tasks, manualChecks, currentPhase) {
   await orm.transaction(async (tx) => {
-    const [row] = await tx.select({ cnt: count2() }).from(planPhases).where(eq18(planPhases.itemId, itemId));
+    const [row] = await tx.select({ cnt: count2() }).from(planPhases).where(eq18(planPhases.itemId, itemId2));
     const phaseCount = row?.cnt ?? 0;
-    await shiftPhasesUp(tx, itemId, phaseIdx);
-    await tx.insert(planPhases).values({ itemId, idx: phaseIdx, name, manualChecks });
+    await shiftPhasesUp(tx, itemId2, phaseIdx);
+    await tx.insert(planPhases).values({ itemId: itemId2, idx: phaseIdx, name, manualChecks });
     if (tasks.length) {
-      await tx.insert(planTasks).values(tasks.map((task, i) => ({ itemId, phaseIdx, idx: i, task })));
+      await tx.insert(planTasks).values(tasks.map((task, i) => ({ itemId: itemId2, phaseIdx, idx: i, task })));
     }
     if (currentPhase !== void 0 && currentPhase - 1 >= phaseIdx) {
       const atReviewSlot = currentPhase - 1 >= phaseCount;
-      await tx.update(items).set({ currentPhase: atReviewSlot ? phaseIdx + 1 : currentPhase + 1 }).where(eq18(items.id, itemId));
+      await tx.update(items).set({ currentPhase: atReviewSlot ? phaseIdx + 1 : currentPhase + 1 }).where(eq18(items.id, itemId2));
     }
   });
 }
 
 // src/commands/backlog/insertSubtask.ts
 import { sql as sql6 } from "drizzle-orm";
-async function insertSubtask(orm, itemId, title, description) {
+async function insertSubtask(orm, itemId2, title, description) {
   await orm.insert(itemSubtasks).values({
-    itemId,
-    idx: sql6`(SELECT COALESCE(MAX(${itemSubtasks.idx}) + 1, 0) FROM ${itemSubtasks} WHERE ${itemSubtasks.itemId} = ${itemId})`,
+    itemId: itemId2,
+    idx: sql6`(SELECT COALESCE(MAX(${itemSubtasks.idx}) + 1, 0) FROM ${itemSubtasks} WHERE ${itemSubtasks.itemId} = ${itemId2})`,
     title,
     description: description ?? null,
     status: "todo"
@@ -8348,7 +8531,7 @@ async function add(options2) {
   const description = options2.desc?.replaceAll(String.raw`\n`, "\n") ?? await promptDescription();
   const acceptanceCriteria2 = options2.ac ?? await promptAcceptanceCriteria();
   const orm = await getDb();
-  const id2 = await insertItem(
+  const id = await insertItem(
     orm,
     {
       type,
@@ -8361,12 +8544,12 @@ async function add(options2) {
     getOrigin()
   );
   if (type === "bug") {
-    await insertPhaseAt(orm, id2, 0, "Fix", ["Fix the bug"], null, void 0);
+    await insertPhaseAt(orm, id, 0, "Fix", ["Fix the bug"], null, void 0);
   }
   for (const subtask of loadConfig().subtasks ?? []) {
-    await insertSubtask(orm, id2, subtask.title, subtask.description);
+    await insertSubtask(orm, id, subtask.title, subtask.description);
   }
-  console.log(chalk69.green(`Added item #${id2}: ${name}`));
+  console.log(chalk69.green(`Added item ${formatItemId(id)}: ${name}`));
 }
 
 // src/commands/backlog/addPhase.ts
@@ -8375,8 +8558,8 @@ import chalk71 from "chalk";
 // src/commands/backlog/resolveInsertPosition.ts
 import chalk70 from "chalk";
 import { count as count3, eq as eq19 } from "drizzle-orm";
-async function resolveInsertPosition(orm, itemId, position) {
-  const [row] = await orm.select({ cnt: count3() }).from(planPhases).where(eq19(planPhases.itemId, itemId));
+async function resolveInsertPosition(orm, itemId2, position) {
+  const [row] = await orm.select({ cnt: count3() }).from(planPhases).where(eq19(planPhases.itemId, itemId2));
   const phaseCount = row?.cnt ?? 0;
   if (position === void 0) return phaseCount;
   const pos = Number.parseInt(position, 10);
@@ -8398,9 +8581,9 @@ function serializeManualChecks(manualCheck) {
 }
 
 // src/commands/backlog/addPhase.ts
-async function addPhase(id2, name, options2) {
+async function addPhase(id, name, options2) {
   if (!ensureRemoteOrigin()) return;
-  const found = await findOneItem(id2);
+  const found = await findOneItem(id);
   if (!found) return;
   const tasks = options2.task ?? [];
   if (tasks.length === 0) {
@@ -8409,12 +8592,12 @@ async function addPhase(id2, name, options2) {
     return;
   }
   const { orm } = found;
-  const itemId = found.item.id;
-  const phaseIdx = await resolveInsertPosition(orm, itemId, options2.position);
+  const itemId2 = found.item.id;
+  const phaseIdx = await resolveInsertPosition(orm, itemId2, options2.position);
   if (phaseIdx === void 0) return;
   await insertPhaseAt(
     orm,
-    itemId,
+    itemId2,
     phaseIdx,
     name,
     tasks,
@@ -8424,7 +8607,7 @@ async function addPhase(id2, name, options2) {
   const verb = options2.position !== void 0 ? "Inserted" : "Added";
   console.log(
     chalk71.green(
-      `${verb} phase ${phaseIdx + 1} "${name}" to item #${itemId} with ${tasks.length} task(s).`
+      `${verb} phase ${phaseIdx + 1} "${name}" to item ${formatItemId(itemId2)} with ${tasks.length} task(s).`
     )
   );
 }
@@ -8437,6 +8620,15 @@ function filterItems(items2, options2) {
     return items2.filter((i) => i.status !== "done" && i.status !== "wontdo");
   return items2;
 }
+function repoPrefixer(items2, allRepos) {
+  if (!allRepos) return () => "";
+  const labels = originDisplayLabels(
+    items2.flatMap((i) => i.origin ? [i.origin] : [])
+  );
+  const repoNameOf = (item) => item.origin ? labels.get(item.origin) ?? "" : "";
+  const width = Math.max(0, ...items2.map((i) => repoNameOf(i).length));
+  return (item) => `${chalk72.dim(repoNameOf(item).padEnd(width))} `;
+}
 async function list2(options2) {
   const allItems = await loadBacklog(options2.allRepos);
   const items2 = filterItems(allItems, options2);
@@ -8444,15 +8636,10 @@ async function list2(options2) {
     console.log(chalk72.dim("Backlog is empty."));
     return;
   }
-  const labels = originDisplayLabels(
-    items2.flatMap((i) => i.origin ? [i.origin] : [])
-  );
-  const repoNameOf = (item) => item.origin ? labels.get(item.origin) ?? "" : "";
-  const prefixWidth = options2.allRepos ? Math.max(0, ...items2.map((i) => repoNameOf(i).length)) : 0;
+  const prefixOf = repoPrefixer(items2, !!options2.allRepos);
   for (const item of items2) {
-    const repoPrefix = options2.allRepos ? `${chalk72.dim(repoNameOf(item).padEnd(prefixWidth))} ` : "";
     console.log(
-      `${repoPrefix}${statusIcon(item.status)} ${typeLabel(item.type)} ${chalk72.dim(`#${item.id}`)} ${starMarker(item)}${item.name}${phaseLabel(item)}${dependencyLabel(item, allItems)}`
+      `${prefixOf(item)}${statusIcon(item.status)} ${typeLabel(item.type)} ${chalk72.dim(formatItemId(item.id))} ${starMarker(item)}${item.name}${phaseLabel(item)}${dependencyLabel(item, allItems)}`
     );
     if (options2.verbose) {
       printVerboseDetails(item);
@@ -8504,10 +8691,10 @@ import { eq as eq20 } from "drizzle-orm";
 async function loadDependencyGraph(orm) {
   const rows = await orm.select({ itemId: links.itemId, targetId: links.targetId }).from(links).where(eq20(links.type, "depends-on"));
   const graph = /* @__PURE__ */ new Map();
-  for (const { itemId, targetId } of rows) {
-    const bucket = graph.get(itemId);
+  for (const { itemId: itemId2, targetId } of rows) {
+    const bucket = graph.get(itemId2);
     if (bucket) bucket.push(targetId);
-    else graph.set(itemId, [targetId]);
+    else graph.set(itemId2, [targetId]);
   }
   return graph;
 }
@@ -8520,7 +8707,9 @@ function validateLinkTarget(fromItem, fromNum, toNum, linkType) {
   );
   if (duplicate) {
     console.log(
-      chalk73.yellow(`Link already exists: #${fromNum} ${linkType} #${toNum}`)
+      chalk73.yellow(
+        `Link already exists: ${formatItemId(fromNum)} ${linkType} ${formatItemId(toNum)}`
+      )
     );
     return false;
   }
@@ -8541,50 +8730,62 @@ async function createsCycle(orm, linkType, fromNum, toNum) {
   if (linkType !== "depends-on") return false;
   const graph = await loadDependencyGraph(orm);
   if (!hasCycle(graph, fromNum, toNum)) return false;
-  fail2(`Cannot add dependency: #${fromNum} \u2192 #${toNum} would create a cycle.`);
+  fail2(
+    `Cannot add dependency: ${formatItemId(fromNum)} \u2192 ${formatItemId(toNum)} would create a cycle.`
+  );
   return true;
 }
 async function link(fromId, toId, opts) {
   const linkType = parseLinkType(opts.type);
   if (!linkType) return;
-  const fromNum = Number.parseInt(fromId, 10);
-  const toNum = Number.parseInt(toId, 10);
+  const fromNum = parseItemId(fromId);
+  const toNum = parseItemId(toId);
   if (fromNum === toNum) return void fail2("Cannot link an item to itself.");
+  const from = formatItemId(fromNum);
+  const to = formatItemId(toNum);
   const { orm } = await getReady();
   const fromItem = await loadItem(orm, fromNum);
-  if (!fromItem) return void fail2(`Item #${fromNum} not found.`);
+  if (!fromItem) return void fail2(`Item ${from} not found.`);
   const toItem = await loadItem(orm, toNum);
-  if (!toItem) return void fail2(`Item #${toNum} not found.`);
+  if (!toItem) return void fail2(`Item ${to} not found.`);
   if (!validateLinkTarget(fromItem, fromNum, toNum, linkType)) return;
   if (await createsCycle(orm, linkType, fromNum, toNum)) return;
   await orm.insert(links).values({ itemId: fromNum, type: linkType, targetId: toNum });
-  console.log(
-    chalk74.green(`Linked #${fromNum} ${linkType} #${toNum} (${toItem.name})`)
-  );
+  console.log(chalk74.green(`Linked ${from} ${linkType} ${to} (${toItem.name})`));
 }
 
 // src/commands/backlog/unlink.ts
 import chalk75 from "chalk";
 import { and as and7, eq as eq21 } from "drizzle-orm";
 async function unlink(fromId, toId) {
-  const fromNum = Number.parseInt(fromId, 10);
-  const toNum = Number.parseInt(toId, 10);
+  const fromNum = parseItemId(fromId);
+  const toNum = parseItemId(toId);
   const { orm } = await getReady();
   const fromItem = await loadItem(orm, fromNum);
   if (!fromItem) {
-    console.log(chalk75.red(`Item #${fromId} not found.`));
+    console.log(chalk75.red(`Item ${formatItemId(fromNum)} not found.`));
     return;
   }
   if (!fromItem.links || fromItem.links.length === 0) {
-    console.log(chalk75.yellow(`No links found on item #${fromId}.`));
+    console.log(
+      chalk75.yellow(`No links found on item ${formatItemId(fromNum)}.`)
+    );
     return;
   }
   if (!fromItem.links.some((l) => l.targetId === toNum)) {
-    console.log(chalk75.yellow(`No link from #${fromId} to #${toId} found.`));
+    console.log(
+      chalk75.yellow(
+        `No link from ${formatItemId(fromNum)} to ${formatItemId(toNum)} found.`
+      )
+    );
     return;
   }
   await orm.delete(links).where(and7(eq21(links.itemId, fromNum), eq21(links.targetId, toNum)));
-  console.log(chalk75.green(`Removed link from #${fromId} to #${toId}.`));
+  console.log(
+    chalk75.green(
+      `Removed link from ${formatItemId(fromNum)} to ${formatItemId(toNum)}.`
+    )
+  );
 }
 
 // src/commands/backlog/registerLinkCommands.ts
@@ -8679,7 +8880,7 @@ function registerMoveRepoCommand(cmd) {
 // src/commands/backlog/registerNextCommand.ts
 function registerNextCommand(cmd) {
   cmd.command("next").argument("[id]", "Backlog item ID to run first").description("Pick and run the next backlog item, or open /draft if none").option("-w, --write", "Run Claude with auto permission mode (default)").option("--no-write", "Run Claude without auto permission mode").option("--once", "Exit after the first completed item run").action(
-    (id2, opts) => next({ allowEdits: opts.write !== false, once: opts.once }, id2)
+    (id, opts) => next({ allowEdits: opts.write !== false, once: opts.once }, id)
   );
 }
 
@@ -8700,9 +8901,14 @@ import { randomUUID as randomUUID2 } from "crypto";
 import chalk79 from "chalk";
 
 // src/commands/backlog/surfaceCreatedItem.ts
-async function surfaceCreatedItem(slashCommand, id2) {
-  const numericId = Number.parseInt(id2, 10);
-  if (Number.isNaN(numericId)) return;
+async function surfaceCreatedItem(slashCommand, id) {
+  let numericId;
+  try {
+    numericId = parseItemId(id);
+  } catch (error) {
+    if (error instanceof InvalidItemIdError) return;
+    throw error;
+  }
   const { orm } = await getReady();
   const item = await loadItem(orm, numericId);
   if (!item) return;
@@ -8716,33 +8922,34 @@ async function surfaceCreatedItem(slashCommand, id2) {
 
 // src/commands/backlog/tryRunById.ts
 import chalk78 from "chalk";
-async function tryRunById(id2, options2) {
-  const numericId = Number.parseInt(id2, 10);
+async function tryRunById(id, options2) {
+  const numericId = parseItemId(id);
+  const label2 = formatItemId(numericId);
   const { orm } = await getReady();
-  const item = Number.isNaN(numericId) ? void 0 : await loadItem(orm, numericId);
+  const item = await loadItem(orm, numericId);
   if (!item) {
-    console.log(chalk78.red(`Item #${id2} not found.`));
+    console.log(chalk78.red(`Item ${label2} not found.`));
     return false;
   }
   if (item.status === "done") {
-    console.log(chalk78.red(`Item #${id2} is already done.`));
+    console.log(chalk78.red(`Item ${label2} is already done.`));
     return false;
   }
   if (item.status === "wontdo") {
-    console.log(chalk78.red(`Item #${id2} is marked won't do.`));
+    console.log(chalk78.red(`Item ${label2} is marked won't do.`));
     return false;
   }
   const hasDeps = (item.links ?? []).some((l) => l.type === "depends-on");
   if (hasDeps && isBlocked(item, await loadItemSummaries(orm, getOrigin()))) {
     console.log(
-      chalk78.red(`Item #${id2} is blocked by unresolved dependencies.`)
+      chalk78.red(`Item ${label2} is blocked by unresolved dependencies.`)
     );
     return false;
   }
   console.log(chalk78.bold(`
-Running backlog item #${id2}...
+Running backlog item ${label2}...
 `));
-  await run2(id2, options2);
+  await run2(id, options2);
   return true;
 }
 
@@ -8803,8 +9010,10 @@ async function pickItemForRefine() {
   }
   if (active.length === 1) {
     const item = active[0];
-    console.log(chalk80.bold(`Auto-selecting item #${item.id}: ${item.name}`));
-    return String(item.id);
+    console.log(
+      chalk80.bold(`Auto-selecting item ${formatItemId(item.id)}: ${item.name}`)
+    );
+    return formatItemId(item.id);
   }
   const { selected } = await exitOnCancel(
     enquirer7.prompt({
@@ -8812,18 +9021,18 @@ async function pickItemForRefine() {
       name: "selected",
       message: "Choose a backlog item to refine:",
       choices: active.map((item) => ({
-        name: `${typeLabel(item.type)} #${item.id}: ${item.name}`
+        name: `${typeLabel(item.type)} ${formatItemId(item.id)}: ${item.name}`
       }))
     })
   );
-  return selected.match(/#(\d+)/)?.[1] ?? "";
+  return selected.match(/(a\d+):/)?.[1] ?? "";
 }
-async function refine(id2, options2) {
-  const itemId = id2 ?? await pickItemForRefine();
-  if (!itemId) return;
-  const numericId = Number.parseInt(itemId, 10);
-  const item = Number.isNaN(numericId) ? void 0 : await loadItem((await getReady()).orm, numericId);
-  await launchMode(`refine ${itemId}`, {
+async function refine(id, options2) {
+  const itemId2 = id ?? await pickItemForRefine();
+  if (!itemId2) return;
+  const numericId = parseItemId(itemId2);
+  const item = await loadItem((await getReady()).orm, numericId);
+  await launchMode(`refine ${itemId2}`, {
     ...options2,
     itemId: item ? numericId : void 0,
     itemName: item?.name
@@ -8833,20 +9042,17 @@ async function refine(id2, options2) {
 // src/commands/backlog/registerRefineCommand.ts
 function registerRefineCommand(cmd) {
   cmd.command("refine").argument("[id]", "Backlog item ID").description("Alias for refine").option("--once", "Exit when the initial task completes").action(
-    (id2, opts) => refine(id2, { once: opts.once })
+    (id, opts) => refine(id, { once: opts.once })
   );
 }
 
 // src/commands/backlog/rewindPhase.ts
 import chalk81 from "chalk";
-async function rewindPhase(id2, phase, opts) {
+async function rewindPhase(id, phase, opts) {
   const phaseNumber = Number.parseInt(phase, 10);
-  const { orm } = await getReady();
-  const item = await loadItem(orm, Number.parseInt(id2, 10));
-  if (!item) {
-    console.log(chalk81.red(`Item #${id2} not found.`));
-    return;
-  }
+  const found = await findOneItem(id);
+  if (!found) return;
+  const { orm, item } = found;
   const result = await rewindItemToPhase(orm, item, phaseNumber, opts.reason);
   if (!result.ok) {
     console.log(chalk81.red(result.error));
@@ -8855,7 +9061,7 @@ async function rewindPhase(id2, phase, opts) {
   }
   console.log(
     chalk81.green(
-      `Rewound item #${id2} to phase ${phaseNumber} (${result.phaseName}).`
+      `Rewound item ${formatItemId(item.id)} to phase ${phaseNumber} (${result.phaseName}).`
     )
   );
 }
@@ -8871,9 +9077,9 @@ function registerRunCommand(cmd) {
     "--resume-session <id>",
     "Resume an interrupted Claude session for the current phase (used by the sessions daemon on restart)"
   ).action(
-    async (id2, opts) => {
+    async (id, opts) => {
       if (!opts.resumeSession) pullIfConfigured();
-      await run2(id2, {
+      await run2(id, {
         allowEdits: opts.write !== false,
         resumeSessionId: opts.resumeSession
       });
@@ -8897,7 +9103,7 @@ async function search(query) {
   );
   for (const item of items2) {
     console.log(
-      `${statusIcon(item.status)} ${typeLabel(item.type)} ${chalk82.dim(`#${item.id}`)} ${item.name}`
+      `${statusIcon(item.status)} ${typeLabel(item.type)} ${chalk82.dim(formatItemId(item.id))} ${item.name}`
     );
   }
 }
@@ -8909,20 +9115,22 @@ function registerSearchCommand(cmd) {
 
 // src/commands/backlog/delete/index.ts
 import chalk83 from "chalk";
-async function del(id2) {
-  const name = await removeItem(id2);
+async function del(id) {
+  const name = await removeItem(id);
   if (name) {
-    console.log(chalk83.green(`Deleted item #${id2}: ${name}`));
+    console.log(
+      chalk83.green(`Deleted item ${formatItemId(parseItemId(id))}: ${name}`)
+    );
   }
 }
 
 // src/commands/backlog/done/index.ts
 import chalk84 from "chalk";
-async function done(id2, summary) {
-  const found = await findOneItem(id2);
+async function done(id, summary) {
+  const found = await findOneItem(id);
   if (!found) return;
   const { orm, item } = found;
-  if (!checkSubtasksComplete(id2, item)) {
+  if (!checkSubtasksComplete(item)) {
     process.exitCode = 1;
     return;
   }
@@ -8932,7 +9140,7 @@ async function done(id2, summary) {
     if (pending.length > 0) {
       console.log(
         chalk84.red(
-          `Cannot complete item #${id2}: ${pending.length} pending phase(s):`
+          `Cannot complete item ${formatItemId(item.id)}: ${pending.length} pending phase(s):`
         )
       );
       for (const phase of pending) {
@@ -8947,7 +9155,9 @@ async function done(id2, summary) {
     const phase = item.currentPhase ?? 1;
     await appendComment(orm, item.id, summary, { phase, type: "summary" });
   }
-  console.log(chalk84.green(`Completed item #${id2}: ${item.name}`));
+  console.log(
+    chalk84.green(`Completed item ${formatItemId(item.id)}: ${item.name}`)
+  );
 }
 
 // src/commands/backlog/set-status/index.ts
@@ -8958,7 +9168,7 @@ var allowedStatuses = [
   "done",
   "wontdo"
 ];
-async function setStatusCommand(id2, status2) {
+async function setStatusCommand(id, status2) {
   if (!allowedStatuses.includes(status2)) {
     console.log(
       chalk85.red(
@@ -8968,9 +9178,13 @@ async function setStatusCommand(id2, status2) {
     process.exitCode = 1;
     return;
   }
-  const name = await setStatus(id2, status2);
+  const name = await setStatus(id, status2);
   if (name) {
-    console.log(chalk85.green(`Set item #${id2} to ${status2}: ${name}`));
+    console.log(
+      chalk85.green(
+        `Set item ${formatItemId(parseItemId(id))} to ${status2}: ${name}`
+      )
+    );
   }
 }
 
@@ -8979,27 +9193,33 @@ import chalk87 from "chalk";
 
 // src/commands/backlog/setStarred.ts
 import chalk86 from "chalk";
-async function setStarred(id2, starred) {
+async function setStarred(id, starred) {
   const { orm } = await getReady();
-  const name = await updateStarred(orm, Number.parseInt(id2, 10), starred);
-  if (name === void 0) console.log(chalk86.red(`Item #${id2} not found.`));
+  const numId = parseItemId(id);
+  const name = await updateStarred(orm, numId, starred);
+  if (name === void 0)
+    console.log(chalk86.red(`Item ${formatItemId(numId)} not found.`));
   return name;
 }
 
 // src/commands/backlog/star/index.ts
-async function star(id2) {
-  const name = await setStarred(id2, true);
+async function star(id) {
+  const name = await setStarred(id, true);
   if (name) {
-    console.log(chalk87.green(`Starred item #${id2}: ${name}`));
+    console.log(
+      chalk87.green(`Starred item ${formatItemId(parseItemId(id))}: ${name}`)
+    );
   }
 }
 
 // src/commands/backlog/start/index.ts
 import chalk88 from "chalk";
-async function start(id2) {
-  const name = await setStatus(id2, "in-progress");
+async function start(id) {
+  const name = await setStatus(id, "in-progress");
   if (name) {
-    console.log(chalk88.green(`Started item #${id2}: ${name}`));
+    console.log(
+      chalk88.green(`Started item ${formatItemId(parseItemId(id))}: ${name}`)
+    );
   }
 }
 
@@ -9014,23 +9234,27 @@ async function stop() {
     return;
   }
   for (const item of stopped) {
-    console.log(chalk89.yellow(`Stopped item #${item.id}: ${item.name}`));
+    console.log(
+      chalk89.yellow(`Stopped item ${formatItemId(item.id)}: ${item.name}`)
+    );
   }
 }
 
 // src/commands/backlog/unstar/index.ts
 import chalk90 from "chalk";
-async function unstar(id2) {
-  const name = await setStarred(id2, false);
+async function unstar(id) {
+  const name = await setStarred(id, false);
   if (name) {
-    console.log(chalk90.green(`Unstarred item #${id2}: ${name}`));
+    console.log(
+      chalk90.green(`Unstarred item ${formatItemId(parseItemId(id))}: ${name}`)
+    );
   }
 }
 
 // src/commands/backlog/wontdo/index.ts
 import chalk91 from "chalk";
-async function wontdo(id2, reason) {
-  const found = await findOneItem(id2);
+async function wontdo(id, reason) {
+  const found = await findOneItem(id);
   if (!found) return;
   const { orm, item } = found;
   await updateStatus(orm, item.id, "wontdo");
@@ -9038,7 +9262,9 @@ async function wontdo(id2, reason) {
     const phase = item.currentPhase ?? 1;
     await appendComment(orm, item.id, reason, { phase, type: "summary" });
   }
-  console.log(chalk91.red(`Won't do item #${id2}: ${item.name}`));
+  console.log(
+    chalk91.red(`Won't do item ${formatItemId(item.id)}: ${item.name}`)
+  );
 }
 
 // src/commands/backlog/registerStatusCommands.ts
@@ -9057,7 +9283,7 @@ function registerStatusCommands(cmd) {
 
 // src/commands/backlog/addSubtask.ts
 import chalk92 from "chalk";
-async function addSubtask(id2, options2) {
+async function addSubtask(id, options2) {
   const title = options2.title?.trim();
   if (!title) {
     console.log(chalk92.red("A sub-task title is required (--title)."));
@@ -9073,7 +9299,7 @@ async function addSubtask(id2, options2) {
     process.exitCode = 1;
     return;
   }
-  const found = await findOneItem(id2);
+  const found = await findOneItem(id);
   if (!found) {
     process.exitCode = 1;
     return;
@@ -9081,7 +9307,9 @@ async function addSubtask(id2, options2) {
   const { orm, item } = found;
   const description = options2.desc?.replaceAll(String.raw`\n`, "\n");
   await insertSubtask(orm, item.id, title, description);
-  console.log(chalk92.green(`Added sub-task to item #${id2}: ${title}`));
+  console.log(
+    chalk92.green(`Added sub-task to item ${formatItemId(item.id)}: ${title}`)
+  );
 }
 
 // src/commands/backlog/editSubtask.ts
@@ -9089,13 +9317,13 @@ import chalk94 from "chalk";
 
 // src/commands/backlog/resolveSubtaskIndex.ts
 import chalk93 from "chalk";
-function resolveSubtaskIndex(id2, index3, item) {
+function resolveSubtaskIndex(index3, item) {
   const position = Number.parseInt(index3, 10);
   const subtasks = item.subtasks ?? [];
   if (Number.isNaN(position) || position < 1 || position > subtasks.length) {
     console.log(
       chalk93.red(
-        `Item #${id2} has no sub-task ${index3}${subtasks.length > 0 ? ` (1-${subtasks.length})` : ""}.`
+        `Item ${formatItemId(item.id)} has no sub-task ${index3}${subtasks.length > 0 ? ` (1-${subtasks.length})` : ""}.`
       )
     );
     process.exitCode = 1;
@@ -9105,25 +9333,25 @@ function resolveSubtaskIndex(id2, index3, item) {
 }
 
 // src/commands/backlog/findSubtask.ts
-async function findSubtask(id2, index3) {
-  const found = await findOneItem(id2);
+async function findSubtask(id, index3) {
+  const found = await findOneItem(id);
   if (!found) {
     process.exitCode = 1;
     return void 0;
   }
-  const idx = resolveSubtaskIndex(id2, index3, found.item);
+  const idx = resolveSubtaskIndex(index3, found.item);
   if (idx === void 0) return void 0;
   return { orm: found.orm, item: found.item, idx };
 }
 
 // src/commands/backlog/updateSubtask.ts
 import { and as and9, eq as eq25 } from "drizzle-orm";
-async function updateSubtask(orm, itemId, idx, fields) {
+async function updateSubtask(orm, itemId2, idx, fields) {
   const set = {};
   if (fields.title !== void 0) set.title = fields.title;
   if (fields.description !== void 0) set.description = fields.description;
   if (fields.status !== void 0) set.status = fields.status;
-  const [row] = await orm.update(itemSubtasks).set(set).where(and9(eq25(itemSubtasks.itemId, itemId), eq25(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
+  const [row] = await orm.update(itemSubtasks).set(set).where(and9(eq25(itemSubtasks.itemId, itemId2), eq25(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
   return row?.title;
 }
 
@@ -9156,8 +9384,8 @@ function buildUpdate(options2) {
   }
   return fields;
 }
-async function editSubtask(id2, index3, options2) {
-  const found = await findSubtask(id2, index3);
+async function editSubtask(id, index3, options2) {
+  const found = await findSubtask(id, index3);
   if (!found) return;
   const fields = buildUpdate(options2);
   if (typeof fields === "string") {
@@ -9168,7 +9396,9 @@ async function editSubtask(id2, index3, options2) {
   const { orm, item, idx } = found;
   const title = await updateSubtask(orm, item.id, idx, fields);
   console.log(
-    chalk94.green(`Updated sub-task ${idx + 1} of item #${id2}: ${title}`)
+    chalk94.green(
+      `Updated sub-task ${idx + 1} of item ${formatItemId(item.id)}: ${title}`
+    )
   );
 }
 
@@ -9177,34 +9407,36 @@ import chalk95 from "chalk";
 
 // src/commands/backlog/deleteSubtask.ts
 import { and as and10, asc as asc6, eq as eq26 } from "drizzle-orm";
-async function deleteSubtask(orm, itemId, idx) {
-  const [row] = await orm.delete(itemSubtasks).where(and10(eq26(itemSubtasks.itemId, itemId), eq26(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
+async function deleteSubtask(orm, itemId2, idx) {
+  const [row] = await orm.delete(itemSubtasks).where(and10(eq26(itemSubtasks.itemId, itemId2), eq26(itemSubtasks.idx, idx))).returning({ title: itemSubtasks.title });
   if (!row) return void 0;
-  const remaining = await orm.select({ idx: itemSubtasks.idx }).from(itemSubtasks).where(eq26(itemSubtasks.itemId, itemId)).orderBy(asc6(itemSubtasks.idx));
+  const remaining = await orm.select({ idx: itemSubtasks.idx }).from(itemSubtasks).where(eq26(itemSubtasks.itemId, itemId2)).orderBy(asc6(itemSubtasks.idx));
   for (let i = 0; i < remaining.length; i++) {
     const oldIdx = remaining[i].idx;
     if (oldIdx === i) continue;
     await orm.update(itemSubtasks).set({ idx: i }).where(
-      and10(eq26(itemSubtasks.itemId, itemId), eq26(itemSubtasks.idx, oldIdx))
+      and10(eq26(itemSubtasks.itemId, itemId2), eq26(itemSubtasks.idx, oldIdx))
     );
   }
   return row.title;
 }
 
 // src/commands/backlog/removeSubtask.ts
-async function removeSubtask(id2, index3) {
-  const found = await findSubtask(id2, index3);
+async function removeSubtask(id, index3) {
+  const found = await findSubtask(id, index3);
   if (!found) return;
   const { orm, item, idx } = found;
   const title = await deleteSubtask(orm, item.id, idx);
   console.log(
-    chalk95.green(`Removed sub-task ${idx + 1} of item #${id2}: ${title}`)
+    chalk95.green(
+      `Removed sub-task ${idx + 1} of item ${formatItemId(item.id)}: ${title}`
+    )
   );
 }
 
 // src/commands/backlog/subtaskStatus.ts
 import chalk96 from "chalk";
-async function subtaskStatus(id2, index3, status2) {
+async function subtaskStatus(id, index3, status2) {
   if (!validSubtaskStatuses.includes(status2)) {
     console.log(
       chalk96.red(
@@ -9214,7 +9446,7 @@ async function subtaskStatus(id2, index3, status2) {
     process.exitCode = 1;
     return;
   }
-  const found = await findSubtask(id2, index3);
+  const found = await findSubtask(id, index3);
   if (!found) return;
   const { orm, item, idx } = found;
   const title = await updateSubtaskStatus(
@@ -9225,7 +9457,7 @@ async function subtaskStatus(id2, index3, status2) {
   );
   console.log(
     chalk96.green(
-      `Set sub-task ${idx + 1} of item #${id2} to ${status2}: ${title}`
+      `Set sub-task ${idx + 1} of item ${formatItemId(item.id)} to ${status2}: ${title}`
     )
   );
 }
@@ -9259,13 +9491,13 @@ import { and as and12, asc as asc8, eq as eq28 } from "drizzle-orm";
 
 // src/commands/backlog/reindexPhases.ts
 import { and as and11, asc as asc7, count as count5, eq as eq27 } from "drizzle-orm";
-async function reindexPhases(db, itemId) {
-  const remaining = await db.select({ idx: planPhases.idx }).from(planPhases).where(eq27(planPhases.itemId, itemId)).orderBy(asc7(planPhases.idx));
+async function reindexPhases(db, itemId2) {
+  const remaining = await db.select({ idx: planPhases.idx }).from(planPhases).where(eq27(planPhases.itemId, itemId2)).orderBy(asc7(planPhases.idx));
   for (let i = 0; i < remaining.length; i++) {
     const oldIdx = remaining[i].idx;
     if (oldIdx === i) continue;
-    await db.update(planTasks).set({ phaseIdx: i }).where(and11(eq27(planTasks.itemId, itemId), eq27(planTasks.phaseIdx, oldIdx)));
-    await db.update(planPhases).set({ idx: i }).where(and11(eq27(planPhases.itemId, itemId), eq27(planPhases.idx, oldIdx)));
+    await db.update(planTasks).set({ phaseIdx: i }).where(and11(eq27(planTasks.itemId, itemId2), eq27(planTasks.phaseIdx, oldIdx)));
+    await db.update(planPhases).set({ idx: i }).where(and11(eq27(planPhases.itemId, itemId2), eq27(planPhases.idx, oldIdx)));
   }
 }
 async function adjustCurrentPhase(db, item, removedIdx) {
@@ -9283,18 +9515,18 @@ async function adjustCurrentPhase(db, item, removedIdx) {
 }
 
 // src/commands/backlog/reorderPhaseRows.ts
-async function reorderPhaseRows(orm, itemId, fromIdx, toIdx) {
+async function reorderPhaseRows(orm, itemId2, fromIdx, toIdx) {
   await orm.transaction(async (tx) => {
-    const [phaseRow] = await tx.select({ name: planPhases.name, manualChecks: planPhases.manualChecks }).from(planPhases).where(and12(eq28(planPhases.itemId, itemId), eq28(planPhases.idx, fromIdx)));
-    const tasks = await tx.select({ idx: planTasks.idx, task: planTasks.task }).from(planTasks).where(and12(eq28(planTasks.itemId, itemId), eq28(planTasks.phaseIdx, fromIdx))).orderBy(asc8(planTasks.idx));
+    const [phaseRow] = await tx.select({ name: planPhases.name, manualChecks: planPhases.manualChecks }).from(planPhases).where(and12(eq28(planPhases.itemId, itemId2), eq28(planPhases.idx, fromIdx)));
+    const tasks = await tx.select({ idx: planTasks.idx, task: planTasks.task }).from(planTasks).where(and12(eq28(planTasks.itemId, itemId2), eq28(planTasks.phaseIdx, fromIdx))).orderBy(asc8(planTasks.idx));
     await tx.delete(planTasks).where(
-      and12(eq28(planTasks.itemId, itemId), eq28(planTasks.phaseIdx, fromIdx))
+      and12(eq28(planTasks.itemId, itemId2), eq28(planTasks.phaseIdx, fromIdx))
     );
-    await tx.delete(planPhases).where(and12(eq28(planPhases.itemId, itemId), eq28(planPhases.idx, fromIdx)));
-    await reindexPhases(tx, itemId);
-    await shiftPhasesUp(tx, itemId, toIdx);
+    await tx.delete(planPhases).where(and12(eq28(planPhases.itemId, itemId2), eq28(planPhases.idx, fromIdx)));
+    await reindexPhases(tx, itemId2);
+    await shiftPhasesUp(tx, itemId2, toIdx);
     await tx.insert(planPhases).values({
-      itemId,
+      itemId: itemId2,
       idx: toIdx,
       name: phaseRow.name,
       manualChecks: phaseRow.manualChecks
@@ -9302,7 +9534,7 @@ async function reorderPhaseRows(orm, itemId, fromIdx, toIdx) {
     if (tasks.length) {
       await tx.insert(planTasks).values(
         tasks.map((t) => ({
-          itemId,
+          itemId: itemId2,
           phaseIdx: toIdx,
           idx: t.idx,
           task: t.task
@@ -9326,19 +9558,19 @@ function toIndex(value, phaseCount) {
   }
   return pos - 1;
 }
-async function movePhase(id2, from, to) {
-  const found = await findOneItem(id2);
+async function movePhase(id, from, to) {
+  const found = await findOneItem(id);
   if (!found) return;
   const { orm, item } = found;
-  const itemId = item.id;
-  const [row] = await orm.select({ cnt: count6() }).from(planPhases).where(eq29(planPhases.itemId, itemId));
+  const itemId2 = item.id;
+  const [row] = await orm.select({ cnt: count6() }).from(planPhases).where(eq29(planPhases.itemId, itemId2));
   const phaseCount = row?.cnt ?? 0;
   const fromIdx = toIndex(from, phaseCount);
   if (fromIdx === void 0) return;
   const toIdx = toIndex(to, phaseCount);
   if (toIdx === void 0) return;
   if (fromIdx !== toIdx) {
-    await reorderPhaseRows(orm, itemId, fromIdx, toIdx);
+    await reorderPhaseRows(orm, itemId2, fromIdx, toIdx);
   }
   console.log(chalk97.green(`Moved phase ${from} to position ${to}.`));
 }
@@ -9348,26 +9580,26 @@ import chalk99 from "chalk";
 
 // src/commands/backlog/applyPhaseUpdate.ts
 import { and as and13, eq as eq30 } from "drizzle-orm";
-async function applyPhaseUpdate(orm, itemId, phaseIdx, fields) {
+async function applyPhaseUpdate(orm, itemId2, phaseIdx, fields) {
   await orm.transaction(async (tx) => {
     if (fields.name) {
       await tx.update(planPhases).set({ name: fields.name }).where(
-        and13(eq30(planPhases.itemId, itemId), eq30(planPhases.idx, phaseIdx))
+        and13(eq30(planPhases.itemId, itemId2), eq30(planPhases.idx, phaseIdx))
       );
     }
     if (fields.manualCheck) {
       await tx.update(planPhases).set({ manualChecks: JSON.stringify(fields.manualCheck) }).where(
-        and13(eq30(planPhases.itemId, itemId), eq30(planPhases.idx, phaseIdx))
+        and13(eq30(planPhases.itemId, itemId2), eq30(planPhases.idx, phaseIdx))
       );
     }
     if (fields.task) {
       await tx.delete(planTasks).where(
-        and13(eq30(planTasks.itemId, itemId), eq30(planTasks.phaseIdx, phaseIdx))
+        and13(eq30(planTasks.itemId, itemId2), eq30(planTasks.phaseIdx, phaseIdx))
       );
       if (fields.task.length) {
         await tx.insert(planTasks).values(
           fields.task.map((task, i) => ({
-            itemId,
+            itemId: itemId2,
             phaseIdx,
             idx: i,
             task
@@ -9381,21 +9613,23 @@ async function applyPhaseUpdate(orm, itemId, phaseIdx, fields) {
 // src/commands/backlog/findPhase.ts
 import chalk98 from "chalk";
 import { and as and14, count as count7, eq as eq31 } from "drizzle-orm";
-async function findPhase(id2, phase) {
-  const found = await findOneItem(id2);
+async function findPhase(id, phase) {
+  const found = await findOneItem(id);
   if (!found) return void 0;
   const { orm, item } = found;
-  const itemId = item.id;
+  const itemId2 = item.id;
   const phaseIdx = Number.parseInt(phase, 10) - 1;
-  const [row] = await orm.select({ cnt: count7() }).from(planPhases).where(and14(eq31(planPhases.itemId, itemId), eq31(planPhases.idx, phaseIdx)));
+  const [row] = await orm.select({ cnt: count7() }).from(planPhases).where(and14(eq31(planPhases.itemId, itemId2), eq31(planPhases.idx, phaseIdx)));
   if (!row || row.cnt === 0) {
     console.log(
-      chalk98.red(`Phase ${phaseIdx + 1} not found on item #${itemId}.`)
+      chalk98.red(
+        `Phase ${phaseIdx + 1} not found on item ${formatItemId(itemId2)}.`
+      )
     );
     process.exitCode = 1;
     return void 0;
   }
-  return { item, orm, itemId, phaseIdx };
+  return { item, orm, itemId: itemId2, phaseIdx };
 }
 
 // src/commands/backlog/update/parseListIndex.ts
@@ -9493,11 +9727,11 @@ function resolveChecks(o, current) {
     CHECK_FLAGS
   );
 }
-function buildFields(name, tasks, checks) {
+function buildFields(name, tasks, checks2) {
   const fields = {
     name,
     task: tasks.items,
-    manualCheck: checks.items
+    manualCheck: checks2.items
   };
   if (!fields.name && !fields.task && !fields.manualCheck) {
     return {
@@ -9510,16 +9744,16 @@ function buildFields(name, tasks, checks) {
 function resolvePhaseFields(options2, current) {
   const tasks = resolveTasks(options2, current);
   if (!tasks.ok) return tasks;
-  const checks = resolveChecks(options2, current);
-  if (!checks.ok) return checks;
-  return buildFields(options2.name, tasks, checks);
+  const checks2 = resolveChecks(options2, current);
+  if (!checks2.ok) return checks2;
+  return buildFields(options2.name, tasks, checks2);
 }
 
 // src/commands/backlog/updatePhase.ts
-async function updatePhase(id2, phase, options2) {
-  const found = await findPhase(id2, phase);
+async function updatePhase(id, phase, options2) {
+  const found = await findPhase(id, phase);
   if (!found) return;
-  const { item, orm, itemId, phaseIdx } = found;
+  const { item, orm, itemId: itemId2, phaseIdx } = found;
   const resolved = resolvePhaseFields(options2, item.plan?.[phaseIdx]);
   if (!resolved.ok) {
     console.log(chalk99.red(resolved.error));
@@ -9527,7 +9761,7 @@ async function updatePhase(id2, phase, options2) {
     return;
   }
   const { name, task, manualCheck } = resolved.fields;
-  await applyPhaseUpdate(orm, itemId, phaseIdx, { name, task, manualCheck });
+  await applyPhaseUpdate(orm, itemId2, phaseIdx, { name, task, manualCheck });
   const fields = [
     name && "name",
     task && "tasks",
@@ -9535,20 +9769,20 @@ async function updatePhase(id2, phase, options2) {
   ].filter(Boolean).join(", ");
   console.log(
     chalk99.green(
-      `Updated ${fields} on phase ${phaseIdx + 1} of item #${itemId}.`
+      `Updated ${fields} on phase ${phaseIdx + 1} of item ${formatItemId(itemId2)}.`
     )
   );
 }
 
 // src/commands/backlog/registerUpdatePhaseCommand.ts
-function collect(value, previous) {
+function collect2(value, previous) {
   return [...previous, value];
 }
 function registerUpdatePhaseCommand(cmd) {
-  cmd.command("update-phase <id> <phase>").description("Modify a plan phase on a backlog item").option("--name <name>", "New phase name").option("--task <task...>", "Replace tasks (repeatable)").option("--manual-check <check...>", "Replace manual checks (repeatable)").option("--add-task <text>", "Append one task (repeatable)", collect, []).option("--edit-task <n> <text...>", "Replace task n (1-based) in place").option("--remove-task <n>", "Remove task n (1-based)").option(
+  cmd.command("update-phase <id> <phase>").description("Modify a plan phase on a backlog item").option("--name <name>", "New phase name").option("--task <task...>", "Replace tasks (repeatable)").option("--manual-check <check...>", "Replace manual checks (repeatable)").option("--add-task <text>", "Append one task (repeatable)", collect2, []).option("--edit-task <n> <text...>", "Replace task n (1-based) in place").option("--remove-task <n>", "Remove task n (1-based)").option(
     "--add-check <text>",
     "Append one manual check (repeatable)",
-    collect,
+    collect2,
     []
   ).option(
     "--edit-check <n> <text...>",
@@ -9559,20 +9793,22 @@ function registerUpdatePhaseCommand(cmd) {
 // src/commands/backlog/removePhase.ts
 import chalk100 from "chalk";
 import { and as and15, eq as eq32 } from "drizzle-orm";
-async function removePhase(id2, phase) {
-  const found = await findPhase(id2, phase);
+async function removePhase(id, phase) {
+  const found = await findPhase(id, phase);
   if (!found) return;
-  const { item, orm, itemId, phaseIdx } = found;
+  const { item, orm, itemId: itemId2, phaseIdx } = found;
   await orm.transaction(async (tx) => {
     await tx.delete(planTasks).where(
-      and15(eq32(planTasks.itemId, itemId), eq32(planTasks.phaseIdx, phaseIdx))
+      and15(eq32(planTasks.itemId, itemId2), eq32(planTasks.phaseIdx, phaseIdx))
     );
-    await tx.delete(planPhases).where(and15(eq32(planPhases.itemId, itemId), eq32(planPhases.idx, phaseIdx)));
-    await reindexPhases(tx, itemId);
+    await tx.delete(planPhases).where(and15(eq32(planPhases.itemId, itemId2), eq32(planPhases.idx, phaseIdx)));
+    await reindexPhases(tx, itemId2);
     await adjustCurrentPhase(tx, item, phaseIdx);
   });
   console.log(
-    chalk100.green(`Removed phase ${phaseIdx + 1} from item #${itemId}.`)
+    chalk100.green(
+      `Removed phase ${phaseIdx + 1} from item ${formatItemId(itemId2)}.`
+    )
   );
 }
 
@@ -9634,8 +9870,8 @@ function buildUpdateValues(options2) {
 }
 
 // src/commands/backlog/update/index.ts
-async function update(id2, options2) {
-  const found = await findOneItem(id2);
+async function update(id, options2) {
+  const found = await findOneItem(id);
   if (!found) return;
   let ac = options2.ac;
   if (hasAcMutations(options2)) {
@@ -9657,13 +9893,15 @@ async function update(id2, options2) {
   const built = buildUpdateValues({ ...options2, ac });
   if (!built) return;
   const { orm } = found;
-  const itemId = found.item.id;
-  await orm.update(items).set(built.set).where(eq33(items.id, itemId));
-  console.log(chalk102.green(`Updated ${built.fields} on item #${itemId}.`));
+  const itemId2 = found.item.id;
+  await orm.update(items).set(built.set).where(eq33(items.id, itemId2));
+  console.log(
+    chalk102.green(`Updated ${built.fields} on item ${formatItemId(itemId2)}.`)
+  );
 }
 
 // src/commands/backlog/registerUpdateCommands.ts
-function collect2(value, previous) {
+function collect3(value, previous) {
   return [...previous, value];
 }
 function registerUpdateCommands(cmd) {
@@ -9673,7 +9911,7 @@ function registerUpdateCommands(cmd) {
   ).option("--type <type>", "New type (story or bug)").option("--ac <criterion...>", "Replace acceptance criteria (repeatable)").option(
     "--add-ac <text>",
     "Append one acceptance criterion (repeatable)",
-    collect2,
+    collect3,
     []
   ).option(
     "--edit-ac <n> <text...>",
@@ -9721,6 +9959,7 @@ function registerBacklog(program2) {
   for (const register of registrars) {
     register(cmd);
   }
+  configHelp(cmd, backlogConfigHelp);
 }
 
 // src/commands/branch/validateSlug.ts
@@ -9769,19 +10008,27 @@ async function branch(slug, options2) {
 
 // src/commands/registerBranch.ts
 function registerBranch(program2) {
-  program2.command("branch <slug>").description(
+  const branchCommand = program2.command("branch <slug>").description(
     "Create and switch to a branch off the fresh remote default branch"
-  ).option("--jira <key>", "Jira issue key to include in the branch name").addHelpText(
-    "after",
-    `
-Branch name is assembled as [<prefix>/][<JIRA>-]<slug>, e.g. sw/BAD-671-add-login-form.
-
-Config:
-  assist config set branch.prefix sw          # optional; prepends "<prefix>/" (omitted when unset)
-  assist config set branch.defaultBranch main # optional; overrides the live remote default branch`
-  ).action(
+  ).option("--jira <key>", "Jira issue key to include in the branch name").action(
     (slug, options2) => branch(slug, options2)
   );
+  configHelp(
+    branchCommand,
+    [
+      {
+        key: "branch.prefix",
+        setter: "assist config set branch.prefix sw",
+        note: 'optional; prepends "<prefix>/" (omitted when unset)'
+      },
+      {
+        key: "branch.defaultBranch",
+        setter: "assist config set branch.defaultBranch main",
+        note: "optional; overrides the live remote default branch"
+      }
+    ],
+    "Branch name is assembled as [<prefix>/][<JIRA>-]<slug>, e.g. sw/BAD-671-add-login-form."
+  );
 }
 
 // src/commands/cliHook/index.ts
@@ -10834,6 +11081,13 @@ function denyRemove(pattern2, options2) {
 // src/commands/registerDeny.ts
 function registerDeny(parent) {
   const denyCommand = parent.command("deny").description("Manage command deny rules").action(denyList);
+  configHelp(denyCommand, [
+    {
+      key: "deny",
+      setter: "assist deny add <pattern> <message>",
+      note: "command patterns blocked with a correction message"
+    }
+  ]);
   denyCommand.command("add").description("Add a deny rule for a command pattern").argument("<pattern>", "Command prefix to deny").argument("<message>", "Correction message shown to the agent").option("-g, --global", "Write to global ~/.assist.yml").action(denyAdd);
   denyCommand.command("remove").description("Remove a deny rule by pattern").argument("<pattern>", "Command prefix to remove").option("-g, --global", "Remove from global ~/.assist.yml").action(denyRemove);
   denyCommand.command("list").description("List all deny rules").action(denyList);
@@ -10844,6 +11098,13 @@ function registerCliHook(program2) {
   const cmd = program2.command("cli-hook").description("PreToolUse hook for auto-approving read-only CLI commands").action(() => {
     cliHook();
   });
+  configHelp(cmd, [
+    {
+      key: "cliReadVerbs",
+      setter: 'assist config set cliReadVerbs.git "status"',
+      note: "extra per-CLI verbs treated as read-only for auto-approval"
+    }
+  ]);
   cmd.command("check <command>").description("Check whether a command would be auto-approved").option("--tool <tool>", "Tool name to check against", "Bash").action((command, options2) => {
     cliHookCheck(command, options2.tool);
   });
@@ -11589,6 +11850,15 @@ async function analyze(pattern2) {
   await maintainability(searchPattern);
 }
 
+// src/commands/complexity/complexityConfigHelp.ts
+var complexityConfigHelp = [
+  {
+    key: "complexity.ignore",
+    setter: 'assist config set complexity.ignore "**/*test.ts*"',
+    note: "globs excluded from maintainability (default: **/*test.ts*)"
+  }
+];
+
 // src/commands/registerComplexity.ts
 function registerComplexity(program2) {
   const complexityCommand = program2.command("complexity").description("Analyze TypeScript code complexity metrics").argument("[pattern]").action((pattern2) => {
@@ -11611,6 +11881,7 @@ function registerComplexity(program2) {
     []
   ).action(maintainability);
   complexityCommand.command("sloc [pattern]").description("Count source lines of code per file").option("--threshold <number>", "Max lines threshold", Number.parseInt).action(sloc);
+  configHelp(complexityCommand, complexityConfigHelp);
 }
 
 // src/commands/config/index.ts
@@ -12312,6 +12583,25 @@ function version() {
   console.log(`${chalk127.bold("next:")} ${nextVersion ?? chalk127.dim("none")}`);
 }
 
+// src/commands/devlog/devlogConfigHelp.ts
+var devlogConfigHelp = [
+  {
+    key: "devlog.name",
+    setter: "assist config set devlog.name my-repo",
+    note: "override the repo name reported in devlog entries"
+  },
+  {
+    key: "devlog.ignore",
+    setter: 'assist config set devlog.ignore "**/*.lock"',
+    note: "globs excluded when grouping commits"
+  },
+  {
+    key: "devlog.skip",
+    setter: "assist devlog skip 2026-07-10",
+    note: "dates (per repo) omitted from devlog output"
+  }
+];
+
 // src/commands/registerDevlog.ts
 function registerDevlog(program2) {
   const devlogCommand = program2.command("devlog").description("Development log utilities");
@@ -12328,6 +12618,7 @@ function registerDevlog(program2) {
     "Only show repos pushed within N days (default: 30)",
     Number.parseInt
   ).option("--all", "Show all non-archived repos regardless of push date").action(repos);
+  configHelp(devlogCommand, devlogConfigHelp);
 }
 
 // src/commands/dotnet/checkBuildLocks.ts
@@ -12953,6 +13244,13 @@ function registerDotnet(program2) {
   cmd.command("check-locks").description("Check if build output files are locked by a debugger").action(checkBuildLocksCommand);
   cmd.command("deps").description("Show .csproj project dependency tree and solution membership").argument("<csproj>", "Path to a .csproj file").option("--json", "Output as JSON").action(deps);
   cmd.command("in-sln").description("Check whether a .csproj is referenced by any .sln file").argument("<csproj>", "Path to a .csproj file").action(inSln);
+  configHelp(cmd, [
+    {
+      key: "dotnet.inspect.suppress",
+      setter: "assist config set dotnet.inspect.suppress CSharpWarnings::CS0168",
+      note: "inspection issue-type IDs suppressed by default"
+    }
+  ]);
 }
 
 // src/commands/editHook/index.ts
@@ -13546,12 +13844,12 @@ async function printPendingHandovers() {
 
 // src/commands/handover/recallHandover.ts
 import { and as and18, desc as desc5, eq as eq36, isNull as isNull3 } from "drizzle-orm";
-async function recallHandover(orm, origin, id2) {
+async function recallHandover(orm, origin, id) {
   const [row] = await orm.select().from(handovers).where(
     and18(
       eq36(handovers.origin, origin),
       isNull3(handovers.recalledAt),
-      ...id2 === void 0 ? [] : [eq36(handovers.id, id2)]
+      ...id === void 0 ? [] : [eq36(handovers.id, id)]
     )
   ).orderBy(desc5(handovers.createdAt), desc5(handovers.id)).limit(1);
   if (!row) return void 0;
@@ -13560,12 +13858,12 @@ async function recallHandover(orm, origin, id2) {
 }
 
 // src/commands/handover/recallAndPrint.ts
-async function recallAndPrint(id2) {
+async function recallAndPrint(id) {
   const orm = await getDb();
   const content = await recallHandover(
     orm,
     getCurrentOrigin(process.cwd()),
-    id2
+    id
   );
   if (content !== void 0) console.log(content);
 }
@@ -13595,7 +13893,7 @@ function registerHandover(program2) {
   cmd.command("recall").argument("[id]", "Id of a specific handover to recall").description(
     "Print an unrecalled handover for this repo and mark it recalled (most recent by default, or the given id)"
   ).action(
-    (id2) => recallAndPrint(id2 === void 0 ? void 0 : Number(id2))
+    (id) => recallAndPrint(id === void 0 ? void 0 : Number(id))
   );
   cmd.command("load").description(
     "SessionStart hook: migrate any disk handovers, then advise how many unrecalled handovers exist for this repo"
@@ -13770,6 +14068,13 @@ function registerJira(program2) {
   jiraCommand.command("auth").description("Authenticate with Jira via API token").action(() => jiraAuth());
   jiraCommand.command("ac <issue-key>").description("Print acceptance criteria for a Jira issue").action((issueKey) => acceptanceCriteria(issueKey));
   jiraCommand.command("view <issue-key>").description("Print the title and description of a Jira issue").action((issueKey) => viewIssue(issueKey));
+  configHelp(jiraCommand, [
+    {
+      key: "jira.acField",
+      setter: "assist config set jira.acField customfield_11937",
+      note: "custom field holding acceptance criteria (default: customfield_11937)"
+    }
+  ]);
 }
 
 // src/commands/reviewComments.ts
@@ -13798,7 +14103,7 @@ async function reviewComments(number) {
 var RESUME_SESSION_FLAG = "Resume an interrupted Claude session (used by the sessions daemon on restart)";
 function registerNext(program2) {
   program2.command("next").argument("[id]", "Backlog item ID to run first").description("Alias for backlog next").option("--once", "Exit after the first completed item run").action(
-    (id2, opts) => next({ allowEdits: true, once: opts.once }, id2)
+    (id, opts) => next({ allowEdits: true, once: opts.once }, id)
   );
 }
 function registerDescriptionLaunch(program2, name, slashCommand, description, alias) {
@@ -13819,7 +14124,7 @@ function registerReviewComments(program2) {
 }
 function registerRefine(program2) {
   program2.command("refine").argument("[id]", "Backlog item ID").description("Launch Claude in /refine mode to refine a backlog item").option("--once", "Exit when the initial task completes").option("--resume-session <id>", RESUME_SESSION_FLAG).action(
-    (id2, opts) => refine(id2, { once: opts.once, resumeSessionId: opts.resumeSession })
+    (id, opts) => refine(id, { once: opts.once, resumeSessionId: opts.resumeSession })
   );
 }
 function registerLaunch(program2) {
@@ -13957,6 +14262,13 @@ function registerMermaid(program2) {
   ).action(
     (file, options2) => mermaidExport(file, options2)
   );
+  configHelp(cmd, [
+    {
+      key: "mermaid.krokiUrl",
+      setter: "assist config set mermaid.krokiUrl https://kroki.io",
+      note: "Kroki server used to render diagrams (default: https://kroki.io)"
+    }
+  ]);
 }
 
 // src/commands/netcap/netcap.ts
@@ -14190,8 +14502,8 @@ function parseRscRows(flight) {
 }
 function makeRscResolver(rows) {
   return (ref) => {
-    const [id2, ...path58] = ref.slice(1).replace(/^[L@]/, "").split(":");
-    let v = rows[id2];
+    const [id, ...path58] = ref.slice(1).replace(/^[L@]/, "").split(":");
+    let v = rows[id];
     for (const key of path58) {
       if (v == null || typeof v !== "object") return void 0;
       v = v[key];
@@ -14280,9 +14592,9 @@ function activityPermalink(urn) {
 // src/commands/netcap/activityUrnDate.ts
 function activityUrnDate(urn) {
   if (!urn) return void 0;
-  const id2 = urn.split(":").pop();
-  if (!id2 || !/^\d+$/.test(id2)) return void 0;
-  return new Date(Number(BigInt(id2) >> 22n)).toISOString();
+  const id = urn.split(":").pop();
+  if (!id || !/^\d+$/.test(id)) return void 0;
+  return new Date(Number(BigInt(id) >> 22n)).toISOString();
 }
 
 // src/commands/netcap/dedupeLinks.ts
@@ -14379,7 +14691,7 @@ function findAuthorSlug(flight) {
 }
 function findCommentaryRows(rows) {
   return Object.keys(rows).filter(
-    (id2) => /"componentkey":"feed-commentary_/.test(JSON.stringify(rows[id2]))
+    (id) => /"componentkey":"feed-commentary_/.test(JSON.stringify(rows[id]))
   );
 }
 function extractLinkedInPosts(flight, author = findAuthorSlug(flight)) {
@@ -14387,7 +14699,7 @@ function extractLinkedInPosts(flight, author = findAuthorSlug(flight)) {
   const resolve18 = makeRscResolver(rows);
   const mentionMap = buildMentionMap(rows, resolve18);
   const posts = [];
-  for (const id2 of findCommentaryRows(rows)) {
+  for (const id of findCommentaryRows(rows)) {
     const raw = {
       text: [],
       hashtags: [],
@@ -14395,7 +14707,7 @@ function extractLinkedInPosts(flight, author = findAuthorSlug(flight)) {
       links: [],
       related: []
     };
-    walkPostRow(rows[id2], resolve18, raw);
+    walkPostRow(rows[id], resolve18, raw);
     const post = buildPost(raw, mentionMap, author);
     if (post) posts.push(post);
   }
@@ -14827,8 +15139,8 @@ function assertThreadCreated(stdout) {
   } catch {
     throw new Error(`GitHub returned an unparseable response: ${stdout}`);
   }
-  const id2 = parsed.data?.addPullRequestReviewThread?.thread?.id;
-  if (typeof id2 !== "string" || id2.length === 0) {
+  const id = parsed.data?.addPullRequestReviewThread?.thread?.id;
+  if (typeof id !== "string" || id.length === 0) {
     throw new Error(
       "GitHub did not create a review thread (no thread id returned); the line is likely outside the PR diff."
     );
@@ -14917,9 +15229,9 @@ function parsePrBody(body) {
   return sections;
 }
 function serializePrBody(sections) {
-  return sections.map((section2) => `## ${section2.heading}
+  return sections.map((section3) => `## ${section3.heading}
 
-${section2.content}`).join("\n\n");
+${section3.content}`).join("\n\n");
 }
 
 // src/commands/prs/editPrBody.ts
@@ -14967,11 +15279,11 @@ function countSentences(paragraph) {
 }
 function splitParagraphs(body) {
   const paragraphs = [];
-  let section2 = "(intro)";
+  let section3 = "(intro)";
   let lines = [];
   const flush = () => {
     if (lines.length > 0) {
-      paragraphs.push({ section: section2, lines });
+      paragraphs.push({ section: section3, lines });
       lines = [];
     }
   };
@@ -14979,7 +15291,7 @@ function splitParagraphs(body) {
     const heading = line.match(/^#{1,6}\s+(.*)$/);
     if (heading) {
       flush();
-      section2 = heading[1].trim();
+      section3 = heading[1].trim();
     } else if (line.trim() === "") {
       flush();
     } else {
@@ -15639,8 +15951,22 @@ function wontfix(commentId, reason) {
   }
 }
 
+// src/commands/prs/prsConfigHelp.ts
+var prsConfigHelp = [
+  {
+    key: "prs.slack",
+    setter: 'assist config set prs.slack "#pull-requests"',
+    note: "Slack channel PRs are announced to (used by /prs-slack)"
+  },
+  {
+    key: "prs.required",
+    setter: "assist config set prs.required true",
+    note: "require a branch when running a backlog item"
+  }
+];
+
 // src/commands/registerPrsEdit.ts
-function collect3(value, previous) {
+function collect4(value, previous) {
   return previous.concat([value]);
 }
 function registerPrsEdit(prsCommand) {
@@ -15649,13 +15975,13 @@ function registerPrsEdit(prsCommand) {
   ).option("-t, --title <title>", "New title for the pull request").option("--what <what>", "Replace the ## What section").option("--why <why>", "Replace the ## Why section").option("--how <how>", "Replace the ## How section").option(
     "--resolves <key>",
     "Jira issue key resolved by this PR, appended to ## Why (repeatable)",
-    collect3,
+    collect4,
     []
   ).action(edit);
 }
 
 // src/commands/registerPrsRaise.ts
-function collect4(value, previous) {
+function collect5(value, previous) {
   return previous.concat([value]);
 }
 function registerPrsRaise(prsCommand) {
@@ -15664,20 +15990,20 @@ function registerPrsRaise(prsCommand) {
   ).option("-t, --title <title>", "Title for the pull request").option("--what <what>", "What the change does (## What section)").option("--why <why>", "Why the change is needed (## Why section)").option("--how <how>", "How the change works (optional ## How section)").option(
     "--resolves <key>",
     "Jira issue key resolved by this PR, appended to ## Why (repeatable)",
-    collect4,
+    collect5,
     []
   ).option(
     "--force",
     "Overwrite the title and body of an existing pull request"
-  ).option("-B, --base <branch>", "Branch into which the pull request merges").option("-H, --head <branch>", "Branch that contains the commits").option("-d, --draft", "Mark the pull request as a draft").option("-w, --web", "Open the browser to create the pull request").option("-l, --label <label>", "Add a label (repeatable)", collect4, []).option(
+  ).option("-B, --base <branch>", "Branch into which the pull request merges").option("-H, --head <branch>", "Branch that contains the commits").option("-d, --draft", "Mark the pull request as a draft").option("-w, --web", "Open the browser to create the pull request").option("-l, --label <label>", "Add a label (repeatable)", collect5, []).option(
     "-a, --assignee <login>",
     "Assign a person by login (repeatable)",
-    collect4,
+    collect5,
     []
   ).option(
     "-r, --reviewer <handle>",
     "Request a review (repeatable)",
-    collect4,
+    collect5,
     []
   ).option("-m, --milestone <name>", "Add the pull request to a milestone").action(raise);
 }
@@ -15702,6 +16028,7 @@ function registerPrs(program2) {
   prsCommand.command("comment <path> <line> <body>").description("Add a line comment to the pending review").action((path58, line, body) => {
     comment2(path58, Number.parseInt(line, 10), body);
   });
+  configHelp(prsCommand, prsConfigHelp);
 }
 
 // src/commands/ravendb/ravendbAuth.ts
@@ -15797,9 +16124,9 @@ function searchItems(search2) {
   const lower = search2.toLowerCase();
   return items2.filter((i) => i.title.toLowerCase().includes(lower));
 }
-function getItemFields(itemId) {
+function getItemFields(itemId2) {
   try {
-    const item = JSON.parse(opExec(`item get "${itemId}" --format=json`));
+    const item = JSON.parse(opExec(`item get "${itemId2}" --format=json`));
     return item.fields.filter((f) => f.reference && f.label);
   } catch {
     console.error(chalk154.red("Failed to get item details from 1Password."));
@@ -15824,11 +16151,11 @@ async function selectOpSecret(searchTerm) {
     console.error(chalk155.red(`No items found matching "${search2}".`));
     process.exit(1);
   }
-  const itemId = await selectOne(
+  const itemId2 = await selectOne(
     "Select item:",
     items2.map((i) => ({ name: `${i.title} (${i.vault.name})`, value: i.id }))
   );
-  const fields = getItemFields(itemId);
+  const fields = getItemFields(itemId2);
   if (fields.length === 0) {
     console.error(chalk155.red("No fields with references found on this item."));
     process.exit(1);
@@ -16036,6 +16363,20 @@ async function ravendbCollections(connectionName) {
   }
 }
 
+// src/commands/ravendb/ravendbConfigHelp.ts
+var ravendbConfigHelp = [
+  {
+    key: "ravendb.connections",
+    setter: "assist ravendb auth add",
+    note: "named RavenDB connections (add/list/remove via ravendb auth)"
+  },
+  {
+    key: "ravendb.defaultConnection",
+    setter: "assist ravendb set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/ravendb/ravendbQuery.ts
 import chalk164 from "chalk";
 
@@ -16124,6 +16465,7 @@ function registerRavendb(program2) {
     (connection, collection, options2) => ravendbQuery(connection, collection, options2)
   );
   cmd.command("collections [connection]").description("List collections in a RavenDB database").action((connection) => ravendbCollections(connection));
+  configHelp(cmd, ravendbConfigHelp);
 }
 
 // src/commands/refactor/check/index.ts
@@ -16369,9 +16711,9 @@ function addImportPreservingSuppressions(sourceFile, structure) {
 import { SyntaxKind as SyntaxKind3 } from "ts-morph";
 function collectReferencedNames(sourceFile) {
   const names = /* @__PURE__ */ new Set();
-  for (const id2 of sourceFile.getDescendantsOfKind(SyntaxKind3.Identifier)) {
-    if (id2.getFirstAncestorByKind(SyntaxKind3.ImportDeclaration)) continue;
-    names.add(id2.getText());
+  for (const id of sourceFile.getDescendantsOfKind(SyntaxKind3.Identifier)) {
+    if (id.getFirstAncestorByKind(SyntaxKind3.ImportDeclaration)) continue;
+    names.add(id.getText());
   }
   return names;
 }
@@ -16422,7 +16764,7 @@ function updateImporters(functionName, sourceFile, importers) {
 
 // src/commands/refactor/extract/applyExtraction.ts
 function isNameReferencedInSource(sourceFile, name) {
-  return sourceFile.getDescendantsOfKind(SyntaxKind4.Identifier).some((id2) => id2.getText() === name);
+  return sourceFile.getDescendantsOfKind(SyntaxKind4.Identifier).some((id) => id.getText() === name);
 }
 async function applyExtraction(functionName, sourceFile, destPath, plan2, project) {
   project.createSourceFile(destPath, plan2.destContent, { overwrite: false });
@@ -16506,8 +16848,8 @@ function collectPrivateFunctions(target, fnMap) {
 import { SyntaxKind as SyntaxKind6 } from "ts-morph";
 function getReferencedIdentifiers(fn) {
   const names = /* @__PURE__ */ new Set();
-  for (const id2 of fn.getDescendantsOfKind(SyntaxKind6.Identifier)) {
-    names.add(id2.getText());
+  for (const id of fn.getDescendantsOfKind(SyntaxKind6.Identifier)) {
+    names.add(id.getText());
   }
   return names;
 }
@@ -16675,8 +17017,8 @@ function matchImport(importDecl, neededNames) {
 function getReferencedNames(nodes) {
   const names = /* @__PURE__ */ new Set();
   for (const node of nodes) {
-    for (const id2 of node.getDescendantsOfKind(SyntaxKind12.Identifier)) {
-      names.add(id2.getText());
+    for (const id of node.getDescendantsOfKind(SyntaxKind12.Identifier)) {
+      names.add(id.getText());
     }
   }
   return names;
@@ -16866,9 +17208,9 @@ function isInsideExtractedFunction(node, extracted) {
 }
 function sourceReferencesName(sourceFile, functionName, extractedNames) {
   const extracted = new Set(extractedNames);
-  for (const id2 of sourceFile.getDescendantsOfKind(SyntaxKind13.Identifier)) {
-    if (id2.getText() !== functionName) continue;
-    const parent = id2.getParent();
+  for (const id of sourceFile.getDescendantsOfKind(SyntaxKind13.Identifier)) {
+    if (id.getText() !== functionName) continue;
+    const parent = id.getParent();
     if (!parent || DECLARATION_KINDS.has(parent.getKind())) continue;
     if (!isInsideExtractedFunction(parent, extracted)) return true;
   }
@@ -16908,13 +17250,13 @@ function buildPlan2(functionName, sourceFile, sourcePath, destPath, project) {
 // src/commands/refactor/extract/displayPlan.ts
 import path33 from "path";
 import chalk166 from "chalk";
-function section(title) {
+function section2(title) {
   return `
   ${chalk166.cyan(title)}`;
 }
 function displayImporters(plan2, cwd) {
   if (plan2.importersToUpdate.length === 0) return;
-  console.log(section("Update importers:"));
+  console.log(section2("Update importers:"));
   for (const imp of plan2.importersToUpdate) {
     const rel = path33.relative(cwd, imp.file.getFilePath());
     console.log(`    ${chalk166.dim(rel)}: \u2192 import from "${imp.relPath}"`);
@@ -16928,18 +17270,18 @@ function displayPlan(functionName, relDest, plan2, cwd) {
     console.log(`    ${name}`);
   }
   if (plan2.imports.length > 0) {
-    console.log(section("Imports to copy:"));
+    console.log(section2("Imports to copy:"));
     for (const imp of plan2.imports) {
       console.log(`    ${formatImportLine(imp)}`);
     }
   }
   if (plan2.exportedDeps.length > 0) {
-    console.log(section("New imports from source:"));
+    console.log(section2("New imports from source:"));
     console.log(
       `    import { ${plan2.exportedDeps.join(", ")} } from "${plan2.sourceRelPath}";`
     );
   }
-  console.log(section("Source file changes:"));
+  console.log(section2("Source file changes:"));
   console.log(`    Remove: ${plan2.extractedNames.join(", ")}`);
   if (plan2.sourceNeedsReimport) {
     console.log(
@@ -16948,7 +17290,7 @@ function displayPlan(functionName, relDest, plan2, cwd) {
   }
   displayImporters(plan2, cwd);
   if (plan2.barrel) {
-    console.log(section("Barrel export:"));
+    console.log(section2("Barrel export:"));
     console.log(
       `    Add: export { ${functionName} } from "${plan2.barrelRelPath}";`
     );
@@ -17346,8 +17688,8 @@ function isDeclaration(identifier) {
   return parent !== void 0 && declarationKinds.includes(parent.getKind());
 }
 function findSymbol(sourceFile, symbolName) {
-  for (const id2 of sourceFile.getDescendantsOfKind(SyntaxKind14.Identifier)) {
-    if (id2.getText() === symbolName && isDeclaration(id2)) return id2;
+  for (const id of sourceFile.getDescendantsOfKind(SyntaxKind14.Identifier)) {
+    if (id.getText() === symbolName && isDeclaration(id)) return id;
   }
   return void 0;
 }
@@ -17717,6 +18059,15 @@ async function restructure(pattern2, options2 = {}) {
   }
 }
 
+// src/commands/refactor/refactorConfigHelp.ts
+var refactorConfigHelp = [
+  {
+    key: "restructure.ignore",
+    setter: 'assist config set restructure.ignore "src/generated/**"',
+    note: "globs excluded from restructure coupling analysis"
+  }
+];
+
 // src/commands/registerRefactor.ts
 function registerCheck(parent) {
   parent.command("check [pattern]").description("Check for files that exceed the maximum line count").option("--modified", "Check only staged and unstaged files").option("--staged", "Check only staged files").option("--unstaged", "Check only unstaged files").option(
@@ -17733,13 +18084,14 @@ function registerRename(parent) {
   ).option("--apply", "Execute the rename (default: dry-run)").action(renameSymbol);
 }
 function registerRestructure(parent) {
-  parent.command("restructure [pattern]").description(
+  const restructureCommand = parent.command("restructure [pattern]").description(
     "Analyze import graph and restructure tightly-coupled files into nested directories"
   ).option("--apply", "Execute the restructuring (default: dry-run)").option(
     "--max-depth <number>",
     "Maximum nesting iterations (default: 3)",
     Number.parseInt
   ).action(restructure);
+  configHelp(restructureCommand, refactorConfigHelp);
 }
 function registerRefactor(program2) {
   const refactorCommand = program2.command("refactor").description("Run refactoring checks for code quality");
@@ -19554,6 +19906,20 @@ var seqAuth = createConnectionAuth({
   onFirst: (c) => setDefaultConnection(c.name)
 });
 
+// src/commands/seq/seqConfigHelp.ts
+var seqConfigHelp = [
+  {
+    key: "seq.connections",
+    setter: "assist seq auth add",
+    note: "named Seq connections (add/list/remove via seq auth)"
+  },
+  {
+    key: "seq.defaultConnection",
+    setter: "assist seq set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/seq/seqQuery.ts
 import chalk184 from "chalk";
 
@@ -19823,17 +20189,18 @@ function registerSeq(program2) {
     "--to <date>",
     "End of query window (UTC date or relative e.g. 5m, 1h, 2d)"
   ).option("--json", "Output raw JSON").action((filter, options2) => seqQuery(filter, options2));
+  configHelp(cmd, seqConfigHelp);
 }
 
 // src/commands/registerSignal.ts
 function registerSignal(program2) {
   const signalCommand = program2.command("signal").description("Write an assist signal file");
-  signalCommand.command("next").argument("[id]", "Backlog item ID to run directly").description("Write a next signal to chain into assist next").action((id2) => {
-    writeSignal("next", id2 ? { id: id2 } : void 0);
+  signalCommand.command("next").argument("[id]", "Backlog item ID to run directly").description("Write a next signal to chain into assist next").action((id) => {
+    writeSignal("next", id ? { id } : void 0);
     console.log("Signal written.");
   });
-  signalCommand.command("done").argument("[id]", "Backlog item ID created by the session").description("Write a done signal to end a --once launch session").action((id2) => {
-    writeSignal("done", id2 ? { id: id2 } : void 0);
+  signalCommand.command("done").argument("[id]", "Backlog item ID created by the session").description("Write a done signal to end a --once launch session").action((id) => {
+    writeSignal("done", id ? { id } : void 0);
     console.log("Signal written.");
   });
 }
@@ -19977,6 +20344,20 @@ async function sqlColumns(table, connectionName) {
   }
 }
 
+// src/commands/sql/sqlConfigHelp.ts
+var sqlConfigHelp = [
+  {
+    key: "sql.connections",
+    setter: "assist sql auth add",
+    note: "named MSSQL connections (add/list/remove via sql auth)"
+  },
+  {
+    key: "sql.defaultConnection",
+    setter: "assist sql set-connection <name>",
+    note: "connection used when none is passed"
+  }
+];
+
 // src/commands/sql/sqlMutate.ts
 import chalk189 from "chalk";
 
@@ -20105,6 +20486,7 @@ function registerSql(program2) {
   ).action(
     (table, connection) => sqlColumns(table, connection)
   );
+  configHelp(cmd, sqlConfigHelp);
 }
 
 // src/commands/transcript/shared.ts
@@ -20440,9 +20822,29 @@ function move(file, options2) {
   console.log(`Summary target:       ${summaryPath}`);
 }
 
+// src/commands/transcript/transcriptConfigHelp.ts
+var transcriptConfigHelp = [
+  {
+    key: "transcript.vttDir",
+    setter: "assist transcript configure",
+    note: "pick-up directory scanned for raw .vtt files"
+  },
+  {
+    key: "transcript.transcriptsDir",
+    setter: "assist transcript configure",
+    note: "directory dated markdown transcripts are written to"
+  },
+  {
+    key: "transcript.summaryDir",
+    setter: "assist transcript configure",
+    note: "directory generated transcript summaries are written to"
+  }
+];
+
 // src/commands/registerTranscript.ts
 function registerTranscript(program2) {
   const transcriptCommand = program2.command("transcript").description("Meeting transcript utilities");
+  configHelp(transcriptCommand, transcriptConfigHelp);
   transcriptCommand.command("configure").description("Configure transcript directories").action(configure);
   transcriptCommand.command("list").description("List raw .vtt filenames waiting in the pick-up directory").action(list4);
   transcriptCommand.command("move <file>").description(
@@ -20450,6 +20852,59 @@ function registerTranscript(program2) {
   ).requiredOption("--date <YYYY-MM-DD>", "meeting date").requiredOption("--client <name>", "client name").action(move);
 }
 
+// src/commands/registerVerifyChecks.ts
+var checks = [
+  {
+    name: "hardcoded-colors",
+    description: "Check for hardcoded hex colors in src/",
+    action: hardcodedColors
+  },
+  {
+    name: "block-comments",
+    description: "Fail on any comment on a changed line, whether added or edited",
+    action: blockComments
+  },
+  {
+    name: "no-venv",
+    description: "Check that no venv folders exist in the repo",
+    action: noVenv
+  },
+  {
+    name: "forbidden-strings",
+    description: "Check configured JSON files for values matching forbiddenStrings rules",
+    action: forbiddenStrings
+  },
+  {
+    name: "config-keys",
+    description: "Check every assistConfigSchema key is surfaced in some command's --help via configHelp",
+    action: configKeys
+  }
+];
+function registerVerifyChecks(verifyCommand) {
+  for (const check2 of checks) {
+    verifyCommand.command(check2.name).description(check2.description).action(check2.action);
+  }
+}
+
+// src/commands/verify/verifyConfigHelp.ts
+var verifyConfigHelp = [
+  {
+    key: "blockComments.ignore",
+    setter: 'assist config set blockComments.ignore "**/*.test.ts"',
+    note: "globs exempt from the block-comments check"
+  },
+  {
+    key: "hardcodedColors.ignore",
+    setter: 'assist config set hardcodedColors.ignore "**/theme.ts"',
+    note: "globs exempt from the hardcoded-colors check"
+  },
+  {
+    key: "forbiddenStrings",
+    setter: 'assist config set forbiddenStrings.0.disallowed "secret"',
+    note: "per-file value rules enforced by the forbidden-strings check"
+  }
+];
+
 // src/commands/registerVerify.ts
 function runScope(scope, options2) {
   if (scope && scope !== "all") {
@@ -20471,14 +20926,8 @@ function registerVerify(program2) {
     "--package-json",
     "Write scripts to package.json instead of assist.yml"
   ).action(init3);
-  verifyCommand.command("hardcoded-colors").description("Check for hardcoded hex colors in src/").action(hardcodedColors);
-  verifyCommand.command("block-comments").description(
-    "Fail on any comment on a changed line, whether added or edited"
-  ).action(blockComments);
-  verifyCommand.command("no-venv").description("Check that no venv folders exist in the repo").action(noVenv);
-  verifyCommand.command("forbidden-strings").description(
-    "Check configured JSON files for values matching forbiddenStrings rules"
-  ).action(forbiddenStrings);
+  registerVerifyChecks(verifyCommand);
+  configHelp(verifyCommand, verifyConfigHelp);
 }
 
 // src/commands/voice/devices.ts
@@ -20732,6 +21181,50 @@ function stop2() {
   console.log("Voice daemon stopped");
 }
 
+// src/commands/voice/voiceConfigHelp.ts
+var voiceConfigHelp = [
+  {
+    key: "voice.wakeWords",
+    setter: 'assist config set voice.wakeWords "computer"',
+    note: "wake words that activate the daemon (default: computer)"
+  },
+  {
+    key: "voice.mic",
+    setter: "assist config set voice.mic <device>",
+    note: "audio input device (defaults to the system default)"
+  },
+  {
+    key: "voice.cwd",
+    setter: "assist config set voice.cwd <path>",
+    note: "working directory commands are dispatched from"
+  },
+  {
+    key: "voice.modelsDir",
+    setter: "assist config set voice.modelsDir ~/.assist/voice/models",
+    note: "directory VAD/STT models download to"
+  },
+  {
+    key: "voice.lockDir",
+    setter: "assist config set voice.lockDir <path>",
+    note: "directory holding the daemon lock file"
+  },
+  {
+    key: "voice.submitWindows",
+    setter: 'assist config set voice.submitWindows "Code"',
+    note: "window titles where transcriptions auto-submit"
+  },
+  {
+    key: "voice.models.vad",
+    setter: "assist config set voice.models.vad <path>",
+    note: "override the voice-activity-detection model path"
+  },
+  {
+    key: "voice.models.smartTurn",
+    setter: "assist config set voice.models.smartTurn <path>",
+    note: "override the smart-turn model path"
+  }
+];
+
 // src/commands/registerVoice.ts
 function registerVoice(program2) {
   const voiceCommand = program2.command("voice").description("Voice interaction daemon for hands-free Claude commands");
@@ -20741,6 +21234,7 @@ function registerVoice(program2) {
   voiceCommand.command("status").description("Check voice daemon status").action(status);
   voiceCommand.command("devices").description("List available audio input devices").action(devices);
   voiceCommand.command("logs").description("Tail voice daemon logs").option("-n, --lines <count>", "Number of lines to show", "20").action((options2) => logs(options2));
+  configHelp(voiceCommand, voiceConfigHelp);
 }
 
 // src/commands/roam/auth.ts
@@ -20971,8 +21465,82 @@ function registerRoam(program2) {
   roamCommand.command("stop-claude-code-icon").description("Signal Claude Code session stop to Roam local API").action(stopClaudeCodeIcon);
   roamCommand.command("show-codex-icon").description("Forward Codex hook activity to Roam local API").action(showCodexIcon);
   roamCommand.command("stop-codex-icon").description("Signal Codex session stop to Roam local API").action(stopCodexIcon);
+  configHelp(roamCommand, [
+    {
+      key: "roam.clientId",
+      setter: "assist roam auth",
+      note: "OAuth client ID (written by the auth flow)"
+    },
+    {
+      key: "roam.clientSecret",
+      setter: "assist roam auth",
+      note: "OAuth client secret (written by the auth flow)"
+    },
+    {
+      key: "roam.accessToken",
+      setter: "assist roam auth",
+      note: "OAuth access token (managed by the auth flow)"
+    },
+    {
+      key: "roam.refreshToken",
+      setter: "assist roam auth",
+      note: "OAuth refresh token (managed by the auth flow)"
+    },
+    {
+      key: "roam.tokenExpiresAt",
+      setter: "assist roam auth",
+      note: "access-token expiry epoch (managed by the auth flow)"
+    }
+  ]);
 }
 
+// src/commands/rootConfigHelp.ts
+var rootConfigHelp = {
+  sync: [
+    {
+      key: "sync.autoConfirm",
+      setter: "assist config set sync.autoConfirm true",
+      note: "skip the settings.json overwrite prompt"
+    }
+  ],
+  commit: [
+    {
+      key: "commit.conventional",
+      setter: "assist config set commit.conventional true",
+      note: "enforce conventional commit message format"
+    },
+    {
+      key: "commit.pull",
+      setter: "assist config set commit.pull true",
+      note: "pull before committing"
+    },
+    {
+      key: "commit.push",
+      setter: "assist config set commit.push true",
+      note: "push after committing"
+    },
+    {
+      key: "commit.expectedBranch",
+      setter: "assist config set commit.expectedBranch main",
+      note: "warn when committing off this branch"
+    }
+  ],
+  notify: [
+    {
+      key: "notify.enabled",
+      setter: "assist config set notify.enabled false",
+      note: "enable or disable desktop notifications (default: enabled)"
+    }
+  ],
+  screenshot: [
+    {
+      key: "screenshot.outputDir",
+      setter: "assist config set screenshot.outputDir ./screenshots",
+      note: "directory screenshots are written to (default: ./screenshots)"
+    }
+  ]
+};
+
 // src/commands/run/index.ts
 import { resolve as resolve14 } from "path";
 
@@ -21137,30 +21705,32 @@ function execRunConfig(config, args) {
     config.quiet
   );
 }
-function parseBacklogRunOptions(id2, args) {
+function parseBacklogRunOptions(id, args) {
   let allowEdits = true;
   for (const arg of args) {
     if (arg === "--write" || arg === "-w") allowEdits = true;
     else if (arg === "--no-write") allowEdits = false;
     else {
-      console.error(`error: unexpected argument '${arg}' for 'run ${id2}'`);
+      console.error(`error: unexpected argument '${arg}' for 'run ${id}'`);
       process.exit(1);
     }
   }
   return { allowEdits };
 }
+async function tryBacklogRunAlias(name, args) {
+  if (!/^a?\d+$/.test(name)) return false;
+  if (lookupRunConfig(name).kind !== "not-found") return false;
+  pullIfConfigured();
+  await run2(name, parseBacklogRunOptions(name, args));
+  return true;
+}
 async function run3(name, args) {
   if (!name) {
     console.error("error: missing required argument 'name'");
     console.error(formatConfiguredCommands());
     process.exit(1);
   }
-  if (/^\d+$/.test(name) && lookupRunConfig(name).kind === "not-found") {
-    const options2 = parseBacklogRunOptions(name, args);
-    pullIfConfigured();
-    await run2(name, options2);
-    return;
-  }
+  if (await tryBacklogRunAlias(name, args)) return;
   execRunConfig(findRunConfig(name), args);
 }
 
@@ -21327,12 +21897,8 @@ function remove() {
   console.log(`Removed run configuration: ${name}`);
 }
 
-// src/commands/run/registerRun.ts
-function registerRun(program2) {
-  const runCommand = program2.command("run").description("Run a configured command from assist.yml").argument("[name]", "Name of the configured command").argument("[args...]", "Arguments to pass to the command").allowUnknownOption().addHelpText(
-    "after",
-    "\nA purely numeric name with no matching command is an alias for\n'assist backlog run <id>' (forwards --write/--no-write/-w)."
-  ).addHelpText("after", () => formatConfiguredCommands()).action((name, args) => run3(name, args));
+// src/commands/run/registerRunSubcommands.ts
+function registerRunSubcommands(runCommand) {
   runCommand.command("list").description("List configured run commands").option("-v, --verbose", "Show full command details").action((opts) => listRunConfigs(!!opts.verbose));
   runCommand.command("add").description("Add a new run configuration to assist.yml").argument("<name>", "Name for the run configuration").argument("<command>", "Command to execute").argument("[args...]", "Static args to pass to the command").option(
     "--cwd <dir>",
@@ -21345,6 +21911,25 @@ function registerRun(program2) {
   runCommand.command("remove").description("Remove a run configuration from assist.yml").argument("<name>", "Name of the run configuration to remove").action(() => remove());
 }
 
+// src/commands/run/runConfigHelp.ts
+var runConfigHelp = [
+  {
+    key: "run",
+    setter: "assist run add <name> <command>",
+    note: "configured commands runnable via assist run <name>"
+  }
+];
+
+// src/commands/run/registerRun.ts
+function registerRun(program2) {
+  const runCommand = program2.command("run").description("Run a configured command from assist.yml").argument("[name]", "Name of the configured command").argument("[args...]", "Arguments to pass to the command").allowUnknownOption().addHelpText(
+    "after",
+    "\nAn a-prefixed item id (e.g. a555) with no matching command is an alias for\n'assist backlog run <id>' (forwards --write/--no-write/-w)."
+  ).addHelpText("after", () => formatConfiguredCommands()).action((name, args) => run3(name, args));
+  configHelp(runCommand, runConfigHelp);
+  registerRunSubcommands(runCommand);
+}
+
 // src/commands/screenshot/index.ts
 import { execSync as execSync54 } from "child_process";
 import { existsSync as existsSync51, mkdirSync as mkdirSync22, unlinkSync as unlinkSync19, writeFileSync as writeFileSync39 } from "fs";
@@ -21815,7 +22400,7 @@ function broadcast(clients, msg) {
 
 // src/commands/sessions/daemon/toSessionInfo.ts
 function toSessionInfo({
-  id: id2,
+  id,
   name,
   title,
   subtitle,
@@ -21835,7 +22420,7 @@ function toSessionInfo({
   autoAdvance
 }) {
   return {
-    id: id2,
+    id,
     name,
     title,
     subtitle,
@@ -21978,10 +22563,10 @@ function shellEscape(s) {
 }
 
 // src/commands/sessions/daemon/createAssistSession.ts
-function createAssistSession(id2, assistArgs, cwd, meta) {
+function createAssistSession(id, assistArgs, cwd, meta) {
   const startedAt = Date.now();
   return {
-    id: id2,
+    id,
     name: `assist ${assistArgs.join(" ")}`,
     title: meta?.title,
     subtitle: meta?.subtitle,
@@ -21990,7 +22575,7 @@ function createAssistSession(id2, assistArgs, cwd, meta) {
     startedAt,
     runningMs: 0,
     runningSince: startedAt,
-    pty: spawnPty(["assist", ...assistArgs], cwd, id2),
+    pty: spawnPty(["assist", ...assistArgs], cwd, id),
     scrollback: "",
     assistArgs,
     cwd
@@ -21998,21 +22583,21 @@ function createAssistSession(id2, assistArgs, cwd, meta) {
 }
 
 // src/commands/sessions/daemon/dismissSession.ts
-function dismissSession(sessions, id2) {
-  const s = sessions.get(id2);
+function dismissSession(sessions, id) {
+  const s = sessions.get(id);
   if (!s) return false;
   if (s.status !== "done") s.pty?.kill();
   s.activityWatcher?.close();
   removeActivity(s.id);
   if (s.activity?.itemId != null) releaseLock(s.activity.itemId);
-  sessions.delete(id2);
-  daemonLog(`session ${id2} dismissed (${s.name})`);
+  sessions.delete(id);
+  daemonLog(`session ${id} dismissed (${s.name})`);
   return true;
 }
 function drainSessions(sessions, onDrained) {
   const names = [...sessions.values()].map((s) => s.name);
   const ids = [...sessions.keys()];
-  for (const id2 of ids) dismissSession(sessions, id2);
+  for (const id of ids) dismissSession(sessions, id);
   onDrained();
   daemonLog(
     ids.length > 0 ? `drained ${ids.length} session(s): ${names.join(", ")}` : "drained 0 sessions"
@@ -22043,10 +22628,10 @@ function spawnRun(opts) {
 }
 
 // src/commands/sessions/daemon/createSession.ts
-function sessionBase(id2, status2) {
+function sessionBase(id, status2) {
   const startedAt = Date.now();
   return {
-    id: id2,
+    id,
     status: status2,
     startedAt,
     runningMs: 0,
@@ -22056,21 +22641,21 @@ function sessionBase(id2, status2) {
     scrollback: ""
   };
 }
-function createSession(id2, prompt, cwd) {
+function createSession(id, prompt, cwd) {
   const claudeSessionId = randomUUID4();
   return {
-    ...sessionBase(id2, prompt ? "running" : "waiting"),
-    name: prompt?.slice(0, 40) || `Session ${id2}`,
+    ...sessionBase(id, prompt ? "running" : "waiting"),
+    name: prompt?.slice(0, 40) || `Session ${id}`,
     commandType: "claude",
-    pty: spawnClaude2({ prompt, cwd, sessionId: id2, claudeSessionId }),
+    pty: spawnClaude2({ prompt, cwd, sessionId: id, claudeSessionId }),
     cwd,
     claudeSessionId,
     initialPrompt: prompt
   };
 }
-function createRunSession(id2, runName, runArgs, cwd) {
+function createRunSession(id, runName, runArgs, cwd) {
   return {
-    ...sessionBase(id2, "running"),
+    ...sessionBase(id, "running"),
     name: `run: ${runName}`,
     commandType: "run",
     pty: spawnRun({ name: runName, args: runArgs, cwd }),
@@ -22118,9 +22703,9 @@ function logSpawnedSession(session) {
 
 // src/shared/db/recordPhaseActiveMs.ts
 import { sql as sql9 } from "drizzle-orm";
-async function recordPhaseActiveMs(db, itemId, phaseIdx, activeMs) {
+async function recordPhaseActiveMs(db, itemId2, phaseIdx, activeMs) {
   if (activeMs <= 0) return;
-  await db.insert(phaseUsage).values({ itemId, phaseIdx, activeMs }).onConflictDoUpdate({
+  await db.insert(phaseUsage).values({ itemId: itemId2, phaseIdx, activeMs }).onConflictDoUpdate({
     target: [phaseUsage.itemId, phaseUsage.phaseIdx],
     set: {
       activeMs: sql9`${phaseUsage.activeMs} + excluded.active_ms`
@@ -22129,10 +22714,10 @@ async function recordPhaseActiveMs(db, itemId, phaseIdx, activeMs) {
 }
 
 // src/commands/sessions/daemon/persistPhaseActiveMs.ts
-async function persistPhaseActiveMs(itemId, phaseIdx, activeMs) {
+async function persistPhaseActiveMs(itemId2, phaseIdx, activeMs) {
   try {
     if (!process.env.ASSIST_DATABASE_URL && !loadConfig().database.url) return;
-    await recordPhaseActiveMs(await getDb(), itemId, phaseIdx, activeMs);
+    await recordPhaseActiveMs(await getDb(), itemId2, phaseIdx, activeMs);
   } catch (error) {
     daemonLog(`phase-active-ms persist failed: ${String(error)}`);
   }
@@ -22189,13 +22774,13 @@ function shouldAutoRun(session) {
       run: false,
       reason: `command "${cmd ?? "(none)"}" is not draft/bug/refine`
     };
-  const itemId = session.activity?.itemId;
-  if (itemId == null)
+  const itemId2 = session.activity?.itemId;
+  if (itemId2 == null)
     return {
       run: false,
       reason: "no itemId in activity (draft did not create an item)"
     };
-  return { run: true, itemId };
+  return { run: true, itemId: itemId2 };
 }
 
 // src/commands/sessions/daemon/watchEscInterrupt.ts
@@ -22267,8 +22852,8 @@ function makeStatusChangeHandler(dismiss, notify2, reuseForRun) {
 
 // src/shared/db/recordPhaseTokens.ts
 import { sql as sql10 } from "drizzle-orm";
-async function recordPhaseTokens(db, itemId, phaseIdx, totalIn, totalOut) {
-  await db.insert(phaseUsage).values({ itemId, phaseIdx, lastTotalIn: totalIn, lastTotalOut: totalOut }).onConflictDoUpdate({
+async function recordPhaseTokens(db, itemId2, phaseIdx, totalIn, totalOut) {
+  await db.insert(phaseUsage).values({ itemId: itemId2, phaseIdx, lastTotalIn: totalIn, lastTotalOut: totalOut }).onConflictDoUpdate({
     target: [phaseUsage.itemId, phaseUsage.phaseIdx],
     set: {
       tokensDown: sql10`${phaseUsage.tokensDown} + CASE WHEN ${phaseUsage.lastTotalIn} IS NULL THEN 0 ELSE GREATEST(excluded.last_total_in - ${phaseUsage.lastTotalIn}, 0) END`,
@@ -22280,10 +22865,10 @@ async function recordPhaseTokens(db, itemId, phaseIdx, totalIn, totalOut) {
 }
 
 // src/commands/sessions/daemon/persistPhaseTokens.ts
-async function persistPhaseTokens(itemId, phaseIdx, totalIn, totalOut) {
+async function persistPhaseTokens(itemId2, phaseIdx, totalIn, totalOut) {
   try {
     if (!process.env.ASSIST_DATABASE_URL && !loadConfig().database.url) return;
-    await recordPhaseTokens(await getDb(), itemId, phaseIdx, totalIn, totalOut);
+    await recordPhaseTokens(await getDb(), itemId2, phaseIdx, totalIn, totalOut);
   } catch (error) {
     daemonLog(`phase-tokens persist failed: ${String(error)}`);
   }
@@ -22317,19 +22902,19 @@ function applyReviewPause(session, activity2) {
 
 // src/shared/db/getPhaseActiveMs.ts
 import { and as and19, eq as eq37 } from "drizzle-orm";
-async function getPhaseActiveMs(db, itemId, phaseIdx) {
+async function getPhaseActiveMs(db, itemId2, phaseIdx) {
   const [row] = await db.select({ activeMs: phaseUsage.activeMs }).from(phaseUsage).where(
-    and19(eq37(phaseUsage.itemId, itemId), eq37(phaseUsage.phaseIdx, phaseIdx))
+    and19(eq37(phaseUsage.itemId, itemId2), eq37(phaseUsage.phaseIdx, phaseIdx))
   );
   return row?.activeMs ?? 0;
 }
 
 // src/commands/sessions/daemon/loadPhaseActiveMs.ts
-async function loadPhaseActiveMs(itemId, phaseIdx) {
+async function loadPhaseActiveMs(itemId2, phaseIdx) {
   try {
     if (!process.env.ASSIST_DATABASE_URL && !loadConfig().database.url)
       return null;
-    return await getPhaseActiveMs(await getDb(), itemId, phaseIdx);
+    return await getPhaseActiveMs(await getDb(), itemId2, phaseIdx);
   } catch (error) {
     daemonLog(`phase-active-ms load failed: ${String(error)}`);
     return null;
@@ -22545,9 +23130,9 @@ function killPtyTree(pty2) {
 }
 
 // src/commands/sessions/daemon/restoreBase.ts
-function restoreBase(id2, persisted) {
+function restoreBase(id, persisted) {
   return {
-    id: id2,
+    id,
     name: persisted.name,
     title: persisted.title,
     subtitle: persisted.subtitle,
@@ -22560,9 +23145,9 @@ function restoreBase(id2, persisted) {
 }
 
 // src/commands/sessions/daemon/errorSession.ts
-function errorSession(id2, persisted, error) {
+function errorSession(id, persisted, error) {
   return {
-    ...restoreBase(id2, persisted),
+    ...restoreBase(id, persisted),
     status: "error",
     startedAt: persisted.startedAt,
     runningMs: persisted.runningMs ?? 0,
@@ -22598,28 +23183,28 @@ function restoredSession(base, persisted, pty2, status2) {
 }
 
 // src/commands/sessions/daemon/restoreInteractiveSession.ts
-function restoreInteractiveSession(id2, persisted, base) {
+function restoreInteractiveSession(id, persisted, base) {
   if (persisted.commandType !== "run" && persisted.claudeSessionId) {
-    return resumeViaClaude(id2, persisted, base);
+    return resumeViaClaude(id, persisted, base);
   }
   if (persisted.commandType === "claude") {
-    return unrecoverableClaude(id2, persisted);
+    return unrecoverableClaude(id, persisted);
   }
   return notRestoredStub(base, persisted);
 }
-function resumeViaClaude(id2, persisted, base) {
+function resumeViaClaude(id, persisted, base) {
   const idle = persisted.status === "waiting";
   const pty2 = spawnClaude2({
     resumeSessionId: persisted.claudeSessionId,
     prompt: idle ? void 0 : buildResumePrompt(),
     cwd: persisted.cwd,
-    sessionId: id2
+    sessionId: id
   });
   return idle ? waitingSession(base, persisted, pty2) : runningSession(base, persisted, pty2);
 }
-function unrecoverableClaude(id2, persisted) {
+function unrecoverableClaude(id, persisted) {
   return errorSession(
-    id2,
+    id,
     persisted,
     "no claude session id was recorded before the daemon stopped, so the conversation cannot be resumed"
   );
@@ -22639,9 +23224,9 @@ function notRestoredStub(base, persisted) {
 }
 
 // src/commands/sessions/daemon/updatedSession.ts
-function updatedSession(id2, persisted) {
+function updatedSession(id, persisted) {
   return {
-    ...restoreBase(id2, persisted),
+    ...restoreBase(id, persisted),
     status: "done",
     startedAt: persisted.startedAt,
     runningMs: persisted.runningMs ?? 0,
@@ -22654,20 +23239,20 @@ function isUpdate(persisted) {
 }
 
 // src/commands/sessions/daemon/restoreSession.ts
-function restoreSession(id2, persisted) {
-  const base = restoreBase(id2, persisted);
-  if (isUpdate(persisted)) return updatedSession(id2, persisted);
+function restoreSession(id, persisted) {
+  const base = restoreBase(id, persisted);
+  if (isUpdate(persisted)) return updatedSession(id, persisted);
   if (needsWrapperRelaunch(persisted)) {
     const idle = persisted.status === "waiting";
     const pty2 = spawnPty(
       assistResumeArgs(persisted),
       persisted.cwd,
-      id2,
+      id,
       idle ? { ASSIST_RESUME_IDLE: "1" } : void 0
     );
     return idle ? waitingSession(base, persisted, pty2) : runningSession(base, persisted, pty2);
   }
-  return restoreInteractiveSession(id2, persisted, base);
+  return restoreInteractiveSession(id, persisted, base);
 }
 function needsWrapperRelaunch(persisted) {
   return isBacklogRun(persisted) || isOnceLaunch(persisted) && !!persisted.claudeSessionId;
@@ -22683,20 +23268,20 @@ function isOnceLaunch(persisted) {
 // src/commands/sessions/daemon/restoreOne.ts
 function restoreOne(persisted, spawn12, sessions) {
   try {
-    const id2 = spawn12((sid) => restoreSession(sid, persisted));
-    logUnresumable(persisted.name, id2, sessions.get(id2));
+    const id = spawn12((sid) => restoreSession(sid, persisted));
+    logUnresumable(persisted.name, id, sessions.get(id));
   } catch (error) {
     const reason = logRestoreError(persisted.name, error);
     try {
-      spawn12((id2) => errorSession(id2, persisted, reason));
+      spawn12((id) => errorSession(id, persisted, reason));
     } catch {
     }
   }
 }
-function logUnresumable(name, id2, session) {
+function logUnresumable(name, id, session) {
   if (session?.status === "error")
     daemonLog(
-      `could not resume restored session "${name}" (id ${id2}): ${session.error}`
+      `could not resume restored session "${name}" (id ${id}): ${session.error}`
     );
 }
 function logRestoreError(name, error) {
@@ -22738,17 +23323,17 @@ function restoreAll(spawn12, sessions) {
 }
 
 // src/commands/sessions/daemon/resumeSession.ts
-function resumeSession(id2, sessionId, cwd, name) {
+function resumeSession(id, sessionId, cwd, name) {
   const startedAt = Date.now();
   return {
-    id: id2,
+    id,
     name: name ? `${name.slice(0, 36)} (R)` : `Resume ${sessionId.slice(0, 8)}`,
     commandType: "claude",
     status: "waiting",
     startedAt,
     runningMs: 0,
     runningSince: null,
-    pty: spawnClaude2({ resumeSessionId: sessionId, cwd, sessionId: id2 }),
+    pty: spawnClaude2({ resumeSessionId: sessionId, cwd, sessionId: id }),
     scrollback: "",
     cwd,
     /* why: bind the card to the conversation it is resuming so a daemon restart
@@ -22777,8 +23362,8 @@ function respawnThunk(session) {
 }
 
 // src/commands/sessions/daemon/reuseSessionForRun.ts
-function reuseSessionForRun(session, itemId, clients, onStatusChange) {
-  const assistArgs = ["backlog", "run", String(itemId)];
+function reuseSessionForRun(session, itemId2, clients, onStatusChange) {
+  const assistArgs = ["backlog", "run", String(itemId2)];
   session.pty?.kill();
   session.assistArgs = assistArgs;
   session.name = `assist ${assistArgs.join(" ")}`;
@@ -22796,7 +23381,7 @@ function reuseSessionForRun(session, itemId, clients, onStatusChange) {
   broadcast(clients, { type: "clear", sessionId: session.id });
   wirePtyEvents(session, clients, onStatusChange);
   daemonLog(
-    `session ${session.id} reused for backlog run ${itemId}: ${session.name}`
+    `session ${session.id} reused for backlog run ${itemId2}: ${session.name}`
   );
 }
 
@@ -22936,14 +23521,14 @@ async function discoverWindowsSessions(conn) {
 
 // src/commands/sessions/daemon/toWindowsSessionId.ts
 var PREFIX = "w-";
-function toWindowsSessionId(id2) {
-  return isWindowsSessionId(id2) ? id2 : `${PREFIX}${id2}`;
+function toWindowsSessionId(id) {
+  return isWindowsSessionId(id) ? id : `${PREFIX}${id}`;
 }
-function isWindowsSessionId(id2) {
-  return id2.startsWith(PREFIX);
+function isWindowsSessionId(id) {
+  return id.startsWith(PREFIX);
 }
-function stripWindowsSessionId(id2) {
-  let stripped = id2;
+function stripWindowsSessionId(id) {
+  let stripped = id;
   while (stripped.startsWith(PREFIX)) stripped = stripped.slice(PREFIX.length);
   return stripped;
 }
@@ -23038,8 +23623,8 @@ function handleSessions(state, msg) {
     id: toWindowsSessionId(s.id)
   }));
   const live = new Set(state.windowsSessions.map((s) => s.id));
-  for (const id2 of state.scrollback.keys())
-    if (!live.has(id2)) state.scrollback.delete(id2);
+  for (const id of state.scrollback.keys())
+    if (!live.has(id)) state.scrollback.delete(id);
   state.onSessionsChanged();
 }
 
@@ -23442,34 +24027,34 @@ function watchPromptSubmit(session, data, onStatusChange) {
 }
 
 // src/commands/sessions/daemon/writeToSession.ts
-function writeToSession(sessions, id2, data, onStatusChange) {
-  const s = sessions.get(id2);
+function writeToSession(sessions, id, data, onStatusChange) {
+  const s = sessions.get(id);
   if (!s || s.status === "done") return;
   s.pty?.write(data);
   watchEscInterrupt(s, data, onStatusChange);
   watchPromptSubmit(s, data, onStatusChange);
 }
-function resizeSession(sessions, id2, cols, rows) {
-  const s = sessions.get(id2);
+function resizeSession(sessions, id, cols, rows) {
+  const s = sessions.get(id);
   if (s && s.status !== "done") s.pty?.resize(cols, rows);
 }
-function setAutoRun(sessions, id2, enabled) {
-  const s = sessions.get(id2);
+function setAutoRun(sessions, id, enabled) {
+  const s = sessions.get(id);
   if (!s) return false;
   s.autoRun = enabled;
-  daemonLog(`session ${id2} autorun ${enabled ? "on" : "off"}`);
+  daemonLog(`session ${id} autorun ${enabled ? "on" : "off"}`);
   return true;
 }
-function setAutoAdvance(sessions, id2, enabled) {
-  const s = sessions.get(id2);
+function setAutoAdvance(sessions, id, enabled) {
+  const s = sessions.get(id);
   if (!s) return false;
   s.autoAdvance = enabled;
-  const itemId = s.activity?.itemId;
-  if (itemId != null) {
-    if (enabled) clearPause(itemId);
-    else requestPause(itemId);
+  const itemId2 = s.activity?.itemId;
+  if (itemId2 != null) {
+    if (enabled) clearPause(itemId2);
+    else requestPause(itemId2);
   }
-  daemonLog(`session ${id2} autoadvance ${enabled ? "on" : "off"}`);
+  daemonLog(`session ${id} autoadvance ${enabled ? "on" : "off"}`);
   return true;
 }
 
@@ -23513,58 +24098,58 @@ var SessionManager = class {
   }
   spawnWith = (create) => this.add(create(sessionLimits.nextId(this.sessions.size, this.idCounter)));
   spawn(prompt, cwd) {
-    return this.spawnWith((id2) => createSession(id2, prompt, cwd));
+    return this.spawnWith((id) => createSession(id, prompt, cwd));
   }
   spawnRun(runName, runArgs, cwd) {
-    return this.spawnWith((id2) => createRunSession(id2, runName, runArgs, cwd));
+    return this.spawnWith((id) => createRunSession(id, runName, runArgs, cwd));
   }
   spawnAssist(assistArgs, cwd, meta) {
     return this.spawnWith(
-      (id2) => createAssistSession(id2, assistArgs, cwd, meta)
+      (id) => createAssistSession(id, assistArgs, cwd, meta)
     );
   }
   resume(sessionId, cwd, name) {
-    return this.spawnWith((id2) => resumeSession(id2, sessionId, cwd, name));
+    return this.spawnWith((id) => resumeSession(id, sessionId, cwd, name));
   }
   onStatusChange = makeStatusChangeHandler(
-    (id2) => this.dismissSession(id2),
+    (id) => this.dismissSession(id),
     () => this.notify(),
-    (session, itemId) => reuseSessionForRun(session, itemId, this.clients, this.onStatusChange)
+    (session, itemId2) => reuseSessionForRun(session, itemId2, this.clients, this.onStatusChange)
   );
   wire(session) {
     this.sessions.set(session.id, session);
     wirePtyEvents(session, this.clients, this.onStatusChange);
     this.notify();
   }
-  writeToSession(id2, data) {
-    writeToSession(this.sessions, id2, data, this.onStatusChange);
+  writeToSession(id, data) {
+    writeToSession(this.sessions, id, data, this.onStatusChange);
   }
-  resizeSession(id2, cols, rows) {
-    resizeSession(this.sessions, id2, cols, rows);
+  resizeSession(id, cols, rows) {
+    resizeSession(this.sessions, id, cols, rows);
   }
-  retrySession(id2) {
-    const s = this.sessions.get(id2);
+  retrySession(id) {
+    const s = this.sessions.get(id);
     if (s && retrySession(s, this.clients, this.onStatusChange)) this.notify();
   }
-  restart(id2) {
-    const s = this.sessions.get(id2);
+  restart(id) {
+    const s = this.sessions.get(id);
     if (s && restartSession(s, this.clients, this.onStatusChange))
       this.notify();
   }
-  dismissSession = (id2) => {
-    if (dismissSession(this.sessions, id2)) this.notify();
+  dismissSession = (id) => {
+    if (dismissSession(this.sessions, id)) this.notify();
   };
-  setAutoRun(id2, enabled) {
-    if (setAutoRun(this.sessions, id2, enabled)) this.notify();
+  setAutoRun(id, enabled) {
+    if (setAutoRun(this.sessions, id, enabled)) this.notify();
   }
-  setAutoAdvance(id2, enabled) {
-    if (setAutoAdvance(this.sessions, id2, enabled)) this.notify();
+  setAutoAdvance(id, enabled) {
+    if (setAutoAdvance(this.sessions, id, enabled)) this.notify();
   }
-  setStatus(id2, status2) {
-    const session = this.sessions.get(id2);
+  setStatus(id, status2) {
+    const session = this.sessions.get(id);
     if (!session) {
       daemonLog(
-        `set-status for unknown session id=${id2} status=${status2} (no live session; ignoring)`
+        `set-status for unknown session id=${id} status=${status2} (no live session; ignoring)`
       );
       return;
     }
@@ -23637,7 +24222,7 @@ function deriveSessionType(commandName, name) {
 
 // src/commands/sessions/shared/backlogRunMarkers.ts
 function backlogRunMarkers(text9) {
-  const match = text9.match(/backlog item #(\d+):[ \t]*([^\n]*)/);
+  const match = text9.match(/backlog item a(\d+):[ \t]*([^\n]*)/);
   if (!match) return { commandName: "", commandArgs: "" };
   const title = match[2].trim();
   return {
@@ -24057,7 +24642,7 @@ function onListening(manager, checkAutoExit) {
   process.on("exit", cleanupOwnedFiles);
   const restored = manager.restore();
   const liveIds = new Set(manager.listSessions().map((s) => s.id));
-  manager.active.restore((id2) => liveIds.has(id2));
+  manager.active.restore((id) => liveIds.has(id));
   daemonLog(
     restored.length > 0 ? `restored ${restored.length} session(s): ${restored.join(", ")}` : "no persisted sessions to restore"
   );
@@ -24253,27 +24838,27 @@ function truncate3(text9, maxChars = 500) {
 function scanSessionBacklogRefs(filePath) {
   const ids = /* @__PURE__ */ new Set();
   for (const text9 of iterateUserMessages(filePath, Number.MAX_SAFE_INTEGER)) {
-    for (const id2 of extractBacklogIds(text9)) {
-      ids.add(id2);
+    for (const id of extractBacklogIds(text9)) {
+      ids.add(id);
     }
   }
   return [...ids].sort((a, b) => a - b);
 }
 function extractBacklogIds(text9) {
   const ids = [];
-  for (const m of text9.matchAll(/backlog\s+run\s+(\d+)/gi)) {
+  for (const m of text9.matchAll(/backlog\s+run\s+a(\d+)/gi)) {
     ids.push(Number.parseInt(m[1], 10));
   }
-  for (const m of text9.matchAll(/backlog\s+(?:item\s+)?#(\d+)/gi)) {
+  for (const m of text9.matchAll(/backlog\s+(?:item\s+)?a(\d+)/gi)) {
     ids.push(Number.parseInt(m[1], 10));
   }
-  for (const m of text9.matchAll(/backlog\s+phase-done\s+(\d+)/gi)) {
+  for (const m of text9.matchAll(/backlog\s+phase-done\s+a(\d+)/gi)) {
     ids.push(Number.parseInt(m[1], 10));
   }
-  for (const m of text9.matchAll(/backlog\s+comment\s+(\d+)/gi)) {
+  for (const m of text9.matchAll(/backlog\s+comment\s+a(\d+)/gi)) {
     ids.push(Number.parseInt(m[1], 10));
   }
-  for (const m of text9.matchAll(/(?:^|[\s(])#(\d{1,4})(?=[\s).,;:!?]|$)/gm)) {
+  for (const m of text9.matchAll(/(?:^|[\s(])a(\d{1,4})(?=[\s).,;:!?]|$)/gm)) {
     ids.push(Number.parseInt(m[1], 10));
   }
   return ids;
@@ -24306,7 +24891,7 @@ function buildPrompt2(firstMessage, backlogIds) {
     "Return ONLY the summary, no quotes or explanation."
   ];
   if (backlogIds.length > 0) {
-    const refs = backlogIds.map((id2) => `#${id2}`).join(", ");
+    const refs = backlogIds.map((id) => formatItemId(id)).join(", ");
     parts.push(
       `The session references backlog item(s) ${refs}. Start the summary with "Backlog ${refs} \u2014" if relevant.`
     );
@@ -24381,6 +24966,28 @@ function registerSessions(program2) {
   cmd.command("set-status <status>").description(
     "Report the current session's status to the sessions daemon (used by Claude Code hooks)"
   ).action(setSessionStatus);
+  configHelp(cmd, [
+    {
+      key: "sessions.windowsProjectsRoot",
+      setter: "assist config set sessions.windowsProjectsRoot /mnt/c/Users/you/.claude/projects",
+      note: "WSL path to the Windows .claude/projects root to discover"
+    },
+    {
+      key: "sessions.windowsDaemonHost",
+      setter: "assist config set sessions.windowsDaemonHost 127.0.0.1",
+      note: "host the WSL daemon dials to reach the Windows daemon (default: 127.0.0.1)"
+    },
+    {
+      key: "sessions.windowsDaemonPort",
+      setter: "assist config set sessions.windowsDaemonPort 51764",
+      note: "TCP port the Windows daemon listens on (default: 51764)"
+    },
+    {
+      key: "sessions.windowsVersionCheck",
+      setter: "assist config set sessions.windowsVersionCheck block",
+      note: "Windows daemon version mismatch handling: block | warn | off"
+    }
+  ]);
 }
 
 // src/commands/statusLine.ts
@@ -24697,12 +25304,25 @@ async function update2() {
   await restartDaemonAfterUpdate();
 }
 
+// src/reportCliError.ts
+import chalk198 from "chalk";
+function reportCliError(error) {
+  if (error instanceof InvalidItemIdError) {
+    console.error(chalk198.red(error.message));
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+}
+
 // src/index.ts
 var program = new Command();
 program.name("assist").description("CLI application").version(package_default.version).option("--no-open", "Do not open a browser on startup").action((options2) => web({ port: "3100", open: options2.open }));
-program.command("sync").description("Copy command files to ~/.claude/commands").option("-y, --yes", "Overwrite settings.json without prompting").action((options2) => sync(options2));
+var syncCommand = program.command("sync").description("Copy command files to ~/.claude/commands").option("-y, --yes", "Overwrite settings.json without prompting").action((options2) => sync(options2));
+configHelp(syncCommand, rootConfigHelp.sync);
 program.command("init").description("Initialize VS Code and verify configurations").action(init5);
-program.command("commit").description("Create a git commit with validation").argument("<args...>", "status | <message> [files...]").action(commit);
+var commitCommand = program.command("commit").description("Create a git commit with validation").argument("<args...>", "status | <message> [files...]").action(commit);
+configHelp(commitCommand, rootConfigHelp.commit);
 registerConfig(program);
 registerRun(program);
 registerNew(program);
@@ -24711,12 +25331,14 @@ lintCommand.command("init").description("Initialize oxlint with baseline linter
 var vscodeCommand = program.command("vscode").description("VS Code configuration utilities");
 vscodeCommand.command("init").description("Add VS Code configuration files").action(init4);
 program.command("status-line").description("Format Claude Code status line from JSON stdin").action(statusLine);
-program.command("notify").description(
+var notifyCommand = program.command("notify").description(
   "Show notification from Claude Code hook (reads JSON from stdin)"
 ).action(notify);
+configHelp(notifyCommand, rootConfigHelp.notify);
 program.command("update").description("Update assist to the latest version and sync commands").action(update2);
 program.command("coverage").description("Print global statement coverage percentage").action(coverage);
-program.command("screenshot").description("Capture a screenshot of a running application window").argument("<process>", "Name of the running process (e.g. notepad, code)").action(screenshot);
+var screenshotCommand = program.command("screenshot").description("Capture a screenshot of a running application window").argument("<process>", "Name of the running process (e.g. notepad, code)").action(screenshot);
+configHelp(screenshotCommand, rootConfigHelp.screenshot);
 registerActivity(program);
 registerBackup(program);
 registerCliHook(program);
@@ -24751,7 +25373,4 @@ registerPrompts(program);
 registerDeny(program);
 registerLaunch(program);
 registerSignal(program);
-program.parseAsync().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-}).finally(() => closeDb());
+program.parseAsync().catch(reportCliError).finally(() => closeDb());