claude-code-autoconfig 1.0.133 → 1.0.135

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

@@ -858,35 +858,20 @@
                                 <span class="tree-folder-icon">📁</span>
                                 <span class="folder">.claude</span>
                             </div>
-                            <div class="tree-item indent-2 folder-row hidden collapsed" data-info="agents" data-folder="agents" data-parent="claude-dir">
-                                <span class="tree-chevron">›</span>
-                                <span class="tree-folder-icon">📁</span>
-                                <span class="folder">agents</span>
-                            </div>
-                            <div class="tree-item indent-3 hidden" data-info="create-retro-item" data-parent="agents">
-                                <span class="tree-spacer"></span>
-                                <span class="tree-file-icon">📄</span>
-                                <span class="file">create-retro-item.md</span>
-                            </div>
-                            <div class="tree-item indent-3 hidden" data-info="docs-refresh-agent" data-parent="agents">
-                                <span class="tree-spacer"></span>
-                                <span class="tree-file-icon">📄</span>
-                                <span class="file">docs-refresh.md</span>
-                            </div>
                             <div class="tree-item indent-2 folder-row hidden collapsed" data-info="commands" data-folder="commands" data-parent="claude-dir">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
                                 <span class="folder">commands</span>
                             </div>
-                            <div class="tree-item indent-3 hidden" data-info="autoconfig" data-parent="commands">
+                            <div class="tree-item indent-3 hidden" data-info="autoconfig-update" data-parent="commands">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
-                                <span class="file">autoconfig.md</span>
+                                <span class="file">autoconfig-update.md</span>
                             </div>
-                            <div class="tree-item indent-3 hidden" data-info="autoconfig-update" data-parent="commands">
+                            <div class="tree-item indent-3 hidden" data-info="autoconfig" data-parent="commands">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
-                                <span class="file">autoconfig-update.md</span>
+                                <span class="file">autoconfig.md</span>
                             </div>
                             <div class="tree-item indent-3 hidden" data-info="commit-and-push" data-parent="commands">
                                 <span class="tree-spacer"></span>
@@ -903,12 +888,17 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">gls.md</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="publish" data-parent="commands">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">publish.md</span>
+                            </div>
                             <div class="tree-item indent-3 hidden" data-info="recover-context" data-parent="commands">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">recover-context.md</span>
                             </div>
-                            <div class="tree-item indent-3 hidden" data-info="docs-cmd" data-parent="commands">
+                            <div class="tree-item indent-3 hidden" data-info="show-docs" data-parent="commands">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">show-docs.md</span>
@@ -923,12 +913,27 @@
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">test.md</span>
                             </div>
+                            <div class="tree-item indent-2 folder-row hidden collapsed" data-info="agents" data-folder="agents" data-parent="claude-dir">
+                                <span class="tree-chevron">›</span>
+                                <span class="tree-folder-icon">📁</span>
+                                <span class="folder">agents</span>
+                            </div>
+                            <div class="tree-item indent-3 hidden" data-info="create-retro-item-agent" data-parent="agents">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">create-retro-item.md</span>
+                            </div>
+                            <div class="tree-item indent-3 hidden" data-info="docs-refresh-agent" data-parent="agents">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">docs-refresh.md</span>
+                            </div>
                             <div class="tree-item indent-2 folder-row hidden collapsed" data-info="feedback" data-folder="feedback" data-parent="claude-dir">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
                                 <span class="folder">feedback</span>
                             </div>
-                            <div class="tree-item indent-3 hidden" data-info="feedback-template" data-parent="feedback">
+                            <div class="tree-item indent-3 hidden" data-info="feedback-feedback" data-parent="feedback">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">FEEDBACK.md</span>
@@ -938,11 +943,21 @@
                                 <span class="tree-folder-icon">📁</span>
                                 <span class="folder">hooks</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="feedback-rule-check-hook" data-parent="hooks">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">feedback-rule-check.js</span>
+                            </div>
                             <div class="tree-item indent-3 hidden" data-info="format-hook" data-parent="hooks">
                                 <span class="tree-spacer"></span>
                                 <span class="tree-file-icon">📄</span>
                                 <span class="file">format.js</span>
                             </div>
+                            <div class="tree-item indent-3 hidden" data-info="migrate-feedback-hook" data-parent="hooks">
+                                <span class="tree-spacer"></span>
+                                <span class="tree-file-icon">📄</span>
+                                <span class="file">migrate-feedback.js</span>
+                            </div>
                             <div class="tree-item indent-2 folder-row hidden collapsed" data-info="docs" data-folder="docs-folder" data-parent="claude-dir">
                                 <span class="tree-chevron">›</span>
                                 <span class="tree-folder-icon">📁</span>
@@ -968,13 +983,7 @@
                                 <span class="tree-file-icon">⚙️</span>
                                 <span class="file">settings.json</span>
                             </div>
