@anthropologies/claudestory 0.1.55 → 0.1.57

package/README.md

@@ -1,6 +1,8 @@
 # claudestory
 
-Cross-session context persistence for AI coding assistants. Tracks tickets, issues, roadmap phases, blockers, and session handovers in a `.story/` directory that AI tools read and write natively.
+An agentic development framework. Track tickets, issues, and progress for your project in a `.story/` directory that AI tools read and write natively.
+
+**[claudestory.com](https://claudestory.com)** | **[Documentation](https://claudestory.com/cli)** | **[Privacy Policy](https://claudestory.com/privacy)**
 
 ## Installation
 
@@ -201,4 +203,4 @@ Everything else in `.story/` should be tracked.
 
 ## License
 
-MIT
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) -- free for personal and noncommercial use. For commercial licensing, contact shayegh@me.com.

package/dist/cli.js

@@ -2634,6 +2634,20 @@ function formatReference(commands, mcpTools, format) {
     lines.push(`- **${tool.name}**${params} \u2014 ${tool.description}`);
   }
   lines.push("");
+  lines.push("## /story design");
+  lines.push("");
+  lines.push("Evaluate frontend code against platform-specific design best practices.");
+  lines.push("");
+  lines.push("```");
+  lines.push("/story design                    # Auto-detect platform, evaluate frontend");
+  lines.push("/story design web                # Evaluate against web best practices");
+  lines.push("/story design ios                # Evaluate against iOS HIG");
+  lines.push("/story design macos              # Evaluate against macOS HIG");
+  lines.push("/story design android            # Evaluate against Material Design");
+  lines.push("```");
+  lines.push("");
+  lines.push("Creates issues automatically when claudestory MCP tools or CLI are available. Checks for existing design issues to avoid duplicates on repeated runs. Outputs markdown checklist as fallback when neither MCP nor CLI is available.");
+  lines.push("");
   lines.push("## Common Workflows");
   lines.push("");
   lines.push("### Session Start");
@@ -8358,7 +8372,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "0.1.55";
+  return "0.1.57";
 }
 var init_version_check = __esm({
   "src/autonomous/version-check.ts"() {
@@ -8965,7 +8979,7 @@ ${ticket.description}` : "",
       "# Autonomous Session Started",
       "",
       `You are now in autonomous mode. ${sessionDesc}${checkpointDesc}`,
-      "Do NOT stop to summarize. Do NOT ask the user. Pick a ticket or issue and start working immediately.",
+      "Do NOT stop to summarize. Do NOT ask the user. Do NOT cancel for context management \u2014 compaction is automatic. Pick a ticket or issue and start working immediately.",
       "",
       "## Ticket Candidates",
       "",
@@ -8992,6 +9006,7 @@ ${ticket.description}` : "",
         "Do NOT ask the user for confirmation or approval.",
         "Do NOT stop or summarize between tickets \u2014 call autonomous_guide IMMEDIATELY.",
         "You are in autonomous mode \u2014 continue working until done.",
+        "NEVER cancel due to context size. Claude Story's hooks compact context automatically and preserve all session state.",
         ...versionWarning ? [`**Warning:** ${versionWarning}`] : []
       ],
       transitionedFrom: "INIT"
@@ -9315,7 +9330,8 @@ ${driftPreamble}Recovered to state: **${mapping.state}**. Continue from here.`,
       reminders: [
         "Do NOT stop or summarize. Pick the next ticket IMMEDIATELY.",
         "Do NOT ask the user for confirmation.",
-        "You are in autonomous mode \u2014 continue working."
+        "You are in autonomous mode \u2014 continue working.",
+        "Context compacted successfully \u2014 all session state preserved. Continue working."
       ]
     });
   }
@@ -9417,6 +9433,30 @@ async function handleCancel(root, args) {
   if (info.state.state === "SESSION_END" || info.state.status === "completed") {
     return guideError(new Error("Session already ended."));
   }
+  const isAutoMode = info.state.mode === "auto" || !info.state.mode;
+  const hasTicketsRemaining = info.state.config.maxTicketsPerSession === 0 || info.state.completedTickets.length < info.state.config.maxTicketsPerSession;
+  const isWorkingState = !["SESSION_END", "HANDOVER", "COMPACT"].includes(info.state.state);
+  if (isAutoMode && hasTicketsRemaining && isWorkingState) {
+    return {
+      content: [{
+        type: "text",
+        text: [
+          "# Cancel Rejected \u2014 Session Still Active",
+          "",
+          `You have completed ${info.state.completedTickets.length} ticket(s) with more work remaining.`,
+          "Do NOT cancel an autonomous session due to context size.",
+          "If you need to manage context, Claude Code handles compaction automatically.",
+          "",
+          "Continue working by calling `claudestory_autonomous_guide` with:",
+          "```json",
+          `{ "sessionId": "${info.state.sessionId}", "action": "report", "report": { "completedAction": "ticket_picked", "ticketId": "T-XXX" } }`,
+          "```",
+          "",
+          "To force-cancel (admin only), run: `claudestory session stop`"
+        ].join("\n")
+      }]
+    };
+  }
   await recoverPendingMutation(info.dir, info.state, root);
   const cancelInfo = findSessionById(root, args.sessionId) ?? info;
   let ticketReleased = false;
