chief-clancy 0.2.0-beta.1 → 0.2.0-beta.3

package/README.md

@@ -192,7 +192,7 @@ Clancy also merges a section into your `CLAUDE.md` (or creates one) that tells C
 
 ## Optional enhancements
 
-Set during `/clancy:init` advanced setup, or by editing `.clancy/.env` directly.
+Set during `/clancy:init` advanced setup, or by editing `.clancy/.env` directly. Use `/clancy:settings` → "Save as defaults" to save non-credential settings to `~/.clancy/defaults.json` — new projects created with `/clancy:init` will inherit them automatically.
 
 ### Figma MCP
 
@@ -336,6 +336,12 @@ Your board tokens and API keys live in `.clancy/.env`. Although Claude doesn't n
 
 This prevents Claude from reading these files regardless of what commands run. Clancy automatically adds `.clancy/.env` to `.gitignore` during init, but the deny list is an additional layer.
 
+### Credential guard
+
+Clancy installs a `PreToolUse` hook (`clancy-credential-guard.js`) that scans every Write, Edit, and MultiEdit operation for credential patterns — API keys, tokens, passwords, private keys, and connection strings. If a match is found, the operation is blocked with a message telling Claude to move the credential to `.clancy/.env` instead. Files that are expected to contain credentials (`.clancy/.env`, `.env.example`, etc.) are exempt.
+
+This is best-effort — it won't catch every possible credential format, but it prevents the most common accidental leaks.
+
 ### Token scopes
 
 Use the minimum permissions each integration requires:
@@ -418,6 +424,8 @@ lsof -ti:5173 | xargs kill -9   # replace 5173 with your PLAYWRIGHT_DEV_PORT
 
 Or directly: `npx chief-clancy@latest`
 
+The update workflow shows what's changed (changelog diff) and asks for confirmation before overwriting. If you've customised any command or workflow files, they're automatically backed up to `.claude/clancy/local-patches/` before the update — check there to reapply your changes afterwards.
+
 ---
 
 **Uninstalling?**
