claude-code-autoconfig 1.0.82 → 1.0.83

package/.claude/commands/autoconfig-update.md

@@ -0,0 +1,142 @@
+<!-- @description Manages and installs updates to Claude Code configuration. -->
+
+<!-- @applied
+-->
+
+# Autoconfig Update
+
+Check for and install pending updates to your Claude Code configuration.
+
+## Step 1: Pull Latest Updates
+
+Run this command via Bash to pull new update files from the latest package:
+
+```bash
+npx claude-code-autoconfig@latest --pull-updates
+```
+
+This copies any new update `.md` files into `.claude/updates/` and refreshes this command file (preserving the `@applied` block above).
+
+After the command completes, check `.claude/updates/` directory. If it doesn't exist or is empty, output:
+
+```
+No new updates available. You're up to date.
+```
+
+Then stop — do not continue to further steps.
+
+## Step 2: Parse Update Files
+
+Read all `.md` files in `.claude/updates/` matching the pattern `NNN-*.md` (e.g., `001-debug-methodology.md`).
+
+For each file, extract metadata from the HTML comment headers at the top:
+
+| Header | Pattern | Required |
+|--------|---------|----------|
+| `@title` | `<!-- @title (.+?) -->` | Yes |
+| `@type` | `<!-- @type (.+?) -->` | Yes |
+| `@description` | `<!-- @description (.+?) -->` | Yes |
+| `@files` | `<!-- @files (.+?) -->` | Yes |
+
+Extract the numeric ID from the filename prefix (e.g., `001` from `001-debug-methodology.md`).
+
+Skip any files that are malformed (missing required headers) with a warning.
+
+## Step 3: Filter Already Applied
+
+Parse the `<!-- @applied -->` block in THIS file (`.claude/commands/autoconfig-update.md`) to get the list of already-applied update IDs. Extract the three-digit ID from the start of each line.
+
+Filter out any updates whose ID appears in the applied list. If no pending updates remain, output:
+
+```
+All updates are already installed. You're up to date.
+```
+
+Then stop.
+
+## Step 4: Display Summary
+
+Output the pending updates as a numbered list:
+
+```
+These are the latest updates to claude-code-autoconfig:
+
+001 - Debug Methodology
+002 - Some other feature
+003 - Another update
+
+Press 1 to install all updates
+Press 2 to review each update before install
+```
+
+Wait for the user to respond with 1 or 2.
+
+## Step 5a: Install All (User picked 1)
+
+For each pending update (in ID order):
+1. Read the update `.md` file body (everything below the metadata comments)
+2. Follow the instructions in the body to apply the update
+3. After successful application, append to the `@applied` block in THIS file:
+   ```
+   {id} - {title}
+   ```
+
+After all updates are applied, go to Step 6.
+
+## Step 5b: Review Each (User picked 2)
+
+For each pending update (in ID order), display a box:
+
+```
+╔══════════════════════════════════════════════════════════╗
+║  UPDATE {n} of {total}                          ⬡ {type} ║
+╠══════════════════════════════════════════════════════════╣
+║                                                          ║
+║  {title}                                                 ║
+║                                                          ║
+║  {description — wrap to fit within box borders}          ║
+║                                                          ║
+║  Files:  {comma-separated list of files touched}         ║
+║                                                          ║
+╠══════════════════════════════════════════════════════════╣
+║  [y] Install    [s] Skip    [a] Install all remaining    ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+**Box rendering rules:**
+- Box width: 58 visible characters (including border chars)
+- Use Unicode box-drawing characters: `╔ ═ ╗ ║ ╠ ╣ ╚ ╝`
+- Pad content lines with spaces so right `║` aligns at column 58
+- Wrap description text to fit within the borders (54 chars of content)
+- `{n}` is the position in the pending list (1, 2, 3...), `{total}` is count of pending
+
+**User actions:**
+- `y` → Apply this update (follow body instructions), append to `@applied`, show next
+- `s` → Skip this update (do NOT add to `@applied` — it will appear again next run)
+- `a` → Apply this update AND all remaining updates without further prompts
+
+After all updates are reviewed, go to Step 6.
+
+## Step 6: Summary and Cleanup
+
+Show a summary of what happened:
+
+```
+✅ Installed: 001, 003
+⏭️  Skipped:  002
+
+Run /autoconfig-update again anytime to install skipped updates.
+```
+
+If all were installed:
+```
+✅ All updates installed.
+```
+
+Then delete the `.claude/updates/` directory (it's ephemeral — updates are tracked in the @applied block above).
+
+If the user installed any updates that modified `.claude/commands/autoconfig.md`, suggest:
+
+```
+Run /sync-claude-md to apply these changes to your current project's CLAUDE.md.
+```

package/.claude/commands/autoconfig.md

@@ -287,7 +287,29 @@ Set session-level env vars:
 - Optimize for Claude's efficiency, not human documentation
 - When uncertain, leave it out — Claude can ask or explore
 
-## Step 7: Update the Docs
+## Step 7: Configure MEMORY.md
+
+Claude Code has a persistent auto memory file (`MEMORY.md`) that loads into the system prompt at the start of every session. Write the debugging methodology to this file so Claude always follows evidence-based troubleshooting.
+
+**Locate the MEMORY.md file:**
+
+The file lives at `~/.claude/projects/{encoded-project-path}/memory/MEMORY.md` where the project path is encoded by replacing path separators with dashes and removing colons (e.g., `C:\CODE\my-project` becomes `C--CODE-my-project`).
+
+**Write this content** (append if file already exists, create if it doesn't):
+
+```markdown
+## Debugging — Evidence Before Solutions
+NEVER guess the root cause and jump to coding a fix. Always:
+1. Add logging / check actual data first
+2. Confirm root cause with evidence
+3. Only then propose and implement a fix
+If you can't determine the cause from code alone, add diagnostic logging and verify with runtime data.
+CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence. Even if a mismatch looks obvious across multiple files, verify with runtime data before implementing. The more "obvious" the cause looks, the more important it is to verify — that's when the temptation to skip evidence gathering is strongest.
+```
+
+**Important**: Use the Write tool (or Edit to append). Do not skip this step — it ensures Claude investigates root causes before making changes in every future session.
+
+## Step 8: Update the Docs
 
 After populating CLAUDE.md, update the docs file preview to show the actual content:
 
@@ -306,7 +328,7 @@ This ensures double-clicking CLAUDE.md in the docs shows the real generated cont
 
 - macOS: `open .claude/docs/autoconfig.docs.html`
 - Linux: `xdg-open .claude/docs/autoconfig.docs.html`
-- Windows: `start .claude/docs/autoconfig.docs.html`
+- Windows: `powershell -NoProfile -Command "Start-Process '.claude/docs/autoconfig.docs.html'"`
 
 If the docs file exists, output:
 

package/.claude/commands/publish.md

@@ -0,0 +1,24 @@
+<!-- @description Runs tests, bumps version, commits, and publishes to npm. -->
+
+# Publish
+
+Run tests, bump the patch version, commit, push, and publish to npm.
+
+## Steps
+
+1. Run the project's test suite (`npm test`)
+2. **If tests fail, stop here.** Do not publish broken code.
+3. Check for uncommitted changes. If there are any:
+   a. Stage all changes (`git add -A`)
+   b. Generate a conventional commit message based on the diff
+   c. Commit the changes
+4. Bump the version: `npm version patch`
+5. Push the commit and tag: `git push && git push --tags`
+6. Publish to npm: `npm publish`
+7. Output the new version number on success
+
+## Important
+
+- Always run tests before publishing — never skip this step
+- If any step fails, stop immediately and report the error
+- Do not use `--force` on publish unless the user explicitly asks

package/.claude/commands/show-docs.md

@@ -38,15 +38,10 @@ For each file in `.claude/` that is newer than the docs HTML:
 
 ## Step 3: Open Docs
 
-Open the docs in the default browser using the appropriate command for the OS:
+Open the docs in the default browser. Use the command matching the current OS:
 
-```bash
-# macOS
-open .claude/docs/autoconfig.docs.html
+- **macOS:** `open .claude/docs/autoconfig.docs.html`
+- **Linux:** `xdg-open .claude/docs/autoconfig.docs.html`
+- **Windows:** `powershell -NoProfile -Command "Start-Process '.claude/docs/autoconfig.docs.html'"`
 
