feat(docs): add doc-reference drift gate

.chezmoidata.toml

@@ -29,8 +29,8 @@
   #   - /configure:mcp command for interactive selection
   #   - MCP Management skill for automated installation based on project needs
   #
-  # Note: The update-ai-tools.sh script only installs servers with enabled=true.
-  # For project-specific needs, manually create .mcp.json in your project root.
+  # Note: This is a registry only — servers are installed per-project into that
+  # project's .mcp.json (via /configure:mcp), not from this file directly.
 
   [mcp_servers.graphiti-memory]
     enabled = false

.claude/rules/package-registries.md

@@ -18,5 +18,5 @@ Packages are managed through `.chezmoidata/packages.toml` with profile activatio
 
 - Registry of available servers in `.chezmoidata.toml` under `[mcp_servers]`
 - Enable/disable per server — `enabled = true/false`
-- Project-specific overrides in per-project `.mcp.json`
-- Use `update-ai-tools.sh` for safe updates during active sessions
+- Servers are installed per-project into that project's `.mcp.json`
+- Use `/configure:mcp` to install servers into a project; `./cleanup-mcp-servers.sh` to remove them (run only when no Claude sessions are active)

.claude/rules/shell-completions.md

@@ -3,7 +3,7 @@
 ## Overview
 
 Shell completions are managed via chezmoi's data-driven approach:
-- **Registry**: `.chezmoidata.toml` under `[packages.completion_tools.zsh_completions]`
+- **Registry**: `.chezmoidata/completions.toml` under `[packages.completion_tools.zsh_completions]`
 - **Generator**: `run_onchange_02-generate-completions.sh.tmpl`
 - **Output**: `~/.zfunc/_<tool>` (Zsh completion files)
 
@@ -15,7 +15,7 @@ Shell completions are managed via chezmoi's data-driven approach:
    # or check tool documentation
    ```
 
-2. **Add to registry** in `.chezmoidata.toml`:
+2. **Add to registry** in `.chezmoidata/completions.toml`:
    ```toml
    [packages.completion_tools.zsh_completions]
      # ... existing entries ...
@@ -41,7 +41,7 @@ Shell completions are managed via chezmoi's data-driven approach:
 ## How It Works
 
 The `run_onchange` script:
-1. Detects changes via `.chezmoidata.toml` hash in template header
+1. Detects changes via `.chezmoidata/completions.toml` hash in template header
 2. Iterates over all entries in `zsh_completions`
 3. Skips tools not installed (`command -v` check)
 4. Generates `~/.zfunc/_<tool>` for each available tool
@@ -71,6 +71,6 @@ rm -f ~/.zcompdump && compinit
 **Force regeneration:**
 ```bash
 # Touch the data file to trigger run_onchange
-touch ~/.local/share/chezmoi/.chezmoidata.toml
+touch ~/.local/share/chezmoi/.chezmoidata/completions.toml
 chezmoi apply
 ```

.claude/rules/testing.md

@@ -9,7 +9,7 @@
 | Lua | `mise run lint:lua` | After modifying Neovim config |
 | Actions | `mise run lint:actions` | After modifying workflows |
 | Full | `mise run test` | Before committing |
-| Docker | `mise run test:docker` | For environment changes |
+| Docker | `mise run docker` | For environment changes |
 
 ## Linting Standards
 

.claude/skills/neovim-configuration/SKILL.md

@@ -5,8 +5,8 @@ reviewed: 2025-12-16
 name: neovim-configuration
 description: |
   Modern Neovim configuration expertise including Lua scripting, plugin management with
-  lazy.nvim, LSP setup with Mason, AI integration with CodeCompanion, and workflow
-  optimization. Covers keymaps, autocommands, and treesitter configuration.
+  lazy.nvim, LSP setup with Mason, AI integration with claudecode.nvim/opencode.nvim,
+  and workflow optimization. Covers keymaps, autocommands, and treesitter configuration.
   Use when user mentions Neovim, nvim, lazy.nvim, Mason, init.lua, Lua config,
   nvim plugins, or Neovim customization.
 allowed-tools: Glob, Grep, Read, Edit, Write