@@ -9483,12 +9523,18 @@ function guideResult(state, currentState, opts) {
     contextPressure: state.contextPressure?.level ?? "low",
     branch: state.git?.branch ?? null
   };
+  const allReminders = [...opts.reminders ?? []];
+  if ((state.mode === "auto" || !state.mode) && currentState !== "SESSION_END") {
+    allReminders.push(
+      "NEVER cancel this session due to context size. Compaction is automatic \u2014 Claude Story preserves all session state across compactions via hooks."
+    );
+  }
   const output = {
     sessionId: state.sessionId,
     state: currentState,
     transitionedFrom: opts.transitionedFrom,
     instruction: opts.instruction,
-    reminders: opts.reminders ?? [],
+    reminders: allReminders,
     contextAdvice: "ok",
     sessionSummary: summary
   };
@@ -10923,7 +10969,7 @@ var init_mcp = __esm({
     init_init();
     ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "0.1.55";
+    version = "0.1.57";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -11527,6 +11573,7 @@ var init_reference = __esm({
 // src/cli/commands/setup-skill.ts
 var setup_skill_exports = {};
 __export(setup_skill_exports, {
+  copyDirRecursive: () => copyDirRecursive,
   handleSetupSkill: () => handleSetupSkill,
   registerPreCompactHook: () => registerPreCompactHook,
   registerSessionStartHook: () => registerSessionStartHook,
@@ -11534,7 +11581,7 @@ __export(setup_skill_exports, {
   removeHook: () => removeHook,
   resolveSkillSourceDir: () => resolveSkillSourceDir
 });
-import { mkdir as mkdir5, writeFile as writeFile3, readFile as readFile5, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
+import { mkdir as mkdir5, writeFile as writeFile3, readFile as readFile5, readdir as readdir4, copyFile, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
 import { join as join21, dirname as dirname5 } from "path";
 import { homedir } from "os";
@@ -11555,6 +11602,43 @@ function resolveSkillSourceDir() {
   ${sourcePath}`
   );
 }
+async function copyDirRecursive(srcDir, destDir) {
+  const tmpDir = destDir + ".tmp";
+  const bakDir = destDir + ".bak";
+  if (!existsSync12(destDir) && existsSync12(bakDir)) {
+    await rename2(bakDir, destDir);
+  }
+  if (existsSync12(tmpDir)) await rm(tmpDir, { recursive: true, force: true });
+  if (existsSync12(bakDir)) await rm(bakDir, { recursive: true, force: true });
+  await mkdir5(tmpDir, { recursive: true });
+  const entries = await readdir4(srcDir, { withFileTypes: true, recursive: true });
+  const written = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const parent = entry.parentPath ?? entry.path ?? srcDir;
+    const relativePath = join21(parent, entry.name).slice(srcDir.length + 1);
+    const srcPath = join21(srcDir, relativePath);
+    const destPath = join21(tmpDir, relativePath);
+    await mkdir5(dirname5(destPath), { recursive: true });
+    await copyFile(srcPath, destPath);
+    written.push(relativePath);
+  }
+  if (existsSync12(destDir)) {
+    await rename2(destDir, bakDir);
+  }
+  try {
+    await rename2(tmpDir, destDir);
+  } catch (err) {
+    if (existsSync12(bakDir)) await rename2(bakDir, destDir).catch(() => {
+    });
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+    throw err;
+  }
+  await rm(bakDir, { recursive: true, force: true }).catch(() => {
+  });
+  return written;
+}
 function isHookWithCommand(entry, command) {
   if (typeof entry !== "object" || entry === null) return false;
   const e = entry;
@@ -11740,6 +11824,19 @@ async function handleSetupSkill(options = {}) {
       missingFiles.push(filename);
     }
   }
+  const designSrcDir = join21(srcSkillDir, "design");
+  if (existsSync12(designSrcDir)) {
+    const designDestDir = join21(skillDir, "design");
+    try {
+      const designFiles = await copyDirRecursive(designSrcDir, designDestDir);
+      for (const f of designFiles) writtenFiles.push(`design/${f}`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Warning: design skill copy failed: ${msg}
+`);
+      missingFiles.push("design/");
+    }
+  }
   log(`${existed ? "Updated" : "Installed"} /story skill at ${skillDir}/`);
   log(`  ${writtenFiles.join(" + ")} written`);
   if (missingFiles.length > 0) {
@@ -14354,7 +14451,7 @@ async function runCli() {
     registerSessionCommand: registerSessionCommand2,
     registerRepairCommand: registerRepairCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "0.1.55";
+  const version2 = "0.1.57";
   class HandledError extends Error {
     constructor() {
       super("HANDLED_ERROR");

package/dist/index.d.ts

@@ -1377,42 +1377,15 @@ declare const SnapshotV1Schema: z.ZodObject<{
         file: z.ZodString;
         message: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        type: string;
         message: string;
+        type: string;
         file: string;
     }, {
-        type: string;
         message: string;
+        type: string;
         file: string;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    version: 1;
-    config: {
-        version: number;
-        type: string;
-        language: string;
-        project: string;
-        features: {
-            issues: boolean;
-            tickets: boolean;
-            handovers: boolean;
-            roadmap: boolean;
-            reviews: boolean;
-        } & {
-            [k: string]: unknown;
-        };
-        schemaVersion?: number | undefined;
-        recipe?: string | undefined;
-        recipeOverrides?: {
-            maxTicketsPerSession?: number | undefined;
-            compactThreshold?: string | undefined;
-            reviewBackends?: string[] | undefined;
-            handoverInterval?: number | undefined;
-            stages?: Record<string, Record<string, unknown>> | undefined;
-        } | undefined;
-    } & {
-        [k: string]: unknown;
-    };
     issues: z.objectOutputType<{
         id: z.ZodString;
         title: z.ZodString;
@@ -1449,8 +1422,8 @@ declare const SnapshotV1Schema: z.ZodObject<{
         claimedBySession: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.ZodTypeAny, "passthrough">[];
     roadmap: {
-        date: string;
         title: string;
+        date: string;
         phases: z.objectOutputType<{
             id: z.ZodString;
             label: z.ZodString;
@@ -1468,6 +1441,7 @@ declare const SnapshotV1Schema: z.ZodObject<{
     } & {
         [k: string]: unknown;
     };
+    version: 1;
     project: string;
     notes: z.objectOutputType<{
         id: z.ZodString;
@@ -1493,19 +1467,11 @@ declare const SnapshotV1Schema: z.ZodObject<{
         status: z.ZodEnum<["active", "deprecated", "superseded"]>;
     }, z.ZodTypeAny, "passthrough">[];
     createdAt: string;
-    handoverFilenames: string[];
-    warnings?: {
-        type: string;
-        message: string;
-        file: string;
-    }[] | undefined;
-}, {
-    version: 1;
     config: {
-        version: number;
         type: string;
-        language: string;
+        version: number;
         project: string;
+        language: string;
         features: {
             issues: boolean;
             tickets: boolean;
@@ -1527,6 +1493,13 @@ declare const SnapshotV1Schema: z.ZodObject<{
     } & {
         [k: string]: unknown;
     };
+    handoverFilenames: string[];
+    warnings?: {
+        message: string;
+        type: string;
+        file: string;
+    }[] | undefined;
+}, {
     issues: z.objectInputType<{
         id: z.ZodString;
         title: z.ZodString;
@@ -1563,8 +1536,8 @@ declare const SnapshotV1Schema: z.ZodObject<{
         claimedBySession: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.ZodTypeAny, "passthrough">[];
     roadmap: {
-        date: string;
         title: string;
+        date: string;
         phases: z.objectInputType<{
             id: z.ZodString;
             label: z.ZodString;
@@ -1582,8 +1555,35 @@ declare const SnapshotV1Schema: z.ZodObject<{
     } & {
         [k: string]: unknown;
     };
+    version: 1;
     project: string;
     createdAt: string;
+    config: {
+        type: string;
+        version: number;
+        project: string;
+        language: string;
+        features: {
+            issues: boolean;
+            tickets: boolean;
+            handovers: boolean;
+            roadmap: boolean;
+            reviews: boolean;
+        } & {
+            [k: string]: unknown;
+        };
+        schemaVersion?: number | undefined;
+        recipe?: string | undefined;
+        recipeOverrides?: {
+            maxTicketsPerSession?: number | undefined;
+            compactThreshold?: string | undefined;
+            reviewBackends?: string[] | undefined;
+            handoverInterval?: number | undefined;
+            stages?: Record<string, Record<string, unknown>> | undefined;
+        } | undefined;
+    } & {
+        [k: string]: unknown;
+    };
     notes?: z.objectInputType<{
         id: z.ZodString;
         title: z.ZodNullable<z.ZodString>;
@@ -1608,8 +1608,8 @@ declare const SnapshotV1Schema: z.ZodObject<{
         status: z.ZodEnum<["active", "deprecated", "superseded"]>;
     }, z.ZodTypeAny, "passthrough">[] | undefined;
     warnings?: {
-        type: string;
         message: string;
+        type: string;
         file: string;
     }[] | undefined;
     handoverFilenames?: string[] | undefined;

package/dist/mcp.js

@@ -7816,7 +7816,7 @@ function getInstalledVersion() {
   }
 }
 function getRunningVersion() {
-  return "0.1.55";
+  return "0.1.57";
 }
 
 // src/autonomous/guide.ts
@@ -8439,7 +8439,7 @@ ${ticket.description}` : "",
       "# Autonomous Session Started",
       "",
       `You are now in autonomous mode. ${sessionDesc}${checkpointDesc}`,
-      "Do NOT stop to summarize. Do NOT ask the user. Pick a ticket or issue and start working immediately.",
+      "Do NOT stop to summarize. Do NOT ask the user. Do NOT cancel for context management \u2014 compaction is automatic. Pick a ticket or issue and start working immediately.",
       "",
       "## Ticket Candidates",
       "",
@@ -8466,6 +8466,7 @@ ${ticket.description}` : "",
         "Do NOT ask the user for confirmation or approval.",
         "Do NOT stop or summarize between tickets \u2014 call autonomous_guide IMMEDIATELY.",
         "You are in autonomous mode \u2014 continue working until done.",
+        "NEVER cancel due to context size. Claude Story's hooks compact context automatically and preserve all session state.",
         ...versionWarning ? [`**Warning:** ${versionWarning}`] : []
       ],
       transitionedFrom: "INIT"
@@ -8790,7 +8791,8 @@ ${driftPreamble}Recovered to state: **${mapping.state}**. Continue from here.`,
       reminders: [
         "Do NOT stop or summarize. Pick the next ticket IMMEDIATELY.",
         "Do NOT ask the user for confirmation.",
-        "You are in autonomous mode \u2014 continue working."
+        "You are in autonomous mode \u2014 continue working.",
+        "Context compacted successfully \u2014 all session state preserved. Continue working."
       ]
     });
   }
@@ -8892,6 +8894,30 @@ async function handleCancel(root, args) {
   if (info.state.state === "SESSION_END" || info.state.status === "completed") {
     return guideError(new Error("Session already ended."));
   }
+  const isAutoMode = info.state.mode === "auto" || !info.state.mode;
+  const hasTicketsRemaining = info.state.config.maxTicketsPerSession === 0 || info.state.completedTickets.length < info.state.config.maxTicketsPerSession;
+  const isWorkingState = !["SESSION_END", "HANDOVER", "COMPACT"].includes(info.state.state);
+  if (isAutoMode && hasTicketsRemaining && isWorkingState) {
+    return {
+      content: [{
+        type: "text",
+        text: [
+          "# Cancel Rejected \u2014 Session Still Active",
+          "",
+          `You have completed ${info.state.completedTickets.length} ticket(s) with more work remaining.`,
+          "Do NOT cancel an autonomous session due to context size.",
+          "If you need to manage context, Claude Code handles compaction automatically.",
+          "",
+          "Continue working by calling `claudestory_autonomous_guide` with:",
+          "```json",
+          `{ "sessionId": "${info.state.sessionId}", "action": "report", "report": { "completedAction": "ticket_picked", "ticketId": "T-XXX" } }`,
+          "```",
+          "",
+          "To force-cancel (admin only), run: `claudestory session stop`"
+        ].join("\n")
+      }]
+    };
+  }
   await recoverPendingMutation(info.dir, info.state, root);
   const cancelInfo = findSessionById(root, args.sessionId) ?? info;
   let ticketReleased = false;
@@ -8958,12 +8984,18 @@ function guideResult(state, currentState, opts) {
     contextPressure: state.contextPressure?.level ?? "low",
     branch: state.git?.branch ?? null
   };
+  const allReminders = [...opts.reminders ?? []];
+  if ((state.mode === "auto" || !state.mode) && currentState !== "SESSION_END") {
+    allReminders.push(
+      "NEVER cancel this session due to context size. Compaction is automatic \u2014 Claude Story preserves all session state across compactions via hooks."
+    );
+  }
   const output = {
     sessionId: state.sessionId,
     state: currentState,
     transitionedFrom: opts.transitionedFrom,
     instruction: opts.instruction,
-    reminders: opts.reminders ?? [],
+    reminders: allReminders,
     contextAdvice: "ok",
     sessionSummary: summary
   };
@@ -10055,7 +10087,7 @@ async function ensureGitignoreEntries(gitignorePath, entries) {
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.55";
+var version = "0.1.57";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.55",
-  "license": "UNLICENSED",
-  "description": "Cross-session context persistence for AI coding projects. Tracks tickets, issues, roadmap, and handovers so every session builds on the last.",
+  "version": "0.1.57",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "description": "An agentic development framework. Track tickets, issues, and progress for your project so every session builds on the last.",
+  "homepage": "https://claudestory.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AmirShayegh/ClaudeStory"
+  },
   "keywords": [
     "claudestory",
     "claude-code",

package/src/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: story
-description: Cross-session context persistence for AI coding projects. Load project context, manage sessions, guide setup.
+description: Track tickets, issues, and progress for your project. Load project context, manage sessions, guide setup.
 ---
 
 # /story -- Project Context & Session Management
@@ -21,6 +21,8 @@ claudestory tracks tickets, issues, roadmap, and handovers in a `.story/` direct
 - `/story export` -> export project for sharing. Ask the user whether to export the current phase or the full project, then call `claudestory_export` with either `phase` or `all` set
 - `/story status` -> quick status check (call `claudestory_status` MCP tool)
 - `/story settings` -> manage project settings (see Settings section below)
+- `/story design` -> evaluate frontend design (read `design/design.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
+- `/story design <platform>` -> evaluate for specific platform: web, ios, macos, android (read `design/design.md` in the same directory as this skill file)
 - `/story help` -> show all capabilities (read `reference.md` in the same directory as this skill file; if not found, tell user to run `claudestory setup-skill`)
 
 If the user's intent doesn't match any of these, use the full context load.
@@ -132,6 +134,7 @@ Example: "Rules: integer cents for money, billing engine is pure logic, TDD for
 Tip: You can also use these modes anytime:
   /story guided T-XXX   One ticket end-to-end with planning and code review
   /story review T-XXX   Review code you already wrote
+  /story design          Evaluate frontend against platform best practices
 ```
 
 Show this once or twice, then never again.
@@ -182,6 +185,8 @@ When working on a task and you encounter a bug, inconsistency, or improvement op
 
 When starting work on a ticket, update its status to `inprogress`. When done, update to `complete` in the same commit as the code change.
 
+**Frontend design guidance:** When working on UI or frontend tickets, read `design/design.md` in the same directory as this skill file for design principles and platform-specific best practices. Follow its priority order (clarity > hierarchy > platform correctness > accessibility > state completeness) and load the relevant platform reference. This applies to any ticket involving components, layouts, styling, or visual design.
+
 ## Managing Tickets and Issues
 
 Ticket and issue create/update operations are available via both CLI and MCP tools. Delete remains CLI-only.
@@ -361,3 +366,4 @@ Additional skill documentation, loaded on demand:
 - **`setup-flow.md`** -- Project detection and AI-Assisted Setup Flow (new project initialization)
 - **`autonomous-mode.md`** -- Autonomous mode, review, plan, and guided execution tiers
 - **`reference.md`** -- Full CLI command and MCP tool reference
+- **`design/design.md`** -- Frontend design evaluation and implementation guidance, with platform references in `design/references/`

package/src/skill/autonomous-mode.md

@@ -14,6 +14,8 @@ This file is referenced from SKILL.md for `/story auto`, `/story review`, `/stor
 4. The guide advances through: PICK_TICKET -> PLAN -> PLAN_REVIEW -> IMPLEMENT -> CODE_REVIEW -> FINALIZE -> COMPLETE -> loop
 5. Continue until the guide returns SESSION_END
 
+**Frontend design:** If the current ticket involves UI, frontend, components, layouts, or styling, read `design/design.md` in the same directory as the skill file for design principles. Load the relevant platform reference from `design/references/`. Apply the priority order (clarity > hierarchy > platform correctness > accessibility > state completeness) during both planning and implementation.
+
 **Critical rules for autonomous mode:**
 - Do NOT use Claude Code's plan mode -- write plans as markdown files
 - Do NOT ask the user for confirmation or approval
@@ -21,9 +23,21 @@ This file is referenced from SKILL.md for `/story auto`, `/story review`, `/stor
 - Follow the guide's instructions exactly -- it specifies which tools to call, what parameters to use
 - After each step completes, call `claudestory_autonomous_guide` with `action: "report"` and the results
 
+**Recommended setup for long sessions:**
+
+Run Claude Code with: `claude --model claude-opus-4-6 --dangerously-skip-permissions`
+
+- **Skip-permissions** enables unattended execution -- no approval prompts consuming context
+- **Claude Story handles compaction automatically** -- context preserved across compactions, do not cancel because context feels large
+- Use only in **trusted repositories** -- skip-permissions disables safety prompts for all tool use
+
 **If the guide says to compact:** Call `claudestory_autonomous_guide` with `action: "pre_compact"`, then run `/compact`, then call with `action: "resume"`.
 
-**If something goes wrong:** Call `claudestory_autonomous_guide` with `action: "cancel"` to cleanly end the session.
+**If something goes wrong:**
+- Context feels large -- do nothing, compaction is automatic via hooks
+- Compaction happened -- call with `action: "resume"` to continue
+- Session stuck after compact -- run `claudestory session clear-compact` in terminal, then `action: "resume"`
+- Unrecoverable error -- run `claudestory session stop` in terminal (admin escape hatch)
 
 ## Tiered Access -- Review, Plan, Guided Modes