@@ -426,7 +434,7 @@ Or directly: `npx chief-clancy@latest`
 /clancy:uninstall
 ```
 
-Removes slash commands from your chosen location. Optionally removes `.clancy/` (credentials and docs). Never touches `CLAUDE.md`.
+Removes slash commands from your chosen location. Cleans up the `<!-- clancy:start -->` / `<!-- clancy:end -->` block from `CLAUDE.md` (or deletes it entirely if Clancy created it) and removes the `.clancy/.env` entry from `.gitignore`. Optionally removes `.clancy/` (credentials and docs).
 
 ---
 

package/bin/install.js

@@ -49,6 +49,13 @@ async function choose(question, options, defaultChoice = 1) {
   return raw.trim() || String(defaultChoice);
 }
 
+const crypto = require('crypto');
+
+function fileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').digest('hex', content);
+}
+
 function copyDir(src, dest) {
   // Use lstatSync (not statSync) to detect symlinks — statSync follows them and misreports
   if (fs.existsSync(dest)) {
@@ -65,6 +72,73 @@ function copyDir(src, dest) {
   }
 }
 
+/**
+ * Build a manifest of installed files with SHA-256 hashes.
+ * Format: { "relative/path.md": "<sha256>", ... }
+ */
+function buildManifest(baseDir) {
+  const manifest = {};
+  function walk(dir, prefix) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(full, rel);
+      } else {
+        const content = fs.readFileSync(full);
+        manifest[rel] = crypto.createHash('sha256').update(content).digest('hex');
+      }
+    }
+  }
+  walk(baseDir, '');
+  return manifest;
+}
+
+/**
+ * Detect files modified by the user since last install by comparing
+ * current file hashes against the stored manifest. Returns array of
+ * { rel, absPath } for modified files.
+ */
+function detectModifiedFiles(baseDir, manifestPath) {
+  if (!fs.existsSync(manifestPath)) return [];
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch { return []; }
+
+  const modified = [];
+  for (const [rel, hash] of Object.entries(manifest)) {
+    const absPath = path.join(baseDir, rel);
+    if (!fs.existsSync(absPath)) continue;
+    const content = fs.readFileSync(absPath);
+    const currentHash = crypto.createHash('sha256').update(content).digest('hex');
+    if (currentHash !== hash) {
+      modified.push({ rel, absPath });
+    }
+  }
+  return modified;
+}
+
+/**
+ * Back up modified files to a patches directory alongside the install.
+ * Returns the backup directory path if any files were backed up.
+ */
+function backupModifiedFiles(modified, patchesDir) {
+  if (modified.length === 0) return null;
+  fs.mkdirSync(patchesDir, { recursive: true });
+  for (const { rel, absPath } of modified) {
+    const backupPath = path.join(patchesDir, rel);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    fs.copyFileSync(absPath, backupPath);
+  }
+  // Write metadata so /clancy:update workflow knows what was backed up
+  fs.writeFileSync(
+    path.join(patchesDir, 'backup-meta.json'),
+    JSON.stringify({ backed_up: modified.map(m => m.rel), date: new Date().toISOString() }, null, 2)
+  );
+  return patchesDir;
+}
+
 async function main() {
   console.log('');
   console.log(blue('  ██████╗██╗      █████╗ ███╗   ██╗ ██████╗██╗   ██╗'));
@@ -116,14 +190,42 @@ async function main() {
   console.log(dim(`  Installing to: ${dest}`));
 
   try {
+    // Determine manifest and patches paths (sibling to commands dir)
+    const claudeDir = path.dirname(path.dirname(dest)); // .claude/ (parent of commands/)
+    const manifestPath = path.join(claudeDir, 'clancy', 'manifest.json');
+    const patchesDir = path.join(claudeDir, 'clancy', 'local-patches');
+
     if (fs.existsSync(dest) || fs.existsSync(workflowsDest)) {
       console.log('');
+
+      // Detect user-modified files before overwriting
+      const modified = detectModifiedFiles(dest, manifestPath);
+      const modifiedWorkflows = detectModifiedFiles(workflowsDest, manifestPath.replace('manifest.json', 'workflows-manifest.json'));
+      const allModified = [...modified, ...modifiedWorkflows];
+
+      if (allModified.length > 0) {
+        console.log(blue('  Modified files detected:'));
+        for (const { rel } of allModified) {
+          console.log(`    ${dim('•')} ${rel}`);
+        }
+        console.log('');
+        console.log(dim('  These will be backed up to .claude/clancy/local-patches/'));
+        console.log(dim('  before overwriting. You can reapply them after the update.'));
+        console.log('');
+      }
+
       const overwrite = await ask(blue(`  Commands already exist at ${dest}. Overwrite? [y/N] `));
       if (!overwrite.trim().toLowerCase().startsWith('y')) {
         console.log('\n  Aborted. No files changed.');
         rl.close();
         process.exit(0);
       }
+
+      // Back up modified files before overwriting
+      if (allModified.length > 0) {
+        backupModifiedFiles(allModified, patchesDir);
+        console.log(green(`\n  ✓ ${allModified.length} modified file(s) backed up to local-patches/`));
+      }
     }
 
     copyDir(COMMANDS_SRC, dest);
@@ -150,6 +252,14 @@ async function main() {
     // Write VERSION file so /clancy:doctor and /clancy:update can read the installed version
     fs.writeFileSync(path.join(dest, 'VERSION'), PKG.version);
 
+    // Write manifests so future updates can detect user-modified files
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(buildManifest(dest), null, 2));
+    fs.writeFileSync(
+      manifestPath.replace('manifest.json', 'workflows-manifest.json'),
+      JSON.stringify(buildManifest(workflowsDest), null, 2)
+    );
+
     // Install hooks and register them in Claude settings.json
     const claudeConfigDir = dest === GLOBAL_DEST
       ? path.join(homeDir, '.claude')
@@ -161,6 +271,7 @@ async function main() {
       'clancy-check-update.js',
       'clancy-statusline.js',
       'clancy-context-monitor.js',
+      'clancy-credential-guard.js',
     ];
 
     try {
@@ -196,9 +307,11 @@ async function main() {
       const updateScript    = path.join(hooksInstallDir, 'clancy-check-update.js');
       const statuslineScript = path.join(hooksInstallDir, 'clancy-statusline.js');
       const monitorScript   = path.join(hooksInstallDir, 'clancy-context-monitor.js');
+      const guardScript     = path.join(hooksInstallDir, 'clancy-credential-guard.js');
 
       registerHook('SessionStart', `node ${updateScript}`);
       registerHook('PostToolUse',  `node ${monitorScript}`);
+      registerHook('PreToolUse',   `node ${guardScript}`);
 
       // Statusline: registered as top-level key, not inside hooks
       if (!settings.statusLine) {

package/hooks/clancy-credential-guard.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Clancy Credential Guard — PreToolUse hook.
+// Scans file content being written or edited for credential patterns
+// (API keys, tokens, passwords, private keys) and blocks the operation
+// if a match is found. Best-effort — never fails the tool call on error.
+
+'use strict';
+
+const CREDENTIAL_PATTERNS = [
+  // Generic API keys and tokens
+  { name: 'Generic API key', pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{20,}["']?/i },
+  { name: 'Generic secret', pattern: /(?:secret|private[_-]?key)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{20,}["']?/i },
+  { name: 'Generic token', pattern: /(?:auth[_-]?token|access[_-]?token|bearer)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{20,}["']?/i },
+  { name: 'Generic password', pattern: /(?:password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{8,}["']?/i },
+
+  // AWS
+  { name: 'AWS Access Key', pattern: /AKIA[0-9A-Z]{16}/ },
+  { name: 'AWS Secret Key', pattern: /(?:aws_secret_access_key|aws_secret)\s*[:=]\s*["']?[A-Za-z0-9/+=]{40}["']?/i },
+
+  // GitHub
+  { name: 'GitHub PAT (classic)', pattern: /ghp_[A-Za-z0-9]{36}/ },
+  { name: 'GitHub PAT (fine-grained)', pattern: /github_pat_[A-Za-z0-9_]{82}/ },
+  { name: 'GitHub OAuth token', pattern: /gho_[A-Za-z0-9]{36}/ },
+
+  // Slack
+  { name: 'Slack token', pattern: /xox[bpors]-[0-9]{10,}-[A-Za-z0-9-]+/ },
+
+  // Stripe
+  { name: 'Stripe key', pattern: /(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{24,}/ },
+
+  // Private keys
+  { name: 'Private key', pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/ },
+
+  // Jira/Atlassian API tokens (base64-like, 24+ chars after the prefix)
+  { name: 'Atlassian API token', pattern: /(?:jira_api_token|atlassian[_-]?token)\s*[:=]\s*["']?[A-Za-z0-9+/=]{24,}["']?/i },
+
+  // Linear API key
+  { name: 'Linear API key', pattern: /lin_api_[A-Za-z0-9]{40,}/ },
+
+  // Generic connection strings
+  { name: 'Database connection string', pattern: /(?:mongodb|postgres|mysql|redis):\/\/[^\s"']+:[^\s"']+@/i },
+];
+
+// Files that are expected to contain credentials — skip them
+const ALLOWED_PATHS = [
+  '.clancy/.env',
+  '.env.local',
+  '.env.example',
+  '.env.development',
+  '.env.test',
+];
+
+function isAllowedPath(filePath) {
+  if (!filePath) return false;
+  return ALLOWED_PATHS.some(allowed => filePath.endsWith(allowed));
+}
+
+function scanForCredentials(content) {
+  if (!content || typeof content !== 'string') return [];
+  const matches = [];
+  for (const { name, pattern } of CREDENTIAL_PATTERNS) {
+    if (pattern.test(content)) {
+      matches.push(name);
+    }
+  }
+  return matches;
+}
+
+try {
+  const input = JSON.parse(process.argv[2] || '{}');
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+
+  // Only check file-writing tools
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+    // Pass through — not a file write
+    console.log(JSON.stringify({ decision: 'approve' }));
+    process.exit(0);
+  }
+
+  const filePath = toolInput.file_path || '';
+
+  // Skip files that are expected to contain credentials
+  if (isAllowedPath(filePath)) {
+    console.log(JSON.stringify({ decision: 'approve' }));
+    process.exit(0);
+  }
+
+  // Collect content to scan based on tool type
+  let contentToScan = '';
+  if (toolName === 'Write') {
+    contentToScan = toolInput.content || '';
+  } else if (toolName === 'Edit') {
+    contentToScan = toolInput.new_string || '';
+  } else if (toolName === 'MultiEdit') {
+    const edits = toolInput.edits || [];
+    contentToScan = edits.map(e => e.new_string || '').join('\n');
+  }
+
+  const found = scanForCredentials(contentToScan);
+
+  if (found.length > 0) {
+    console.log(JSON.stringify({
+      decision: 'block',
+      reason: `Credential guard: blocked writing to ${filePath}. Detected: ${found.join(', ')}. Move credentials to .clancy/.env instead.`,
+    }));
+  } else {
+    console.log(JSON.stringify({ decision: 'approve' }));
+  }
+} catch {
+  // Best-effort — never block on error
+  console.log(JSON.stringify({ decision: 'approve' }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chief-clancy",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "description": "Autonomous, board-driven development for Claude Code — scaffolds docs, integrates Kanban boards, runs tickets in a loop.",
   "keywords": [
     "claude",

package/src/workflows/settings.md

@@ -408,9 +408,50 @@ When updating a value:
 
 ---
 
+### Save as global defaults
+
+At the bottom of the settings menu (before Exit), show:
+
+```
+[{N}] Save as defaults   save current settings for all future projects
+```
+
+When selected:
+
+1. Read the current `.clancy/.env` and extract only the non-credential, non-board-specific settings:
+   - `MAX_ITERATIONS`
+   - `CLANCY_MODEL`
+   - `CLANCY_BASE_BRANCH`
+   - `PLAYWRIGHT_ENABLED`
+   - `PLAYWRIGHT_STARTUP_WAIT`
+
+2. Write these to `~/.clancy/defaults.json`:
+   ```json
+   {
+     "MAX_ITERATIONS": "5",
+     "CLANCY_MODEL": "claude-sonnet-4-6",
+     "CLANCY_BASE_BRANCH": "main"
+   }
+   ```
+
+3. Print: `✓ Defaults saved to ~/.clancy/defaults.json — new projects will inherit these settings.`
+
+4. Loop back to the settings menu.
+
+**Never save credentials, board-specific settings (status filter, sprint, label), or webhook URLs to global defaults.**
+
+---
+
+## Step 6 — Load global defaults during init
+
+When `/clancy:init` creates `.clancy/.env`, check if `~/.clancy/defaults.json` exists. If so, pre-populate the `.env` with those values instead of the built-in defaults. The user's answers during init still take priority — defaults are only used for settings that init doesn't ask about (max iterations, model, etc.).
+
+---
+
 ## Notes
 
 - All changes are written to `.clancy/.env` immediately after confirmation
 - Switching boards verifies credentials before making any changes — nothing is written if verification fails
 - `/clancy:init` remains available for a full re-setup (re-scaffolds scripts and docs)
 - This command never restarts any servers or triggers any ticket processing
+- Global defaults (`~/.clancy/defaults.json`) are optional — if the file doesn't exist, built-in defaults are used

package/src/workflows/uninstall.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Remove Clancy's slash commands from the local project, globally, or both. Optionally remove the `.clancy/` project folder (which includes `.clancy/.env`). Never touch `CLAUDE.md` under any circumstances.
+Remove Clancy's slash commands from the local project, globally, or both. Optionally remove the `.clancy/` project folder (which includes `.clancy/.env`). Clean up CLAUDE.md and .gitignore changes made during init.
 
 ---
 
@@ -50,14 +50,15 @@ Print: `✓ Clancy commands removed from [location].`
 ### Step 2b — Remove hooks
 
 For each location being removed, delete these hook files if they exist:
-- Project-local: `.claude/hooks/clancy-check-update.js`, `.claude/hooks/clancy-statusline.js`, `.claude/hooks/clancy-context-monitor.js`
-- Global: `~/.claude/hooks/clancy-check-update.js`, `~/.claude/hooks/clancy-statusline.js`, `~/.claude/hooks/clancy-context-monitor.js`
+- Project-local: `.claude/hooks/clancy-check-update.js`, `.claude/hooks/clancy-statusline.js`, `.claude/hooks/clancy-context-monitor.js`, `.claude/hooks/clancy-credential-guard.js`
+- Global: `~/.claude/hooks/clancy-check-update.js`, `~/.claude/hooks/clancy-statusline.js`, `~/.claude/hooks/clancy-context-monitor.js`, `~/.claude/hooks/clancy-credential-guard.js`
 
 Then remove the Clancy hook registrations from the corresponding `settings.json` (`.claude/settings.json` for local, `~/.claude/settings.json` for global):
 - Remove any entry in `hooks.SessionStart` whose `command` contains `clancy-check-update`
 - Remove any entry in `hooks.PostToolUse` whose `command` contains `clancy-context-monitor`
+- Remove any entry in `hooks.PreToolUse` whose `command` contains `clancy-credential-guard`
 - Remove the `statusLine` key if its `command` value contains `clancy-statusline`
-- If removing an entry leaves a `hooks.SessionStart` or `hooks.PostToolUse` array empty, remove the key entirely
+- If removing an entry leaves a `hooks.SessionStart`, `hooks.PostToolUse`, or `hooks.PreToolUse` array empty, remove the key entirely
 
 Also remove the update check cache if it exists: `~/.claude/cache/clancy-update-check.json`
 
@@ -65,7 +66,46 @@ If `settings.json` does not exist or cannot be parsed, skip silently — do not
 
 ---
 
-## Step 3 — Offer to remove .clancy/ (if present)
+## Step 3 — Clean up CLAUDE.md
+
+Check whether `CLAUDE.md` exists in the current project directory.
+
+If it does, check for Clancy markers (`<!-- clancy:start -->` and `<!-- clancy:end -->`):
+
+**If markers found:**
+
+Read the full file content. Determine whether Clancy created the file or appended to an existing one:
+
+- **Clancy created it** (the file contains only whitespace outside the markers — no meaningful content before `<!-- clancy:start -->` or after `<!-- clancy:end -->`): delete the entire file.
+- **Clancy appended to an existing file** (there is meaningful content outside the markers): remove everything from `<!-- clancy:start -->` through `<!-- clancy:end -->` (inclusive), plus any blank lines immediately before the start marker that were added as spacing. Write the cleaned file back.
+
+Print `✓ CLAUDE.md cleaned up.` (or `✓ CLAUDE.md removed.` if deleted).
+
+**If no markers found:** skip — Clancy didn't modify this file.
+
+**If CLAUDE.md does not exist:** skip.
+
+---
+
+## Step 4 — Clean up .gitignore
+
+Check whether `.gitignore` exists in the current project directory.
+
+If it does, check whether it contains the Clancy entries (`# Clancy credentials` and/or `.clancy/.env`):
+
+**If found:** remove the `# Clancy credentials` comment line and the `.clancy/.env` line. Also remove any blank line immediately before or after the removed block to avoid leaving double blank lines. Write the cleaned file back.
+
+If the file is now empty (or contains only whitespace) after removal, delete it entirely — Clancy created it during init.
+
+Print `✓ .gitignore cleaned up.` (or `✓ .gitignore removed.` if deleted).
+
+**If not found:** skip — Clancy didn't modify this file.
+
+**If .gitignore does not exist:** skip.
+
+---
+
+## Step 5 — Offer to remove .clancy/ (if present)
 
 Check whether `.clancy/` exists in the current project directory.
 
