@anthropologies/claudestory 0.1.7 → 0.1.9

package/dist/cli.js

@@ -100,7 +100,7 @@ var init_project_root_discovery = __esm({
 
 // src/models/types.ts
 import { z } from "zod";
-var TICKET_ID_REGEX, ISSUE_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, ISSUE_STATUSES, ISSUE_SEVERITIES, OUTPUT_FORMATS, DATE_REGEX, DateSchema, TicketIdSchema, IssueIdSchema;
+var TICKET_ID_REGEX, ISSUE_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, ISSUE_STATUSES, ISSUE_SEVERITIES, NOTE_STATUSES, NOTE_ID_REGEX, NoteIdSchema, OUTPUT_FORMATS, DATE_REGEX, DateSchema, TicketIdSchema, IssueIdSchema;
 var init_types = __esm({
   "src/models/types.ts"() {
     "use strict";
@@ -111,6 +111,9 @@ var init_types = __esm({
     TICKET_TYPES = ["task", "feature", "chore"];
     ISSUE_STATUSES = ["open", "inprogress", "resolved"];
     ISSUE_SEVERITIES = ["critical", "high", "medium", "low"];
+    NOTE_STATUSES = ["active", "archived"];
+    NOTE_ID_REGEX = /^N-\d+$/;
+    NoteIdSchema = z.string().regex(NOTE_ID_REGEX, "Note ID must match N-NNN");
     OUTPUT_FORMATS = ["json", "md"];
     DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
     DateSchema = z.string().regex(DATE_REGEX, "Date must be YYYY-MM-DD").refine(
@@ -184,60 +187,86 @@ var init_issue = __esm({
   }
 });
 
-// src/models/roadmap.ts
+// src/models/note.ts
 import { z as z4 } from "zod";
+var NoteSchema;
+var init_note = __esm({
+  "src/models/note.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_types();
+    NoteSchema = z4.object({
+      id: NoteIdSchema,
+      title: z4.preprocess((v) => v ?? null, z4.string().nullable()),
+      content: z4.string().refine((v) => v.trim().length > 0, "Content cannot be empty"),
+      tags: z4.preprocess(
+        (v) => {
+          const raw = Array.isArray(v) ? v : [];
+          return raw.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "")).filter((t) => t.length > 0).filter((t, i, a) => a.indexOf(t) === i);
+        },
+        z4.array(z4.string())
+      ),
+      status: z4.enum(NOTE_STATUSES),
+      createdDate: DateSchema,
+      updatedDate: DateSchema
+    }).passthrough();
+  }
+});
+
+// src/models/roadmap.ts
+import { z as z5 } from "zod";
 var BlockerSchema, PhaseSchema, RoadmapSchema;
 var init_roadmap = __esm({
   "src/models/roadmap.ts"() {
     "use strict";
     init_esm_shims();
     init_types();
-    BlockerSchema = z4.object({
-      name: z4.string().min(1),
+    BlockerSchema = z5.object({
+      name: z5.string().min(1),
       // Legacy format (pre-T-082)
-      cleared: z4.boolean().optional(),
+      cleared: z5.boolean().optional(),
       // New date-based format (T-082 migration)
       createdDate: DateSchema.optional(),
       clearedDate: DateSchema.nullable().optional(),
       // Present in all current data but optional for future minimal blockers
-      note: z4.string().nullable().optional()
+      note: z5.string().nullable().optional()
     }).passthrough();
-    PhaseSchema = z4.object({
-      id: z4.string().min(1),
-      label: z4.string(),
-      name: z4.string(),
-      description: z4.string(),
-      summary: z4.string().optional()
+    PhaseSchema = z5.object({
+      id: z5.string().min(1),
+      label: z5.string(),
+      name: z5.string(),
+      description: z5.string(),
+      summary: z5.string().optional()
     }).passthrough();
-    RoadmapSchema = z4.object({
-      title: z4.string(),
+    RoadmapSchema = z5.object({
+      title: z5.string(),
       date: DateSchema,
-      phases: z4.array(PhaseSchema),
-      blockers: z4.array(BlockerSchema)
+      phases: z5.array(PhaseSchema),
+      blockers: z5.array(BlockerSchema)
     }).passthrough();
   }
 });
 
 // src/models/config.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var FeaturesSchema, ConfigSchema;
 var init_config = __esm({
   "src/models/config.ts"() {
     "use strict";
     init_esm_shims();
-    FeaturesSchema = z5.object({
-      tickets: z5.boolean(),
-      issues: z5.boolean(),
-      handovers: z5.boolean(),
-      roadmap: z5.boolean(),
-      reviews: z5.boolean()
+    FeaturesSchema = z6.object({
+      tickets: z6.boolean(),
+      issues: z6.boolean(),
+      handovers: z6.boolean(),
+      roadmap: z6.boolean(),
+      reviews: z6.boolean()
     }).passthrough();
-    ConfigSchema = z5.object({
-      version: z5.number().int().min(1),
-      schemaVersion: z5.number().int().optional(),
-      project: z5.string().min(1),
-      type: z5.string(),
-      language: z5.string(),
+    ConfigSchema = z6.object({
+      version: z6.number().int().min(1),
+      schemaVersion: z6.number().int().optional(),
+      project: z6.string().min(1),
+      type: z6.string(),
+      language: z6.string(),
       features: FeaturesSchema
     }).passthrough();
   }
@@ -253,6 +282,7 @@ var init_project_state = __esm({
       // --- Public raw inputs (readonly) ---
       tickets;
       issues;
+      notes;
       roadmap;
       config;
       handoverFilenames;
@@ -267,15 +297,19 @@ var init_project_state = __esm({
       reverseBlocksMap;
       ticketsByID;
       issuesByID;
+      notesByID;
       // --- Counts ---
       totalTicketCount;
       openTicketCount;
       completeTicketCount;
       openIssueCount;
       issuesBySeverity;
+      activeNoteCount;
+      archivedNoteCount;
       constructor(input) {
         this.tickets = input.tickets;
         this.issues = input.issues;
+        this.notes = input.notes;
         this.roadmap = input.roadmap;
         this.config = input.config;
         this.handoverFilenames = input.handoverFilenames;
@@ -341,6 +375,11 @@ var init_project_state = __esm({
           iByID.set(i.id, i);
         }
         this.issuesByID = iByID;
+        const nByID = /* @__PURE__ */ new Map();
+        for (const n of input.notes) {
+          nByID.set(n.id, n);
+        }
+        this.notesByID = nByID;
         this.totalTicketCount = input.tickets.length;
         this.openTicketCount = input.tickets.filter(
           (t) => t.status !== "complete"
@@ -358,6 +397,12 @@ var init_project_state = __esm({
           }
         }
         this.issuesBySeverity = bySev;
+        this.activeNoteCount = input.notes.filter(
+          (n) => n.status === "active"
+        ).length;
+        this.archivedNoteCount = input.notes.filter(
+          (n) => n.status === "archived"
+        ).length;
       }
       // --- Query Methods ---
       isUmbrella(ticket) {
@@ -404,6 +449,9 @@ var init_project_state = __esm({
       issueByID(id) {
         return this.issuesByID.get(id);
       }
+      noteByID(id) {
+        return this.notesByID.get(id);
+      }
       // --- Deletion Safety ---
       /** IDs of tickets that list `ticketId` in their blockedBy. */
       ticketsBlocking(ticketId) {
@@ -523,7 +571,8 @@ import {
   stat,
   realpath,
   lstat,
-  open
+  open,
+  mkdir
 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 import { join as join3, resolve as resolve2, relative as relative2, extname as extname2, dirname as dirname2, basename } from "path";
@@ -581,6 +630,12 @@ async function loadProject(root, options) {
     IssueSchema,
     warnings
   );
+  const notes = await loadDirectory(
+    join3(wrapDir, "notes"),
+    absRoot,
+    NoteSchema,
+    warnings
+  );
   const handoversDir = join3(wrapDir, "handovers");
   const handoverFilenames = await listHandovers(
     handoversDir,
@@ -601,6 +656,7 @@ async function loadProject(root, options) {
   const state = new ProjectState({
     tickets,
     issues,
+    notes,
     roadmap,
     config,
     handoverFilenames
@@ -727,6 +783,43 @@ async function deleteIssue(id, root) {
     await unlink(targetPath);
   });
 }
+async function writeNoteUnlocked(note, root) {
+  const parsed = NoteSchema.parse(note);
+  if (!NOTE_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "notes", `${parsed.id}.json`);
+  await mkdir(dirname2(targetPath), { recursive: true });
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function deleteNote(id, root) {
+  if (!NOTE_ID_REGEX.test(id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "notes", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    try {
+      await stat(targetPath);
+    } catch {
+      throw new ProjectLoaderError(
+        "not_found",
+        `Note file not found: notes/${id}.json`
+      );
+    }
+    await unlink(targetPath);
+  });
+}
 async function withProjectLock(root, options, handler) {
   const absRoot = resolve2(root);
   const wrapDir = join3(absRoot, ".story");
@@ -884,8 +977,9 @@ async function loadProjectUnlocked(absRoot) {
   const warnings = [];
   const tickets = await loadDirectory(join3(wrapDir, "tickets"), absRoot, TicketSchema, warnings);
   const issues = await loadDirectory(join3(wrapDir, "issues"), absRoot, IssueSchema, warnings);
+  const notes = await loadDirectory(join3(wrapDir, "notes"), absRoot, NoteSchema, warnings);
   const handoverFilenames = await listHandovers(join3(wrapDir, "handovers"), absRoot, warnings);
-  const state = new ProjectState({ tickets, issues, roadmap, config, handoverFilenames });
+  const state = new ProjectState({ tickets, issues, notes, roadmap, config, handoverFilenames });
   return { state, warnings };
 }
 async function loadSingletonFile(filename, wrapDir, root, schema) {
@@ -1076,6 +1170,7 @@ var init_project_loader = __esm({
     init_esm_shims();
     init_ticket();
     init_issue();
+    init_note();
     init_roadmap();
     init_config();
     init_types();
@@ -1180,6 +1275,51 @@ async function parseHandoverFilename(raw, handoversDir) {
   }
   return raw;
 }
+function parseNoteId(raw) {
+  const result = NoteIdSchema.safeParse(raw);
+  if (!result.success) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid note ID "${raw}": ${formatZodError(result.error)}`
+    );
+  }
+  return result.data;
+}
+function normalizeTags(raw) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of raw) {
+    if (typeof item !== "string") continue;
+    const normalized = item.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    if (normalized && !seen.has(normalized)) {
+      seen.add(normalized);
+      result.push(normalized);
+    }
+  }
+  return result;
+}
+async function readStdinContent() {
+  if (process.stdin.isTTY) {
+    throw new CliValidationError(
+      "invalid_input",
+      "--stdin requires piped input, not a TTY"
+    );
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const content = Buffer.concat(
+    chunks.map((c) => Buffer.isBuffer(c) ? c : Buffer.from(c))
+  ).toString("utf-8");
+  if (!content.trim()) {
+    throw new CliValidationError(
+      "invalid_input",
+      "Stdin content is empty"
+    );
+  }
+  return content;
+}
 var CliValidationError;
 var init_helpers = __esm({
   "src/cli/helpers.ts"() {
@@ -1232,6 +1372,53 @@ function nextTicket(state) {
   }
   return { kind: "empty_project" };
 }
+function nextTickets(state, count) {
+  const effectiveCount = Math.max(1, count);
+  const phases = state.roadmap.phases;
+  if (phases.length === 0 || state.leafTickets.length === 0) {
+    return { kind: "empty_project" };
+  }
+  const candidates = [];
+  const skippedBlockedPhases = [];
+  let allPhasesComplete = true;
+  for (const phase of phases) {
+    if (candidates.length >= effectiveCount) break;
+    const leaves = state.phaseTickets(phase.id);
+    if (leaves.length === 0) continue;
+    const status = state.phaseStatus(phase.id);
+    if (status === "complete") continue;
+    allPhasesComplete = false;
+    const incompleteLeaves = leaves.filter((t) => t.status !== "complete");
+    const unblocked = incompleteLeaves.filter((t) => !state.isBlocked(t));
+    if (unblocked.length === 0) {
+      skippedBlockedPhases.push({
+        phaseId: phase.id,
+        blockedCount: incompleteLeaves.length
+      });
+      continue;
+    }
+    const remaining = effectiveCount - candidates.length;
+    for (const ticket of unblocked.slice(0, remaining)) {
+      const impact = ticketsUnblockedBy(ticket.id, state);
+      const progress = ticket.parentTicket ? umbrellaProgress(ticket.parentTicket, state) : null;
+      candidates.push({
+        ticket,
+        unblockImpact: { ticketId: ticket.id, wouldUnblock: impact },
+        umbrellaProgress: progress
+      });
+    }
+  }
+  if (candidates.length > 0) {
+    return { kind: "found", candidates, skippedBlockedPhases };
+  }
+  if (skippedBlockedPhases.length > 0) {
+    return { kind: "all_blocked", phases: skippedBlockedPhases };
+  }
+  if (allPhasesComplete) {
+    return { kind: "all_complete" };
+  }
+  return { kind: "empty_project" };
+}
 function blockedTickets(state) {
   return state.leafTickets.filter(
     (t) => t.status !== "complete" && state.isBlocked(t)
@@ -1279,6 +1466,9 @@ function isBlockerCleared(blocker) {
   if (blocker.clearedDate != null) return true;
   return false;
 }
+function descendantLeaves(ticketId, state) {
+  return collectDescendantLeaves(ticketId, state, /* @__PURE__ */ new Set());
+}
 function collectDescendantLeaves(ticketId, state, visited) {
   if (visited.has(ticketId)) return [];
   visited.add(ticketId);
@@ -1318,9 +1508,17 @@ __export(output_formatter_exports, {
   formatIssue: () => formatIssue,
   formatIssueList: () => formatIssueList,
   formatNextTicketOutcome: () => formatNextTicketOutcome,
+  formatNextTicketsOutcome: () => formatNextTicketsOutcome,
+  formatNote: () => formatNote,
+  formatNoteCreateResult: () => formatNoteCreateResult,
+  formatNoteDeleteResult: () => formatNoteDeleteResult,
+  formatNoteList: () => formatNoteList,
+  formatNoteUpdateResult: () => formatNoteUpdateResult,
   formatPhaseList: () => formatPhaseList,
   formatPhaseTickets: () => formatPhaseTickets,
   formatRecap: () => formatRecap,
+  formatRecommendations: () => formatRecommendations,
+  formatReference: () => formatReference,
   formatSnapshotResult: () => formatSnapshotResult,
   formatStatus: () => formatStatus,
   formatTicket: () => formatTicket,
@@ -1372,6 +1570,8 @@ function formatStatus(state, format) {
     openTickets: state.leafTicketCount - state.completeLeafTicketCount,
     blockedTickets: state.blockedCount,
     openIssues: state.openIssueCount,
+    activeNotes: state.activeNoteCount,
+    archivedNotes: state.archivedNoteCount,
     handovers: state.handoverFilenames.length,
     phases: phases.map((p) => ({
       id: p.phase.id,
@@ -1388,6 +1588,7 @@ function formatStatus(state, format) {
     "",
     `Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete, ${state.blockedCount} blocked`,
     `Issues: ${state.openIssueCount} open`,
+    `Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`,
     `Handovers: ${state.handoverFilenames.length}`,
     "",
     "## Phases",
@@ -1484,6 +1685,52 @@ function formatNextTicketOutcome(outcome, state, format) {
     }
   }
 }
+function formatNextTicketsOutcome(outcome, state, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(outcome), null, 2);
+  }
+  switch (outcome.kind) {
+    case "empty_project":
+      return "No phased tickets found.";
+    case "all_complete":
+      return "All phases complete.";
+    case "all_blocked": {
+      const details = outcome.phases.map((p) => `${escapeMarkdownInline(p.phaseId)} (${p.blockedCount} blocked)`).join(", ");
+      return `All incomplete tickets are blocked across ${outcome.phases.length} phase${outcome.phases.length === 1 ? "" : "s"}: ${details}`;
+    }
+    case "found": {
+      const { candidates, skippedBlockedPhases } = outcome;
+      const lines = [];
+      for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        const t = c.ticket;
+        if (i > 0) lines.push("", "---", "");
+        if (candidates.length === 1) {
+          lines.push(`# Next: ${escapeMarkdownInline(t.id)} \u2014 ${escapeMarkdownInline(t.title)}`);
+        } else {
+          lines.push(`# ${i + 1}. ${escapeMarkdownInline(t.id)} \u2014 ${escapeMarkdownInline(t.title)}`);
+        }
+        lines.push("", `Phase: ${t.phase ?? "none"} | Order: ${t.order} | Type: ${t.type}`);
+        if (c.unblockImpact.wouldUnblock.length > 0) {
+          const ids = c.unblockImpact.wouldUnblock.map((u) => u.id).join(", ");
+          lines.push(`Completing this unblocks: ${ids}`);
+        }
+        if (c.umbrellaProgress) {
+          const p = c.umbrellaProgress;
+          lines.push(`Parent progress: ${p.complete}/${p.total} complete (${p.status})`);
+        }
+        if (t.description) {
+          lines.push("", fencedBlock(t.description));
+        }
+      }
+      if (skippedBlockedPhases.length > 0) {
+        const details = skippedBlockedPhases.map((p) => `${escapeMarkdownInline(p.phaseId)} (${p.blockedCount} blocked)`).join(", ");
+        lines.push("", "---", "", `Skipped blocked phases: ${details}`);
+      }
+      return lines.join("\n");
+    }
+  }
+}
 function formatTicketList(tickets, format) {
   if (format === "json") {
     return JSON.stringify(successEnvelope(tickets), null, 2);
@@ -1598,6 +1845,56 @@ function formatBlockerList(roadmap, format) {
   }
   return lines.join("\n");
 }
+function formatNote(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  const title = note.title ?? `${note.createdDate} \u2014 ${note.id}`;
+  const statusBadge = note.status === "archived" ? " (archived)" : "";
+  const lines = [
+    `# ${escapeMarkdownInline(title)}${statusBadge}`,
+    "",
+    `Status: ${note.status}`
+  ];
+  if (note.tags.length > 0) {
+    lines.push(`Tags: ${note.tags.join(", ")}`);
+  }
+  lines.push(`Created: ${note.createdDate} | Updated: ${note.updatedDate}`);
+  lines.push("", fencedBlock(note.content));
+  return lines.join("\n");
+}
+function formatNoteList(notes, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(notes), null, 2);
+  }
+  if (notes.length === 0) return "No notes found.";
+  const lines = [];
+  for (const n of notes) {
+    const title = n.title ?? n.id;
+    const status = n.status === "archived" ? "[x]" : "[ ]";
+    const tagInfo = n.status === "archived" ? " (archived)" : n.tags.length > 0 ? ` (${n.tags.join(", ")})` : "";
+    lines.push(`${status} ${n.id}: ${escapeMarkdownInline(title)}${tagInfo}`);
+  }
+  return lines.join("\n");
+}
+function formatNoteCreateResult(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  return `Created note ${note.id}: ${note.title ?? note.id}`;
+}
+function formatNoteUpdateResult(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  return `Updated note ${note.id}: ${note.title ?? note.id}`;
+}
+function formatNoteDeleteResult(id, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ id, deleted: true }), null, 2);
+  }
+  return `Deleted note ${id}.`;
+}
 function formatError(code, message, format) {
   if (format === "json") {
     return JSON.stringify(errorEnvelope(code, message), null, 2);
@@ -1612,6 +1909,7 @@ function formatInitResult(result, format) {
   if (result.warnings.length > 0) {
     lines.push("", `Warning: ${result.warnings.length} corrupt file(s) found. Run \`claudestory validate\` to inspect.`);
   }
+  lines.push("", "Tip: Run `claudestory setup-skill` to install the /story skill for Claude Code.");
   return lines.join("\n");
 }
 function formatHandoverList(filenames, format) {
@@ -1675,7 +1973,7 @@ function formatRecap(recap, state, format) {
         }
       }
       const ticketChanges = changes.tickets;
-      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0) {
+      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0 || ticketChanges.descriptionChanged.length > 0) {
         lines.push("");
         lines.push("## Tickets");
         for (const t of ticketChanges.statusChanged) {
@@ -1687,9 +1985,12 @@ function formatRecap(recap, state, format) {
         for (const t of ticketChanges.removed) {
           lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **removed**`);
         }
+        for (const t of ticketChanges.descriptionChanged) {
+          lines.push(`- ${t.id}: description updated`);
+        }
       }
       const issueChanges = changes.issues;
-      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0) {
+      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0 || issueChanges.impactChanged.length > 0) {
         lines.push("");
         lines.push("## Issues");
         for (const i of issueChanges.resolved) {
@@ -1701,6 +2002,9 @@ function formatRecap(recap, state, format) {
         for (const i of issueChanges.added) {
           lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **new**`);
         }
+        for (const i of issueChanges.impactChanged) {
+          lines.push(`- ${i.id}: impact updated`);
+        }
       }
       if (changes.blockers.added.length > 0 || changes.blockers.cleared.length > 0) {
         lines.push("");
@@ -1712,6 +2016,19 @@ function formatRecap(recap, state, format) {
           lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
         }
       }
+      if (changes.notes && (changes.notes.added.length > 0 || changes.notes.removed.length > 0 || changes.notes.updated.length > 0)) {
+        lines.push("");
+        lines.push("## Notes");
+        for (const n of changes.notes.added) {
+          lines.push(`- ${n.id}: added`);
+        }
+        for (const n of changes.notes.removed) {
+          lines.push(`- ${n.id}: removed`);
+        }
+        for (const n of changes.notes.updated) {
+          lines.push(`- ${n.id}: updated (${n.changedFields.join(", ")})`);
+        }
+      }
     }
   }
   const actions = recap.suggestedActions;
@@ -1850,6 +2167,12 @@ function formatFullExport(state, format) {
           severity: i.severity,
           status: i.status
         })),
+        notes: state.notes.map((n) => ({
+          id: n.id,
+          title: n.title,
+          status: n.status,
+          tags: n.tags
+        })),
         blockers: state.roadmap.blockers.map((b) => ({
           name: b.name,
           cleared: isBlockerCleared(b),
@@ -1865,6 +2188,7 @@ function formatFullExport(state, format) {
   lines.push("");
   lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete`);
   lines.push(`Issues: ${state.openIssueCount} open`);
+  lines.push(`Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`);
   lines.push("");
   lines.push("## Phases");
   for (const p of phases) {
@@ -1891,6 +2215,16 @@ function formatFullExport(state, format) {
       lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}${resolved}`);
     }
   }
+  const activeNotes = state.notes.filter((n) => n.status === "active");
+  if (activeNotes.length > 0) {
+    lines.push("");
+    lines.push("## Notes");
+    for (const n of activeNotes) {
+      const title = n.title ?? n.id;
+      const tagInfo = n.tags.length > 0 ? ` (${n.tags.join(", ")})` : "";
+      lines.push(`- ${n.id}: ${escapeMarkdownInline(title)}${tagInfo}`);
+    }
+  }
   const blockers = state.roadmap.blockers;
   if (blockers.length > 0) {
     lines.push("");
@@ -1903,7 +2237,7 @@ function formatFullExport(state, format) {
   return lines.join("\n");
 }
 function hasAnyChanges(diff) {
-  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0;
+  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.tickets.descriptionChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.issues.impactChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0 || (diff.notes?.added.length ?? 0) > 0 || (diff.notes?.removed.length ?? 0) > 0 || (diff.notes?.updated.length ?? 0) > 0;
 }
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
@@ -1914,6 +2248,79 @@ function formatTicketOneLiner(t, state) {
   const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
   return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
 }
+function formatReference(commands, mcpTools, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ commands, mcpTools }), null, 2);
+  }
+  const lines = [];
+  lines.push("# claudestory Reference");
+  lines.push("");
+  lines.push("## CLI Commands");
+  lines.push("");
+  for (const cmd of commands) {
+    lines.push(`### ${cmd.name}`);
+    lines.push(cmd.description);
+    lines.push("");
+    lines.push("```");
+    lines.push(cmd.usage);
+    lines.push("```");
+    lines.push("");
+  }
+  lines.push("## MCP Tools");
+  lines.push("");
+  for (const tool of mcpTools) {
+    const params = tool.params?.length ? ` (${tool.params.join(", ")})` : "";
+    lines.push(`- **${tool.name}**${params} \u2014 ${tool.description}`);
+  }
+  lines.push("");
+  lines.push("## Common Workflows");
+  lines.push("");
+  lines.push("### Session Start");
+  lines.push("1. `claudestory status` \u2014 project overview");
+  lines.push("2. `claudestory recap` \u2014 what changed since last snapshot");
+  lines.push("3. `claudestory handover latest` \u2014 last session context");
+  lines.push("4. `claudestory ticket next` \u2014 what to work on");
+  lines.push("");
+  lines.push("### Session End");
+  lines.push("1. `claudestory snapshot` \u2014 save state for diffs");
+  lines.push("2. `claudestory handover create --content <md>` \u2014 write session handover");
+  lines.push("");
+  lines.push("### Project Setup");
+  lines.push("1. `npm install -g @anthropologies/claudestory` \u2014 install CLI");
+  lines.push("2. `claudestory setup-skill` \u2014 install /story skill for Claude Code");
+  lines.push("3. `claudestory init --name my-project` \u2014 initialize .story/ in your project");
+  lines.push("");
+  lines.push("## Troubleshooting");
+  lines.push("");
+  lines.push("- **MCP not connected:** Run `claude mcp add claudestory -s user -- claudestory --mcp`");
+  lines.push("- **CLI not found:** Run `npm install -g @anthropologies/claudestory`");
+  lines.push("- **Stale data:** Run `claudestory validate` to check integrity");
+  lines.push("- **/story not available:** Run `claudestory setup-skill` to install the skill");
+  return lines.join("\n");
+}
+function formatRecommendations(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  if (result.recommendations.length === 0) {
+    return "No recommendations \u2014 all work is complete or blocked.";
+  }
+  const lines = ["# Recommendations", ""];
+  for (let i = 0; i < result.recommendations.length; i++) {
+    const rec = result.recommendations[i];
+    lines.push(
+      `${i + 1}. **${escapeMarkdownInline(rec.id)}** (${rec.kind}) \u2014 ${escapeMarkdownInline(rec.title)}`
+    );
+    lines.push(`   _${escapeMarkdownInline(rec.reason)}_`);
+    lines.push("");
+  }
+  if (result.totalCandidates > result.recommendations.length) {
+    lines.push(
+      `Showing ${result.recommendations.length} of ${result.totalCandidates} candidates.`
+    );
+  }
+  return lines.join("\n");
+}
 var ExitCode;
 var init_output_formatter = __esm({
   "src/core/output-formatter.ts"() {
@@ -1977,6 +2384,20 @@ function validateProject(state) {
       });
     }
   }
+  const noteIDCounts = /* @__PURE__ */ new Map();
+  for (const n of state.notes) {
+    noteIDCounts.set(n.id, (noteIDCounts.get(n.id) ?? 0) + 1);
+  }
+  for (const [id, count] of noteIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_note_id",
+        message: `Duplicate note ID: ${id} appears ${count} times.`,
+        entity: id
+      });
+    }
+  }
   const phaseIDCounts = /* @__PURE__ */ new Map();
   for (const p of state.roadmap.phases) {
     phaseIDCounts.set(p.id, (phaseIDCounts.get(p.id) ?? 0) + 1);
@@ -2207,12 +2628,13 @@ var init_validate = __esm({
 });
 
 // src/cli/commands/handover.ts
-import { mkdir } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir2 } from "fs/promises";
 import { join as join4, resolve as resolve4 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
-async function handleHandoverLatest(ctx) {
+async function handleHandoverLatest(ctx, count = 1) {
   if (ctx.state.handoverFilenames.length === 0) {
     return {
       output: formatError("not_found", "No handovers found", ctx.format),
@@ -2220,25 +2642,38 @@ async function handleHandoverLatest(ctx) {
       errorCode: "not_found"
     };
   }
-  const filename = ctx.state.handoverFilenames[0];
-  await parseHandoverFilename(filename, ctx.handoversDir);
-  try {
-    const content = await readHandover(ctx.handoversDir, filename);
-    return { output: formatHandoverContent(filename, content, ctx.format) };
-  } catch (err) {
-    if (err.code === "ENOENT") {
+  const filenames = ctx.state.handoverFilenames.slice(0, count);
+  const parts = [];
+  for (const filename of filenames) {
+    await parseHandoverFilename(filename, ctx.handoversDir);
+    try {
+      const content = await readHandover(ctx.handoversDir, filename);
+      parts.push(formatHandoverContent(filename, content, ctx.format));
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        if (count > 1) continue;
+        return {
+          output: formatError("not_found", `Handover file not found: ${filename}`, ctx.format),
+          exitCode: ExitCode.USER_ERROR,
+          errorCode: "not_found"
+        };
+      }
       return {
-        output: formatError("not_found", `Handover file not found: ${filename}`, ctx.format),
+        output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
         exitCode: ExitCode.USER_ERROR,
-        errorCode: "not_found"
+        errorCode: "io_error"
       };
     }
+  }
+  if (parts.length === 0) {
     return {
-      output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
+      output: formatError("not_found", "No handovers found", ctx.format),
       exitCode: ExitCode.USER_ERROR,
-      errorCode: "io_error"
+      errorCode: "not_found"
     };
   }
+  const separator = ctx.format === "json" ? "\n" : "\n\n---\n\n";
+  return { output: parts.join(separator) };
 }
 async function handleHandoverGet(filename, ctx) {
   await parseHandoverFilename(filename, ctx.handoversDir);
@@ -2281,7 +2716,7 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
   await withProjectLock(root, { strict: false }, async () => {
     const absRoot = resolve4(root);
     const handoversDir = join4(absRoot, ".story", "handovers");
-    await mkdir(handoversDir, { recursive: true });
+    await mkdir2(handoversDir, { recursive: true });
     const wrapDir = join4(absRoot, ".story");
     const datePrefix = `${date}-`;
     const seqRegex = new RegExp(`^${date}-(\\d{2})-`);
@@ -2297,15 +2732,26 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
       }
     } catch {
     }
-    const nextSeq = maxSeq + 1;
+    let nextSeq = maxSeq + 1;
     if (nextSeq > 99) {
       throw new CliValidationError(
         "conflict",
         `Too many handovers for ${date}; limit is 99 per day`
       );
     }
-    const candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
-    const candidatePath = join4(handoversDir, candidate);
+    let candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+    let candidatePath = join4(handoversDir, candidate);
+    while (existsSync4(candidatePath)) {
+      nextSeq++;
+      if (nextSeq > 99) {
+        throw new CliValidationError(
+          "conflict",
+          `Too many handovers for ${date}; limit is 99 per day`
+        );
+      }
+      candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+      candidatePath = join4(handoversDir, candidate);
+    }
     await parseHandoverFilename(candidate, handoversDir);
     await guardPath(candidatePath, wrapDir);
     await atomicWrite(candidatePath, content);
@@ -2421,12 +2867,24 @@ function nextIssueID(issues) {
   }
   return `ISS-${String(max + 1).padStart(3, "0")}`;
 }
+function nextNoteID(notes) {
+  let max = 0;
+  for (const n of notes) {
+    if (!NOTE_ID_REGEX.test(n.id)) continue;
+    const match = n.id.match(NOTE_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `N-${String(max + 1).padStart(3, "0")}`;
+}
 function nextOrder(phaseId, state) {
   const tickets = state.phaseTickets(phaseId);
   if (tickets.length === 0) return 10;
   return tickets[tickets.length - 1].order + 10;
 }
-var TICKET_NUMERIC_REGEX, ISSUE_NUMERIC_REGEX;
+var TICKET_NUMERIC_REGEX, ISSUE_NUMERIC_REGEX, NOTE_NUMERIC_REGEX;
 var init_id_allocation = __esm({
   "src/core/id-allocation.ts"() {
     "use strict";
@@ -2434,6 +2892,7 @@ var init_id_allocation = __esm({
     init_types();
     TICKET_NUMERIC_REGEX = /^T-(\d+)[a-z]?$/;
     ISSUE_NUMERIC_REGEX = /^ISS-(\d+)$/;
+    NOTE_NUMERIC_REGEX = /^N-(\d+)$/;
   }
 });
 
@@ -2474,13 +2933,15 @@ function handleTicketGet(id, ctx) {
   }
   return { output: formatTicket(ticket, ctx.state, ctx.format) };
 }
-function handleTicketNext(ctx) {
-  const outcome = nextTicket(ctx.state);
+function handleTicketNext(ctx, count = 1) {
+  if (count <= 1) {
+    const outcome2 = nextTicket(ctx.state);
+    const exitCode2 = outcome2.kind === "found" ? ExitCode.OK : ExitCode.USER_ERROR;
+    return { output: formatNextTicketOutcome(outcome2, ctx.state, ctx.format), exitCode: exitCode2 };
+  }
+  const outcome = nextTickets(ctx.state, count);
   const exitCode = outcome.kind === "found" ? ExitCode.OK : ExitCode.USER_ERROR;
-  return {
-    output: formatNextTicketOutcome(outcome, ctx.state, ctx.format),
-    exitCode
-  };
+  return { output: formatNextTicketsOutcome(outcome, ctx.state, ctx.format), exitCode };
 }
 function handleTicketBlocked(ctx) {
   const blocked = blockedTickets(ctx.state);
@@ -2525,6 +2986,7 @@ function validatePostWriteState(candidate, state, isCreate) {
   const postState = new ProjectState({
     tickets: existingTickets,
     issues: [...state.issues],
+    notes: [...state.notes],
     roadmap: state.roadmap,
     config: state.config,
     handoverFilenames: [...state.handoverFilenames]
@@ -2673,6 +3135,9 @@ function handleIssueList(filters, ctx) {
     }
     issues = issues.filter((i) => i.severity === filters.severity);
   }
+  if (filters.component) {
+    issues = issues.filter((i) => i.components.includes(filters.component));
+  }
   return { output: formatIssueList(issues, ctx.format) };
 }
 function handleIssueGet(id, ctx) {
@@ -2705,6 +3170,7 @@ function validatePostWriteIssueState(candidate, state, isCreate) {
   const postState = new ProjectState({
     tickets: [...state.tickets],
     issues: existingIssues,
+    notes: [...state.notes],
     roadmap: state.roadmap,
     config: state.config,
     handoverFilenames: [...state.handoverFilenames]
@@ -2740,7 +3206,8 @@ async function handleIssueCreate(args, format, root) {
       location: args.location,
       discoveredDate: todayISO(),
       resolvedDate: null,
-      relatedTickets: args.relatedTickets
+      relatedTickets: args.relatedTickets,
+      phase: args.phase ?? null
     };
     validatePostWriteIssueState(issue, state, true);
     await writeIssueUnlocked(issue, root);
@@ -2822,14 +3289,14 @@ var init_issue2 = __esm({
 });
 
 // src/core/snapshot.ts
-import { readdir as readdir3, readFile as readFile3, mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
+import { readdir as readdir3, readFile as readFile3, mkdir as mkdir3, unlink as unlink2 } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
 import { join as join5, resolve as resolve5 } from "path";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 async function saveSnapshot(root, loadResult) {
   const absRoot = resolve5(root);
   const snapshotsDir = join5(absRoot, ".story", "snapshots");
-  await mkdir2(snapshotsDir, { recursive: true });
+  await mkdir3(snapshotsDir, { recursive: true });
   const { state, warnings } = loadResult;
   const now = /* @__PURE__ */ new Date();
   const filename = formatSnapshotFilename(now);
@@ -2841,6 +3308,7 @@ async function saveSnapshot(root, loadResult) {
     roadmap: state.roadmap,
     tickets: [...state.tickets],
     issues: [...state.issues],
+    notes: [...state.notes],
     ...warnings.length > 0 ? {
       warnings: warnings.map((w) => ({
         type: w.type,
@@ -2860,7 +3328,7 @@ async function saveSnapshot(root, loadResult) {
 }
 async function loadLatestSnapshot(root) {
   const snapshotsDir = join5(resolve5(root), ".story", "snapshots");
-  if (!existsSync4(snapshotsDir)) return null;
+  if (!existsSync5(snapshotsDir)) return null;
   const files = await listSnapshotFiles(snapshotsDir);
   if (files.length === 0) return null;
   for (const filename of files) {
@@ -2881,12 +3349,18 @@ function diffStates(snapshotState, currentState) {
   const ticketsAdded = [];
   const ticketsRemoved = [];
   const ticketsStatusChanged = [];
+  const ticketsDescriptionChanged = [];
   for (const [id, cur] of curTickets) {
     const snap = snapTickets.get(id);
     if (!snap) {
       ticketsAdded.push({ id, title: cur.title });
-    } else if (snap.status !== cur.status) {
-      ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    } else {
+      if (snap.status !== cur.status) {
+        ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+      }
+      if (snap.description !== cur.description) {
+        ticketsDescriptionChanged.push({ id, title: cur.title });
+      }
     }
   }
   for (const [id, snap] of snapTickets) {
@@ -2899,15 +3373,21 @@ function diffStates(snapshotState, currentState) {
   const issuesAdded = [];
   const issuesResolved = [];
   const issuesStatusChanged = [];
+  const issuesImpactChanged = [];
   for (const [id, cur] of curIssues) {
     const snap = snapIssues.get(id);
     if (!snap) {
       issuesAdded.push({ id, title: cur.title });
-    } else if (snap.status !== cur.status) {
-      if (cur.status === "resolved") {
-        issuesResolved.push({ id, title: cur.title });
-      } else {
-        issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    } else {
+      if (snap.status !== cur.status) {
+        if (cur.status === "resolved") {
+          issuesResolved.push({ id, title: cur.title });
+        } else {
+          issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+        }
+      }
+      if (snap.impact !== cur.impact) {
+        issuesImpactChanged.push({ id, title: cur.title });
       }
     }
   }
@@ -2956,11 +3436,37 @@ function diffStates(snapshotState, currentState) {
       phasesRemoved.push({ id, name: snapPhase.name });
     }
   }
+  const snapNotes = new Map(snapshotState.notes.map((n) => [n.id, n]));
+  const curNotes = new Map(currentState.notes.map((n) => [n.id, n]));
+  const notesAdded = [];
+  const notesRemoved = [];
+  const notesUpdated = [];
+  for (const [id, cur] of curNotes) {
+    const snap = snapNotes.get(id);
+    if (!snap) {
+      notesAdded.push({ id, title: cur.title });
+    } else {
+      const changedFields = [];
+      if (snap.title !== cur.title) changedFields.push("title");
+      if (snap.content !== cur.content) changedFields.push("content");
+      if (JSON.stringify([...snap.tags].sort()) !== JSON.stringify([...cur.tags].sort())) changedFields.push("tags");
+      if (snap.status !== cur.status) changedFields.push("status");
+      if (changedFields.length > 0) {
+        notesUpdated.push({ id, title: cur.title, changedFields });
+      }
+    }
+  }
+  for (const [id, snap] of snapNotes) {
+    if (!curNotes.has(id)) {
+      notesRemoved.push({ id, title: snap.title });
+    }
+  }
   return {
-    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged },
-    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged },
+    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged, descriptionChanged: ticketsDescriptionChanged },
+    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged, impactChanged: issuesImpactChanged },
     blockers: { added: blockersAdded, cleared: blockersCleared },
-    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged }
+    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged },
+    notes: { added: notesAdded, removed: notesRemoved, updated: notesUpdated }
   };
 }
 function buildRecap(currentState, snapshotInfo) {
@@ -2985,6 +3491,7 @@ function buildRecap(currentState, snapshotInfo) {
   const snapshotState = new ProjectState({
     tickets: snapshot.tickets,
     issues: snapshot.issues,
+    notes: snapshot.notes ?? [],
     roadmap: snapshot.roadmap,
     config: snapshot.config,
     handoverFilenames: []
@@ -3039,25 +3546,27 @@ var init_snapshot = __esm({
     init_esm_shims();
     init_ticket();
     init_issue();
+    init_note();
     init_roadmap();
     init_config();
     init_project_state();
     init_queries();
     init_project_loader();
-    LoadWarningSchema = z6.object({
-      type: z6.string(),
-      file: z6.string(),
-      message: z6.string()
+    LoadWarningSchema = z7.object({
+      type: z7.string(),
+      file: z7.string(),
+      message: z7.string()
     });
-    SnapshotV1Schema = z6.object({
-      version: z6.literal(1),
-      createdAt: z6.string().datetime({ offset: true }),
-      project: z6.string(),
+    SnapshotV1Schema = z7.object({
+      version: z7.literal(1),
+      createdAt: z7.string().datetime({ offset: true }),
+      project: z7.string(),
       config: ConfigSchema,
       roadmap: RoadmapSchema,
-      tickets: z6.array(TicketSchema),
-      issues: z6.array(IssueSchema),
-      warnings: z6.array(LoadWarningSchema).optional()
+      tickets: z7.array(TicketSchema),
+      issues: z7.array(IssueSchema),
+      notes: z7.array(NoteSchema).optional().default([]),
+      warnings: z7.array(LoadWarningSchema).optional()
     });
     MAX_SNAPSHOTS = 20;
   }
@@ -3078,12 +3587,390 @@ var init_recap = __esm({
   }
 });
 
-// src/cli/commands/snapshot.ts
-async function handleSnapshot(root, format) {
-  let result;
-  await withProjectLock(root, { strict: false }, async (loadResult) => {
-    result = await saveSnapshot(root, loadResult);
+// src/cli/commands/note.ts
+function handleNoteList(filters, ctx) {
+  let notes = [...ctx.state.notes];
+  if (filters.status) {
+    if (!NOTE_STATUSES.includes(filters.status)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown note status "${filters.status}": must be one of ${NOTE_STATUSES.join(", ")}`
+      );
+    }
+    notes = notes.filter((n) => n.status === filters.status);
+  }
+  if (filters.tag) {
+    const normalized = normalizeTags([filters.tag]);
+    if (normalized.length === 0) {
+      notes = [];
+    } else {
+      const tag = normalized[0];
+      notes = notes.filter((n) => n.tags.includes(tag));
+    }
+  }
+  notes.sort((a, b) => {
+    const dateCmp = b.updatedDate.localeCompare(a.updatedDate);
+    if (dateCmp !== 0) return dateCmp;
+    return a.id.localeCompare(b.id);
   });
+  return { output: formatNoteList(notes, ctx.format) };
+}
+function handleNoteGet(id, ctx) {
+  const note = ctx.state.noteByID(id);
+  if (!note) {
+    return {
+      output: formatError("not_found", `Note ${id} not found`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "not_found"
+    };
+  }
+  return { output: formatNote(note, ctx.format) };
+}
+async function handleNoteCreate(args, format, root) {
+  if (!args.content.trim()) {
+    throw new CliValidationError("invalid_input", "Note content cannot be empty");
+  }
+  let createdNote;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const id = nextNoteID(state.notes);
+    const today = todayISO();
+    const tags = args.tags ? normalizeTags(args.tags) : [];
+    const note = {
+      id,
+      title: args.title && args.title.trim() !== "" ? args.title : null,
+      content: args.content,
+      tags,
+      status: "active",
+      createdDate: today,
+      updatedDate: today
+    };
+    await writeNoteUnlocked(note, root);
+    createdNote = note;
+  });
+  if (!createdNote) throw new Error("Note not created");
+  return { output: formatNoteCreateResult(createdNote, format) };
+}
+async function handleNoteUpdate(id, updates, format, root) {
+  if (updates.content !== void 0 && !updates.content.trim()) {
+    throw new CliValidationError("invalid_input", "Note content cannot be empty");
+  }
+  if (updates.status && !NOTE_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown note status "${updates.status}": must be one of ${NOTE_STATUSES.join(", ")}`
+    );
+  }
+  let updatedNote;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.noteByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Note ${id} not found`);
+    }
+    const note = { ...existing };
+    if (updates.content !== void 0) {
+      note.content = updates.content;
+    }
+    if (updates.title !== void 0) {
+      const trimmed = updates.title?.trim();
+      note.title = !trimmed ? null : updates.title;
+    }
+    if (updates.clearTags) {
+      note.tags = [];
+    } else if (updates.tags !== void 0) {
+      note.tags = normalizeTags(updates.tags);
+    }
+    if (updates.status !== void 0) {
+      note.status = updates.status;
+    }
+    note.updatedDate = todayISO();
+    await writeNoteUnlocked(note, root);
+    updatedNote = note;
+  });
+  if (!updatedNote) throw new Error("Note not updated");
+  return { output: formatNoteUpdateResult(updatedNote, format) };
+}
+async function handleNoteDelete(id, format, root) {
+  await deleteNote(id, root);
+  return { output: formatNoteDeleteResult(id, format) };
+}
+var init_note2 = __esm({
+  "src/cli/commands/note.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_project_loader();
+    init_id_allocation();
+    init_output_formatter();
+    init_types();
+    init_helpers();
+  }
+});
+
+// src/core/recommend.ts
+function recommend(state, count) {
+  const effectiveCount = Math.max(1, Math.min(10, count));
+  const dedup = /* @__PURE__ */ new Map();
+  const phaseIndex = buildPhaseIndex(state);
+  const generators = [
+    () => generateValidationSuggestions(state),
+    () => generateCriticalIssues(state),
+    () => generateInProgressTickets(state, phaseIndex),
+    () => generateHighImpactUnblocks(state),
+    () => generateNearCompleteUmbrellas(state, phaseIndex),
+    () => generatePhaseMomentum(state),
+    () => generateQuickWins(state, phaseIndex),
+    () => generateOpenIssues(state)
+  ];
+  for (const gen of generators) {
+    for (const rec of gen()) {
+      const existing = dedup.get(rec.id);
+      if (!existing || rec.score > existing.score) {
+        dedup.set(rec.id, rec);
+      }
+    }
+  }
+  const curPhase = currentPhase(state);
+  const curPhaseIdx = curPhase ? phaseIndex.get(curPhase.id) ?? 0 : 0;
+  for (const [id, rec] of dedup) {
+    if (rec.kind !== "ticket") continue;
+    const ticket = state.ticketByID(id);
+    if (!ticket || ticket.phase == null) continue;
+    const ticketPhaseIdx = phaseIndex.get(ticket.phase);
+    if (ticketPhaseIdx === void 0) continue;
+    const phasesAhead = ticketPhaseIdx - curPhaseIdx;
+    if (phasesAhead > 0) {
+      const penalty = Math.min(phasesAhead * PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY);
+      dedup.set(id, {
+        ...rec,
+        score: rec.score - penalty,
+        reason: rec.reason + " (future phase)"
+      });
+    }
+  }
+  const all = [...dedup.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const catDiff = CATEGORY_PRIORITY[a.category] - CATEGORY_PRIORITY[b.category];
+    if (catDiff !== 0) return catDiff;
+    return a.id.localeCompare(b.id);
+  });
+  return {
+    recommendations: all.slice(0, effectiveCount),
+    totalCandidates: all.length
+  };
+}
+function generateValidationSuggestions(state) {
+  const result = validateProject(state);
+  if (result.errorCount === 0) return [];
+  return [
+    {
+      id: "validate",
+      kind: "action",
+      title: "Run claudestory validate",
+      category: "validation_errors",
+      reason: `${result.errorCount} validation error${result.errorCount === 1 ? "" : "s"} \u2014 fix before other work`,
+      score: 1e3
+    }
+  ];
+}
+function generateCriticalIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "critical" || i.severity === "high")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "critical_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress, ensure it's being addressed` : `${capitalize(issue.severity)} severity issue \u2014 address before new features`,
+    score: 900 - Math.min(index, 99)
+  }));
+}
+function generateInProgressTickets(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "inprogress"
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "inprogress_ticket",
+    reason: "In-progress \u2014 finish what's started",
+    score: 800 - Math.min(index, 99)
+  }));
+}
+function generateHighImpactUnblocks(state) {
+  const candidates = [];
+  for (const ticket of state.leafTickets) {
+    if (ticket.status === "complete") continue;
+    if (state.isBlocked(ticket)) continue;
+    const wouldUnblock = ticketsUnblockedBy(ticket.id, state);
+    if (wouldUnblock.length >= 2) {
+      candidates.push({ ticket, unblockCount: wouldUnblock.length });
+    }
+  }
+  candidates.sort((a, b) => b.unblockCount - a.unblockCount);
+  return candidates.map(({ ticket, unblockCount }, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "high_impact_unblock",
+    reason: `Completing this unblocks ${unblockCount} other ticket${unblockCount === 1 ? "" : "s"}`,
+    score: 700 - Math.min(index, 99)
+  }));
+}
+function generateNearCompleteUmbrellas(state, phaseIndex) {
+  const candidates = [];
+  for (const umbrellaId of state.umbrellaIDs) {
+    const progress = umbrellaProgress(umbrellaId, state);
+    if (!progress) continue;
+    if (progress.total < 2) continue;
+    if (progress.status === "complete") continue;
+    const ratio = progress.complete / progress.total;
+    if (ratio < 0.8) continue;
+    const leaves = descendantLeaves(umbrellaId, state);
+    const incomplete = leaves.filter((t) => t.status !== "complete");
+    const sorted = sortByPhaseAndOrder(incomplete, phaseIndex);
+    if (sorted.length === 0) continue;
+    const umbrella = state.ticketByID(umbrellaId);
+    candidates.push({
+      umbrellaId,
+      umbrellaTitle: umbrella?.title ?? umbrellaId,
+      firstIncompleteLeaf: sorted[0],
+      complete: progress.complete,
+      total: progress.total,
+      ratio
+    });
+  }
+  candidates.sort((a, b) => b.ratio - a.ratio);
+  return candidates.map((c, index) => ({
+    id: c.firstIncompleteLeaf.id,
+    kind: "ticket",
+    title: c.firstIncompleteLeaf.title,
+    category: "near_complete_umbrella",
+    reason: `${c.complete}/${c.total} complete in umbrella ${c.umbrellaId} \u2014 close it out`,
+    score: 600 - Math.min(index, 99)
+  }));
+}
+function generatePhaseMomentum(state) {
+  const outcome = nextTicket(state);
+  if (outcome.kind !== "found") return [];
+  const ticket = outcome.ticket;
+  return [
+    {
+      id: ticket.id,
+      kind: "ticket",
+      title: ticket.title,
+      category: "phase_momentum",
+      reason: `Next in phase order (${ticket.phase ?? "none"})`,
+      score: 500
+    }
+  ];
+}
+function generateQuickWins(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "open" && t.type === "chore" && !state.isBlocked(t)
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "quick_win",
+    reason: "Chore \u2014 quick win",
+    score: 400 - Math.min(index, 99)
+  }));
+}
+function generateOpenIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "medium" || i.severity === "low")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "open_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress` : `${capitalize(issue.severity)} severity issue`,
+    score: 300 - Math.min(index, 99)
+  }));
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function buildPhaseIndex(state) {
+  const index = /* @__PURE__ */ new Map();
+  state.roadmap.phases.forEach((p, i) => index.set(p.id, i));
+  return index;
+}
+function sortByPhaseAndOrder(tickets, phaseIndex) {
+  return [...tickets].sort((a, b) => {
+    const aPhase = (a.phase != null ? phaseIndex.get(a.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    const bPhase = (b.phase != null ? phaseIndex.get(b.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    if (aPhase !== bPhase) return aPhase - bPhase;
+    return a.order - b.order;
+  });
+}
+var SEVERITY_RANK, PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY, CATEGORY_PRIORITY;
+var init_recommend = __esm({
+  "src/core/recommend.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_queries();
+    init_validation();
+    SEVERITY_RANK = {
+      critical: 4,
+      high: 3,
+      medium: 2,
+      low: 1
+    };
+    PHASE_DISTANCE_PENALTY = 100;
+    MAX_PHASE_PENALTY = 400;
+    CATEGORY_PRIORITY = {
+      validation_errors: 1,
+      critical_issue: 2,
+      inprogress_ticket: 3,
+      high_impact_unblock: 4,
+      near_complete_umbrella: 5,
+      phase_momentum: 6,
+      quick_win: 7,
+      open_issue: 8
+    };
+  }
+});
+
+// src/cli/commands/recommend.ts
+function handleRecommend(ctx, count) {
+  const result = recommend(ctx.state, count);
+  return { output: formatRecommendations(result, ctx.format) };
+}
+var init_recommend2 = __esm({
+  "src/cli/commands/recommend.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_recommend();
+    init_output_formatter();
+  }
+});
+
+// src/cli/commands/snapshot.ts
+async function handleSnapshot(root, format, options) {
+  let result;
+  await withProjectLock(root, { strict: false }, async (loadResult) => {
+    result = await saveSnapshot(root, loadResult);
+  });
+  if (!result) {
+    throw new Error("snapshot: withProjectLock completed without setting result");
+  }
+  if (options?.quiet) {
+    return { output: "" };
+  }
   return { output: formatSnapshotResult(result, format) };
 }
 var init_snapshot2 = __esm({
@@ -3354,7 +4241,7 @@ var init_phase = __esm({
 });
 
 // src/mcp/tools.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 import { join as join7 } from "path";
 function formatMcpError(code, message) {
   return `[${code}] ${message}`;
@@ -3424,8 +4311,14 @@ function registerAllTools(server, pinnedRoot) {
     description: "First non-complete phase with its description"
   }, () => runMcpReadTool(pinnedRoot, handlePhaseCurrent));
   server.registerTool("claudestory_ticket_next", {
-    description: "Highest-priority unblocked ticket with unblock impact and umbrella progress"
-  }, () => runMcpReadTool(pinnedRoot, handleTicketNext));
+    description: "Highest-priority unblocked ticket(s) with unblock impact and umbrella progress",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of candidates to return (default: 1)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleTicketNext(ctx, args.count ?? 1)
+  ));
   server.registerTool("claudestory_ticket_blocked", {
     description: "All blocked tickets with their blocking dependencies"
   }, () => runMcpReadTool(pinnedRoot, handleTicketBlocked));
@@ -3433,8 +4326,14 @@ function registerAllTools(server, pinnedRoot) {
     description: "List handover filenames (newest first)"
   }, () => runMcpReadTool(pinnedRoot, handleHandoverList));
   server.registerTool("claudestory_handover_latest", {
-    description: "Content of the most recent handover document"
-  }, () => runMcpReadTool(pinnedRoot, handleHandoverLatest));
+    description: "Content of the most recent handover document(s)",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of recent handovers to return (default: 1)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleHandoverLatest(ctx, args.count ?? 1)
+  ));
   server.registerTool("claudestory_blocker_list", {
     description: "All roadmap blockers with dates and status"
   }, () => runMcpReadTool(pinnedRoot, handleBlockerList));
@@ -3444,7 +4343,7 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_phase_tickets", {
     description: "Leaf tickets for a specific phase, sorted by order",
     inputSchema: {
-      phaseId: z7.string().describe("Phase ID (e.g. p5b, dogfood)")
+      phaseId: z8.string().describe("Phase ID (e.g. p5b, dogfood)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === args.phaseId);
@@ -3460,9 +4359,9 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_list", {
     description: "List leaf tickets with optional filters",
     inputSchema: {
-      status: z7.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
-      phase: z7.string().optional().describe("Filter by phase ID"),
-      type: z7.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
+      status: z8.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
+      phase: z8.string().optional().describe("Filter by phase ID"),
+      type: z8.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     if (args.phase) {
@@ -3483,42 +4382,52 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_get", {
     description: "Get a ticket by ID (includes umbrella tickets)",
     inputSchema: {
-      id: z7.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
+      id: z8.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleTicketGet(args.id, ctx)));
   server.registerTool("claudestory_issue_list", {
     description: "List issues with optional filters",
     inputSchema: {
-      status: z7.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
-      severity: z7.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low")
+      status: z8.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
+      severity: z8.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low"),
+      component: z8.string().optional().describe("Filter by component name")
     }
   }, (args) => runMcpReadTool(
     pinnedRoot,
-    (ctx) => handleIssueList({ status: args.status, severity: args.severity }, ctx)
+    (ctx) => handleIssueList({ status: args.status, severity: args.severity, component: args.component }, ctx)
   ));
   server.registerTool("claudestory_issue_get", {
     description: "Get an issue by ID",
     inputSchema: {
-      id: z7.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
+      id: z8.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleIssueGet(args.id, ctx)));
   server.registerTool("claudestory_handover_get", {
     description: "Content of a specific handover document by filename",
     inputSchema: {
-      filename: z7.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
+      filename: z8.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleHandoverGet(args.filename, ctx)));
   server.registerTool("claudestory_recap", {
     description: "Session diff \u2014 changes since last snapshot + suggested next actions. Shows what changed and what to work on."
   }, () => runMcpReadTool(pinnedRoot, handleRecap));
+  server.registerTool("claudestory_recommend", {
+    description: "Context-aware ranked work suggestions mixing tickets and issues",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of recommendations (default: 5)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleRecommend(ctx, args.count ?? 5)
+  ));
   server.registerTool("claudestory_snapshot", {
     description: "Save current project state for session diffs. Creates a snapshot in .story/snapshots/."
   }, () => runMcpWriteTool(pinnedRoot, handleSnapshot));
   server.registerTool("claudestory_export", {
     description: "Self-contained project document for sharing",
     inputSchema: {
-      phase: z7.string().optional().describe("Export a single phase by ID"),
-      all: z7.boolean().optional().describe("Export entire project")
+      phase: z8.string().optional().describe("Export a single phase by ID"),
+      all: z8.boolean().optional().describe("Export entire project")
     }
   }, (args) => {
     if (!args.phase && !args.all) {
@@ -3540,8 +4449,8 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_handover_create", {
     description: "Create a handover document from markdown content",
     inputSchema: {
-      content: z7.string().describe("Markdown content of the handover"),
-      slug: z7.string().optional().describe("Slug for filename (e.g. phase5b-wrapup). Default: session")
+      content: z8.string().describe("Markdown content of the handover"),
+      slug: z8.string().optional().describe("Slug for filename (e.g. phase5b-wrapup). Default: session")
     }
   }, (args) => {
     if (!args.content?.trim()) {
@@ -3555,6 +4464,177 @@ function registerAllTools(server, pinnedRoot) {
       (root) => handleHandoverCreate(args.content, args.slug ?? "session", "md", root)
     );
   });
+  server.registerTool("claudestory_ticket_create", {
+    description: "Create a new ticket",
+    inputSchema: {
+      title: z8.string().describe("Ticket title"),
+      type: z8.enum(TICKET_TYPES).describe("Ticket type: task, feature, chore"),
+      phase: z8.string().optional().describe("Phase ID"),
+      description: z8.string().optional().describe("Ticket description"),
+      blockedBy: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("IDs of blocking tickets"),
+      parentTicket: z8.string().regex(TICKET_ID_REGEX).optional().describe("Parent ticket ID (makes this a sub-ticket)")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleTicketCreate(
+      {
+        title: args.title,
+        type: args.type,
+        phase: args.phase ?? null,
+        description: args.description ?? "",
+        blockedBy: args.blockedBy ?? [],
+        parentTicket: args.parentTicket ?? null
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_ticket_update", {
+    description: "Update an existing ticket",
+    inputSchema: {
+      id: z8.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001)"),
+      status: z8.enum(TICKET_STATUSES).optional().describe("New status: open, inprogress, complete"),
+      title: z8.string().optional().describe("New title"),
+      order: z8.number().optional().describe("New sort order"),
+      description: z8.string().optional().describe("New description"),
+      phase: z8.string().nullable().optional().describe("New phase ID (null to clear)"),
+      parentTicket: z8.string().regex(TICKET_ID_REGEX).nullable().optional().describe("Parent ticket ID (null to clear)"),
+      blockedBy: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("IDs of blocking tickets")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleTicketUpdate(
+      args.id,
+      {
+        status: args.status,
+        title: args.title,
+        order: args.order,
+        description: args.description,
+        phase: args.phase,
+        parentTicket: args.parentTicket,
+        blockedBy: args.blockedBy
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_issue_create", {
+    description: "Create a new issue",
+    inputSchema: {
+      title: z8.string().describe("Issue title"),
+      severity: z8.enum(ISSUE_SEVERITIES).describe("Issue severity: critical, high, medium, low"),
+      impact: z8.string().describe("Impact description"),
+      components: z8.array(z8.string()).optional().describe("Affected components"),
+      relatedTickets: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("Related ticket IDs"),
+      location: z8.array(z8.string()).optional().describe("File locations"),
+      phase: z8.string().optional().describe("Phase ID")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleIssueCreate(
+      {
+        title: args.title,
+        severity: args.severity,
+        impact: args.impact,
+        components: args.components ?? [],
+        relatedTickets: args.relatedTickets ?? [],
+        location: args.location ?? [],
+        phase: args.phase
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_issue_update", {
+    description: "Update an existing issue",
+    inputSchema: {
+      id: z8.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)"),
+      status: z8.enum(ISSUE_STATUSES).optional().describe("New status: open, inprogress, resolved"),
+      title: z8.string().optional().describe("New title"),
+      severity: z8.enum(ISSUE_SEVERITIES).optional().describe("New severity"),
+      impact: z8.string().optional().describe("New impact description"),
+      resolution: z8.string().nullable().optional().describe("Resolution description (null to clear)"),
+      components: z8.array(z8.string()).optional().describe("Affected components"),
+      relatedTickets: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("Related ticket IDs"),
+      location: z8.array(z8.string()).optional().describe("File locations")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleIssueUpdate(
+      args.id,
+      {
+        status: args.status,
+        title: args.title,
+        severity: args.severity,
+        impact: args.impact,
+        resolution: args.resolution,
+        components: args.components,
+        relatedTickets: args.relatedTickets,
+        location: args.location
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_note_list", {
+    description: "List notes with optional status/tag filters",
+    inputSchema: {
+      status: z8.enum(NOTE_STATUSES).optional().describe("Filter by status: active, archived"),
+      tag: z8.string().optional().describe("Filter by tag")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleNoteList({ status: args.status, tag: args.tag }, ctx)
+  ));
+  server.registerTool("claudestory_note_get", {
+    description: "Get a note by ID",
+    inputSchema: {
+      id: z8.string().regex(NOTE_ID_REGEX).describe("Note ID (e.g. N-001)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleNoteGet(args.id, ctx)));
+  server.registerTool("claudestory_note_create", {
+    description: "Create a new note",
+    inputSchema: {
+      content: z8.string().describe("Note content"),
+      title: z8.string().optional().describe("Note title"),
+      tags: z8.array(z8.string()).optional().describe("Tags for the note")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleNoteCreate(
+      {
+        content: args.content,
+        title: args.title ?? null,
+        tags: args.tags ?? []
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_note_update", {
+    description: "Update an existing note",
+    inputSchema: {
+      id: z8.string().regex(NOTE_ID_REGEX).describe("Note ID (e.g. N-001)"),
+      content: z8.string().optional().describe("New content"),
+      title: z8.string().nullable().optional().describe("New title (null to clear)"),
+      tags: z8.array(z8.string()).optional().describe("New tags (replaces existing)"),
+      status: z8.enum(NOTE_STATUSES).optional().describe("New status: active, archived")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleNoteUpdate(
+      args.id,
+      {
+        content: args.content,
+        title: args.title,
+        tags: args.tags,
+        clearTags: args.tags !== void 0 && args.tags.length === 0,
+        status: args.status
+      },
+      format,
+      root
+    )
+  ));
 }
 var INFRASTRUCTURE_ERROR_CODES;
 var init_tools = __esm({
@@ -3572,6 +4652,8 @@ var init_tools = __esm({
     init_ticket2();
     init_issue2();
     init_recap();
+    init_note2();
+    init_recommend2();
     init_snapshot2();
     init_export();
     init_handover();
@@ -3586,7 +4668,7 @@ var init_tools = __esm({
 
 // src/mcp/index.ts
 var mcp_exports = {};
-import { realpathSync, existsSync as existsSync5 } from "fs";
+import { realpathSync, existsSync as existsSync6 } from "fs";
 import { resolve as resolve7, join as join8, isAbsolute } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -3601,7 +4683,7 @@ function tryDiscoverRoot() {
     const resolved = resolve7(envRoot);
     try {
       const canonical = realpathSync(resolved);
-      if (existsSync5(join8(canonical, CONFIG_PATH2))) {
+      if (existsSync6(join8(canonical, CONFIG_PATH2))) {
         return canonical;
       }
       process.stderr.write(`Warning: No .story/config.json at ${canonical}
@@ -3652,7 +4734,7 @@ var init_mcp = __esm({
     init_tools();
     ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "0.1.7";
+    version = "0.1.9";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -3662,7 +4744,7 @@ var init_mcp = __esm({
 });
 
 // src/core/init.ts
-import { mkdir as mkdir3, stat as stat2 } from "fs/promises";
+import { mkdir as mkdir4, stat as stat2 } from "fs/promises";
 import { join as join9, resolve as resolve8 } from "path";
 async function initProject(root, options) {
   const absRoot = resolve8(root);
@@ -3686,9 +4768,18 @@ async function initProject(root, options) {
       ".story/ already exists. Use --force to overwrite config and roadmap."
     );
   }
-  await mkdir3(join9(wrapDir, "tickets"), { recursive: true });
-  await mkdir3(join9(wrapDir, "issues"), { recursive: true });
-  await mkdir3(join9(wrapDir, "handovers"), { recursive: true });
+  await mkdir4(join9(wrapDir, "tickets"), { recursive: true });
+  await mkdir4(join9(wrapDir, "issues"), { recursive: true });
+  await mkdir4(join9(wrapDir, "handovers"), { recursive: true });
+  await mkdir4(join9(wrapDir, "notes"), { recursive: true });
+  const created = [
+    ".story/config.json",
+    ".story/roadmap.json",
+    ".story/tickets/",
+    ".story/issues/",
+    ".story/handovers/",
+    ".story/notes/"
+  ];
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const config = {
     version: 2,
@@ -3733,13 +4824,7 @@ async function initProject(root, options) {
   }
   return {
     root: absRoot,
-    created: [
-      ".story/config.json",
-      ".story/roadmap.json",
-      ".story/tickets/",
-      ".story/issues/",
-      ".story/handovers/"
-    ],
+    created,
     warnings
   };
 }
@@ -3763,6 +4848,7 @@ var init_core = __esm({
     init_handover_parser();
     init_errors();
     init_queries();
+    init_recommend();
     init_id_allocation();
     init_validation();
     init_init();
@@ -3953,18 +5039,510 @@ function registerInitCommand(yargs) {
         process.exitCode = ExitCode.USER_ERROR;
       }
     }
-  );
+  );
+}
+var init_init2 = __esm({
+  "src/cli/commands/init.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_init();
+    init_errors();
+    init_output_formatter();
+    init_project_root_discovery();
+    init_helpers();
+    init_run();
+  }
+});
+
+// src/cli/commands/reference.ts
+function handleReference(format) {
+  return formatReference(COMMANDS, MCP_TOOLS, format);
+}
+var COMMANDS, MCP_TOOLS;
+var init_reference = __esm({
+  "src/cli/commands/reference.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_output_formatter();
+    COMMANDS = [
+      {
+        name: "init",
+        description: "Initialize a new .story/ project",
+        usage: "claudestory init [--name <name>] [--type <type>] [--language <lang>] [--force] [--format json|md]",
+        flags: ["--name", "--type", "--language", "--force"]
+      },
+      {
+        name: "status",
+        description: "Project summary: phase statuses, ticket/issue counts, blockers",
+        usage: "claudestory status [--format json|md]"
+      },
+      {
+        name: "ticket list",
+        description: "List tickets with optional filters",
+        usage: "claudestory ticket list [--status <s>] [--phase <p>] [--type <t>] [--format json|md]",
+        flags: ["--status", "--phase", "--type"]
+      },
+      {
+        name: "ticket get",
+        description: "Get ticket details by ID",
+        usage: "claudestory ticket get <id> [--format json|md]"
+      },
+      {
+        name: "ticket next",
+        description: "Suggest next ticket(s) to work on",
+        usage: "claudestory ticket next [--count N] [--format json|md]"
+      },
+      {
+        name: "ticket blocked",
+        description: "List blocked tickets with their blocking dependencies",
+        usage: "claudestory ticket blocked [--format json|md]"
+      },
+      {
+        name: "ticket create",
+        description: "Create a new ticket",
+        usage: "claudestory ticket create --title <t> --type <type> [--phase <p>] [--description <d>] [--blocked-by <ids>] [--parent-ticket <id>] [--format json|md]",
+        flags: ["--title", "--type", "--phase", "--description", "--blocked-by", "--parent-ticket"]
+      },
+      {
+        name: "ticket update",
+        description: "Update a ticket",
+        usage: "claudestory ticket update <id> [--status <s>] [--title <t>] [--phase <p>] [--order <n>] [--description <d>] [--blocked-by <ids>] [--parent-ticket <id>] [--format json|md]",
+        flags: ["--status", "--title", "--phase", "--order", "--description", "--blocked-by", "--parent-ticket"]
+      },
+      {
+        name: "ticket delete",
+        description: "Delete a ticket",
+        usage: "claudestory ticket delete <id> [--force] [--format json|md]",
+        flags: ["--force"]
+      },
+      {
+        name: "issue list",
+        description: "List issues with optional filters",
+        usage: "claudestory issue list [--status <s>] [--severity <sev>] [--format json|md]",
+        flags: ["--status", "--severity"]
+      },
+      {
+        name: "issue get",
+        description: "Get issue details by ID",
+        usage: "claudestory issue get <id> [--format json|md]"
+      },
+      {
+        name: "issue create",
+        description: "Create a new issue",
+        usage: "claudestory issue create --title <t> --severity <s> --impact <i> [--components <c>] [--related-tickets <ids>] [--location <locs>] [--format json|md]",
+        flags: ["--title", "--severity", "--impact", "--components", "--related-tickets", "--location"]
+      },
+      {
+        name: "issue update",
+        description: "Update an issue",
+        usage: "claudestory issue update <id> [--status <s>] [--title <t>] [--severity <sev>] [--impact <i>] [--resolution <r>] [--components <c>] [--related-tickets <ids>] [--location <locs>] [--format json|md]",
+        flags: ["--status", "--title", "--severity", "--impact", "--resolution", "--components", "--related-tickets", "--location"]
+      },
+      {
+        name: "issue delete",
+        description: "Delete an issue",
+        usage: "claudestory issue delete <id> [--format json|md]"
+      },
+      {
+        name: "phase list",
+        description: "List all phases with derived status",
+        usage: "claudestory phase list [--format json|md]"
+      },
+      {
+        name: "phase current",
+        description: "Show current (first non-complete) phase",
+        usage: "claudestory phase current [--format json|md]"
+      },
+      {
+        name: "phase tickets",
+        description: "List tickets in a specific phase",
+        usage: "claudestory phase tickets --phase <id> [--format json|md]",
+        flags: ["--phase"]
+      },
+      {
+        name: "phase create",
+        description: "Create a new phase",
+        usage: "claudestory phase create --id <id> --name <n> --label <l> --description <d> [--summary <s>] [--after <id>] [--at-start] [--format json|md]",
+        flags: ["--id", "--name", "--label", "--description", "--summary", "--after", "--at-start"]
+      },
+      {
+        name: "phase rename",
+        description: "Rename/update phase metadata",
+        usage: "claudestory phase rename <id> [--name <n>] [--label <l>] [--description <d>] [--summary <s>] [--format json|md]",
+        flags: ["--name", "--label", "--description", "--summary"]
+      },
+      {
+        name: "phase move",
+        description: "Move a phase to a new position",
+        usage: "claudestory phase move <id> [--after <id>] [--at-start] [--format json|md]",
+        flags: ["--after", "--at-start"]
+      },
+      {
+        name: "phase delete",
+        description: "Delete a phase",
+        usage: "claudestory phase delete <id> [--reassign <phase-id>] [--format json|md]",
+        flags: ["--reassign"]
+      },
+      {
+        name: "handover list",
+        description: "List handover filenames (newest first)",
+        usage: "claudestory handover list [--format json|md]"
+      },
+      {
+        name: "handover latest",
+        description: "Content of most recent handover",
+        usage: "claudestory handover latest [--format json|md]"
+      },
+      {
+        name: "handover get",
+        description: "Content of a specific handover",
+        usage: "claudestory handover get <filename> [--format json|md]"
+      },
+      {
+        name: "handover create",
+        description: "Create a new handover document",
+        usage: "claudestory handover create [--content <md>] [--stdin] [--slug <slug>] [--format json|md]",
+        flags: ["--content", "--stdin", "--slug"]
+      },
+      {
+        name: "blocker list",
+        description: "List all roadmap blockers",
+        usage: "claudestory blocker list [--format json|md]"
+      },
+      {
+        name: "blocker add",
+        description: "Add a new blocker",
+        usage: "claudestory blocker add --name <n> [--note <note>] [--format json|md]",
+        flags: ["--name", "--note"]
+      },
+      {
+        name: "blocker clear",
+        description: "Clear (resolve) a blocker",
+        usage: "claudestory blocker clear --name <n> [--note <note>] [--format json|md]",
+        flags: ["--name", "--note"]
+      },
+      {
+        name: "note list",
+        description: "List notes with optional status/tag filters",
+        usage: "claudestory note list [--status <s>] [--tag <t>] [--format json|md]",
+        flags: ["--status", "--tag"]
+      },
+      {
+        name: "note get",
+        description: "Get a note by ID",
+        usage: "claudestory note get <id> [--format json|md]"
+      },
+      {
+        name: "note create",
+        description: "Create a new note",
+        usage: "claudestory note create --content <c> [--title <t>] [--tags <tags>] [--format json|md]",
+        flags: ["--content", "--title", "--tags"]
+      },
+      {
+        name: "note update",
+        description: "Update a note",
+        usage: "claudestory note update <id> [--content <c>] [--title <t>] [--tags <tags>] [--clear-tags] [--status <s>] [--format json|md]",
+        flags: ["--content", "--title", "--tags", "--clear-tags", "--status"]
+      },
+      {
+        name: "note delete",
+        description: "Delete a note",
+        usage: "claudestory note delete <id> [--format json|md]"
+      },
+      {
+        name: "validate",
+        description: "Reference integrity + schema checks on all .story/ files",
+        usage: "claudestory validate [--format json|md]"
+      },
+      {
+        name: "snapshot",
+        description: "Save current project state for session diffs",
+        usage: "claudestory snapshot [--quiet] [--format json|md]",
+        flags: ["--quiet"]
+      },
+      {
+        name: "recap",
+        description: "Session diff \u2014 changes since last snapshot + suggested actions",
+        usage: "claudestory recap [--format json|md]"
+      },
+      {
+        name: "export",
+        description: "Self-contained project document for sharing",
+        usage: "claudestory export [--phase <id>] [--all] [--format json|md]",
+        flags: ["--phase", "--all"]
+      },
+      {
+        name: "recommend",
+        description: "Context-aware work suggestions",
+        usage: "claudestory recommend [--count N] [--format json|md]"
+      },
+      {
+        name: "reference",
+        description: "Print CLI command and MCP tool reference",
+        usage: "claudestory reference [--format json|md]"
+      },
+      {
+        name: "setup-skill",
+        description: "Install the /story skill globally for Claude Code",
+        usage: "claudestory setup-skill"
+      }
+    ];
+    MCP_TOOLS = [
+      { name: "claudestory_status", description: "Project summary: phase statuses, ticket/issue counts, blockers" },
+      { name: "claudestory_phase_list", description: "All phases with derived status" },
+      { name: "claudestory_phase_current", description: "First non-complete phase" },
+      { name: "claudestory_phase_tickets", description: "Leaf tickets for a specific phase", params: ["phaseId"] },
+      { name: "claudestory_ticket_list", description: "List leaf tickets with optional filters", params: ["status?", "phase?", "type?"] },
+      { name: "claudestory_ticket_get", description: "Get a ticket by ID", params: ["id"] },
+      { name: "claudestory_ticket_next", description: "Highest-priority unblocked ticket(s)", params: ["count?"] },
+      { name: "claudestory_ticket_blocked", description: "All blocked tickets with dependencies" },
+      { name: "claudestory_issue_list", description: "List issues with optional filters", params: ["status?", "severity?"] },
+      { name: "claudestory_issue_get", description: "Get an issue by ID", params: ["id"] },
+      { name: "claudestory_handover_list", description: "List handover filenames (newest first)" },
+      { name: "claudestory_handover_latest", description: "Content of most recent handover" },
+      { name: "claudestory_handover_get", description: "Content of a specific handover", params: ["filename"] },
+      { name: "claudestory_handover_create", description: "Create a handover from markdown content", params: ["content", "slug?"] },
+      { name: "claudestory_blocker_list", description: "All roadmap blockers with status" },
+      { name: "claudestory_validate", description: "Reference integrity + schema checks" },
+      { name: "claudestory_recap", description: "Session diff \u2014 changes since last snapshot" },
+      { name: "claudestory_recommend", description: "Context-aware ranked work suggestions", params: ["count?"] },
+      { name: "claudestory_snapshot", description: "Save current project state snapshot" },
+      { name: "claudestory_export", description: "Self-contained project document", params: ["phase?", "all?"] },
+      { name: "claudestory_note_list", description: "List notes", params: ["status?", "tag?"] },
+      { name: "claudestory_note_get", description: "Get note by ID", params: ["id"] },
+      { name: "claudestory_note_create", description: "Create note", params: ["content", "title?", "tags?"] },
+      { name: "claudestory_note_update", description: "Update note", params: ["id", "content?", "title?", "tags?", "status?"] },
+      { name: "claudestory_ticket_create", description: "Create ticket", params: ["title", "type", "phase?", "description?", "blockedBy?", "parentTicket?"] },
+      { name: "claudestory_ticket_update", description: "Update ticket", params: ["id", "status?", "title?", "order?", "description?", "phase?", "parentTicket?"] },
+      { name: "claudestory_issue_create", description: "Create issue", params: ["title", "severity", "impact", "components?", "relatedTickets?", "location?", "phase?"] },
+      { name: "claudestory_issue_update", description: "Update issue", params: ["id", "status?", "title?", "severity?", "impact?", "resolution?", "components?", "relatedTickets?", "location?"] }
+    ];
+  }
+});
+
+// src/cli/commands/setup-skill.ts
+var setup_skill_exports = {};
+__export(setup_skill_exports, {
+  handleSetupSkill: () => handleSetupSkill,
+  registerPreCompactHook: () => registerPreCompactHook,
+  resolveSkillSourceDir: () => resolveSkillSourceDir
+});
+import { mkdir as mkdir5, writeFile as writeFile2, readFile as readFile4, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import { join as join11, dirname as dirname3 } from "path";
+import { homedir } from "os";
+import { execFileSync } from "child_process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+function log(msg) {
+  process.stdout.write(msg + "\n");
+}
+function resolveSkillSourceDir() {
+  const thisDir = dirname3(fileURLToPath2(import.meta.url));
+  const bundledPath = join11(thisDir, "..", "src", "skill");
+  if (existsSync7(join11(bundledPath, "SKILL.md"))) return bundledPath;
+  const sourcePath = join11(thisDir, "..", "..", "skill");
+  if (existsSync7(join11(sourcePath, "SKILL.md"))) return sourcePath;
+  throw new Error(
+    `Cannot find bundled skill files. Checked:
+  ${bundledPath}
+  ${sourcePath}`
+  );
+}
+function isOurHook(entry) {
+  if (typeof entry !== "object" || entry === null) return false;
+  const e = entry;
+  return e.type === "command" && typeof e.command === "string" && e.command.trim() === HOOK_COMMAND;
+}
+async function registerPreCompactHook(settingsPath) {
+  const path2 = settingsPath ?? join11(homedir(), ".claude", "settings.json");
+  let raw = "{}";
+  if (existsSync7(path2)) {
+    try {
+      raw = await readFile4(path2, "utf-8");
+    } catch {
+      process.stderr.write(`Could not read ${path2} \u2014 skipping hook registration.
+`);
+      return "skipped";
+    }
+  }
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
+      process.stderr.write(`${path2} is not a JSON object \u2014 skipping hook registration.
+`);
+      return "skipped";
+    }
+  } catch {
+    process.stderr.write(`${path2} contains invalid JSON \u2014 skipping hook registration.
+`);
+    process.stderr.write("  Fix the file manually or delete it to reset.\n");
+    return "skipped";
+  }
+  if ("hooks" in settings) {
+    if (typeof settings.hooks !== "object" || settings.hooks === null || Array.isArray(settings.hooks)) {
+      process.stderr.write(`${path2} has unexpected hooks format \u2014 skipping hook registration.
+`);
+      return "skipped";
+    }
+  } else {
+    settings.hooks = {};
+  }
+  const hooks = settings.hooks;
+  if ("PreCompact" in hooks) {
+    if (!Array.isArray(hooks.PreCompact)) {
+      process.stderr.write(`${path2} has unexpected hooks.PreCompact format \u2014 skipping hook registration.
+`);
+      return "skipped";
+    }
+  } else {
+    hooks.PreCompact = [];
+  }
+  const preCompact = hooks.PreCompact;
+  for (const group of preCompact) {
+    if (typeof group !== "object" || group === null) continue;
+    const g = group;
+    if (!Array.isArray(g.hooks)) continue;
+    for (const entry of g.hooks) {
+      if (isOurHook(entry)) return "exists";
+    }
+  }
+  const ourEntry = { type: "command", command: HOOK_COMMAND };
+  let appended = false;
+  for (const group of preCompact) {
+    if (typeof group !== "object" || group === null) continue;
+    const g = group;
+    if (g.matcher === "" && Array.isArray(g.hooks)) {
+      g.hooks.push(ourEntry);
+      appended = true;
+      break;
+    }
+  }
+  if (!appended) {
+    preCompact.push({ matcher: "", hooks: [ourEntry] });
+  }
+  const tmpPath = `${path2}.${process.pid}.tmp`;
+  try {
+    const dir = dirname3(path2);
+    await mkdir5(dir, { recursive: true });
+    await writeFile2(tmpPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    await rename2(tmpPath, path2);
+  } catch (err) {
+    try {
+      await unlink3(tmpPath);
+    } catch {
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Failed to write settings.json: ${message}
+`);
+    return "skipped";
+  }
+  return "registered";
+}
+async function handleSetupSkill(options = {}) {
+  const { skipHooks = false } = options;
+  const skillDir = join11(homedir(), ".claude", "skills", "story");
+  await mkdir5(skillDir, { recursive: true });
+  let srcSkillDir;
+  try {
+    srcSkillDir = resolveSkillSourceDir();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Error: ${message}
+`);
+    process.stderr.write("This may indicate a corrupt installation. Try: npm install -g @anthropologies/claudestory\n");
+    process.exitCode = 1;
+    return;
+  }
+  const oldPrimeDir = join11(homedir(), ".claude", "skills", "prime");
+  if (existsSync7(oldPrimeDir)) {
+    await rm(oldPrimeDir, { recursive: true, force: true });
+    log("Removed old /prime skill (migrated to /story)");
+  }
+  const existed = existsSync7(join11(skillDir, "SKILL.md"));
+  const skillContent = await readFile4(join11(srcSkillDir, "SKILL.md"), "utf-8");
+  await writeFile2(join11(skillDir, "SKILL.md"), skillContent, "utf-8");
+  let referenceWritten = false;
+  const refSrcPath = join11(srcSkillDir, "reference.md");
+  if (existsSync7(refSrcPath)) {
+    const refContent = await readFile4(refSrcPath, "utf-8");
+    await writeFile2(join11(skillDir, "reference.md"), refContent, "utf-8");
+    referenceWritten = true;
+  }
+  log(`${existed ? "Updated" : "Installed"} /story skill at ${skillDir}/`);
+  if (referenceWritten) {
+    log("  SKILL.md + reference.md written");
+  } else {
+    log("  SKILL.md written (reference.md not found \u2014 generate with `claudestory reference --format md`)");
+  }
+  let mcpRegistered = false;
+  let cliInPath = false;
+  try {
+    execFileSync("claudestory", ["--version"], { stdio: "pipe", timeout: 5e3 });
+    cliInPath = true;
+  } catch {
+  }
+  if (cliInPath) {
+    try {
+      execFileSync("claude", ["mcp", "add", "claudestory", "-s", "user", "--", "claudestory", "--mcp"], {
+        stdio: "pipe",
+        timeout: 1e4
+      });
+      mcpRegistered = true;
+      log("  MCP server registered globally");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isAlreadyRegistered = message.includes("already exists");
+      const isNotFound = message.includes("ENOENT") || message.includes("not found");
+      if (isAlreadyRegistered) {
+        mcpRegistered = true;
+        log("  MCP server already registered globally");
+      } else if (isNotFound) {
+        log("");
+        log("MCP registration skipped \u2014 `claude` CLI not found in PATH.");
+        log("  To register manually: claude mcp add claudestory -s user -- claudestory --mcp");
+      } else {
+        log("");
+        log(`MCP registration failed: ${message.split("\n")[0]}`);
+        log("  To register manually: claude mcp add claudestory -s user -- claudestory --mcp");
+      }
+    }
+  } else {
+    log("");
+    log("MCP registration skipped \u2014 `claudestory` not found in PATH.");
+    log("Install globally first, then register MCP:");
+    log("  npm install -g @anthropologies/claudestory");
+    log("  claude mcp add claudestory -s user -- claudestory --mcp");
+  }
+  if (cliInPath && !skipHooks) {
+    const result = await registerPreCompactHook();
+    switch (result) {
+      case "registered":
+        log("  PreCompact hook registered \u2014 snapshots auto-taken before context compaction");
+        break;
+      case "exists":
+        log("  PreCompact hook already configured");
+        break;
+      case "skipped":
+        break;
+    }
+  } else if (!cliInPath) {
+  } else if (skipHooks) {
+    log("  Hook registration skipped (--skip-hooks)");
+  }
+  log("");
+  if (mcpRegistered) {
+    log("Done! Restart Claude Code, then type /story in any project.");
+  } else {
+    log("Skill installed. After registering MCP, restart Claude Code and type /story.");
+  }
 }
-var init_init2 = __esm({
-  "src/cli/commands/init.ts"() {
+var HOOK_COMMAND;
+var init_setup_skill = __esm({
+  "src/cli/commands/setup-skill.ts"() {
     "use strict";
     init_esm_shims();
-    init_init();
-    init_errors();
-    init_output_formatter();
-    init_project_root_discovery();
-    init_helpers();
-    init_run();
+    HOOK_COMMAND = "claudestory snapshot --quiet";
   }
 });
 
@@ -3976,8 +5554,12 @@ __export(register_exports, {
   registerHandoverCommand: () => registerHandoverCommand,
   registerInitCommand: () => registerInitCommand,
   registerIssueCommand: () => registerIssueCommand,
+  registerNoteCommand: () => registerNoteCommand,
   registerPhaseCommand: () => registerPhaseCommand,
   registerRecapCommand: () => registerRecapCommand,
+  registerRecommendCommand: () => registerRecommendCommand,
+  registerReferenceCommand: () => registerReferenceCommand,
+  registerSetupSkillCommand: () => registerSetupSkillCommand,
   registerSnapshotCommand: () => registerSnapshotCommand,
   registerStatusCommand: () => registerStatusCommand,
   registerTicketCommand: () => registerTicketCommand,
@@ -4019,11 +5601,21 @@ function registerHandoverCommand(yargs) {
       }
     ).command(
       "latest",
-      "Content of most recent handover",
-      (y2) => addFormatOption(y2),
+      "Content of most recent handover(s)",
+      (y2) => addFormatOption(
+        y2.option("count", {
+          type: "number",
+          default: 1,
+          describe: "Number of recent handovers to return (default: 1)"
+        })
+      ),
       async (argv) => {
         const format = parseOutputFormat(argv.format);
-        await runReadCommand(format, handleHandoverLatest);
+        const count = Math.max(1, Math.floor(argv.count));
+        await runReadCommand(
+          format,
+          (ctx) => handleHandoverLatest(ctx, count)
+        );
       }
     ).command(
       "get <filename>",
@@ -4300,10 +5892,16 @@ function registerTicketCommand(yargs) {
     ).command(
       "next",
       "Suggest next ticket to work on",
-      (y2) => addFormatOption(y2),
+      (y2) => addFormatOption(y2).option("count", {
+        type: "number",
+        default: 1,
+        describe: "Number of candidates to suggest (1-10)"
+      }),
       async (argv) => {
         const format = parseOutputFormat(argv.format);
-        await runReadCommand(format, handleTicketNext);
+        const raw = Number(argv.count) || 1;
+        const count = Math.max(1, Math.min(10, Math.floor(raw)));
+        await runReadCommand(format, (ctx) => handleTicketNext(ctx, count));
       }
     ).command(
       "blocked",
@@ -4330,8 +5928,10 @@ function registerTicketCommand(yargs) {
           describe: "Phase ID"
         }).option("description", {
           type: "string",
-          default: "",
           describe: "Ticket description"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read description from stdin"
         }).option("blocked-by", {
           type: "string",
           array: true,
@@ -4339,7 +5939,7 @@ function registerTicketCommand(yargs) {
         }).option("parent-ticket", {
           type: "string",
           describe: "Parent ticket ID (makes this a sub-ticket)"
-        })
+        }).conflicts("description", "stdin")
       ),
       async (argv) => {
         const format = parseOutputFormat(argv.format);
@@ -4356,12 +5956,16 @@ function registerTicketCommand(yargs) {
           return;
         }
         try {
+          let description = argv.description ?? "";
+          if (argv.stdin) {
+            description = await readStdinContent();
+          }
           const result = await handleTicketCreate(
             {
               title: argv.title,
               type: argv.type,
               phase: argv.phase === "" ? null : argv.phase ?? null,
-              description: argv.description,
+              description,
               blockedBy: normalizeArrayOption(
                 argv["blocked-by"]
               ),
@@ -4412,6 +6016,9 @@ function registerTicketCommand(yargs) {
         }).option("description", {
           type: "string",
           describe: "New description"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read description from stdin"
         }).option("blocked-by", {
           type: "string",
           array: true,
@@ -4419,7 +6026,7 @@ function registerTicketCommand(yargs) {
         }).option("parent-ticket", {
           type: "string",
           describe: "Parent ticket ID"
-        })
+        }).conflicts("description", "stdin")
       ),
       async (argv) => {
         const format = parseOutputFormat(argv.format);
@@ -4437,6 +6044,10 @@ function registerTicketCommand(yargs) {
           return;
         }
         try {
+          let description = argv.description;
+          if (argv.stdin) {
+            description = await readStdinContent();
+          }
           const result = await handleTicketUpdate(
             id,
             {
@@ -4444,7 +6055,7 @@ function registerTicketCommand(yargs) {
               title: argv.title,
               phase: argv.phase === "" ? null : argv.phase,
               order: argv.order,
-              description: argv.description,
+              description,
               blockedBy: argv["blocked-by"] ? normalizeArrayOption(argv["blocked-by"]) : void 0,
               parentTicket: argv["parent-ticket"] === "" ? null : argv["parent-ticket"]
             },
@@ -4516,6 +6127,9 @@ function registerIssueCommand(yargs) {
         }).option("severity", {
           type: "string",
           describe: "Filter by severity"
+        }).option("component", {
+          type: "string",
+          describe: "Filter by component"
         })
       ),
       async (argv) => {
@@ -4525,7 +6139,8 @@ function registerIssueCommand(yargs) {
           (ctx) => handleIssueList(
             {
               status: argv.status,
-              severity: argv.severity
+              severity: argv.severity,
+              component: argv.component
             },
             ctx
           )
@@ -4560,8 +6175,13 @@ function registerIssueCommand(yargs) {
           describe: "Issue severity"
         }).option("impact", {
           type: "string",
-          demandOption: true,
           describe: "Impact description"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read impact from stdin"
+        }).option("phase", {
+          type: "string",
+          describe: "Phase ID"
         }).option("components", {
           type: "string",
           array: true,
@@ -4574,6 +6194,11 @@ function registerIssueCommand(yargs) {
           type: "string",
           array: true,
           describe: "File locations"
+        }).conflicts("impact", "stdin").check((a) => {
+          if (!a.impact && !a.stdin) {
+            throw new Error("Specify either --impact or --stdin");
+          }
+          return true;
         })
       ),
       async (argv) => {
@@ -4591,11 +6216,15 @@ function registerIssueCommand(yargs) {
           return;
         }
         try {
+          let impact = argv.impact ?? "";
+          if (argv.stdin) {
+            impact = await readStdinContent();
+          }
           const result = await handleIssueCreate(
             {
               title: argv.title,
               severity: argv.severity,
-              impact: argv.impact,
+              impact,
               components: normalizeArrayOption(
                 argv.components
               ),
@@ -4604,7 +6233,8 @@ function registerIssueCommand(yargs) {
               ),
               location: normalizeArrayOption(
                 argv.location
-              )
+              ),
+              phase: argv.phase
             },
             format,
             root
@@ -4648,6 +6278,9 @@ function registerIssueCommand(yargs) {
         }).option("impact", {
           type: "string",
           describe: "New impact description"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read impact from stdin"
         }).option("resolution", {
           type: "string",
           describe: "Resolution description"
@@ -4663,7 +6296,7 @@ function registerIssueCommand(yargs) {
           type: "string",
           array: true,
           describe: "File locations"
-        })
+        }).conflicts("impact", "stdin")
       ),
       async (argv) => {
         const format = parseOutputFormat(argv.format);
@@ -4681,13 +6314,17 @@ function registerIssueCommand(yargs) {
           return;
         }
         try {
+          let impact = argv.impact;
+          if (argv.stdin) {
+            impact = await readStdinContent();
+          }
           const result = await handleIssueUpdate(
             id,
             {
               status: argv.status,
               title: argv.title,
               severity: argv.severity,
-              impact: argv.impact,
+              impact,
               resolution: argv.resolution === "" ? null : argv.resolution,
               components: argv.components ? normalizeArrayOption(argv.components) : void 0,
               relatedTickets: argv["related-tickets"] ? normalizeArrayOption(argv["related-tickets"]) : void 0,
@@ -5054,11 +6691,23 @@ function registerSnapshotCommand(yargs) {
   return yargs.command(
     "snapshot",
     "Save current project state for session diffs",
-    (y) => addFormatOption(y),
+    (y) => addFormatOption(
+      y.option("quiet", {
+        type: "boolean",
+        default: false,
+        describe: "Suppress output (for hook usage)"
+      })
+    ),
     async (argv) => {
       const format = parseOutputFormat(argv.format);
+      const quiet = argv.quiet;
       const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
       if (!root) {
+        if (quiet) {
+          process.stderr.write("No .story/ project found.\n");
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
         writeOutput(
           formatError("not_found", "No .story/ project found.", format)
         );
@@ -5066,10 +6715,18 @@ function registerSnapshotCommand(yargs) {
         return;
       }
       try {
-        const result = await handleSnapshot(root, format);
-        writeOutput(result.output);
+        const result = await handleSnapshot(root, format, { quiet });
+        if (!quiet && result.output) {
+          writeOutput(result.output);
+        }
         process.exitCode = result.exitCode ?? ExitCode.OK;
       } catch (err) {
+        if (quiet) {
+          const message2 = err instanceof Error ? err.message : String(err);
+          process.stderr.write(message2 + "\n");
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
         if (err instanceof CliValidationError) {
           writeOutput(formatError(err.code, err.message, format));
           process.exitCode = ExitCode.USER_ERROR;
@@ -5130,6 +6787,271 @@ function registerExportCommand(yargs) {
     }
   );
 }
+function registerNoteCommand(yargs) {
+  return yargs.command(
+    "note",
+    "Manage notes",
+    (y) => y.command(
+      "list",
+      "List notes",
+      (y2) => addFormatOption(
+        y2.option("status", {
+          type: "string",
+          choices: ["active", "archived"],
+          describe: "Filter by status"
+        }).option("tag", {
+          type: "string",
+          describe: "Filter by tag"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(
+          format,
+          (ctx) => handleNoteList(
+            {
+              status: argv.status,
+              tag: argv.tag
+            },
+            ctx
+          )
+        );
+      }
+    ).command(
+      "get <id>",
+      "Get a note",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Note ID (e.g. N-001)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseNoteId(argv.id);
+        await runReadCommand(format, (ctx) => handleNoteGet(id, ctx));
+      }
+    ).command(
+      "create",
+      "Create a note",
+      (y2) => addFormatOption(
+        y2.option("content", {
+          type: "string",
+          describe: "Note content"
+        }).option("title", {
+          type: "string",
+          describe: "Note title"
+        }).option("tags", {
+          type: "array",
+          describe: "Tags for the note"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read content from stdin"
+        }).conflicts("content", "stdin").check((argv) => {
+          if (!argv.content && !argv.stdin) {
+            throw new Error(
+              "Specify either --content or --stdin"
+            );
+          }
+          return true;
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError("not_found", "No .story/ project found.", format)
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          let content;
+          if (argv.stdin) {
+            content = await readStdinContent();
+          } else {
+            content = argv.content;
+          }
+          const result = await handleNoteCreate(
+            {
+              content,
+              title: argv.title ?? null,
+              tags: argv.tags
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "update <id>",
+      "Update a note",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Note ID (e.g. N-001)"
+        }).option("content", {
+          type: "string",
+          describe: "New content"
+        }).option("title", {
+          type: "string",
+          describe: "New title"
+        }).option("tags", {
+          type: "array",
+          describe: "New tags (replaces existing)"
+        }).option("clear-tags", {
+          type: "boolean",
+          default: false,
+          describe: "Clear all tags"
+        }).option("status", {
+          type: "string",
+          choices: ["active", "archived"],
+          describe: "New status"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read content from stdin"
+        }).conflicts("content", "stdin").conflicts("tags", "clear-tags")
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseNoteId(argv.id);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError("not_found", "No .story/ project found.", format)
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        let content;
+        if (argv.stdin) {
+          content = await readStdinContent();
+        } else {
+          content = argv.content;
+        }
+        try {
+          const result = await handleNoteUpdate(
+            id,
+            {
+              content,
+              title: argv.title === "" ? null : argv.title,
+              tags: argv.tags,
+              clearTags: argv["clear-tags"],
+              status: argv.status
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "delete <id>",
+      "Delete a note",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Note ID (e.g. N-001)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseNoteId(argv.id);
+        await runDeleteCommand(
+          format,
+          false,
+          async (ctx) => handleNoteDelete(id, format, ctx.root)
+        );
+      }
+    ).demandCommand(
+      1,
+      "Specify a note subcommand: list, get, create, update, delete"
+    ).strict(),
+    () => {
+    }
+  );
+}
+function registerReferenceCommand(yargs) {
+  return yargs.command(
+    "reference",
+    "Print CLI command and MCP tool reference",
+    (y) => addFormatOption(y),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      const output = handleReference(format);
+      writeOutput(output);
+    }
+  );
+}
+function registerRecommendCommand(yargs) {
+  return yargs.command(
+    "recommend",
+    "Context-aware work suggestions",
+    (y) => addFormatOption(y).option("count", {
+      type: "number",
+      default: 5,
+      describe: "Number of recommendations (1-10)"
+    }),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      const raw = Number(argv.count) || 5;
+      const count = Math.max(1, Math.min(10, Math.floor(raw)));
+      await runReadCommand(format, (ctx) => handleRecommend(ctx, count));
+    }
+  );
+}
+function registerSetupSkillCommand(yargs) {
+  return yargs.command(
+    "setup-skill",
+    "Install the /story skill globally for Claude Code",
+    (y) => y.option("skip-hooks", {
+      type: "boolean",
+      default: false,
+      description: "Skip PreCompact hook registration"
+    }),
+    async (argv) => {
+      const { handleSetupSkill: handleSetupSkill2 } = await Promise.resolve().then(() => (init_setup_skill(), setup_skill_exports));
+      await handleSetupSkill2({ skipHooks: argv["skip-hooks"] === true });
+    }
+  );
+}
 var init_register = __esm({
   "src/cli/register.ts"() {
     "use strict";
@@ -5143,11 +7065,14 @@ var init_register = __esm({
     init_blocker();
     init_ticket2();
     init_issue2();
+    init_note2();
+    init_recommend2();
     init_phase();
     init_init2();
     init_recap();
     init_export();
     init_snapshot2();
+    init_reference();
   }
 });
 
@@ -5174,9 +7099,13 @@ async function runCli() {
     registerValidateCommand: registerValidateCommand2,
     registerSnapshotCommand: registerSnapshotCommand2,
     registerRecapCommand: registerRecapCommand2,
-    registerExportCommand: registerExportCommand2
+    registerExportCommand: registerExportCommand2,
+    registerNoteCommand: registerNoteCommand2,
+    registerRecommendCommand: registerRecommendCommand2,
+    registerReferenceCommand: registerReferenceCommand2,
+    registerSetupSkillCommand: registerSetupSkillCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "0.1.7";
+  const version2 = "0.1.9";
   class HandledError extends Error {
     constructor() {
       super("HANDLED_ERROR");
@@ -5203,12 +7132,16 @@ async function runCli() {
   cli = registerPhaseCommand2(cli);
   cli = registerTicketCommand2(cli);
   cli = registerIssueCommand2(cli);
+  cli = registerNoteCommand2(cli);
   cli = registerHandoverCommand2(cli);
   cli = registerBlockerCommand2(cli);
   cli = registerValidateCommand2(cli);
   cli = registerSnapshotCommand2(cli);
   cli = registerRecapCommand2(cli);
   cli = registerExportCommand2(cli);
+  cli = registerRecommendCommand2(cli);
+  cli = registerReferenceCommand2(cli);
+  cli = registerSetupSkillCommand2(cli);
   function handleUnexpectedError(err) {
     if (err instanceof HandledError) return;
     const message = err instanceof Error ? err.message : String(err);