@@ -21,7 +21,7 @@ Expert knowledge for modern Neovim configuration with Lua scripting, plugin mana
 **Modern Neovim Configuration**
 - Lua-based configuration with lazy.nvim plugin management
 - LSP setup with Mason for language server management
-- AI integration with CodeCompanion and custom prompt strategies
+- AI integration with claudecode.nvim and opencode.nvim
 - Advanced key mapping and workflow optimization
 
 ## Key Capabilities
@@ -39,9 +39,8 @@ Expert knowledge for modern Neovim configuration with Lua scripting, plugin mana
 - **Code Navigation**: Go-to-definition, references, and symbol search
 
 **AI Integration & Automation**
-- **CodeCompanion**: AI-powered code assistance with custom prompts
-- **Custom Strategies**: Domain-specific AI workflows for different development contexts
-- **Prompt Management**: Custom prompts for Arduino, deployment, debugging, and more
+- **claudecode.nvim**: Claude Code integration for AI-powered coding in Neovim
+- **opencode.nvim**: OpenCode AI agent integration
 - **Workflow Integration**: AI assistance integrated into development workflows
 
 **Advanced Features**

.doc-reference-allow

@@ -0,0 +1,12 @@
+# Allowlist for scripts/check-doc-references.py — one glob per line.
+# Docs matching these globs are skipped by the doc-reference gate.
+
+# Immutable point-in-time records: ADRs intentionally reference paths that were
+# accurate when the decision was made and may since have moved/been removed.
+docs/adrs/**
+
+# Global ~/.claude source tree. These docs reference the external
+# claude-plugins marketplace and OTHER projects' paths (e.g. an aiq project's
+# scripts/aiq.py, docs/source/...), plus runtime ~/.claude structures — none of
+# which are files in THIS repo. Repo-relative existence checking does not apply.
+exact_dot_claude/**

.pre-commit-config.yaml

@@ -53,6 +53,17 @@ repos:
         language: script
         files: '^(exact_dot_claude/(rules/.*\.md|CLAUDE\.md)|tests/test-claude-context-budget\.sh)$'
         pass_filenames: false
+      # Advisory doc-drift nudge: flags docs that reference scripts/paths/links
+      # which no longer exist. ADVISORY (always exits 0) so it never blocks a
+      # commit; `mise run lint:docs` is the strict/enforcing variant for CI.
+      # See scripts/check-doc-references.py and .doc-reference-allow.
+      - id: check-doc-references
+        name: check docs for dangling references (advisory)
+        entry: scripts/check-doc-references.py
+        language: script
+        pass_filenames: false
+        always_run: true
+        verbose: true
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.7
     hooks:

CLAUDE.md

@@ -26,7 +26,7 @@ Managed in [laurigates/claude-plugins](https://github.com/laurigates/claude-plug
 
 ## MCP Servers
 
-Managed per-project in `.mcp.json`. Registry of available servers in `.chezmoidata.toml` under `[mcp_servers]`. Use `/configure-mcp` for guided setup.
+Managed per-project in `.mcp.json`. Registry of available servers in `.chezmoidata.toml` under `[mcp_servers]`. Use `/configure:mcp` for guided setup.
 
 ## Linting
 
@@ -50,9 +50,8 @@ pre-commit run --all-files            # All pre-commit hooks
 
 ### Secret scanning:
 ```bash
-detect-secrets scan --baseline .secrets.baseline
-detect-secrets audit .secrets.baseline
-pre-commit run detect-secrets --all-files
+gitleaks detect --source . --config .gitleaks.toml   # scan the working tree
+pre-commit run gitleaks --all-files                  # via pre-commit
 ```
 
 ## Key Files & Directories
@@ -92,8 +91,6 @@ Blueprint v3.3.0 manages project documentation and rules.
 ## Sub-documentation
 
 - `exact_dot_claude/CLAUDE.md` — Claude Code design and directory structure
-- `exact_dot_claude/commands/CLAUDE.md` — Slash commands guide
-- `exact_dot_claude/skills/CLAUDE.md` — Skills system
 - `private_dot_config/CLAUDE.md` — Application configuration
 - `private_dot_config/nvim/CLAUDE.md` — Neovim configuration
 - `scripts/CLAUDE.md` — Maintenance scripts

README.md

@@ -50,8 +50,9 @@ just plugins-enable
 ```
 
 Or install individually:
+
 ```bash
-claude /plugin install git-plugin@laurigates-claude-plugins
+claude plugin install git-plugin@laurigates-claude-plugins
 ```
 
 ### Bulk Plugin Management
@@ -68,37 +69,36 @@ just plugins-list        # Show installed plugins and status
 
 ## AI Tools & MCP Configuration
 
-AI tools and MCP (Model Context Protocol) servers are configured through the `.chezmoidata.toml` file and automatically installed via the `update-ai-tools.sh` script.
+MCP (Model Context Protocol) servers are managed **per-project** via each project's `.mcp.json`. A curated registry of available servers lives in `.chezmoidata.toml` under `[mcp_servers]`, disabled by default to avoid bloating context in every repository.
 
 ### MCP Server Configuration
 
-MCP servers for Claude Code are dynamically configured from `.chezmoidata.toml`. To manage servers:
+The `[mcp_servers]` registry in `.chezmoidata.toml` records each server's metadata:
 
 - **Enable/disable servers**: Set `enabled = true/false` in the `[mcp_servers]` section
 - **Add new servers**: Create a new `[mcp_servers.name]` section with required fields
 - **Configure options**: `scope`, `command`, `args`, and optional `transport`
 
 Example configuration:
+
 ```toml
 [mcp_servers.my-server]
-  enabled = true
-  scope = "user"
+  enabled = false
+  scope = "project"
   command = "npx"
   args = ["-y", "my-mcp-package"]
   transport = "stdio"  # optional
 ```
 
-**Adding/updating servers** (safe during active Claude sessions):
-```bash
-./update-ai-tools.sh  # or: chezmoi apply update-ai-tools.sh
-```
+**Installing servers into a project**: run the `/configure:mcp` command for interactive, project-scoped selection — it writes the chosen servers to that project's `.mcp.json`.
+
+**Removing servers** (WARNING: disrupts active Claude sessions):
 
-**Cleaning up disabled servers** (WARNING: disrupts active Claude sessions):
 ```bash
 ./cleanup-mcp-servers.sh  # Run only when no Claude sessions are active
 ```
 
-> **Note**: `update-ai-tools.sh` only adds new servers without removing existing ones, making it safe to run during active Claude sessions. Use `cleanup-mcp-servers.sh` only when you need to remove disabled servers and no Claude Code sessions are running.
+> **Note**: `cleanup-mcp-servers.sh` removes MCP servers from user and project scope, so run it only when no Claude Code sessions are active. Afterwards, reinstall per-project with `/configure:mcp`.
 
 ## Claude Code Configuration
 
@@ -111,6 +111,7 @@ Full guide: See [CLAUDE.md](./CLAUDE.md)
 ### Skills
 
 Auto-discovered skills provide contextual guidance:
+
 - **chezmoi-expert** - Dotfiles management, templates, cross-platform configs
 - **neovim-configuration** - Lua config, plugin management, LSP setup
 - **obsidian-bases** - Obsidian Bases database feature for YAML-based views

docs/blueprint/README.md

@@ -4,9 +4,7 @@ Blueprint development structure for this project.
 
 ## Contents
 
-- `manifest.json` — Blueprint configuration and task registry (v3.2.0)
-- `work-orders/` — Detailed work order documents
-- `ai_docs/` — AI-curated documentation
+- `manifest.json` — Blueprint configuration and task registry (v3.3.0)
 
 ## Related Directories
 

docs/components.md

@@ -44,12 +44,8 @@ Configuration is managed via Lua (`private_dot_config/nvim/lua/`).
 -   **Git Integration:**
     -   **[Gitsigns](https://github.com/lewis6991/gitsigns.nvim)**: Shows Git status (added, modified, deleted lines) in the sign column and provides related actions (preview hunk, stage, reset, blame, etc.).
 -   **AI / LLM Integration:**
-    -   **[CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim)**: AI-powered coding plugin supporting Anthropic, Copilot, Gemini, Ollama, OpenAI and other LLMs.
-        -   **Strategies (`strategies.lua`)**: Defines different interaction modes (e.g., chat, workflow).
-        -   **Tools**: Allows the LLM to invoke external commands securely:
-            -   `git diff`, `git log`, `git status`, `git commit`, `git push`
-            -   `arduino-cli compile`, `arduino-cli upload`, `arduino-cli monitor`
-        -   **Prompts (`private_prompts/`)**: Pre-defined prompt templates and workflows (e.g., Arduino code generation).
+    -   **[claudecode.nvim](https://github.com/coder/claudecode.nvim)** (`exact_plugins/claudecode.lua`): Claude Code integration for Neovim.
+    -   **[opencode.nvim](https://github.com/NickvanDyke/opencode.nvim)** (`exact_plugins/opencode.lua`): OpenCode AI agent integration.
 
 ## Terminal Utilities
 

docs/homebrew-mise-migration-analysis.md

@@ -2,6 +2,12 @@
 
 This document analyzes package duplication between Homebrew and the new mise configuration.
 
+> **Note (point-in-time analysis):** the package/tool registries have since been
+> split out of `.chezmoidata.toml` into the `.chezmoidata/` directory —
+> `uv_tools` now lives in `.chezmoidata/uv_tools.toml` and packages in
+> `.chezmoidata/packages.toml`. References to a `uv_tools` section "in
+> `.chezmoidata.toml`" below reflect the layout at the time of writing.
+
 ## 📊 Duplicate Analysis
 
 ### Packages Now Managed by mise (Remove from Homebrew)

docs/prds/project-overview.md

@@ -78,8 +78,7 @@ A chezmoi-managed dotfiles repository that declaratively configures the full dev
 ### Security
 - No secrets in git — API tokens, credentials via `~/.api_tokens`
 - Private files use `private_` chezmoi prefix (mode 600)
-- gitleaks on every commit via pre-commit hook
-- detect-secrets baseline maintained in `.secrets.baseline`
+- gitleaks on every commit via pre-commit hook (see ADR 0015)
 
 ### Reliability
 - Smoke test CI validates setup on Ubuntu and macOS
@@ -102,9 +101,10 @@ A chezmoi-managed dotfiles repository that declaratively configures the full dev
 - **Brewfile** with profile-based package selection via `.chezmoidata/profiles.toml`
 
 ### Key Configuration Files
-- `.chezmoidata.toml` — MCP servers, uv_tools, platform data
+- `.chezmoidata.toml` — MCP servers, platform data
 - `.chezmoidata/packages.toml` — Profile-based Homebrew package registry
 - `.chezmoidata/profiles.toml` — Profile activation flags
+- `.chezmoidata/uv_tools.toml` — Python tools managed by uv
 - `dot_zshrc.tmpl` — Zsh config (template)
 - `private_dot_config/mise/config.toml.tmpl` — mise tools and tasks
 - `private_dot_config/nvim/` — Neovim Lua configuration

exact_dot_claude/docs/blueprint-development/IMPLEMENTATION_SUMMARY.md

@@ -1,5 +1,12 @@
 # Blueprint Development - Implementation Summary
 
+> **Superseded:** Blueprint has since moved to the external
+> [`blueprint-plugin`](https://github.com/laurigates/claude-plugins) marketplace.
+> The in-repo skills (`.claude/skills/blueprint-development/`) and commands
+> (`.claude/commands/`) described below **no longer exist in this repo** — those
+> capabilities now resolve at runtime from the plugin. This document is retained
+> as a historical record of the original in-repo implementation.
+
 This document summarizes the Blueprint Development implementation in your dotfiles repository.
 
 ## What Was Created

exact_dot_claude/docs/blueprint-development/README.md

@@ -254,7 +254,9 @@ Use Blueprint Development in CI:
 
 ## Commands
 
-See `.claude/commands/` for available commands:
+These commands are now provided by the external
+[`blueprint-plugin`](https://github.com/laurigates/claude-plugins) marketplace
+(they no longer live in this repo's `.claude/commands/`):
 
 **PRP Commands:**
 - `/prp-create` - Create a PRP with systematic research and context curation

executable_cleanup-mcp-servers.sh.tmpl

@@ -36,7 +36,7 @@ claude mcp remove --scope={{ $config.scope }} {{ $name }} || true
 {{- end }}
 
 echo ""
-echo "✅ Cleanup complete. Run update-ai-tools.sh to re-add servers."
+echo "✅ Cleanup complete. MCP servers are now managed per-project."
 echo ""
-echo "To re-add servers now:"
-echo "  ./update-ai-tools.sh"
+echo "To reinstall servers into a project, use:"
+echo "  /configure:mcp   (interactive, writes to the project's .mcp.json)"

private_dot_config/CLAUDE.md

@@ -20,6 +20,5 @@ Application configuration files managed by chezmoi. Uses chezmoi naming conventi
 | `rofi/` | Application launcher (Linux) |
 | `sketchybar/` | macOS status bar |
 | `private_dunst/` | Notification daemon (Linux) |
-| `private_i3/` | i3 window manager (Linux) |
 | `fd/` | fd ignore patterns |
 | `pet/` | Snippet manager |

private_dot_config/mise/config.toml.tmpl

@@ -278,9 +278,21 @@ else
     echo "  ⚠️  Warning: Brewfile not found"
 fi
 
+# Documentation references (dangling scripts/paths/links)
+if command -v python3 >/dev/null 2>&1; then
+    echo "  ✓ Checking doc references..."
+    python3 scripts/check-doc-references.py --strict || {
+        echo "  ⚠️  Warning: doc reference check found dangling references"
+    }
+fi
+
 echo "✅ Linting complete!"
 """
 
+[tasks."lint:docs"]
+description = "Check docs for dangling repo-relative references (scripts/paths/links)"
+run = "python3 scripts/check-doc-references.py --strict"
+
 [tasks."lint:shell"]
 description = "Run shellcheck on shell scripts"
 run = 'find . -name "*.sh" -not -path "./node_modules/*" -exec shellcheck {} \\;'

scripts/CLAUDE.md

@@ -13,5 +13,6 @@ Utility scripts for Claude Code infrastructure automation.
 | `audit-secrets-baseline.py` | Audit secrets baseline file |
 | `audit-secrets-selective.py` | Selective secrets audit |
 | `smoke-test-docker.sh` | Docker-based smoke tests for dotfiles |
+| `check-doc-references.py` | Flag docs that reference scripts/paths/links no longer in the repo (advisory pre-commit hook; strict via `mise run lint:docs`). See `.doc-reference-allow` for scoping and `tests/test-check-doc-references.sh` for the contract. |
 
 All shell scripts support `--help`. Run `shellcheck scripts/*.sh` to lint.

scripts/README.md

@@ -160,17 +160,17 @@ uv run --with detect-secrets python3 scripts/audit-secrets-baseline.py
 
 ### Pre-commit Hook
 
-The `.pre-commit-config.yaml` includes detect-secrets:
+Secret scanning in pre-commit is handled by gitleaks; `.pre-commit-config.yaml` includes:
 
 ```yaml
-- repo: https://github.com/Yelp/detect-secrets
-  rev: v1.5.0
+- repo: https://github.com/gitleaks/gitleaks
+  rev: v8.30.0
   hooks:
-    - id: detect-secrets
-      args: ['--baseline', '.secrets.baseline']
-      exclude: (package\.lock\.json|lazy-lock\.json)
+    - id: gitleaks
 ```
 
+detect-secrets is no longer a pre-commit hook — it remains available only as a manual/on-demand baseline-audit tool (see the `uv run --with detect-secrets` commands above).
+
 **Pre-commit workflow**:
 1. Make changes
 2. Run `pre-commit run --all-files` (or let it run on commit)
@@ -277,4 +277,4 @@ This repository excludes:
 - `\.claude/docs/.*` - Claude Code documentation
 - `lazy-lock\.json` - Neovim plugin lock file (git commit hashes)
 
-See `.secrets.baseline` line 115-117 for the current exclusion pattern.
+See `.gitleaks.toml` for the current secret-scan allowlist and exclusion patterns.