@@ -83,7 +123,7 @@ If `.clancy/` does not exist, skip this step entirely.
 
 ---
 
-## Step 4 — Final message
+## Step 6 — Final message
 
 ```
 Clancy uninstalled. To reinstall: npx chief-clancy
@@ -93,7 +133,6 @@ Clancy uninstalled. To reinstall: npx chief-clancy
 
 ## Hard constraints
 
-- **Never touch any `.env` at the project root** — Clancy's credentials live in `.clancy/.env` and are only removed as part of `.clancy/` in Step 3
-- **Never touch `CLAUDE.md`** — under any circumstances, in any scenario
-- Steps 1–2 (commands removal) and Step 3 (`.clancy/` removal) are always asked separately — never bundle them into one confirmation
-- If the user says no to commands removal in Step 2, skip Step 3 entirely and stop
+- **Never touch any `.env` at the project root** — Clancy's credentials live in `.clancy/.env` and are only removed as part of `.clancy/` in Step 5
+- Steps 1–2 (commands removal), Steps 3–4 (CLAUDE.md and .gitignore cleanup), and Step 5 (`.clancy/` removal) are always asked separately — never bundle them into one confirmation
+- If the user says no to commands removal in Step 2, skip all remaining steps and stop

package/src/workflows/update.md

@@ -2,66 +2,201 @@
 
 ## Overview
 
-Update Clancy itself to the latest version via npx.
+Check for Clancy updates via npm, display changelog for versions between installed and latest, obtain user confirmation, and execute clean installation.
 
 ---
 
-## Step 1 — Check current version
+## Step 1 — Detect installed version
 
-Read current version from the installed package (check `~/.claude/commands/clancy/` or `./.claude/commands/clancy/` for a `VERSION` file, or from npm).
+Determine whether Clancy is installed locally or globally by checking both locations:
 
 ```bash
