diff --git a/scripts/work/decompose.mjs b/scripts/work/decompose.mjs
index 001caf8..5f9b911 100644
--- a/scripts/work/decompose.mjs
+++ b/scripts/work/decompose.mjs
@@ -163,6 +163,26 @@ export async function executeDecompose(prdId, prdPath, prdText) {
     });
   } catch (e) {
     console.error("✗ Decomposer dispatch failed:", e.message);
+    if (/Image '.+' not found locally/.test(e.message ?? "")) {
+      console.error(
+        "  One-time setup: pnpm exec sandcastle docker build-image",
+      );
+    }
+    if (
+      /Not logged in|Please run \/login/.test(e.message ?? "") &&
+      process.platform === "darwin"
+    ) {
+      console.error(
+        "  macOS users: Claude Code stores credentials in the Keychain, not in ~/.claude/. Extract once:",
+      );
+      console.error(
+        `    security find-generic-password -s "Claude Code-credentials" -a "$USER" -w > ~/.claude/.credentials.json`,
+      );
+      console.error("    chmod 600 ~/.claude/.credentials.json");
+      console.error(
+        "  OR fall back to API key: export ANTHROPIC_API_KEY=sk-ant-...",
+      );
+    }
     console.error(
       "  See docs/guides/runbook.md → 'Using Sandcastle' for setup.",
     );
diff --git a/scripts/work/dispatch.mjs b/scripts/work/dispatch.mjs
index 248a56b..99da3c7 100644
--- a/scripts/work/dispatch.mjs
+++ b/scripts/work/dispatch.mjs
@@ -239,6 +239,21 @@ async function executeDispatch() {
         "  One-time setup: pnpm exec sandcastle docker build-image",
       );
     }
+    if (
+      /Not logged in|Please run \/login/.test(e.message ?? "") &&
+      process.platform === "darwin"
+    ) {
+      console.error(
+        "  macOS users: Claude Code stores credentials in the Keychain, not in ~/.claude/. Extract once:",
+      );
+      console.error(
+        `    security find-generic-password -s "Claude Code-credentials" -a "$USER" -w > ~/.claude/.credentials.json`,
+      );
+      console.error("    chmod 600 ~/.claude/.credentials.json");
+      console.error(
+        "  OR fall back to API key: export ANTHROPIC_API_KEY=sk-ant-...",
+      );
+    }
     console.error(
       "  See docs/guides/runbook.md → 'Using Sandcastle' for setup.",
     );