-# Linux
-xdg-open .claude/docs/autoconfig.docs.html
-
-# Windows
-start .claude/docs/autoconfig.docs.html
-```
+**Important:** If the command exits with a non-zero exit code or produces an error, tell the user the file failed to open and suggest they open it manually. Do NOT report success unless the command completed without error.

package/.claude/docs/autoconfig.docs.html

@@ -378,21 +378,38 @@
             background: var(--bg-secondary);
             border-radius: 8px;
             overflow: hidden;
-            height: 375px;
+            height: 480px;
             position: relative;
         }
 
         .tree-side {
-            padding: 16px;
+            display: flex;
+            flex-direction: column;
             font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Ubuntu', 'Roboto', 'Noto Sans', sans-serif;
             font-size: 13px;
             line-height: 1.4;
             border-right: 1px solid var(--bg-elevated);
-            overflow-y: auto;
             flex-shrink: 0;
             height: 100%;
         }
 
+        .tree-content {
+            padding: 16px 16px 8px 16px;
+            overflow-y: auto;
+            overflow-x: hidden;
+            flex: 1;
+            min-height: 0;
+        }
+
+        .tree-footer-hint {
+            padding: 6px 16px;
+            font-size: 12px;
+            color: var(--text-secondary);
+            opacity: 0.5;
+            border-top: 1px solid var(--bg-elevated);
+            flex-shrink: 0;
+        }
+
         .tree-item {
             padding: 4px 8px;
             margin: 1px 0;
@@ -466,8 +483,11 @@
 
         .info-side {
             flex: 1;
-            min-width: 200px;
+            min-width: 0;
+            height: 100%;
             overflow-y: auto;
+            overflow-x: hidden;
+            word-wrap: break-word;
         }
 
         .info-panel {
@@ -500,6 +520,13 @@
             color: var(--accent-cyan);
         }
 
+        .info-panel-hint {
+            margin-top: 20px;
+            font-size: 12px;
+            color: var(--text-secondary);
+            opacity: 0.5;
+        }
+
         /* Navigation */
         .nav-container {
             display: flex;
@@ -815,6 +842,12 @@
                 <div class="slide-content">
                     <div class="tree-panel">
                         <div class="tree-side">
+                          <div class="tree-content">
+                            <div class="tree-item" data-info="memory-md">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">MEMORY.md</span>
+                            </div>
                             <div class="tree-item folder-row" data-info="root" data-folder="root">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
@@ -925,6 +958,8 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">CLAUDE.md</span>
                             </div>
+                          </div>
+                          <div class="tree-footer-hint">Double-click any file to preview contents</div>
                         </div>
                         <div class="info-side">
                             <div class="info-panel" id="infoPanel">
@@ -1007,7 +1042,7 @@
             
             // Select CLAUDE.md by default when entering slide 0 (tree view)
             if (currentSlide === 0) {
-                setTimeout(() => selectTreeItemByKey('claude-md'), 100);
+                setTimeout(() => selectTreeItemByKey('memory-md'), 100);
             }
         }
 
@@ -1037,7 +1072,7 @@
         });
         
         // Select CLAUDE.md on initial page load
-        setTimeout(() => selectTreeItemByKey('claude-md'), 300);
+        setTimeout(() => selectTreeItemByKey('memory-md'), 300);
 
         // Keyboard navigation for slides
         document.addEventListener('keydown', (e) => {
@@ -1091,6 +1126,24 @@
             rootItem.querySelector('.folder').textContent = projectName + '/';
         }
 
+        // Build full MEMORY.md path from project location
+        function getMemoryPath() {
+            try {
+                const path = window.location.pathname;
+                // Extract drive + full path up to .claude, then convert to Claude's encoding
+                const claudeIdx = path.indexOf('.claude');
+                if (claudeIdx > 0) {
+                    const projectPath = path.substring(0, claudeIdx - 1);
+                    // Claude encodes the path: C:\CODE\proj → C--CODE-proj
+                    const parts = projectPath.split('/').filter(p => p);
+                    const encoded = parts.join('-').replace(/:/g, '');
+                    return '~/.claude/projects/' + encoded + '/memory/MEMORY.md';
+                }
+            } catch (e) {}
+            return '~/.claude/projects/' + projectName + '/memory/MEMORY.md';
+        }
+        const memoryPath = getMemoryPath();
+
         // Calculate tree side width dynamically
         function setTreeWidth() {
             const treeSide = document.querySelector('.tree-side');
@@ -1120,7 +1173,8 @@
             });
             
             treeSide.style.width = (maxWidth + 32) + 'px';
-            treeSide.style.padding = '16px 8px';
+            treeSide.style.paddingLeft = '8px';
+            treeSide.style.paddingRight = '8px';
         }
         
         if (document.fonts && document.fonts.ready) {
@@ -1167,6 +1221,11 @@
 
         // Tree panel info data - UPDATED
         const treeInfo = {
+            'memory-md': {
+                title: 'MEMORY.md',
+                desc: 'Native Claude Code file — loaded into the system prompt at the start of every session. Autoconfig appends debugging methodology instructions here so Claude always follows evidence-based troubleshooting.<br><br><span style="color: var(--accent-orange);">Location: ' + memoryPath + '</span>',
+                trigger: 'Loaded into system prompt automatically'
+            },
             'root': {
                 title: projectName,
                 desc: 'The autoconfig adds CLAUDE.md at your project root and configuration files inside a .claude/ directory. Nothing else is touched.'
@@ -1267,7 +1326,7 @@
         const infoPanel = document.getElementById('infoPanel');
         const treeItems = document.querySelectorAll('.tree-item');
 
-        let selectedInfoKey = 'claude-md'; // Default selection
+        let selectedInfoKey = 'memory-md'; // Default selection
         
         function showInfo(key) {
             const info = treeInfo[key];
@@ -1429,6 +1488,22 @@
 
         // File Preview Modal
         const fileContents = {
+            'memory-md': {
+                filename: 'MEMORY.md',
+                content: `# Native Claude Code File — Debugging instructions appended by autoconfig
+
+Location: ` + memoryPath + `
+
+---
+
+## Debugging — Evidence Before Solutions
+NEVER guess the root cause and jump to coding a fix. Always:
+1. Add logging / check actual data first
+2. Confirm root cause with evidence
+3. Only then propose and implement a fix
+If you can't determine the cause from code alone, add diagnostic logging and verify with runtime data.
+CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence. Even if a mismatch looks obvious across multiple files, verify with runtime data before implementing. The more "obvious" the cause looks, the more important it is to verify — that's when the temptation to skip evidence gathering is strongest.`
+            },
             'claude-md': {
                 filename: 'CLAUDE.md',
                 content: `# Project Name
@@ -1443,29 +1518,50 @@
       "Read(./**)",
       "Edit(./**)",
       "Write(./**)",
+      "Glob",
+      "Grep",
+      "WebSearch",
+      "WebFetch",
       "Bash(npm run dev)",
       "Bash(npm run build)",
+      "Bash(npm run lint)",
+      "Bash(npm run lint:fix)",
+      "Bash(npm run typecheck)",
       "Bash(npm run test)",
+      "Bash(npm run test:*)",
+      "Bash(npm run validate)",
       "Bash(git status)",
       "Bash(git diff:*)",
       "Bash(git add:*)",
       "Bash(git commit:*)",
-      "Bash(git push:*)"
+      "Bash(git push:*)",
+      "Bash(git pull)",
+      "Bash(git checkout:*)",
+      "Bash(git branch:*)",
+      "Bash(ls:*)",
+      "Bash(dir:*)",
+      "Bash(mkdir:*)",
+      "Bash(mkdir -p:*)",
+      "Bash(start:*)",
+      "Bash(start .claude:*)",
+      "Bash(open:*)",
+      "Bash(open .claude:*)",
+      "Bash(xdg-open:*)",
+      "Bash(xdg-open .claude:*)"
     ],
     "deny": [
       "Read(./.env)",
       "Read(./.env.*)",
-      "Read(./secrets/**)"
+      "Read(./secrets/**)",
+      "Read(./**/credentials.*)",
+      "Read(./**/*.pem)",
+      "Read(./**/*.key)",
+      "Write(./nul)",
+      "Edit(./nul)",
+      "Bash(rm -rf:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)"
     ]
-  },
-  "hooks": {
-    "PostToolUse": [{
-      "matcher": "Edit|Write",
-      "hooks": [{
-        "type": "command",
-        "command": "// Auto-refresh docs when .claude/ changes"
-      }]
-    }]
   }
 }`
             },