-                            <div class="tree-item indent-1" data-info="claude-md" data-parent="root">
-                                <span class="tree-spacer"></span>
-                                <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">
@@ -1254,101 +1263,121 @@
                 title: '.claude/ Directory',
                 desc: 'Commands, rules, settings, and these docs. Keeps configuration organized as your project grows.'
             },
-            'settings': {
-                title: 'settings.json',
-                desc: 'Permissions, security, and hooks. Controls which commands Claude can run and which files it can access.',
-                trigger: 'Claude Code loads this automatically at the start of every session'
-            },
-            'mcp': {
-                title: '.mcp.json',
-                desc: 'MCP (Model Context Protocol) server configuration. Add your MCP server configs here when you\'re ready.<br><br>See <a href="https://docs.anthropic.com/en/docs/claude-code/mcp" target="_blank" style="color: var(--accent-cyan);">MCP documentation</a> for setup instructions.'
-            },
-            'agents': {
-                title: 'agents/',
-                desc: 'Custom agent definitions for specialized tasks. Agents are autonomous workers that can be spawned to handle complex operations independently.'
-            },
-            'create-retro-item': {
-                title: 'create-retro-item.md',
-                desc: '(Experimental) Agent that creates structured retro items for tech debt tracking. Used by the /enable-retro feature.'
-            },
-            'docs-refresh-agent': {
-                title: 'docs-refresh.md',
-                desc: 'Agent that refreshes and updates the interactive docs after configuration changes.'
+                                                            'rules': {
+                title: 'rules/',
+                desc: 'Path-scoped context that loads when Claude works on matching files.'
             },
             'commands': {
                 title: 'commands/',
                 desc: 'On-demand workflows you trigger with <code>/name</code>. Each .md file becomes a <a href="https://docs.anthropic.com/en/docs/claude-code/slash-commands" target="_blank" style="color: var(--accent-cyan);">slash command</a>.'
             },
-            'enable-retro': {
-                title: 'enable-retro.md',
-                desc: '(Experimental) Enables tech debt tracking. Creates <code>.claude/retro/</code> directory and configures Claude to log improvement opportunities as structured story files.',
-                trigger: '/enable-retro'
+            'agents': {
+                title: 'agents/',
+                desc: 'Reusable agent definitions that Claude can invoke for specialized tasks.'
+            },
+            'hooks': {
+                title: 'hooks/',
+                desc: 'Executable hook scripts that trigger on Claude Code events like PostToolUse.'
             },
             'feedback': {
                 title: 'feedback/',
                 desc: 'Team-maintained corrections and guidance for Claude. Add notes here when Claude does something wrong — it learns for next time. This directory persists across <code>/autoconfig</code> runs.'
             },
-            'feedback-template': {
-                title: 'FEEDBACK.md',
-                desc: 'Starter template for team feedback. Add dated entries when Claude makes mistakes — include what went wrong and the correct approach. Claude reads this on every session.'
-            },
-            'hooks': {
-                title: 'hooks/',
-                desc: 'Executable scripts that run in response to Claude Code events. Unlike commands (which are prompts you invoke), hooks trigger automatically based on tool usage patterns.'
-            },
-            'format-hook': {
-                title: 'format.js',
-                desc: 'Runs the project formatter after Write/Edit operations on source files. Filters by file extension and skips generated directories like node_modules.',
-                trigger: 'PostToolUse on Write|Edit (JS/TS projects only)'
+            'autoconfig-update': {
+                title: 'autoconfig-update.md',
+                desc: 'Manages and installs updates to Claude Code configuration.',
+                trigger: '/autoconfig-update'
             },
             'autoconfig': {
                 title: 'autoconfig.md',
                 desc: 'The command you just ran. Analyzes your project and populates CLAUDE.md with real context. Re-run anytime your stack changes.',
                 trigger: '/autoconfig'
             },
-            'autoconfig-update': {
-                title: 'autoconfig-update.md',
-                desc: 'Checks for and installs configuration updates. Tracks which updates have been applied and only runs new ones.',
-                trigger: '/autoconfig-update'
+            'commit-and-push': {
+                title: 'commit-and-push.md',
+                desc: 'Runs tests, then stages all changes, generates a conventional commit message, commits, and pushes.',
+                trigger: '/commit-and-push'
+            },
+            'enable-retro': {
+                title: 'enable-retro.md',
+                desc: '(Experimental) Enable Claude to log tech debt it encounters into .claude/retro.',
+                trigger: '/enable-retro'
             },
             'gls': {
                 title: 'gls.md',
-                desc: 'Gets and displays your latest screenshot(s) for visual context. Auto-detects your screenshot directory on first use.',
+                desc: 'gls.md in commands/',
                 trigger: '/gls'
             },
+            'publish': {
+                title: 'publish.md',
+                desc: 'Runs tests, bumps version, commits, and publishes to npm.',
+                trigger: '/publish'
+            },
             'recover-context': {
                 title: 'recover-context.md',
-                desc: 'Recovers conversation context after compaction. Reads the session transcript to rebuild awareness of what was discussed and decided.',
+                desc: 'Recovers conversation context from the session transcript after compaction.',
                 trigger: '/recover-context'
             },
+            'show-docs': {
+                title: 'show-docs.md',
+                desc: 'Opens the interactive docs in your browser.',
+                trigger: '/show-docs'
+            },
             'sync-claude-md': {
                 title: 'sync-claude-md.md',
-                desc: 'Re-analyzes your project and updates CLAUDE.md to reflect current state. Run when your stack changes significantly.',
+                desc: 'Re-analyzes your project and updates CLAUDE.md to reflect current state.',
                 trigger: '/sync-claude-md'
             },
-            'docs-cmd': {
-                title: 'show-docs.md',
-                desc: 'Opens this interactive docs in your browser. Auto-syncs any changed files before opening.',
-                trigger: '/show-docs'
-            },
             'test': {
                 title: 'test.md',
                 desc: 'Runs your test suite. Auto-detects Jest, Vitest, Pytest, Go, RSpec, or falls back to npm test.',
                 trigger: '/test'
             },
-            'commit-and-push': {
-                title: 'commit-and-push.md',
-                desc: 'Stages all changes, generates a conventional commit message from the diff, commits, and pushes. One command, full workflow.',
-                trigger: '/commit-and-push'
+            'create-retro-item-agent': {
+                title: 'create-retro-item.md',
+                desc: 'Creates a formatted retro item when tech debt or improvements are spotted.',
+                trigger: 'Background agent'
             },
-            'rules': {
-                title: 'rules/',
-                desc: 'Path-scoped context that loads when Claude works on matching files. Optimized rules are based on your project\'s needs, patterns and practices.<br><br><div style="background: var(--bg-elevated); border: 1px solid var(--accent-cyan); border-radius: 8px; padding: 16px; margin-top: 8px;"><strong style="color: var(--accent-orange);">Want optimized rules for your project?</strong><br>Reach out: <a href="mailto:info@adac1001.com" style="color: var(--accent-cyan);">info@adac1001.com</a></div>'
+            'docs-refresh-agent': {
+                title: 'docs-refresh.md',
+                desc: 'Background worker that syncs the docs when .claude/ files change.',
+                trigger: 'Background agent'
+            },
+            'feedback-rule-check-hook': {
+                title: 'feedback-rule-check.js',
+                desc: 'After FEEDBACK.md is edited, notifies Claude to evaluate',
+                trigger: 'PostToolUse on Write|Edit'
+            },
+            'format-hook': {
+                title: 'format.js',
+                desc: 'format.js in hooks/',
+                trigger: 'PostToolUse hook'
+            },
+            'migrate-feedback-hook': {
+                title: 'migrate-feedback.js',
+                desc: 'On session start, migrates custom FEEDBACK.md content to',
+                trigger: 'SessionStart'
+            },
+            'feedback-feedback': {
+                title: 'FEEDBACK.md',
+                desc: 'Human-authored corrections and guidance for Claude. Reserved for team feedback only — Claude must not write here. This directory persists across /autoconfig runs.'
             },
             'docs': {
                 title: 'docs/autoconfig.docs.html',
                 desc: 'This interactive docs. Open it anytime to review what each file does.',
                 trigger: '/show-docs'
+            },
+            'rules': {
+                title: 'rules/',
+                desc: 'Path-scoped context that loads when Claude works on matching files. Optimized rules are based on your project\'s needs, patterns and practices.<br><br><div style="background: var(--bg-elevated); border: 1px solid var(--accent-cyan); border-radius: 8px; padding: 16px; margin-top: 8px;"><strong style="color: var(--accent-orange);">Want optimized rules for your project?</strong><br>Reach out: <a href="mailto:info@adac1001.com" style="color: var(--accent-cyan);">info@adac1001.com</a></div>'
+            },
+            'mcp': {
+                title: '.mcp.json',
+                desc: 'MCP (Model Context Protocol) server configuration. Add your MCP servers here.'
+            },
+            'settings': {
+                title: 'settings.json',
+                desc: 'Permissions and security settings. Controls what Claude can auto-approve (allow) and what is always blocked (deny).'
             }
         };
 
@@ -1540,229 +1569,282 @@ CRITICAL: A plausible-looking cause from code reading is NOT confirmed evidence.
 
 > Run \`/autoconfig\` to populate this based on your project.`
             },
-            'settings': {
-                filename: 'settings.json',
-                content: `{
-  "permissions": {
-    "allow": [
-      "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 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(./**/credentials.*)",
-      "Read(./**/*.pem)",
-      "Read(./**/*.key)",
-      "Write(./nul)",
-      "Edit(./nul)",
-      "Bash(rm -rf:*)",
-      "Bash(curl:*)",
-      "Bash(wget:*)"
-    ]
-  }
-}`
-            },
-            'mcp': {
-                filename: '.mcp.json',
-                content: `{
-  "mcpServers": {}
-}
+                                                            'autoconfig-update': {
+                filename: 'autoconfig-update.md',
+                content: `<!-- @applied
+-->
 
-// Add your MCP server configs here when you're ready.
-// See: https://docs.anthropic.com/en/docs/claude-code/mcp`
-            },
-            'create-retro-item': {
-                filename: 'create-retro-item.md',
-                content: `# Create Retro Item Agent
+# Autoconfig Update
 
-Create a fully-scoped story file in \`.claude/retro/\` when tech debt or improvement opportunities are identified.
+Check for and install pending updates to your Claude Code configuration.
 
-## When to Trigger
+**Style guideline**: Work silently through Steps 1-3. Do not narrate internal steps, implementation details, or progress messages (e.g., "Let me check...", "The @applied block is empty..."). The first output the user sees should be the formatted summary in Step 4 (or the "up to date" message).
 
-Call this agent when you notice:
-- Tech debt that should be addressed later
-- Code that works but could be improved
-- Missing tests, documentation, or error handling
-- Architectural improvements worth tracking
+## Step 1: Pull Latest Updates
 
-## Input
+Run this command via Bash to pull new update files from the latest package:
 
-Provide these details when calling:
-- **title**: Short descriptive name (used for filename)
-- **problem**: What's wrong or what friction was encountered
-- **criteria**: Specific, testable acceptance criteria
-- **approach**: How to fix it
-- **priority**: Critical | High | Medium | Low
-- **effort**: S | M | L | XL
-- **files**: List of files involved
+\`\`\`bash
+npx claude-code-autoconfig@latest --pull-updates
+\`\`\`
 
-## Behavior
+This copies any new update \`.md\` files into \`.claude/updates/\` and refreshes this command file (preserving the \`@applied\` block above).
 
-1. Generate filename from title: \`kebab-case.md\`
-2. Create story file in \`.claude/retro/\` using the template format
-3. Confirm creation with filename
+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.
 
-## Guidelines
+## Step 2: Parse Update Files
 
-- **Be concise**: Keep descriptions actionable, not verbose
-- **Be specific**: Include actual file paths and line numbers when relevant
-- **Don't duplicate**: Check if similar item already exists first
-- **Don't block**: Create the item and continue with the main task`
+Read all \`.md\` files in \`.claude/updates/\` matching the pattern \`NNN-*.md\` (e.g., \`001-debug-methodology.md\`).`
             },
-            'docs-refresh-agent': {
-                filename: 'docs-refresh.md',
-                content: `# Guide Refresh Agent
+            'autoconfig': {
+                filename: 'autoconfig.md',
+                content: `# Autoconfig
 
-Incrementally update the docs's treeInfo when \`.claude/\` files are added or modified.
+Analyze this project and configure Claude Code with real context.
 
-## Trigger
+**Setup Note**: During autoconfig, prefer Glob/Read/Write tools over Bash commands. This ensures smooth setup without permission prompts. Only use Bash for the bootstrap step and opening the guide at the end.
 
-- PostToolUse hook on Edit|Write to \`.claude/\`
+## Step 0a: Bootstrap files from latest package
 
-## Scope
+**MANDATORY: You MUST run this Bash command before doing anything else.** Do not skip it. Do not assume it will fail. It is designed to work inside Claude Code sessions:
 
-- Read \`.claude/**/*.md\` for \`@description\` comments
-- Update \`.claude/docs/autoconfig.docs.html\` treeInfo
+\`\`\`bash
+npx claude-code-autoconfig@latest --bootstrap
+\`\`\`
 
-## Behavior
+This downloads the latest package and copies slash commands, hooks, agents, docs, and settings into \`.claude/\`. The \`--bootstrap\` flag makes it safe to run inside Claude Code — it copies files and exits silently with code 0. If it fails (e.g., no network), continue anyway — the existing files will still work.
+
+## Step 0b: Migrate FEEDBACK.md to Discoveries (one-time)
 
-1. Check which \`.claude/\` file was just modified
-2. Extract the \`<!-- @description ... -->\` comment from the top
-3. Find the corresponding entry in the docs's \`treeInfo\` object
-4. Update only that entry's \`desc\` field
-5. If file is new, add a new treeInfo entry
-6. If file was deleted, remove the treeInfo entry
+Read \`.claude/feedback/FEEDBACK.md\`. If it contains custom content beyond the default template header (sections after the first \`---\`), and \`CLAUDE.md\` does NOT already have a \`## Discoveries\` section:
 
-## Guidelines
+1. Read all custom content from FEEDBACK.md (everything after the first \`---\` separator)
+2. Append a \`## Discoveries\` section to the bottom of CLAUDE.md with that content
+3. Reset FEEDBACK.md to the clean template:
+   \`\`\`
+   <!-- @description Human-authored corrections and guidance for Claude. Reserved for team feedback only — Claude must not write here. This directory persists across /autoconfig runs. -->
 
-- **Be fast**: Only touch the affected entry
-- **Be minimal**: Don't reformat or reorganize unrelated code
-- **Be silent**: Run in background, no output unless error`
+   # Team Feedback
+
+   **This file is for human-authored corrections and guidance only.**
+   Claude reads this file but must never write to it. When Claude discovers project context, gotchas, or learnings, it should append to the \`## Discoveries\` section in CLAUDE.md instead.`
             },
-            'autoconfig': {
-                filename: 'autoconfig.md',
-                content: `# Autoconfig
+            'commit-and-push': {
+                filename: 'commit-and-push.md',
+                content: `# Commit and Push
 
-Analyze this project and configure Claude Code with real context.
+Run tests, stage all changes, create a commit with a good message, and push to the current branch.
 
-**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.
+## Steps
 
-## Step 1: Detect Environment
+1. Run the project's test suite (e.g., \`npm test\`)
+2. **If tests fail, stop here.** Do not commit or push failing code.
+3. Stage all changes (\`git add -A\`)
+4. Generate a conventional commit message based on the diff
+5. Commit the changes
+6. Push to the current branch
 
-**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
+## Commit Message Format
 
-## Step 2: Scan the Project
+Use conventional commits: \`type(scope): description\`
 
-Look for these indicators to understand the project:
+Types: feat, fix, docs, style, refactor, test, chore
 
-**Package/Config Files:**
-- \`package.json\` → Node.js, npm scripts, dependencies
-- \`requirements.txt\` / \`pyproject.toml\` / \`setup.py\` → Python
-- \`Cargo.toml\` → Rust
-- \`go.mod\` → Go
-- \`Gemfile\` → Ruby
-- \`pom.xml\` / \`build.gradle\` → Java
-- \`*.csproj\` / \`*.sln\` → .NET
-- \`composer.json\` → PHP
+Keep the subject line under 50 chars. Add body if the change needs explanation.`
+            },
+            'enable-retro': {
+                filename: 'enable-retro.md',
+                content: `# Enable Retro
+
+Enable the experimental Retro feature, which lets Claude log tech debt and improvement opportunities as structured story files.
+
+## What This Does
+
+1. Creates \`.claude/retro/\` directory with a README
+2. Creates \`.claude/agents/create-retro-item.md\` agent
+3. Adds Retro instructions to CLAUDE.md
+
+## Step 1: Create Retro Directory
 
-**Framework/Testing/Infrastructure** indicators also scanned.
+Create \`.claude/retro/README.md\` with:
 
-## Step 2b: Detect Version Divergence
+\`\`\`markdown
+# Retro Items
 
-Scans for version declarations across the project. Flags mismatches between package.json, hardcoded constants, manifest files, etc.
+Tech debt and improvement opportunities identified during development.
 
-## Step 3: Populate CLAUDE.md
+Each item is a structured story file with:
+- Problem description
+- Acceptance criteria
+- Suggested approach
+- Priority & effort sizing
+- Files involved
+
+## Working with Retro Items
+
+- "Fix retro #001" — Work on a specific item
+- "What's in the retro backlog?" — List pending items`
+            },
+            'gls': {
+                filename: 'gls.md',
+                content: `Get the latest screenshot(s) and display them.
 
-Focus on what Claude Code actually needs. Keep it tight — 30 lines beats 200.
+Usage:
+- \`/gls\` - Get and display the most recent screenshot
+- \`/gls-2\` - Get and display the 2 most recent screenshots
+- \`/gls-3\` - Get and display the 3 most recent screenshots
+- \`/gls-N\` - Get and display the N most recent screenshots
+- \`/gls /path/to/dir\` - Use a specific directory and save it
 
-**Always include:** Project name, tech stack, commands, non-obvious conventions.
-**Skip:** File trees, endpoint lists, model lists — Claude discovers these.
+## Step 1: Check for saved path
 
-## Step 4: Create Rules Directory
-## Step 5: Configure Formatter (JS/Node Projects)
-## Step 6: Configure Settings
-## Step 7: Update the Docs
+Check the \`@screenshotDir\` comment on line 1 of THIS file. If it has a path (not empty), use that path and skip to Step 3.
 
-## After Completion
+If it's empty (i.e., \`<!-- @screenshotDir  -->\`), continue to Step 2.
 
-Opens interactive docs in browser. Clean finale message.`
+## Step 2: Detect screenshot directory
+
+If the user provides a path as an argument (e.g., \`/gls /path/to/dir\`), use that path and skip to Step 2b.
+
+Otherwise, detect the OS and find the screenshot directory. Run this **single Bash command** which finds all candidate directories and reports the newest screenshot in each:
+
+\`\`\`bash
+OS=$(uname -s); echo "OS=$OS"; for d in \\
+  "$HOME/OneDrive/Pictures/Screenshots"* \\
+  "$HOME/Pictures/Screenshots" \\
+  "$HOME/Desktop" \\
+  "$HOME/Pictures" \\
+  "$HOME/Videos/Captures"; do \\
+  [ -d "$d" ] || continue; \\
+  newest=$(ls -t "$d"/*.png "$d"/*.jpg "$d"/*.jpeg "$d"/*.bmp "$d"/*.webp "$d"/*.gif 2>/dev/null | head -1); \\`
             },
-            'commit-and-push': {
-                filename: 'commit-and-push.md',
-                content: `# Commit and Push
+            'publish': {
+                filename: 'publish.md',
+                content: `# Publish
 
-Stage all changes, create a commit with a good message, and push to the current branch.
+Run tests, bump the patch version, commit, push, and publish to npm.
 
 ## Steps
 
-1. Stage all changes (\`git add -A\`)
-2. Generate a conventional commit message based on the diff
-3. Commit the changes
-4. Push to the current branch
+1. **Sync README.md** — Compare the current README against the actual state of the project (file tree, slash commands, features, settings). If anything is out of date or missing, update the README before proceeding. Check:
+   - File tree matches actual \`.claude/\` directory contents
+   - Slash commands table matches actual \`.claude/commands/\` files
+   - Feature sections reflect current capabilities (update system, MEMORY.md, hooks, etc.)
+   - No references to nonexistent commands or files
+2. Run the project's test suite (\`npm test\`)
+3. **If tests fail, stop here.** Do not publish broken code.
+4. 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
+5. Bump the version: \`npm version patch\`
+6. Push the commit and tag: \`git push && git push --tags\`
+7. Publish to npm: \`npm publish\`
+8. 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`
+            },
+            'recover-context': {
+                filename: 'recover-context.md',
+                content: `Recover recent conversation context from the raw session transcript on disk.
 
-## Commit Message Format
+Usage:
+- \`/recover-context -60\` — last 60 minutes of conversation
+- \`/recover-context -30\` — last 30 minutes
+- \`/recover-context -120\` — last 2 hours
+- \`/recover-context -60 --show\` — same as above, but also opens the filtered transcript in default editor
 
-Use conventional commits: \`type(scope): description\`
+The negative number means "go back N minutes from now." The minutes argument is **required**.
 
-Types: feat, fix, docs, style, refactor, test, chore
+## Step 1: Parse the arguments
 
-Keep the subject line under 50 chars. Add body if the change needs explanation.`
+The arguments are: $ARGUMENTS
+
+- If empty or missing, ask the user: "How many minutes back? (e.g., -60)"
+- Strip the leading \`-\` from the number and treat it as the number of minutes to look back
+- Check if \`--show\` flag is present
+
+## Step 2: Find the transcript file
+
+Find the current session's transcript by looking for the most recently modified \`.jsonl\` file in the Claude projects directory:
+
+\`\`\`bash
+ls -t ~/.claude/projects/*/*.jsonl 2>/dev/null | head -1
+\`\`\`
+
+If no transcript is found, tell the user and stop.
+
+## Step 3: Extract conversation context`
             },
-            'docs-cmd': {
+            'show-docs': {
                 filename: 'show-docs.md',
-                content: `# Show Guide
+                content: `# Show Docs
+
+Open the interactive documentation for Claude Code Autoconfig.
 
-Open the interactive docs for Claude Code Autoconfig.
+## Step 1: Sync Docs
 
-## Step 1: Check for Changes
+Run the sync script to ensure the docs reflect the current state of \`.claude/\`:
 
-Compare modification times of files in \`.claude/\` against the docs HTML.
+\`\`\`bash
+node .claude/scripts/sync-docs.js
+\`\`\`
 
-If any files are newer: "Syncing docs with latest changes..." → proceed to delta sync.
+This scans all files in \`.claude/\` (commands, hooks, agents, feedback, updates, settings) and updates the docs HTML file tree, info cards, and content previews automatically. It's fast and idempotent.
 
-## Step 2: Delta Sync
+If the script fails (e.g., file not found), skip to Step 2 — the docs will still open with whatever content they have.
 
-For each changed file, update only that entry in the docs's fileContents.
+## Step 2: Open Docs
 
-## Step 3: Open Guide
+Open the docs in the default browser. Use the command matching the current OS:
 
-Open in default browser (macOS: open, Linux: xdg-open, Windows: start).`
+- **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'"\`
+
+**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.`
+            },
+            'sync-claude-md': {
+                filename: 'sync-claude-md.md',
+                content: `# Sync CLAUDE.md
+
+Re-analyze the project and update CLAUDE.md to reflect current state.
+
+Run this when your project has changed significantly:
+- Added a major framework or dependency
+- Changed npm scripts or build commands
+- Restructured the project
+- Switched databases or services
+
+## Step 1: Check for Team Feedback
+
+Before regenerating, check \`.claude/feedback/FEEDBACK.md\` for any corrections or guidance from the team. Review and incorporate relevant feedback into your regeneration.
+
+## Step 2: Re-analyze the Project
+
+Scan for current project indicators:
+
+**Package/Config Files:**
+- \`package.json\` → dependencies, scripts
+- \`requirements.txt\` / \`pyproject.toml\` → Python deps
+- \`Cargo.toml\`, \`go.mod\`, \`Gemfile\`, etc.
+
+**Framework Indicators:**
+- Config files (next.config.*, vite.config.*, etc.)
+- Directory structure (app/, src/, etc.)
+
+**Infrastructure:**
+- Docker, Terraform, CI/CD configs`
             },
             'test': {
                 filename: 'test.md',
@@ -1776,77 +1858,174 @@ If no scope provided, run the full test suite. Otherwise run tests matching the
 
 Detect the test command from project config (package.json scripts, pytest, go test, etc.) and execute it.`
             },
-            'rules': {
-                filename: 'rules/',
-                content: null,
-                empty: true,
-                emptyMessage: 'This directory is empty.\n\nAdd .md files here to define rules for specific paths in your codebase.'
-            },
-            'docs': {
-                filename: 'autoconfig.docs.html',
-                content: null,
-                empty: true,
-                emptyMessage: "You're looking at it! 👀"
-            },
-            'enable-retro': {
-                filename: 'enable-retro.md',
-                content: `# Enable Retro
+            'create-retro-item-agent': {
+                filename: 'create-retro-item.md',
+                content: `# Create Retro Item Agent
 
-(Experimental) Enable tech debt tracking.
+Create a fully-scoped story file in \`.claude/retro/\` when tech debt or improvement opportunities are identified.
 
-## What This Does
+## When to Trigger
 
-1. Creates \`.claude/retro/\` directory
-2. Creates \`.claude/agents/create-retro-item.md\` agent
-3. Adds Retro instructions to CLAUDE.md
+Call this agent when you notice:
+- Tech debt that should be addressed later
+- Code that works but could be improved
+- Missing tests, documentation, or error handling
+- Architectural improvements worth tracking
 
-## After Enabling
+## Input
 
-Claude will log tech debt and improvement opportunities as structured story files:
-- Problem description
-- Acceptance criteria
-- Suggested approach
-- Priority & effort sizing
-- Files involved
+Provide these details when calling:
+- **title**: Short descriptive name (used for filename)
+- **problem**: What's wrong or what friction was encountered
+- **criteria**: Specific, testable acceptance criteria
+- **approach**: How to fix it
+- **priority**: Critical | High | Medium | Low
+- **effort**: S | M | L | XL
+- **files**: List of files involved
 
-Work through items: "Fix retro #001"`
+## Behavior
+
+1. Generate filename from title: \`kebab-case.md\`
+2. Create story file in \`.claude/retro/\` using this format:
+
+\`\`\`markdown
+# [Title]`
             },
-            'feedback-template': {
-                filename: 'FEEDBACK.md',
-                content: `# Team Feedback
+            'docs-refresh-agent': {
+                filename: 'docs-refresh.md',
+                content: `# Docs Refresh Agent
 
-Add corrections and guidance here when Claude does something wrong.
-Claude reads this directory and learns for next time.
+Sync the interactive docs with the current state of \`.claude/\`.
 
----
+## How
 
-## Debugging Methodology — Evidence Before Solutions
+Run:
 
-**NEVER jump to a fix based on assumptions.** When investigating a bug:
+\`\`\`bash
+node .claude/scripts/sync-docs.js
+\`\`\`
 
-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
+This scans \`.claude/\` for all files, extracts \`@description\` metadata, and updates the docs HTML (file tree, info cards, and content previews).
 
----
+## When to Use
+
+- After adding, modifying, or deleting files in \`.claude/\`
+- Before opening docs with \`/show-docs\` (already built in)
+- As a background task when \`.claude/\` files change`
+            },
+            'feedback-rule-check-hook': {
+                filename: 'feedback-rule-check.js',
+                content: `#!/usr/bin/env node
+
+/**
+ * @name Feedback Rule Migration Check
+ * @description After FEEDBACK.md is edited, notifies Claude to evaluate
+ *              whether any entries would be more reliably delivered as
+ *              .claude/rules/ files with glob patterns.
+ * @trigger PostToolUse on Write|Edit
+ */
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const filePath = data?.tool_input?.file_path || '';
+
+    // Only fire for FEEDBACK.md edits
+    if (!filePath.endsWith('FEEDBACK.md')) {
+      process.exit(0);
+    }
+
+    console.log([
+      'FEEDBACK.md was just modified.',
+      'Review the changes and evaluate whether any entries are tied to specific file types,',
+      'frameworks, or patterns that could be scoped with a glob (e.g., *.py, *.tsx, src/api/**).',
+      '',
+      'If any entries qualify, ask the user:',`
+            },
+            'format-hook': {
+                filename: 'format.js',
+                content: `#!/usr/bin/env node
+
+/**
+ * @name Format Hook
+ * @description Runs project formatter after Write/Edit operations
+ * @trigger PostToolUse on Write|Edit
+ */
 
-## Design Principles
+const { execSync } = require('child_process');
+const path = require('path');
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    handleHook(data);
+  } catch (err) {
+    // Silent exit if no valid input
+    process.exit(0);
+  }
+});
 
-- Each file should have a single responsibility
-- If a file exceeds 500 LOC, look for decomposition opportunities
-- Keep cyclomatic complexity under 10 per function
+function handleHook(data) {
+  const filePath = data?.tool_input?.file_path || '';
 
-## Development Rules
+  // Skip non-source files
+  if (!filePath.match(/\\.(js|jsx|ts|tsx|json|css|scss|md|html)$/)) {`
+            },
+            'migrate-feedback-hook': {
+                filename: 'migrate-feedback.js',
+                content: `#!/usr/bin/env node
+
+/**
+ * @name Feedback to Discoveries Migration
+ * @description On session start, migrates custom FEEDBACK.md content to
+ *              CLAUDE.md Discoveries section. One-time, idempotent.
+ * @trigger SessionStart
+ */
 
-### Testing Requirements
+const fs = require('fs');
+const path = require('path');
+
+const cwd = process.cwd();
+const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+const feedbackPath = path.join(cwd, '.claude', 'feedback', 'FEEDBACK.md');
+
+// Read hook input from stdin (required by hook protocol)
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    migrate();
+  } catch (err) {
+    // Silent exit on any error
+  }
+  process.exit(0);
+});
 
-**CRITICAL: Before committing changes to bin/cli.js, run tests:**
-\\\`npm test\\\`
+function migrate() {`
+            },
+            'feedback-feedback': {
+                filename: 'FEEDBACK.md',
+                content: `# Team Feedback
 
-### Box Drawing Guidelines
+**This file is for human-authored corrections and guidance only.**
+Claude reads this file but must never write to it. When Claude discovers project context, gotchas, or learnings, it should append to the \`## Discoveries\` section in CLAUDE.md instead.
 
-All lines must be exactly 46 visible characters wide (including borders).
-ANSI escape codes don't count toward visible width.`
+---`
+            },
+            'rules': {
+                filename: 'rules/',
+                content: null,
+                empty: true,
+                emptyMessage: 'Add .md files here to define rules for specific paths in your codebase.'
             },
             'hooks': {
                 filename: 'hooks/',
@@ -1854,23 +2033,103 @@ ANSI escape codes don't count toward visible width.`
                 empty: true,
                 emptyMessage: 'Contains executable hook scripts that trigger on Claude Code events.'
             },
-            'format-hook': {
-                filename: 'format.js',
-                content: `/**
- * @name Format Hook
- * @description Runs project formatter after Write/Edit operations
- * @trigger PostToolUse on Write|Edit
- */
-
-// Reads hook input from stdin
-// Filters by file extension (.js, .ts, .json, .css, etc.)
-// Skips generated directories (node_modules, dist, build)
-// Runs: npm run format --silent
-
-// Key behavior:
-// - Only triggers for source files
-// - Silently runs formatter (errors are non-fatal)
-// - Customizable - add your own file filters or formatting logic`
+            'docs': {
+                filename: 'autoconfig.docs.html',
+                content: null,
+                empty: true,
+                emptyMessage: "You\'re looking at it! 👀"
+            },
+            'rules': {
+                filename: 'rules/',
+                content: null,
+                empty: true,
+                emptyMessage: 'This directory is empty.\nAdd .md files here to define rules for specific paths in your codebase.'
+            },
+            'settings': {
+                filename: 'settings.json',
+                content: `{
+  "env": {
+    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/migrate-feedback.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/feedback-rule-check.js"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "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 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(./**/credentials.*)",
+      "Read(./**/*.pem)",
+      "Read(./**/*.key)",
+      "Bash(rm -rf:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)"
+    ]
+  }
+}`
+            },
+            'mcp': {
+                filename: '.mcp.json',
+                content: `{
+  "mcpServers": {}
+}`
             }
         };