-npm view chief-clancy version 2>/dev/null || echo "unknown"
+LOCAL_VERSION_FILE="./.claude/commands/clancy/VERSION"
+GLOBAL_VERSION_FILE="$HOME/.claude/commands/clancy/VERSION"
+
+if [ -f "$LOCAL_VERSION_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
+  INSTALLED=$(cat "$LOCAL_VERSION_FILE")
+  INSTALL_TYPE="LOCAL"
+elif [ -f "$GLOBAL_VERSION_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
+  INSTALLED=$(cat "$GLOBAL_VERSION_FILE")
+  INSTALL_TYPE="GLOBAL"
+else
+  INSTALLED="unknown"
+  INSTALL_TYPE="UNKNOWN"
+fi
+
+echo "$INSTALLED"
+echo "$INSTALL_TYPE"
 ```
 
+Parse output:
+- First line = installed version (or "unknown")
+- Second line = install type (LOCAL, GLOBAL, or UNKNOWN)
+
+**If version is unknown:**
+```
+## Clancy Update
+
+**Installed version:** Unknown
+
+Your installation doesn't include version tracking.
+
+Running fresh install...
+```
+
+Proceed to Step 4 (treat as version 0.0.0 for comparison).
+
 ---
 
-## Step 2 — Run the updater
+## Step 2 — Check latest version
+
+Check npm for the latest published version:
+
+```bash
+npm view chief-clancy version 2>/dev/null
+```
+
+**If npm check fails:**
+```
+Couldn't check for updates (offline or npm unavailable).
+
+To update manually: `npx chief-clancy@latest`
+```
+
+Exit.
+
+---
+
+## Step 3 — Compare versions and confirm
+
+Compare installed vs latest:
+
+**If installed == latest:**
+```
+## Clancy Update
+
+**Installed:** X.Y.Z
+**Latest:** X.Y.Z
+
+You're already on the latest version.
+```
+
+Exit.
+
+**If update available**, fetch the changelog from GitHub and show what's new BEFORE updating:
+
+```bash
+curl -s https://raw.githubusercontent.com/Pushedskydiver/clancy/main/CHANGELOG.md
+```
+
+Extract only the entries between the installed version and the latest version. Display:
 
 ```
-Updating Clancy...
+## Clancy Update Available
+
+**Installed:** {installed}
+**Latest:** {latest}
+
+### What's New
+────────────────────────────────────────────────────────────
+
+{relevant CHANGELOG entries between installed and latest}
+
+────────────────────────────────────────────────────────────
+
+⚠️  **Note:** The update performs a clean install of Clancy command folders:
+- `.claude/commands/clancy/` will be replaced
+- `.claude/clancy/workflows/` will be replaced
+
+If you've modified any Clancy files directly, they'll be automatically backed up
+to `.claude/clancy/local-patches/` before overwriting.
+
+Your project files are preserved:
+- `.clancy/` project folder (scripts, docs, .env, progress log) ✓
+- `CLAUDE.md` ✓
+- Custom commands not in `commands/clancy/` ✓
+- Custom hooks ✓
 ```
 
-Run:
+Ask the user: **"Proceed with update?"** with options:
+- "Yes, update now"
+- "No, cancel"
+
+**If user cancels:** Exit.
+
+---
+
+## Step 4 — Run the update
+
+Run the installer using the detected install type:
+
 ```bash
-npx chief-clancy@latest
+npx -y chief-clancy@latest
 ```
 
-This re-runs the installer, which copies the latest command files into the correct `.claude/commands/clancy/` directory (global or local, matching the existing install location).
+The installer auto-detects whether to install globally or locally based on the existing install.
 
-The update only touches `.claude/commands/clancy/` (slash commands and workflows). It never modifies:
-- `.clancy/clancy-once.sh` or `.clancy/clancy-afk.sh` — shell scripts are not updated
-- `.clancy/docs/` codebase documentation
-- `.clancy/progress.txt` progress log
-- `.clancy/.env` credentials
+This only touches `.claude/commands/clancy/` and `.claude/clancy/workflows/`. It never modifies:
+- `.clancy/clancy-once.sh` or `.clancy/clancy-afk.sh` — shell scripts
+- `.clancy/docs/` — codebase documentation
+- `.clancy/progress.txt` — progress log
+- `.clancy/.env` — credentials
 - `CLAUDE.md`
 
-**To update the shell scripts** (`.clancy/clancy-once.sh`, `.clancy/clancy-afk.sh`), re-run `/clancy:init` — it will detect the existing setup and re-scaffold the scripts without asking for credentials again.
+**To update the shell scripts**, re-run `/clancy:init` — it will detect the existing setup and re-scaffold the scripts without asking for credentials again.
 
 ---
 
-## Step 3 — Show changelog diff
+## Step 5 — Clear update cache and confirm
 
-After update, fetch and display the CHANGELOG section for any versions between old and new:
+Clear the update check cache so the statusline indicator disappears:
 
+```bash
+rm -f "$HOME/.claude/cache/clancy-update-check.json"
+rm -f "./.claude/cache/clancy-update-check.json"
 ```
-Updated Clancy from v{old} to v{new}.
 
-What's new:
-{relevant CHANGELOG entries}
+Display completion message:
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║  Clancy Updated: v{old} → v{new}                        ║
+╚═══════════════════════════════════════════════════════════╝
+
+⚠️  Restart Claude Code to pick up the new commands.
 
 View full changelog: github.com/Pushedskydiver/clancy/blob/main/CHANGELOG.md
 ```
 
-If version is already latest:
+---
+
+## Step 6 — Check for local patches
+
+After the update completes, check if the installer backed up any locally modified files:
+
+Check for `.claude/clancy/local-patches/backup-meta.json` (local install) or `~/.claude/clancy/local-patches/backup-meta.json` (global install).
+
+**If patches were found:**
+
 ```
-Clancy is already up to date (v{version}).
+Local patches were backed up before the update.
+Your modified files are in .claude/clancy/local-patches/
+
+To review what changed:
+  Compare each file in local-patches/ against its counterpart in
+  .claude/commands/clancy/ or .claude/clancy/workflows/ and manually
+  reapply any customisations you want to keep.
+
+Backed up files:
+{list from backup-meta.json}
 ```
 
+**If no patches:** Continue normally (no message needed).
+
 ---
 
 ## Notes
 
 - If the user installed globally, the update applies globally
 - If the user installed locally, the update applies locally
-- After updating, the new commands take effect immediately in Claude Code
+- After updating, restart Claude Code for new commands to take effect