@@ -1552,7 +1648,16 @@ Incrementally update the docs's treeInfo when \`.claude/\` files are added or mo
 
 Analyze this project and configure Claude Code with real context.
 
-## Step 1: Scan the Project
+**Setup Note**: During autoconfig, prefer Glob/Read/Write tools over Bash commands. This ensures smooth setup without permission prompts. Only use Bash for opening the guide at the end.
+
+## Step 1: Detect Environment
+
+**Operating System:**
+Check the platform and note it for command syntax:
+- Windows → use \\\`del\\\`, \\\`rmdir\\\`, backslashes, \\\`.cmd\\\`/\\\`.ps1\\\` scripts
+- macOS/Linux → use \\\`rm\\\`, \\\`mkdir -p\\\`, forward slashes, \\\`.sh\\\` scripts
+
+## Step 2: Scan the Project
 
 Look for these indicators to understand the project:
 
@@ -1566,122 +1671,27 @@ Look for these indicators to understand the project:
 - \`*.csproj\` / \`*.sln\` → .NET
 - \`composer.json\` → PHP
 
-**Framework Indicators:**
-- \`next.config.*\` / \`app/\` directory → Next.js
-- \`vite.config.*\` → Vite
-- \`angular.json\` → Angular
-- \`svelte.config.*\` → Svelte
-- \`remix.config.*\` → Remix
-- \`nuxt.config.*\` → Nuxt
-- \`django\` in imports → Django
-- \`flask\` in imports → Flask
-- \`fastapi\` in imports → FastAPI
-- \`express\` in dependencies → Express
-- \`rails\` / \`Gemfile\` with rails → Rails
-- \`laravel\` → Laravel
-
-**Testing Frameworks:**
-- \`jest.config.*\` / \`@jest\` in deps → Jest
-- \`vitest.config.*\` → Vitest
-- \`pytest.ini\` / \`conftest.py\` → Pytest
-- \`*_test.go\` files → Go testing
-- \`*_spec.rb\` files → RSpec
-- \`cypress/\` or \`playwright/\` → E2E testing
-
-**Infrastructure:**
-- \`Dockerfile\` / \`docker-compose.*\` → Docker
-- \`*.tf\` files → Terraform
-- \`k8s/\` or \`kubernetes/\` → Kubernetes
-- \`.github/workflows/\` → GitHub Actions
-- \`serverless.yml\` → Serverless Framework
-
-## Step 2: Populate CLAUDE.md
-
-Focus on what Claude Code actually needs to work effectively. Claude can explore the codebase itself — don't document what it can discover.
-
-**Always include:**
-- **Project name + one-liner**: What is this thing?
-- **Tech stack**: Runtime, framework, database, key services (so Claude uses correct patterns)
-- **Commands**: How to run, test, build, deploy — Claude needs these to execute tasks
-- **Non-obvious conventions**: Multi-schema databases, monorepo structure, unusual patterns Claude wouldn't infer
-
-**Include if relevant:**
-- **Deployment flow**: If non-standard or involves multiple steps
-
-**Skip these — Claude can discover them:**
-- Detailed project structure trees (Claude can run \`ls\` or \`tree\`)
-- Exhaustive route/endpoint lists (Claude can grep)
-- File-by-file descriptions (Claude can read files)
-- Database model lists (Claude can read schema files)
-
-**Keep it tight.** A 30-line CLAUDE.md that hits the essentials beats a 200-line doc Claude has to parse every session.
-
-## Step 3: Create Rules Directory
-
-Create an empty \`.claude/rules/\` directory. Do not create any subdirectories or rule files.
-
-Rules are path-scoped context files that load automatically when Claude works on matching files. Effective rules require deep understanding of your codebase patterns, team conventions, and quality goals — they should be crafted intentionally, not auto-generated.
-
-## Step 4: Configure Settings
-
-Update \`.claude/settings.json\` using the official schema.
-
-### Deny Patterns (files Claude shouldn't read/write)
-
-Use \`Read()\` for blocking reads, \`Edit()\` for blocking writes:
+**Framework/Testing/Infrastructure** indicators also scanned.
 
-**Always deny (security):**
-\`\`\`
-Read(./.env)
-Read(./.env.*)
-Read(./secrets/**)
-Edit(./.env)
-Edit(./.env.*)
-\`\`\`
+## Step 2b: Detect Version Divergence
 
-**Often deny (generated/vendor):**
-\`\`\`
-Edit(./node_modules/**)
-Edit(./dist/**)
-Edit(./.git/**)
-\`\`\`
+Scans for version declarations across the project. Flags mismatches between package.json, hardcoded constants, manifest files, etc.
 
-### Allow Patterns (auto-approve without prompting)
+## Step 3: Populate CLAUDE.md
 
-Use \`Bash()\` patterns with prefix matching:
+Focus on what Claude Code actually needs. Keep it tight — 30 lines beats 200.
 
-\`\`\`
-Bash(npm run test:*)
-Bash(npm run lint:*)
-Bash(npm run build)
-\`\`\`
+**Always include:** Project name, tech stack, commands, non-obvious conventions.
+**Skip:** File trees, endpoint lists, model lists — Claude discovers these.
 
-### Environment Variables
-
-Set session-level env vars:
-
-\`\`\`json
-{
-  "env": {
-    "NODE_ENV": "development"
-  }
-}
-\`\`\`
-
-**Keep it minimal** — only include patterns that actually exist in this project.
-
-## Guidelines
-
-- Replace ALL placeholder content with real values from THIS project
-- Delete sections that don't apply — no empty stubs
-- Optimize for Claude's efficiency, not human documentation
-- When uncertain, leave it out — Claude can ask or explore
+## Step 4: Create Rules Directory
+## Step 5: Configure Formatter (JS/Node Projects)
+## Step 6: Configure Settings
+## Step 7: Update the Docs
 
 ## After Completion
 
-Once autoconfig is complete, prompt the user:
-
-**Run \`/show-docs\` for an interactive walkthrough of your new Claude Code project setup.**`
+Opens interactive docs in browser. Clean finale message.`
             },
             'commit-and-push': {
                 filename: 'commit-and-push.md',
@@ -1778,19 +1788,35 @@ Work through items: "Fix retro #001"`
 Add corrections and guidance here when Claude does something wrong.
 Claude reads this directory and learns for next time.
 
