diff --git a/.gitignore b/.gitignore
index 8b1105a..3862570 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,6 +18,9 @@ settings.local.json
 
 tmp/
 
+# Blueprint work orders (task-specific, may contain sensitive details)
+docs/blueprint/work-orders/
+
 # Security: prevent accidental commit of secrets/credentials
 .env
 .env.*
diff --git a/CLAUDE.md b/CLAUDE.md
index 4a23ede..c8a2a02 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,6 +72,16 @@ pre-commit run detect-secrets --all-files
 - **smoke.yml** — Multi-platform (Ubuntu/macOS) linting and build
 - **claude.yml** — AI-assisted dev with auto plugin install from [laurigates/claude-plugins](https://github.com/laurigates/claude-plugins)
 
+## Blueprint Documentation
+
+Blueprint v3.2.0 manages project documentation and rules.
+
+- **PRD**: `docs/prds/project-overview.md` — Feature requirements and scope
+- **ADRs**: `docs/adrs/` — 16 Architecture Decision Records ([index](docs/adrs/README.md))
+- **PRPs**: `docs/prps/` — Implementation plans (fish, NixOS, sketchybar)
+- **Manifest**: `docs/blueprint/manifest.json` — Configuration and task registry
+- **Commands**: `/blueprint:status`, `/blueprint:execute`, `/blueprint:derive-plans`
+
 ## Sub-documentation
 
 - `exact_dot_claude/CLAUDE.md` — Claude Code design and directory structure
@@ -80,6 +90,7 @@ pre-commit run detect-secrets --all-files
 - `private_dot_config/CLAUDE.md` — Application configuration
 - `private_dot_config/nvim/CLAUDE.md` — Neovim configuration
 - `scripts/CLAUDE.md` — Maintenance scripts
+- `docs/blueprint/README.md` — Blueprint structure overview
 
 ## Security & Release
 
diff --git a/docs/adr/0001-chezmoi-exact-directory-strategy.md b/docs/adrs/0001-chezmoi-exact-directory-strategy.md
similarity index 100%
rename from docs/adr/0001-chezmoi-exact-directory-strategy.md
rename to docs/adrs/0001-chezmoi-exact-directory-strategy.md
diff --git a/docs/adr/0002-unified-tool-version-management-mise.md b/docs/adrs/0002-unified-tool-version-management-mise.md
similarity index 100%
rename from docs/adr/0002-unified-tool-version-management-mise.md
rename to docs/adrs/0002-unified-tool-version-management-mise.md
diff --git a/docs/adr/0003-skill-activation-trigger-keywords.md b/docs/adrs/0003-skill-activation-trigger-keywords.md
similarity index 100%
rename from docs/adr/0003-skill-activation-trigger-keywords.md
rename to docs/adrs/0003-skill-activation-trigger-keywords.md
diff --git a/docs/adr/0004-subagent-first-delegation-strategy.md b/docs/adrs/0004-subagent-first-delegation-strategy.md
similarity index 100%
rename from docs/adr/0004-subagent-first-delegation-strategy.md
rename to docs/adrs/0004-subagent-first-delegation-strategy.md
diff --git a/docs/adr/0005-namespace-based-command-organization.md b/docs/adrs/0005-namespace-based-command-organization.md
similarity index 100%
rename from docs/adr/0005-namespace-based-command-organization.md
rename to docs/adrs/0005-namespace-based-command-organization.md
diff --git a/docs/adr/0006-documentation-first-development.md b/docs/adrs/0006-documentation-first-development.md
similarity index 100%
rename from docs/adr/0006-documentation-first-development.md
rename to docs/adrs/0006-documentation-first-development.md
diff --git a/docs/adr/0007-layered-knowledge-distribution.md b/docs/adrs/0007-layered-knowledge-distribution.md
similarity index 100%
rename from docs/adr/0007-layered-knowledge-distribution.md
rename to docs/adrs/0007-layered-knowledge-distribution.md
diff --git a/docs/adr/0008-project-scoped-mcp-servers.md b/docs/adrs/0008-project-scoped-mcp-servers.md
similarity index 100%
rename from docs/adr/0008-project-scoped-mcp-servers.md
rename to docs/adrs/0008-project-scoped-mcp-servers.md
diff --git a/docs/adr/0009-conventional-commits-release-please.md b/docs/adrs/0009-conventional-commits-release-please.md
similarity index 100%
rename from docs/adr/0009-conventional-commits-release-please.md
rename to docs/adrs/0009-conventional-commits-release-please.md
diff --git a/docs/adr/0010-tiered-test-execution.md b/docs/adrs/0010-tiered-test-execution.md
similarity index 100%
rename from docs/adr/0010-tiered-test-execution.md
rename to docs/adrs/0010-tiered-test-execution.md
diff --git a/docs/adr/0011-claude-rules-migration.md b/docs/adrs/0011-claude-rules-migration.md
similarity index 97%
rename from docs/adr/0011-claude-rules-migration.md
rename to docs/adrs/0011-claude-rules-migration.md
index d9ec03d..d8e93da 100644
--- a/docs/adr/0011-claude-rules-migration.md
+++ b/docs/adrs/0011-claude-rules-migration.md
@@ -142,7 +142,7 @@ Rules load in this order (lower number = loaded first, higher takes precedence):
 - `.claude/rules/` - The rules directory this ADR introduces
 - `.claude/CLAUDE.md` - High-level design documentation updated to reference rules
 - `CLAUDE.md` (root) - Project overview updated with rules references
-- `docs/adr/0001-chezmoi-exact-directory-strategy.md` - Related decision on `exact_` prefix for `.claude/` management
+- `docs/adrs/0001-chezmoi-exact-directory-strategy.md` - Related decision on `exact_` prefix for `.claude/` management
 
 ## References
 
diff --git a/docs/adr/0012-justfile-command-runner.md b/docs/adrs/0012-justfile-command-runner.md
similarity index 100%
rename from docs/adr/0012-justfile-command-runner.md
rename to docs/adrs/0012-justfile-command-runner.md
diff --git a/docs/adr/0013-nixos-declarative-system-configuration.md b/docs/adrs/0013-nixos-declarative-system-configuration.md
similarity index 100%
rename from docs/adr/0013-nixos-declarative-system-configuration.md
rename to docs/adrs/0013-nixos-declarative-system-configuration.md
diff --git a/docs/adrs/0014-profile-based-package-registry.md b/docs/adrs/0014-profile-based-package-registry.md
new file mode 100644
index 0000000..528a0dc
--- /dev/null
+++ b/docs/adrs/0014-profile-based-package-registry.md
@@ -0,0 +1,47 @@
+# ADR-0014: Profile-Based Package Registry
+
+**Date**: 2026-04-08
+**Status**: Accepted
+**Confidence**: High (direct evidence from codebase)
+
+## Context
+
+The Brewfile was growing large and monolithic, containing packages needed for different use cases (core tools, development, infrastructure, GUI applications) without differentiation. On a minimal machine or a CI runner, there was no easy way to install only the relevant subset.
+
+Commit evidence: `feat(packages): restructure into profile-based package registry`
+
+## Decision
+
+Restructure Homebrew package management into a profile-based registry:
+
+- `.chezmoidata/packages.toml` — Registry of all available packages grouped by profile
+- `.chezmoidata/profiles.toml` — Activation flags per profile (`dev`, `infra`, `gui`, etc.)
+- Chezmoi templates render only packages for active profiles into the final `Brewfile`
+
+Profiles:
+- `core` — Always installed (chezmoi, mise, git, shell tools)
+- `dev` — Development tools (neovim, ripgrep, fd, etc.)
+- `dev_build` — Build dependencies
+- `infra` — Infrastructure tools (terraform, kubectl, helm)
+- `security` — Security scanning tools
+- `embedded` — Arduino, serial tools
+- `services` — Local service dependencies
+- `media` — Media processing tools
+- `gui` — GUI applications (cask installs)
+
+## Consequences
+
+**Positive:**
+- Brewfile is now generated from a single source of truth
+- Easy to enable/disable feature sets by toggling profile flags
+- CI can install only `core` profile for faster smoke tests
+- New machine setup can be tailored to the machine's role
+
+**Negative:**
+- Adds complexity: changes now require editing `packages.toml` instead of `Brewfile` directly
+- Template rendering adds a step between editing and seeing the final Brewfile
+
+## Related
+
+- ADR-0002: Unified Tool Version Management with Mise (complementary system for runtime tools)
+- `docs/prds/project-overview.md` FR-005: Package management
diff --git a/docs/adrs/0015-gitleaks-secret-detection.md b/docs/adrs/0015-gitleaks-secret-detection.md
new file mode 100644
index 0000000..473b733
--- /dev/null
+++ b/docs/adrs/0015-gitleaks-secret-detection.md
@@ -0,0 +1,42 @@
+# ADR-0015: Gitleaks for Secret Detection
+
+**Date**: 2026-04-08
+**Status**: Accepted
+**Confidence**: High (direct evidence from commit history)
+
+## Context
+
+Secret detection was previously handled by `detect-secrets`, which maintains a `.secrets.baseline` file of known false positives. While effective, `detect-secrets` has significant drawbacks in this repository:
+
+- Slow on large repos — scans all content on each run
+- The baseline file requires ongoing maintenance as new "secrets" (false positives) are introduced
+- Poor integration with chezmoi template syntax (`.tmpl` files contain template variables that trigger false positives constantly)
+- Python dependency that adds complexity to the pre-commit setup
+
+Commit evidence: `chore: replace detect-secrets with gitleaks (#169)`
+
+## Decision
+
+Replace `detect-secrets` with `gitleaks` for secret detection:
+
+- `gitleaks` configured via `.gitleaks.toml` with custom rules and allowlists
+- Runs as a pre-commit hook via `gitleaks protect --staged`
+- Handles chezmoi template variables and known false positives via allowlist in `.gitleaks.toml`
+- Removes `.secrets.baseline` maintenance burden
+
+## Consequences
+
+**Positive:**
+- Faster scanning (Rust-based, designed for git repos)
+- Configuration via `.gitleaks.toml` is more readable than JSON baseline
+- Better support for chezmoi template allowlisting
+- No Python runtime dependency for secret scanning
+
+**Negative:**
+- Migration required allowlisting historical false positives in `.gitleaks.toml`
+- Team members must have gitleaks installed (managed via mise/Brewfile)
+
+## Related
+
+- ADR-0010: Tiered Test Execution (pre-commit is the first tier)
+- `docs/prds/project-overview.md` FR-007: Secret management
diff --git a/docs/adrs/0016-shell-completion-auto-generation.md b/docs/adrs/0016-shell-completion-auto-generation.md
new file mode 100644
index 0000000..629f2e1
--- /dev/null
+++ b/docs/adrs/0016-shell-completion-auto-generation.md
@@ -0,0 +1,43 @@
+# ADR-0016: Shell Completion Auto-Generation Pattern
+
+**Date**: 2026-04-08
+**Status**: Accepted
+**Confidence**: Medium (inferred from scripts and commit patterns)
+
+## Context
+
+Shell completions for CLI tools (Claude Code, uv, pip, docker, kubectl, etc.) need to stay in sync with the installed tool versions. Manually maintaining completion scripts is error-prone — completions become stale after tool upgrades, leading to missing or broken tab completion.
+
+The completion list is large (36+ tools in `.chezmoidata/completions.toml`) and grows with each new tool added to the environment.
+
+Commit evidence: `fix(completions): auto-regenerate claude completions on CLI update`, `feat(completions): update Claude CLI completions for v4.6`
+
+## Decision
+
+Auto-generate shell completions rather than version-controlling static completion files:
+
+- `.chezmoidata/completions.toml` — Registry of all tools with their completion commands (e.g., `uv generate-shell-completion zsh`)
+- Chezmoi template (`dot_zshrc.tmpl`) iterates the registry and sources completions dynamically
+- For tools without built-in completion commands (e.g., Claude Code), `scripts/generate-claude-completion.sh` generates from `--help` output and the result is committed as a managed chezmoi file
+- mise hook triggers Claude completion regeneration on Claude CLI version changes
+
+**Trade-offs considered:**
+- Fully dynamic (generate at shell startup): Too slow — 36 completions would noticeably delay shell start
+- Fully static (commit all completion files): Becomes stale; large diffs on tool updates
+- Chosen hybrid: Dynamic for tools with fast `generate-shell-completion` support; committed files for tools that lack it
+
+## Consequences
+
+**Positive:**
+- Completions stay current with tool versions automatically
+- Single registry to add new tools
+- Shell startup stays fast (completions are pre-generated, not runtime-computed)
+
+**Negative:**
+- Claude CLI completions require manual regeneration when Claude Code adds new subcommands
+- `generate-claude-completion.sh` is fragile (parses `--help` output)
+
+## Related
+
+- ADR-0002: Unified Tool Version Management with Mise
+- `docs/prds/project-overview.md` FR-002: Zsh shell configuration
diff --git a/docs/adr/README.md b/docs/adrs/README.md
similarity index 88%
rename from docs/adr/README.md
rename to docs/adrs/README.md
index 7b583f9..92ee698 100644
--- a/docs/adr/README.md
+++ b/docs/adrs/README.md
@@ -23,6 +23,9 @@ An ADR is a document that captures an important architectural decision made alon
 | [0011](0011-claude-rules-migration.md) | Claude Rules Migration | Accepted | 2025-12 |
 | [0012](0012-justfile-command-runner.md) | Justfile Command Runner | Accepted | 2025-12 |
 | [0013](0013-nixos-declarative-system-configuration.md) | NixOS Declarative System Configuration | Accepted | 2025-12 |
+| [0014](0014-profile-based-package-registry.md) | Profile-Based Package Registry | Accepted | 2026-04 |
+| [0015](0015-gitleaks-secret-detection.md) | Gitleaks for Secret Detection | Accepted | 2026-04 |
+| [0016](0016-shell-completion-auto-generation.md) | Shell Completion Auto-Generation Pattern | Accepted | 2026-04 |
 
 ## ADR Format
 
diff --git a/docs/blueprint/README.md b/docs/blueprint/README.md
new file mode 100644
index 0000000..5eb5075
--- /dev/null
+++ b/docs/blueprint/README.md
@@ -0,0 +1,29 @@
+# Blueprint Documentation
+
+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
+
+## Related Directories
+
+- `docs/prds/` — Product Requirements Documents
+- `docs/adrs/` — Architecture Decision Records
+- `docs/prps/` — Product Requirement Prompts
+- `.claude/rules/` — Generated and custom rules
+
+## Commands
+
+```bash
+/blueprint:status          # Check configuration and task health
+/blueprint:derive-prd      # Generate PRD from existing docs/codebase
+/blueprint:derive-plans    # Derive docs from git history
+/blueprint:derive-rules    # Generate rules from git patterns
+/blueprint:generate-rules  # Generate rules from PRDs
+/blueprint:adr-validate    # Validate ADR relationships
+/blueprint:sync-ids        # Assign IDs to documents
+/blueprint:execute         # Run next logical action
+```
diff --git a/docs/blueprint/manifest.json b/docs/blueprint/manifest.json
new file mode 100644
index 0000000..f747fe9
--- /dev/null
+++ b/docs/blueprint/manifest.json
@@ -0,0 +1,170 @@
+{
+  "format_version": "3.2.0",
+  "created_at": "2026-04-07T00:00:00Z",
+  "updated_at": "2026-04-08T00:00:00Z",
+  "created_by": {
+    "blueprint_plugin": "3.2.0"
+  },
+  "project": {
+    "name": "chezmoi",
+    "detected_stack": [
+      "zsh",
+      "lua",
+      "shell",
+      "mise",
+      "chezmoi",
+      "neovim"
+    ]
+  },
+  "structure": {
+    "has_prds": true,
+    "has_adrs": true,
+    "has_prps": true,
+    "has_work_orders": true,
+    "has_ai_docs": false,
+    "has_modular_rules": true,
+    "has_feature_tracker": false,
+    "has_document_detection": true,
+    "claude_md_mode": "both"
+  },
+  "generated": {
+    "rules": {},
+    "commands": {}
+  },
+  "custom_overrides": {
+    "skills": [],
+    "commands": []
+  },
+  "task_registry": {
+    "derive-prd": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-07T00:00:00Z",
+      "last_result": "success",
+      "schedule": "on-demand",
+      "stats": {
+        "runs_total": 1,
+        "items_created": 1
+      },
+      "context": {}
+    },
+    "derive-plans": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "weekly",
+      "stats": {
+        "runs_total": 1,
+        "items_processed": 200,
+        "items_created": 6
+      },
+      "context": {
+        "commits_analyzed_up_to": "afaec005957568bd34ddb0ffd2daa7b4a98a70c8",
+        "commits_analyzed_count": 200
+      }
+    },
+    "derive-rules": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "weekly",
+      "stats": {
+        "runs_total": 1,
+        "items_processed": 200,
+        "items_created": 2
+      },
+      "context": {
+        "commits_analyzed_up_to": "e21bb5b"
+      }
+    },
+    "generate-rules": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "on-change",
+      "stats": {},
+      "context": {}
+    },
+    "adr-validate": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "weekly",
+      "stats": {},
+      "context": {}
+    },
+    "feature-tracker-sync": {
+      "enabled": false,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "daily",
+      "stats": {},
+      "context": {}
+    },
+    "sync-ids": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "on-change",
+      "stats": {},
+      "context": {}
+    },
+    "claude-md": {
+      "enabled": true,
+      "auto_run": false,
+      "last_completed_at": "2026-04-08T00:00:00Z",
+      "last_result": "success",
+      "schedule": "on-change",
+      "stats": {
+        "runs_total": 1
+      },
+      "context": {}
+    },
+    "curate-docs": {
+      "enabled": false,
+      "auto_run": false,
+      "last_completed_at": null,
+      "last_result": null,
+      "schedule": "on-demand",
+      "stats": {},
+      "context": {}
+    }
+  },
+  "id_registry": {
+    "last_prd": 1,
+    "last_prp": 3,
+    "documents": {
+      "PRD-001": {
+        "path": "docs/prds/project-overview.md",
+        "title": "Dotfiles — Product Requirements Document",
+        "github_issues": [],
+        "created": "2026-04-07"
+      },
+      "PRP-001": {
+        "path": "docs/prps/fish-shell-migration.md",
+        "title": "Fish Shell Migration",
+        "github_issues": [],
+        "created": "2026-04-08"
+      },
+      "PRP-002": {
+        "path": "docs/prps/nixos-implementation.md",
+        "title": "NixOS Implementation",
+        "github_issues": [],
+        "created": "2026-04-08"
+      },
+      "PRP-003": {
+        "path": "docs/prps/sketchybar-integration.md",
+        "title": "Sketchybar macOS Integration",
+        "github_issues": [],
+        "created": "2026-04-08"
+      }
+    },
+    "github_issues": {}
+  }
+}
diff --git a/docs/prds/project-overview.md b/docs/prds/project-overview.md
new file mode 100644
index 0000000..ce6ed74
--- /dev/null
+++ b/docs/prds/project-overview.md
@@ -0,0 +1,166 @@
+---
+id: PRD-001
+created: 2026-04-07
+modified: 2026-04-07
+status: Draft
+version: "1.0"
+relates-to: []
+github-issues: []
+name: blueprint-derive-prd
+---
+
+# Dotfiles — Product Requirements Document
+
+## Executive Summary
+
+### Problem Statement
+Setting up a consistent, reproducible development environment across multiple machines (macOS, Linux) is time-consuming and error-prone without a managed dotfiles system. Manual configuration drifts over time, tool versions diverge, and context-specific settings (secrets, platform differences) are difficult to maintain securely.
+
+### Proposed Solution
+A chezmoi-managed dotfiles repository that declaratively configures the full development environment: shell (Zsh), editor (Neovim), CLI tools, package management (Homebrew + mise), and AI tooling (Claude Code + MCP servers). Templates handle cross-platform differences; secret files use the `private_` prefix; exact-match directories ensure no orphaned config files.
+
+### Business Impact
+- **Faster machine setup**: New machines fully configured via `chezmoi init && chezmoi apply` in minutes
+- **Consistency**: Identical tool versions, key bindings, editor settings, and shell behavior across all machines
+- **AI-augmented workflow**: Claude Code with plugins and MCP servers available consistently everywhere
+- **Security**: Secrets managed via `~/.api_tokens` (never committed); gitleaks scanning on every commit
+
+## Stakeholders & Personas
+
+### Stakeholder Matrix
+| Role | Name | Responsibility |
+|------|------|----------------|
+| Owner / Developer | Lauri Gates | All decisions, implementation, maintenance |
+
+### User Personas
+
+#### Primary: Developer (Lauri Gates)
+- **Description**: Software developer working across multiple macOS machines, occasionally Linux
+- **Needs**: Consistent Zsh environment, fast Neovim with LSP, reproducible tool versions, Claude Code with full plugin ecosystem
+- **Pain Points**: Re-configuring tools on new machines; config drift; manual MCP server setup; forgetting which Neovim plugins are in use
+- **Goals**: `chezmoi apply` fully restores the expected environment; AI tooling works out of the box on any machine
+
+## Functional Requirements
+
+### Core Features
+
+| ID | Feature | Description | Priority |
+|----|---------|-------------|----------|
+| FR-001 | Chezmoi dotfile management | Source-controlled dotfiles applied via `chezmoi apply`; templates for cross-platform differences | P0 |
+| FR-002 | Zsh shell configuration | Starship prompt, FZF integration, syntax highlighting, autosuggestions, vi-mode, completions | P0 |
+| FR-003 | Neovim configuration | Lua-based config with lazy.nvim, Treesitter, LSP, completion (blink.cmp), formatters, linters | P0 |
+| FR-004 | Tool version management | mise manages Node, Python, Go, Rust, Bun and CLI tools via pipx/aqua backends | P0 |
+| FR-005 | Package management | Homebrew Brewfile with profile-based package selection (core, dev, infra, gui) | P0 |
+| FR-006 | Claude Code integration | Plugins from laurigates/claude-plugins; MCP server registry in `.chezmoidata.toml`; per-project `.mcp.json` | P1 |
+| FR-007 | Secret management | API tokens in `~/.api_tokens` (sourced by mise); private files use `private_` prefix; gitleaks scanning | P0 |
+| FR-008 | Cross-platform templates | Chezmoi templates handle macOS/Linux differences for shell config, tool paths, platform-specific packages | P1 |
+| FR-009 | CI/CD pipeline | Smoke tests (Ubuntu/macOS), linting (shellcheck, luacheck, actionlint, stylua), secret scanning | P1 |
+| FR-010 | AI-assisted development | Claude Code claude.yml workflow for AI-assisted PRs/issues; auto plugin install in CI | P2 |
+| FR-011 | MCP server management | Dynamic MCP config from `.chezmoidata.toml`; enable/disable servers; per-project overrides | P1 |
+| FR-012 | Task runner | justfile with standard recipes: apply, diff, lint, test, plugin management, tool updates | P1 |
+
+### User Stories
+
+- As a developer, I want `chezmoi apply` to fully configure a new machine so I can start working in under 10 minutes
+- As a developer, I want Neovim LSP to work for my primary languages (Lua, Python, Shell, Go) without manual setup
+- As a developer, I want Claude Code with all my plugins available on every machine without re-installing
+- As a developer, I want to enable/disable MCP servers in one config file that propagates everywhere
+- As a developer, I want my shell to have consistent key bindings, aliases, and completions across machines
+- As a developer, I want secrets kept out of git while still being accessible to tools that need them
+
+## Non-Functional Requirements
+
+### Performance
+- Shell startup time: < 500ms (measured by `time zsh -i -c exit`)
+- `chezmoi apply` idempotent: no changes on second run when environment is current
+- Neovim startup: < 200ms for daily use
+
+### 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`
+
+### Reliability
+- Smoke test CI validates setup on Ubuntu and macOS
+- Docker-based smoke test for isolated environment testing
+- Pre-commit hooks prevent broken commits (shellcheck, luacheck, actionlint)
+
+### Compatibility
+- **Primary**: macOS (darwin/arm64) — Apple Silicon
+- **Secondary**: Ubuntu/Debian Linux (CI, VMs)
+- **Future**: NixOS (ADR-0013 documents intent)
+
+## Technical Considerations
+
+### Architecture
+- **Chezmoi** as the single source of truth for all dotfiles
+- **Templates** (`.tmpl` suffix) for platform/arch-specific config
+- **exact_** prefix for directories where orphaned files should be removed (e.g., `exact_dot_claude/`)
+- **private_** prefix for secret/sensitive config files (chmod 600)
+- **mise** for all runtime tool versions; backends: `pipx:` for Python CLIs, `aqua:` for binaries
+- **Brewfile** with profile-based package selection via `.chezmoidata/profiles.toml`
+
+### Key Configuration Files
+- `.chezmoidata.toml` — MCP servers, uv_tools, platform data
+- `.chezmoidata/packages.toml` — Profile-based Homebrew package registry
+- `.chezmoidata/profiles.toml` — Profile activation flags
+- `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/` — Claude Code config (exact-match semantics)
+
+### Dependencies
+- chezmoi, mise, Homebrew (macOS), git
+- Neovim 0.9+, Lua 5.1+
+- Claude Code CLI (for AI-assisted development features)
+
+### Integration Points
+- GitHub (CI/CD, Claude Code workflows, issue/PR automation)
+- Claude Code plugin marketplace (laurigates/claude-plugins)
+- MCP servers: context7, sequential-thinking, pal, playwright, github
+
+## Success Metrics
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| New machine setup time | < 10 min | Manual timing |
+| Shell startup time | < 500ms | `time zsh -i -c exit` |
+| CI smoke test pass rate | 100% | GitHub Actions |
+| Pre-commit hook pass rate | 100% on main | Git log |
+
+## Scope
+
+### In Scope
+- Zsh shell configuration (prompts, plugins, completions, key bindings)
+- Neovim editor configuration (Lua, plugins, LSP, formatters)
+- Tool version management via mise
+- Package management via Homebrew
+- Claude Code configuration (plugins, skills, rules, MCP servers)
+- Git configuration (delta, conventional commits, pre-commit hooks)
+- CI/CD pipeline (smoke tests, linting, security scanning)
+- Cross-platform templates (macOS primary, Linux secondary)
+- Secret management patterns
+
+### Out of Scope
+- GUI application configuration (beyond Brewfile cask installs)
+- Windows/WSL support
+- NixOS full support (intent documented in ADR-0013, not yet implemented)
+- Team/organization rollout (solo project)
+
+## Timeline & Phases
+
+### Current Phase: Active Development
+Ongoing improvements across all areas: AI tooling expansion, new tool integrations, Claude Code plugin development, performance optimizations.
+
+### Roadmap
+| Phase | Focus | Status |
+|-------|-------|--------|
+| Foundation | Chezmoi, Zsh, Neovim, mise, Homebrew | Complete |
+| AI Integration | Claude Code, plugins, MCP servers, claude.yml | Active |
+| Blueprint | Blueprint development structure, PRDs, ADRs | Active |
+| NixOS | Declarative system configuration (ADR-0013) | Planned |
+
+---
+*Generated from existing documentation via /blueprint:derive-prd*
+*Review and update as project evolves*
diff --git a/docs/prps/fish-shell-migration.md b/docs/prps/fish-shell-migration.md
new file mode 100644
index 0000000..df06b45
--- /dev/null
+++ b/docs/prps/fish-shell-migration.md
@@ -0,0 +1,46 @@
+---
+id: PRP-001
+created: 2026-04-08
+modified: 2026-04-08
+status: Draft
+confidence: 6
+source: git history (private_dot_config/private_fish/ directory existence)
+relates-to: [PRD-001]
+---
+
+# Fish Shell Migration
+
+## Context
+
+An experimental Fish shell configuration exists in `private_dot_config/private_fish/` but Zsh remains the primary shell. Fish offers a better interactive experience out-of-the-box (better completions, syntax highlighting, autosuggestions without plugins), but migration requires porting Zsh-specific configuration.
+
+## Problem
+
+Zsh requires numerous plugins (syntax-highlighting, autosuggestions, vi-mode, fzf-tab) to match Fish's default interactive experience. Each plugin is an external dependency managed via `.chezmoiexternal.toml`. Fish provides these capabilities natively.
+
+## Proposed Approach
+
+1. **Audit Zsh → Fish feature parity**: Map all current Zsh functions, aliases, completions, and integrations to Fish equivalents
+2. **Port key functions**: `ghpc`, `serial-devices`, `serial-monitor`, FZF integration, mise activation, Starship integration
+3. **Handle compatibility**: Some tools (mise, Homebrew) have Fish-specific activation — verify all work
+4. **Dual-shell period**: Run Fish as interactive shell while keeping Zsh for scripting compatibility
+5. **Remove Zsh plugins**: Once feature-parity confirmed, remove external Zsh plugin dependencies from `.chezmoiexternal.toml`
+
+## Success Criteria
+
+- All current Zsh aliases and functions available in Fish
+- Shell startup time ≤ current Zsh baseline (< 500ms)
+- All tool completions (36+ from completions.toml) working
+- mise, Homebrew, FZF, Starship all integrated
+- CI smoke test validates Fish shell setup
+
+## Considerations
+
+- Fish is not POSIX-compatible — scripts must remain Zsh/bash
+- Some tools may have weaker Fish support than Zsh
+- Neovim terminal integration should be tested with Fish
+
+## Related
+
+- `docs/prds/project-overview.md` FR-002: Zsh shell configuration
+- `private_dot_config/private_fish/` — existing experimental config
diff --git a/docs/prps/nixos-implementation.md b/docs/prps/nixos-implementation.md
new file mode 100644
index 0000000..d5397de
--- /dev/null
+++ b/docs/prps/nixos-implementation.md
@@ -0,0 +1,47 @@
+---
+id: PRP-002
+created: 2026-04-08
+modified: 2026-04-08
+status: Draft
+confidence: 5
+source: ADR-0013 (NixOS Declarative System Configuration)
+relates-to: [PRD-001, ADR-0013]
+---
+
+# NixOS Implementation
+
+## Context
+
+ADR-0013 documents the intent to support NixOS as a secondary platform. NixOS offers declarative system configuration that complements chezmoi's dotfile management. The `nixos/` directory exists in the repository but implementation is incomplete.
+
+## Problem
+
+On NixOS, Homebrew is not available and mise has limitations (no system package management). Package installation requires Nix expressions. The current chezmoi templates don't handle NixOS-specific paths or package availability.
+
+## Proposed Approach
+
+1. **Audit NixOS compatibility**: Run chezmoi templates in NixOS environment and identify failures
+2. **Add NixOS detection**: Add `{{ if eq .chezmoi.os "linux" }}` guards for Homebrew-specific sections
+3. **Create home-manager config**: Use home-manager for user-level package management equivalent to Brewfile
+4. **Port Brewfile to home.packages**: Map Homebrew formulas to Nix package names for active profiles
+5. **Handle mise on NixOS**: Configure mise to work with Nix-managed system tools
+6. **CI validation**: Add NixOS container-based smoke test
+
+## Success Criteria
+
+- `chezmoi apply` runs without errors on NixOS
+- All core development tools available via Nix packages
+- Neovim, Zsh, and mise working correctly
+- CI smoke test on NixOS passes
+
+## Considerations
+
+- Nix package names differ from Homebrew formula names — mapping required
+- home-manager is a separate dependency to bootstrap
+- NixOS system-level config (`/etc/nixos/`) is outside chezmoi scope for now
+
+## Related
+
+- `docs/adrs/0013-nixos-declarative-system-configuration.md`
+- `docs/prds/project-overview.md` FR-008: Cross-platform templates
+- `nixos/` directory in repository root
diff --git a/docs/prps/sketchybar-integration.md b/docs/prps/sketchybar-integration.md
new file mode 100644
index 0000000..1405933
--- /dev/null
+++ b/docs/prps/sketchybar-integration.md
@@ -0,0 +1,44 @@
+---
+id: PRP-003
+created: 2026-04-08
+modified: 2026-04-08
+status: Draft
+confidence: 6
+source: git history (sketchybar scope: 5 commits in last 200)
+relates-to: [PRD-001]
+---
+
+# Sketchybar macOS Integration
+
+## Context
+
+Sketchybar is a highly customizable macOS menu bar replacement. The dotfiles include Sketchybar configuration (committed changes in `sketchybar` scope), including a GitHub repos plugin showing PR/issue counts. However, the integration is not fully documented and some components have been removed (k8s plugin, yabai click handler).
+
+## Problem
+
+Sketchybar configuration is present but:
+- Not documented in README or docs/
+- Depends on yabai (tiling WM) for some features that were removed
+- GitHub plugin requires a token — integration with `~/.api_tokens` not verified
+- No smoke test validates Sketchybar config
+
+## Proposed Approach
+
+1. **Document current state**: Audit what plugins/widgets are active and their dependencies
+2. **Verify GitHub token integration**: Ensure the GitHub repos plugin reads from `~/.api_tokens` (never hardcoded)
+3. **Create Sketchybar ADR**: Document the decision to use Sketchybar vs. alternatives (Raycast bar, default menu bar)
+4. **Add to README**: Document Sketchybar as optional macOS-only component
+5. **Consider yabai reintegration**: Decide whether to add yabai back or keep Sketchybar standalone
+6. **Brewfile integration**: Ensure Sketchybar is in the `gui` profile with correct dependencies
+
+## Success Criteria
+
+- Sketchybar config applies cleanly via `chezmoi apply`
+- GitHub plugin displays PR/issue counts using `~/.api_tokens` token
+- Configuration documented in README as macOS-only optional component
+- Separate ADR for Sketchybar architectural decision
+
+## Related
+
+- `docs/prds/project-overview.md` FR-005: Package management (gui profile)
+- `docs/adrs/0013-nixos-declarative-system-configuration.md` (macOS vs. Linux scope)
diff --git a/exact_dot_claude/rules/chezmoi-conventions.md b/exact_dot_claude/rules/chezmoi-conventions.md
new file mode 100644
index 0000000..5c46fa7
--- /dev/null
+++ b/exact_dot_claude/rules/chezmoi-conventions.md
@@ -0,0 +1,46 @@
+# Chezmoi Conventions
+
+Derived from git history patterns (1404 commits, 2018–2026).
+
+## File Naming Prefixes
+
+| Prefix | Meaning | Example |
+|--------|---------|---------|
+| `dot_` | Creates `.filename` target | `dot_zshrc.tmpl` → `~/.zshrc` |
+| `private_` | Mode 0600 (owner-only) | `private_dot_config/` |
+| `exact_` | Remove orphaned files in directory | `exact_dot_claude/` |
+| `.tmpl` suffix | Chezmoi template with Go text/template syntax | `dot_zshrc.tmpl` |
+
+## Template Conventions
+
+- Use `{{ .chezmoi.os }}` for platform branching, not runtime detection
+- Use `.chezmoidata.toml` and `.chezmoidata/` for structured template data
+- Keep templates readable: extract complex logic to helper templates or scripts
+- Template variables for lists (packages, completions, MCP servers) go in `.chezmoidata/`
+
+## Directory Semantics
+
+- `exact_dot_claude/` — Orphaned files auto-removed on `chezmoi apply`; critical for keeping `.claude/` clean
+- `private_dot_config/` — Secret-adjacent configs; mode 0600
+- Never create a `.claude/` directory in the chezmoi source — it's gitignored and used as a runtime directory
+
+## Source vs Target
+
+- **Always edit** source files at `~/.local/share/chezmoi/`
+- **Never edit** target files directly (e.g., `~/.zshrc`)
+- After modifying `exact_dot_claude/rules/`, run `chezmoi apply --force ~/.claude`
+- Use `chezmoi diff` to preview changes before applying
+
+## Script Conventions
+
+- `run_onchange_*` scripts execute when their template hash changes
+- `run_once_*` scripts execute only on first apply
+- Scripts should be idempotent — safe to re-run
+
+## Deprecation Patterns
+
+From commit history: promptly replace deprecated tools and APIs:
+- `docker-compose` → `docker compose` (CLI v2)
+- `vim.loop` → `vim.uv` (Neovim API)
+- `detect-secrets` → `gitleaks` (secret scanning)
+- `curl|sh` → setup actions (CI security)
diff --git a/exact_dot_claude/rules/dependency-management.md b/exact_dot_claude/rules/dependency-management.md
new file mode 100644
index 0000000..13b3d76
--- /dev/null
+++ b/exact_dot_claude/rules/dependency-management.md
@@ -0,0 +1,38 @@
+# Dependency Management
+
+Derived from git history patterns (tooling decisions across 1404 commits).
+
+## Tool Installation Priority
+
+1. **mise** with appropriate backend:
+   - Core runtimes: `python`, `node`, `go`, `rust`, `bun`
+   - Python CLIs: `pipx:` backend (runs via uvx)
+   - Standalone binaries: `aqua:` backend (checksum verification)
+2. **uv tool install** — Python tools as isolated packages
+3. **bun install -g** — JavaScript/TypeScript global packages
+4. **cargo install** / **go install** — When not available via aqua
+5. **brew install** — Last resort for CLI tools; primary for system packages and GUI apps
+
+## Homebrew Package Profiles
+
+Packages are managed through `.chezmoidata/packages.toml` with profile activation in `.chezmoidata/profiles.toml`:
+
+- `core` — Always installed
+- `dev` — Development tools (default: enabled)
+- `infra` — Infrastructure tools (terraform, kubectl, helm)
+- `gui` — GUI applications (cask installs)
+- Enable/disable profiles by toggling flags in `profiles.toml`
+
+## Upgrade Patterns
+
+- Replace deprecated tools promptly — don't maintain compatibility shims
+- When upgrading, remove the old tool entirely (no dual-install period)
+- Update CI workflows alongside local tooling
+- Prefer tools with native completion support over manual completion scripts
+
+## MCP Server Management
+
+- 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
diff --git a/exact_dot_claude/rules/development.md b/exact_dot_claude/rules/development.md
new file mode 100644
index 0000000..5d71d82
--- /dev/null
+++ b/exact_dot_claude/rules/development.md
@@ -0,0 +1,23 @@
+# Development Workflow
+
+## TDD Workflow
+
+Follow RED → GREEN → REFACTOR:
+1. Write a failing test
+2. Implement minimal code to pass
+3. Refactor while keeping tests green
+
+## Commit Conventions
+
+Use conventional commits: `type(scope): description`
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `style`
+
+Common scopes: `zsh`, `nvim`, `mise`, `chezmoi`, `claude`, `brew`, `scripts`
+
+## Chezmoi Workflow
+
+- Always edit source files in `~/.local/share/chezmoi/`, never target files directly
+- Run `chezmoi diff` before `chezmoi apply` to review changes
+- Use `chezmoi apply --dry-run` to preview without applying
+- After modifying `exact_dot_claude/rules/`, run `chezmoi apply -v ~/.claude` to sync
diff --git a/exact_dot_claude/rules/document-management.md b/exact_dot_claude/rules/document-management.md
new file mode 100644
index 0000000..456eda5
--- /dev/null
+++ b/exact_dot_claude/rules/document-management.md
@@ -0,0 +1,31 @@
+# Document Management
+
+## Decision Detection
+
+Watch for these patterns during conversations and prompt to create formal documents:
+
+**Architecture decisions** (→ create ADR in `docs/adrs/`):
+- Choosing between tools, approaches, or patterns
+- Deciding on configuration strategies
+- Selecting package managers or version managers
+- Making cross-platform compatibility choices
+
+**Feature requirements** (→ create/update PRD in `docs/prds/`):
+- Discussing new dotfiles features or capabilities
+- Defining desired shell behaviors or integrations
+- Planning new tool configurations
+
+**Implementation plans** (→ create PRP in `docs/prps/`):
+- Detailed plans for implementing a new tool setup
+- Migration strategies between tools
+- Complex configuration refactoring
+
+## Document Locations
+
+- PRDs: `docs/prds/` — what and why
+- ADRs: `docs/adrs/` — architecture decisions with context and trade-offs
+- PRPs: `docs/prps/` — how to implement
+
+## ADR Naming
+
+`docs/adrs/NNNN-kebab-case-title.md` — use next sequential number.
diff --git a/exact_dot_claude/rules/testing.md b/exact_dot_claude/rules/testing.md
new file mode 100644
index 0000000..8b646e9
--- /dev/null
+++ b/exact_dot_claude/rules/testing.md
@@ -0,0 +1,25 @@
+# Testing Requirements
+
+## Test Tiers
+
+| Tier | Command | When |
+|------|---------|------|
+| Lint | `mise run lint` or `just lint` | After every change |
+| Shell | `mise run lint:shell` | After modifying shell scripts |
+| 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 |
+
+## Linting Standards
+
+- Shell scripts: shellcheck with `.shellcheckrc` config
+- Lua (Neovim): luacheck with `.luacheckrc` config
+- GitHub Actions: actionlint
+- Lua formatting: stylua with `.stylua.toml`
+- Secrets: gitleaks with `.gitleaks.toml`
+- Pre-commit: `pre-commit run --all-files`
+
+## Coverage Expectations
+
+Shell scripts and config files — focus on linting compliance and smoke test passing rather than unit coverage.