-## YYYY-MM-DD: Brief title
+---
+
+## Debugging Methodology — Evidence Before Solutions
+
+**NEVER jump to a fix based on assumptions.** When investigating a bug:
+
+1. **Gather evidence first** — add logging, check server logs, inspect actual data
+2. **Confirm the root cause** — present findings to the user with evidence
+3. **Only then propose a fix** — based on what you observed, not what you guessed
+
+---
+
+## Design Principles
+
+- Each file should have a single responsibility
+- If a file exceeds 500 LOC, look for decomposition opportunities
+- Keep cyclomatic complexity under 10 per function
+
+## Development Rules
 
-Describe what Claude did wrong and what to do instead.
-Keep entries brief and actionable.
+### Testing Requirements
 
-Example:
+**CRITICAL: Before committing changes to bin/cli.js, run tests:**
+\\\`npm test\\\`
 
-## 2026-01-06: Don't use deprecated API
-Claude used \`oldFunction()\` instead of \`newFunction()\`.
-Always use the v2 API for user endpoints.
+### Box Drawing Guidelines
 
-## 2026-01-07: Test database naming
-Use \`test_\` prefix for test databases, not \`dev_\`.`
+All lines must be exactly 46 visible characters wide (including borders).
+ANSI escape codes don't count toward visible width.`
             },
             'hooks': {
                 filename: 'hooks/',

package/.claude/feedback/FEEDBACK.md

@@ -7,6 +7,23 @@ Claude reads this directory and learns for next time.
 
 ---
 
+## Debugging Methodology — Evidence Before Solutions
+
+**NEVER jump to a fix based on assumptions.** When investigating a bug:
+
+1. **Gather evidence first** — add logging, check server logs, inspect actual data
+2. **Confirm the root cause** — present findings to the user with evidence
+3. **Only then propose a fix** — based on what you observed, not what you guessed
+
+If you can't determine the root cause from code reading alone, **add diagnostic logging** and ask the user to reproduce. Do NOT:
+- Guess the root cause and immediately start coding a fix
+- Assume data mismatches without checking the actual data
+- Rewrite logic because you think values "might" differ
+
+The cost of a wrong fix is high: wasted time, unnecessary code complexity, and potentially masking the real issue.
+
+---
+
 ## Design Principles
 
 - Each file should have a single responsibility (one reason to change)

package/.claude/updates/001-debug-methodology.md

@@ -0,0 +1,24 @@
+<!-- @title Debug Methodology -->
+<!-- @type feature -->
+<!-- @description Ensures Claude investigates root cause before making changes instead of guessing -->
+<!-- @files MEMORY.md -->
+
+# Apply Debug Methodology Update
+
+Add the following to the user's `MEMORY.md` file (Claude's persistent auto memory). This ensures the debugging methodology is always loaded into Claude's system prompt for every session.
+
+## Content to Add
+
+```markdown
+## Debugging — Evidence Before Solutions
+NEVER guess the root cause and jump to coding a fix. Always:
+1. Add logging / check actual data first
+2. Confirm root cause with evidence
+3. Only then propose and implement a fix
+If you can't determine the cause from code alone, add diagnostic logging and verify with runtime data.
+CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence. Even if a mismatch looks obvious across multiple files, verify with runtime data before implementing. The more "obvious" the cause looks, the more important it is to verify — that's when the temptation to skip evidence gathering is strongest.
+```
+
+## After Applying
+
+Inform the user: "Debug methodology added to MEMORY.md. It will be active in every future Claude session for this project."

package/bin/cli.js

@@ -27,7 +27,7 @@ const WINDOWS_RESERVED = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'C
   'LPT6', 'LPT7', 'LPT8', 'LPT9'];
 
 // Files/folders installed by autoconfig - don't backup these
-const AUTOCONFIG_FILES = ['commands', 'guide', 'agents', 'migration', 'hooks'];
+const AUTOCONFIG_FILES = ['commands', 'guide', 'agents', 'migration', 'hooks', 'updates'];
 
 function isReservedName(name) {
   const baseName = name.replace(/\.[^.]*$/, '').toUpperCase();
@@ -63,6 +63,95 @@ function formatTimestamp() {
   return `${month}-${day}-${year}_${hour12}-${min}${ampm}`;
 }
 
+// --pull-updates: Copy new update files from package to user's project
+function parseAppliedUpdates(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match = content.match(/<!-- @applied\n([\s\S]*?)-->/);
+  if (!match) return [];
+
+  return match[1].trim().split('\n')
+    .filter(line => line.trim())
+    .map(line => {
+      const idMatch = line.match(/^(\d{3})/);
+      return idMatch ? parseInt(idMatch[1], 10) : 0;
+    })
+    .filter(id => id > 0);
+}
+
+function getHighestAppliedId(appliedIds) {
+  return appliedIds.length > 0 ? Math.max(...appliedIds) : 0;
+}
+
+function pullUpdates() {
+  console.log('\x1b[36m%s\x1b[0m', '🔄 Checking for updates...');
+  console.log();
+
+  const userCmdPath = path.join(cwd, '.claude', 'commands', 'autoconfig-update.md');
+  const packageCmdPath = path.join(packageDir, '.claude', 'commands', 'autoconfig-update.md');
+  const packageUpdatesDir = path.join(packageDir, '.claude', 'updates');
+  const userUpdatesDir = path.join(cwd, '.claude', 'updates');
+
+  // Ensure .claude/commands/ exists
+  fs.mkdirSync(path.join(cwd, '.claude', 'commands'), { recursive: true });
+
+  // Refresh autoconfig-update.md (preserve user's @applied block)
+  if (fs.existsSync(packageCmdPath)) {
+    if (fs.existsSync(userCmdPath)) {
+      const userContent = fs.readFileSync(userCmdPath, 'utf8');
+      const packageContent = fs.readFileSync(packageCmdPath, 'utf8');
+      const userApplied = userContent.match(/<!-- @applied[\s\S]*?-->/);
+      if (userApplied) {
+        const merged = packageContent.replace(/<!-- @applied[\s\S]*?-->/, userApplied[0]);
+        fs.writeFileSync(userCmdPath, merged);
+      } else {
+        fs.copyFileSync(packageCmdPath, userCmdPath);
+      }
+    } else {
+      fs.copyFileSync(packageCmdPath, userCmdPath);
+    }
+  }
+
+  // Check for available updates in package
+  if (!fs.existsSync(packageUpdatesDir)) {
+    console.log('\x1b[32m%s\x1b[0m', '✅ Already up to date');
+    return;
+  }
+
+  const appliedIds = parseAppliedUpdates(userCmdPath);
+  const highestApplied = getHighestAppliedId(appliedIds);
+
+  const updateFiles = fs.readdirSync(packageUpdatesDir).filter(f => f.endsWith('.md'));
+  const newUpdates = updateFiles.filter(file => {
+    const match = file.match(/^(\d{3})-/);
+    if (!match) return false;
+    return parseInt(match[1], 10) > highestApplied;
+  });
+
+  if (newUpdates.length === 0) {
+    console.log('\x1b[32m%s\x1b[0m', '✅ Already up to date');
+    return;
+  }
+
+  // Copy new update files
+  fs.mkdirSync(userUpdatesDir, { recursive: true });
+  for (const file of newUpdates) {
+    fs.copyFileSync(
+      path.join(packageUpdatesDir, file),
+      path.join(userUpdatesDir, file)
+    );
+  }
+
+  console.log('\x1b[32m%s\x1b[0m', `✅ Copied ${newUpdates.length} new update${newUpdates.length > 1 ? 's' : ''} to .claude/updates/`);
+  console.log();
+  console.log('Run \x1b[36mclaude /autoconfig-update\x1b[0m to review and install updates.');
+}
+
+if (process.argv.includes('--pull-updates')) {
+  pullUpdates();
+  process.exit(0);
+}
+
 console.log('\x1b[36m%s\x1b[0m', '🚀 Claude Code Autoconfig');
 console.log();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-autoconfig",
-  "version": "1.0.82",
+  "version": "1.0.83",
   "description": "Intelligent, self-configuring setup for Claude Code. One command analyzes your project, configures Claude, and shows you what it did.",
   "author": "ADAC 1001 <info@adac1001.com>",
   "license": "MIT",
@@ -22,9 +22,10 @@
     "cli"
   ],
   "scripts": {
-    "test": "node test/box-alignment.test.js && node test/cli-install.test.js",
+    "test": "node test/box-alignment.test.js && node test/cli-install.test.js && node test/update-system.test.js",
     "test:box": "node test/box-alignment.test.js",
-    "test:install": "node test/cli-install.test.js"
+    "test:install": "node test/cli-install.test.js",
+    "test:update": "node test/update-system.test.js"
   },
   "bin": {
     "claude-code-autoconfig": "./bin/cli.js"