configs-all 1.0.0

package/docs/plans/2026-03-01-ai-stack-split-architecture.md

@@ -0,0 +1,72 @@
+# AI Stack Split Architecture — wolfe-server + mikpc
+
+_Status: COMPLETED_
+_LastCompletedStep: 6_
+_TotalSteps: 6_
+_Created: 2026-03-01_
+_Completed: 2026-03-01_
+_Summary: Split AI stack across wolfe-server (web UIs) and mikpc (GPU compute). All 8 services + Ollama running and verified. Cross-machine networking via LAN IP (Tailscale ACL blocks tag:wolfe). Five *.wolfe.family domains live._
+
+## Goal
+Split AI stack across two machines:
+- **wolfe-server** (home server): Web UIs + non-GPU services — leverages existing Caddy, Tailscale, systemd, unpack.sh
+- **mikpc** (RTX 5090): GPU compute only — Ollama, ComfyUI, ACE-Step, Speaches
+
+## Architecture
+```
+wolfe-server (services via *.wolfe.family):
+  chat.wolfe.family    → Open WebUI :3000
+  search.wolfe.family  → Perplexica :3002
+  n8n.wolfe.family     → n8n :5678
+  images.wolfe.family  → proxy to mikpc:8188 (ComfyUI)
+  music.wolfe.family   → proxy to mikpc:7860 (ACE-Step)
+  SearXNG :4000 (internal, no domain)
+  Qdrant :6333 (internal, no domain)
+  Postgres (internal, n8n backend)
+
+mikpc (compute-only, no web exposure):
+  Ollama :11434 (systemd, not Docker)
+  ComfyUI :8188 (GPU)
+  ACE-Step :7860 (GPU)
+  Speaches :8000 (GPU)
+```
+
+## Steps
+
+### Step 1: Create wolfe-server service directories
+Create 5 service directories in wolfe-server repo following the established pattern.
+Verify: `ls services/{open-webui,searxng,perplexica,n8n,qdrant}/docker-compose.yml`
+
+### Step 2: Update Caddyfile
+Add 5 new domain entries: chat, search, n8n (local), images, music (proxy to mikpc).
+Verify: `grep -c 'wolfe.family' services/caddy/Caddyfile` shows increased count
+
+### Step 3: Update unpack.sh
+Add SearXNG config file handling (settings.yml, limiter.toml).
+Verify: `grep -c 'searxng' scripts/system/unpack.sh` shows handling exists
+
+### Step 4: Update mikpc compose to compute-only
+Remove non-GPU services, keep ComfyUI, ACE-Step, Speaches.
+Verify: File contains only 3 services
+
+### Step 5: Commit, push, deploy
+- Commit + push wolfe-server
+- Commit + push configs repo
+- SSH to wolfe-server: git pull + unpack.sh
+- SSH to mikpc: redeploy compute-only stack
+Verify: All containers running on both machines
+
+### Step 6: Verify networking and configure services
+- All wolfe-server services connect to mikpc GPU services
+- Perplexica configured with Ollama via API
+- All *.wolfe.family domains resolve
+- End-to-end chat flow works
+Verify: Health checks pass on all services
+
+## Risks
+- Port proxy on mikpc must be active for cross-machine connections
+- Perplexica config resets on container restart (mitigated by configure.sh)
+- Caddy needs Cloudflare DNS for wildcard TLS (already working)
+
+## Execution Journal
+(appended after each step)

package/docs/plans/2026-03-02-ai-stack-expansion.md

@@ -0,0 +1,33 @@
+# AI Stack Expansion: wolfe-server 3060 GPU + New Services
+
+_Status: COMPLETED_
+_LastCompletedStep: 10_
+_TotalSteps: 10_
+_Created: 2026-03-02_
+_Completed: 2026-03-02_
+_Summary: Expanded wolfe-server AI stack with 5 new GPU/CPU services on RTX 3060. Moved Speaches from mikpc to wolfe-server. Added Ollama 7B, Wyoming OpenAI (HA voice), Paperless-ngx, Stirling-PDF. Automated WSL port proxy on mikpc. Cross-machine networking remains broken (Tailscale ACL + LAN issue)._
+
+## Steps Completed
+
+1. Automate fix-ai-proxy on mikpc — systemd service + deploy script integration
+2. Add Speaches to wolfe-server (GPU) — Whisper STT + Kokoro TTS
+3. Add Ollama to wolfe-server (GPU, Docker) — qwen2.5:7b + nomic-embed-text
+4. Add Wyoming OpenAI bridge for HA voice — Speaches → Wyoming protocol
+5. Add Paperless-ngx — Document management with OCR, Postgres+Valkey
+6. Add Stirling-PDF — CPU-only PDF toolkit
+7. Update Caddyfile — paperless.wolfe.family, pdf.wolfe.family
+8. Migrate Speaches references — Open WebUI .env → local host.docker.internal
+9. Remove Speaches from mikpc — docker-compose, fix-ai-proxy.sh, deploy script
+10. Deploy and verify everything — both repos committed, pushed, deployed, verified
+
+## Issues Resolved During Execution
+
+- **wyoming-openai crash**: Speaches v0.8+ removed `/v1/audio/speech/voices`. Fix: set TTS_VOICES env explicitly
+- **Ollama DNS**: Docker internal DNS fails (stub resolver). Fix: explicit dns config in compose
+- **Ollama healthcheck**: Image has no curl/wget. Fix: use `ollama list` command
+- **Open WebUI Ollama URL**: Pointed to unreachable mikpc. Fix: use local host.docker.internal
+
+## Outstanding Issues
+
+- **Cross-machine networking**: wolfe-server cannot reach mikpc via Tailscale (ACL) or LAN (route unreachable). Image gen disabled in Open WebUI until fixed.
+- **HA voice pipeline**: Wyoming OpenAI running, but HA integrations (Wyoming + Ollama conversation agent) need to be added via HA UI manually.

package/docs/plans/2026-03-02-merge-commands-design.md

@@ -0,0 +1,58 @@
+# Design: /merge and /merge-all Slash Commands
+
+_Date: 2026-03-02_
+_Status: APPROVED_
+
+## Problem
+
+No single command to autonomously review a PR, fix issues, and merge it. Currently requires chaining `/review-pr` + manual fixes + `/ship-prod`. Need `/merge` for single PRs and `/merge-all` for batch processing.
+
+## Decisions
+
+- **Merge strategy:** Regular merge commits (`--merge`), never squash. Preserves full git history.
+- **Fix scope:** Full autonomous — check out branch, fix issues, push, re-review. Max 3 iterations.
+- **Branch cleanup:** Always delete remote branch after merge (`--delete-branch`).
+- **Parallelism (`/merge-all`):** Parallel review via subagents, sequential merge to avoid conflicts.
+- **Model:** Sonnet subagents for review+fix work. Opus orchestrates `/merge-all`.
+
+## `/merge` — Review, Fix & Merge PR
+
+**Input:** `$ARGUMENTS` — PR number, URL, or branch name. If omitted, finds PR for current branch, or most recent open PR.
+
+**Flow:**
+
+1. Load PR (resolve from args or auto-detect)
+2. Load project context (CLAUDE.md, docs/context, incidents, spikes)
+3. Review cycle (max 3 iterations):
+   - Fetch PR details + full diff
+   - Read all changed files in full context
+   - Deep review: correctness, security, types, error handling, conventions, testing, performance
+   - If issues: check out branch → fix → test → lint → commit → push → re-review
+   - If clean: proceed
+4. Pre-merge checks: CI passing, local tests, lint
+5. Confidence gate: 100% or stop
+6. Merge: `gh pr merge --merge --delete-branch`
+7. Report: PR URL, iterations, fixes applied, merge status
+
+## `/merge-all` — Review, Fix & Merge All Open PRs
+
+**Input:** `$ARGUMENTS` — optional filter. Default: all open PRs.
+
+**Flow:**
+
+1. List open PRs via `gh pr list`
+2. Phase 1 — Parallel: one Sonnet subagent per PR (review + fix)
+3. Phase 2 — Sequential merge (oldest first): re-check CI → `gh pr merge --merge --delete-branch`
+4. Skip PRs with conflicts or unresolvable issues
+5. Report: summary table per PR
+
+## Safety
+
+- Max 3 fix iterations per PR
+- Never force-merge past failing CI
+- If protected branch requires human reviews, report and skip
+- Merge oldest-first to minimize conflict cascading
+
+## Also Fixed
+
+- `/ship-prod`: Changed `--squash` to `--merge` for consistent history preservation

package/docs/plans/2026-03-02-merge-commands.md

@@ -0,0 +1,354 @@
+# /merge and /merge-all Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Create `/merge` (review, fix, merge one PR) and `/merge-all` (batch process all open PRs) slash commands.
+
+**Architecture:** Two standalone markdown command files. `/merge` is a self-contained Sonnet subagent flow. `/merge-all` orchestrates parallel Sonnet subagents (one per PR) then merges sequentially.
+
+**Tech Stack:** Claude Code slash commands (markdown), `gh` CLI, git
+
+---
+
+### Task 1: Create `/merge` command
+
+**Files:**
+- Create: `claude/commands/merge.md`
+
+**Step 1: Write the command file**
+
+Create `claude/commands/merge.md` with this exact content:
+
+```markdown
+## Merge PR — Review, Fix & Merge
+
+Autonomously review a PR, fix any issues found, and merge it. Combines deep code review with autonomous fix capability. Will not merge until 100% confident the PR is clean.
+
+### Input
+$ARGUMENTS - PR number, URL, or branch name. If omitted, finds PR for current branch, or the most recent open PR in the repo.
+
+### Instructions
+
+**Before delegating, gather project context:**
+1. Read `docs/context/` for the most recent context snapshot — extract Architecture, Conventions, Testing, and Gotchas sections
+2. Read the project CLAUDE.md if it exists — extract Conventions and Common Mistakes sections
+3. Read `docs/incidents/` for recent incidents — are any related to the files being changed?
+4. Read `docs/spikes/` for recent spikes — is this PR implementing a spiked approach?
+
+**Then delegate this task to a subagent using the Agent tool with `model: "sonnet"` and `subagent_type: "general-purpose"`.** Pass the full prompt below (with context injected) to the subagent and relay its result.
+
+### Subagent prompt
+
+You are an autonomous PR reviewer and fixer. Your job is to review PR `$ARGUMENTS`, fix any issues you find, and merge it — but ONLY when you are 100% confident it is clean.
+
+**Project Context:**
+[Inject Architecture, Conventions, Testing, Gotchas from docs/context if available]
+[Inject Conventions, Common Mistakes from project CLAUDE.md if available]
+[Inject any related incidents or spikes if relevant]
+If no project context is available, review against general best practices and note that project context was unavailable.
+
+#### Phase 1: Load the PR
+
+1. **Resolve the PR:**
+   - If `$ARGUMENTS` is a number or URL, use it directly
+   - If `$ARGUMENTS` is a branch name: `gh pr list --head $ARGUMENTS --json number --jq '.[0].number'`
+   - If `$ARGUMENTS` is empty:
+     - Try current branch: `gh pr list --head $(git branch --show-current) --json number --jq '.[0].number'`
+     - If no result: latest open PR: `gh pr list --state open --limit 1 --json number --jq '.[0].number'`
+   - If no PR found, stop: "No open PR found. Create one first with `/pr`."
+
+2. **Fetch PR details:**
+   ```bash
+   gh pr view $PR_NUMBER --json title,body,author,baseRefName,headRefName,additions,deletions,commits,reviewDecision
+   gh pr diff $PR_NUMBER
+   ```
+
+#### Phase 2: Review and Fix Loop (max 3 iterations)
+
+For each iteration:
+
+3. **Deep review** — read all changed files in full context (not just the diff):
+   - Read each modified file completely
+   - Check how changed functions/classes are used elsewhere
+   - Check if tests exist for the changed code
+
+4. **Review every change for:**
+   - **Correctness:** Logic errors, off-by-one, null/undefined, race conditions
+   - **Security:** Hardcoded secrets, injection vulnerabilities, XSS, OWASP top 10
+   - **Types:** Missing types, incorrect types, unsafe `any` (TypeScript)
+   - **Error handling:** Unhandled rejections, missing try/catch, bare exceptions
+   - **Project conventions:** Does the code follow established patterns? (Use project context)
+   - **Testing:** Are new features tested? Edge cases covered?
+   - **Performance:** N+1 queries, unnecessary re-renders, unbounded loops
+   - **Breaking changes:** API contracts, migrations, backwards compatibility
+
+5. **Check for anti-patterns:**
+   - Files that shouldn't be committed (`.env`, `node_modules`, build artifacts)
+   - Tests that test implementation instead of behavior
+   - Missing or inadequate PR description
+
+6. **If issues found — fix them:**
+   - Check out the PR branch: `gh pr checkout $PR_NUMBER`
+   - Fix all identified issues in the code
+   - Run the test suite to verify fixes don't break anything
+   - Run linter to verify code style
+   - Stage and commit fixes:
+     ```bash
+     git add <fixed files>
+     git commit -m "fix: address review feedback — <brief description>"
+     ```
+   - Push to the PR branch: `git push`
+   - **Loop back to step 3** for re-review (track iteration count)
+
+7. **If no issues found — proceed to Phase 3**
+
+#### Phase 3: Pre-Merge Verification
+
+8. **Run all checks in parallel:**
+   - `gh pr checks $PR_NUMBER` — all CI checks must be passing (wait up to 5 minutes for in-progress checks)
+   - Run full test suite locally — all must pass
+   - Run linter — zero errors
+   - Run build if applicable — must succeed
+
+9. **Confidence gate:**
+   - If ANY concern remains: **stop and report**. Do NOT merge.
+   - Only proceed if 100% confident this is merge-ready.
+   - Document what was checked and what gives confidence.
+
+10. **Check for merge blockers:**
+    - `gh pr view $PR_NUMBER --json reviewDecision,mergeStateStatus`
+    - If branch protection requires reviews from others, report: "This PR requires human review approval before it can be merged."
+    - If merge is blocked for any other reason, report the blocker and stop.
+
+#### Phase 4: Merge
+
+11. **Merge the PR:**
+    ```bash
+    gh pr merge $PR_NUMBER --merge --delete-branch
+    ```
+    - Verify: `gh pr view $PR_NUMBER --json state --jq '.state'` should return "MERGED"
+
+12. **Report:**
+    ```
+    ## Merge Report
+    - **PR:** #<number> — <title>
+    - **URL:** <pr_url>
+    - **Review iterations:** <count> (0 = clean on first review)
+    - **Fixes applied:** <list of fix commits, or "None">
+    - **CI checks:** all passing
+    - **Merge method:** merge (full history preserved)
+    - **Branch:** <branch> deleted
+    - **Status:** Successfully merged
+    ```
+
+### Critical Rules
+
+- **NEVER merge with failing CI checks.**
+- **NEVER skip the deep review.** Read every changed file in full.
+- **NEVER proceed past the confidence gate with concerns.**
+- **Max 3 fix iterations.** If still not clean after 3 rounds, stop and report remaining issues.
+- **If in doubt, stop and report.** A delayed merge is always better than merging bad code.
+```
+
+**Step 2: Verify the file exists and looks correct**
+
+Run: `head -5 claude/commands/merge.md`
+Expected: The header lines of the new command.
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/merge.md
+git commit -m "feat: add /merge command — autonomous PR review, fix & merge"
+```
+
+---
+
+### Task 2: Create `/merge-all` command
+
+**Files:**
+- Create: `claude/commands/merge-all.md`
+
+**Step 1: Write the command file**
+
+Create `claude/commands/merge-all.md` with this exact content:
+
+```markdown
+## Merge All PRs — Batch Review, Fix & Merge
+
+Autonomously review, fix, and merge all open PRs. Dispatches parallel subagents to review each PR simultaneously, then merges sequentially (oldest first) to avoid conflicts.
+
+### Input
+$ARGUMENTS - optional filter flags passed to `gh pr list` (e.g., `--author @me`, `--label ready-to-merge`). Default: all open PRs.
+
+### Instructions
+
+**Do NOT delegate this command to a subagent.** This is an orchestration command — Opus runs it directly and dispatches subagents for each PR.
+
+**Before starting, gather project context:**
+1. Read `docs/context/` for the most recent context snapshot — extract Architecture, Conventions, Testing, and Gotchas sections
+2. Read the project CLAUDE.md if it exists — extract Conventions and Common Mistakes sections
+3. Read `docs/incidents/` for recent incidents
+4. Read `docs/spikes/` for recent spikes
+
+#### Phase 1: Discover PRs
+
+1. **List all open PRs:**
+   ```bash
+   gh pr list --state open $ARGUMENTS --json number,title,headRefName,baseRefName,author,createdAt --jq 'sort_by(.number)'
+   ```
+
+2. **If zero PRs:** Report "No open PRs found." and stop.
+
+3. **Report what was found:**
+   ```
+   Found N open PRs:
+   - #1 — title (branch → base)
+   - #2 — title (branch → base)
+   ...
+   ```
+
+#### Phase 2: Parallel Review
+
+4. **Dispatch one Sonnet subagent per PR** using the Agent tool with `model: "sonnet"` and `subagent_type: "general-purpose"`. Launch ALL subagents in a single message (parallel).
+
+   Each subagent gets the same prompt as the `/merge` command's subagent prompt (Phases 1-2 only: load + review/fix loop), but with a modified ending:
+
+   **Instead of merging**, the subagent should:
+   - Complete the review and fix loop (max 3 iterations)
+   - Run pre-merge verification (CI checks, tests, lint)
+   - Report back with:
+     ```
+     PR #<number>: READY | NOT READY | NEEDS HUMAN REVIEW
+     - Review iterations: <count>
+     - Fixes applied: <list or "None">
+     - CI status: passing | failing | pending
+     - Blockers: <list or "None">
+     ```
+
+   **Inject the project context** (gathered above) into each subagent prompt.
+
+5. **Collect all subagent results.** Wait for all to complete.
+
+#### Phase 3: Sequential Merge
+
+6. **For each PR marked READY** (process in order of PR number, oldest first):
+
+   a. **Re-check CI status** (fixes may have triggered new CI runs):
+      ```bash
+      gh pr checks $PR_NUMBER
+      ```
+      If checks are still running, wait up to 5 minutes.
+
+   b. **Check for merge conflicts** (earlier merges may have created conflicts):
+      ```bash
+      gh pr view $PR_NUMBER --json mergeable --jq '.mergeable'
+      ```
+      If `CONFLICTING`, skip this PR and note it in the report.
+
+   c. **Merge:**
+      ```bash
+      gh pr merge $PR_NUMBER --merge --delete-branch
+      ```
+
+   d. **Verify:** `gh pr view $PR_NUMBER --json state --jq '.state'` should return "MERGED"
+
+7. **For PRs marked NOT READY or NEEDS HUMAN REVIEW:** Skip and include in report.
+
+#### Phase 4: Report
+
+8. **Generate summary report:**
+   ```
+   ## Merge All Report
+
+   ### Successfully Merged
+   | PR | Title | Iterations | Fixes | Status |
+   |----|-------|-----------|-------|--------|
+   | #1 | title | 0 | None | Merged |
+   | #3 | title | 2 | fix: ... | Merged |
+
+   ### Skipped
+   | PR | Title | Reason |
+   |----|-------|--------|
+   | #2 | title | Merge conflict after #1 merged |
+   | #4 | title | Requires human review approval |
+   | #5 | title | 3 fix iterations exhausted — issues remain |
+
+   ### Summary
+   - **Total PRs:** N
+   - **Merged:** N
+   - **Skipped:** N
+   - **Action needed:** [list any PRs that need manual attention]
+   ```
+
+### Critical Rules
+
+- **NEVER merge a PR that isn't READY.**
+- **Merge oldest first** to minimize conflict cascading.
+- **If a merge creates conflicts in later PRs, skip them** — don't try to resolve cross-PR conflicts.
+- **Max 3 fix iterations per PR** — same as `/merge`.
+- **Report everything** — the user needs to know what was merged, what was skipped, and why.
+```
+
+**Step 2: Verify the file exists and looks correct**
+
+Run: `head -5 claude/commands/merge-all.md`
+Expected: The header lines of the new command.
+
+**Step 3: Commit**
+
+```bash
+git add claude/commands/merge-all.md
+git commit -m "feat: add /merge-all command — batch review, fix & merge all open PRs"
+```
+
+---
+
+### Task 3: Commit the ship-prod fix and design doc
+
+**Files:**
+- Modified: `claude/commands/ship-prod.md` (already edited — squash → merge)
+- Created: `docs/plans/2026-03-02-merge-commands-design.md`
+
+**Step 1: Commit both changes**
+
+```bash
+git add claude/commands/ship-prod.md docs/plans/2026-03-02-merge-commands-design.md
+git commit -m "fix: use merge commits instead of squash in ship-prod, add merge commands design"
+```
+
+---
+
+### Task 4: Update project CLAUDE.md command documentation
+
+**Files:**
+- Modify: `CLAUDE.md` (project-level, in repo root)
+
+**Step 1: Add /merge and /merge-all to the command list in the Claude Code Command Suite section of MEMORY.md or CLAUDE.md**
+
+Add to the Action layer line in the relevant documentation:
+- `/merge` — Review, fix & merge a single PR
+- `/merge-all` — Batch review, fix & merge all open PRs
+
+**Step 2: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: add /merge and /merge-all to command documentation"
+```
+
+---
+
+### Task 5: Deploy and verify
+
+**Step 1: Deploy configs**
+
+Run: `./scripts/sync/push-configs.zsh`
+Expected: Commands deployed without errors.
+
+**Step 2: Verify commands are available**
+
+Run: `ls ~/.claude/commands/merge*.md`
+Expected: Both `merge.md` and `merge-all.md` present.
+
+**Step 3: Mark plan as COMPLETED**

package/docs/research/2026-03-02-configs-repo-architecture.md

@@ -0,0 +1,152 @@
+# Configs Repo Architecture — Deep Research
+
+_Date: 2026-03-02_
+_Scope: Full repo architecture, sync system, shell config, Claude Code setup, Docker/AI stack_
+
+## Overview
+
+Centralized config management across 4 machines (mikmac, mikbook, duplo, mikpc) with cross-platform macOS/Windows(WSL) support. Git is the sync mechanism — each machine has its own independent clone. Dropbox paths differ per machine.
+
+## Architecture
+
+### Config Sync System (`scripts/sync/`)
+
+The core of the repo. Three files form the sync engine:
+
+**config-common.zsh** — Shared infrastructure:
+- Platform detection (`IS_MAC`/`IS_WINDOWS`/`IS_WSL`)
+- Hostname-based CONFIG_DIR resolution (4 machines, PWD-based fallback on Windows)
+- `get_config_dest()` — 50+ file mappings (source → destination per platform/host)
+- `get_validation_func()` — Maps files to validators (json→jq, yaml→yq, plist→plutil, shell→zsh -n)
+- `safe_copy()` — Validate → backup (timestamped, 5 max) → copy. Returns 0 on error for graceful continuation.
+- Platform transformations: MCP configs (Mac→Windows path/command transforms), Cursor settings (strip Mac-only keys)
+
+**push-configs.zsh** — Deploy repo → system:
+- Iterates all config files, applies platform guards and host-specific routing
+- Special handling: Claude dirs (commands/templates/scripts with stale cleanup), MCP merge into .claude.json (preserves OAuth/state), Windows dual-deploy (WSL + native paths)
+- Zsh theme discovery, IDE extension reporting
+
+**pull-configs.zsh** — Backup system → repo:
+- Reverse of push, with key restriction: never pulls Cursor/MCP configs on Windows (Mac is source of truth)
+- MCP pull extracts mcpServers from .claude.json, replaces CONFIG_DIR with `__CONFIG_DIR__` placeholder
+- Splits host-specific MCP servers to separate files
+
+### Machine Registry
+
+| Machine | CONFIG_DIR | Git Config | SSH Config | Notes |
+|---------|-----------|-----------|-----------|-------|
+| mikmac | `~/Dropbox/dev/configs` | personal | config | Mac Studio, primary dev |
+| mikbook | `~/Dropbox/mikbook/dev/configs` | personal | config | MacBook |
+| duplo | `~/Dropbox/duplo/dev/chiefmikey/configs` | work | config.duplo | Work Mac, has alias-d.zsh |
+| mikpc | `~/Dropbox/mikpc/dev/configs` | personal | config.mikpc | WSL, NTFS quirks, dual-deploy |
+
+### Shell System (`shell/`)
+
+**Load order** (.zshrc entry point):
+1. `variables.zsh` — Platform detection, Homebrew, paths, SSH agent, Node memory
+2. `options.zsh` — History (100K), AUTO_CD, RM_STAR_WAIT, completion behavior
+3. `completion.zsh` — Docker completions, 24h compinit cache, zstyle (menu, case-insensitive)
+4. `keybindings.zsh` — Vim-style history search, word boundaries (`WORDCHARS='_-'`)
+5. `plugins.zsh` — p10k, fzf, zoxide, bat, autosuggestions, syntax-highlighting (Homebrew→ohmy→/usr/share fallback)
+6. `functions.zsh` — Hash dirs (~dev, ~configs), directory stack, precmd title, direnv
+7. `alias.zsh` — Dispatcher loading 8 category files + conditional duplo aliases
+
+**Alias categories** (100+ total aliases):
+- `system.zsh` — Navigation (dev, configs, scripts), editors, sync, upgrade, Docker cleanup
+- `git.zsh` — gs, push, goop, mm/mms/md, pullr/pullm, pushf, sync workflows
+- `development.zsh` — Claude (c, cr, cs), Node (n, nl, nvm lazy-load), Python (py, envy), Ollama AI (ai, aic, air), QMK keyboard
+- `network.zsh` — SSH/mosh/scp aliases for all machines + Raspberry Pi + CloudRock
+- `github-functions.zsh` — gh-update-prs (interactive PR management), gh-tags (release management)
+- `wolfe-server.zsh` — Plex media rsync
+- `environment.zsh` — Secrets loading, ASKPASS
+- `path.zsh` — PATH ordering (Homebrew→GNU→Java→pyenv→dotnet)
+
+**Duplo-only** (`alias-d.zsh`): AWS JIT access (jaws), deployment (duplo-deploy), RDP/SSM sessions, bulk Windows Update automation, Kubernetes/Terraform
+
+**PowerShell** (`powershell/`): Windows native GPU/game debugging (gpu-info, crash-logs, debug-summary)
+
+### Claude Code Config (`claude/`)
+
+**Permission model**: `bypassPermissions` + deny list (25 blocked commands). Only deny rules work reliably in bypass mode.
+
+**Hooks**: Post-tool-use auto-formatting (Prettier for TS/JS/JSON/CSS, Ruff for Python)
+
+**Statusline**: Custom script showing model, user@host, git branch, context %, cache %, tokens, duration, cost, lines changed
+
+**Command suite** (38 slash commands):
+- Orchestration: `/partymode` (full autopilot), `/prep` (research+context+plan), `/go` (execute plans)
+- Documentation: `/research`, `/context`, `/plans`, `/spike`, `/incident`, `/handoff`, `/retro`
+- Action: `/fix-and-test`, `/review`, `/review-pr`, `/guard`, `/ship`, `/ship-prod`
+- Utility: `/morning`, `/dash`, `/sync`, `/push-sync`, `/commit`, `/push`, `/pr`
+- Machine-specific: `/mikpc`, `/duplo`, `/games`
+
+**Key design patterns**:
+- Plans track `_LastCompletedStep_` for resumability
+- Status markers (`PENDING`/`IN PROGRESS`/`COMPLETED`) for agent awareness
+- All doc-consuming commands verify staleness against git log
+- Subagent delegation with model selection (Haiku for mechanical, Sonnet for reasoning)
+
+**MCP servers**: 10 on Mac (GitHub, Docker, memory, context7, MongoDB, Playwright, Terraform, Notion, AWS, Kubernetes), host-specific additions via `mcp-servers.{HOST}.json`
+
+### Docker & AI Stack (`docker/`, `scripts/ai/`)
+
+**AI compute on mikpc** (RTX 5090):
+- Speaches :8000 (Whisper STT + Kokoro TTS)
+- ComfyUI :8188 (FLUX.1 image gen)
+- ACE-Step :7860 (music gen)
+- Ollama :11434 (systemd, not Docker)
+
+**Web UIs on wolfe-server** (separate repo):
+- Open WebUI :3003 (chat.wolfe.family)
+- Perplexica :3002 (search.wolfe.family)
+- n8n :5678 (n8n.wolfe.family)
+- SearXNG :4000 (internal)
+- Qdrant :6333 (internal)
+
+**Cross-machine**: LAN IP 192.168.0.5 (Tailscale ACL blocks tag:wolfe). WSL port proxy (`fix-ai-proxy.sh`) needed after restart.
+
+**Docker cleanup**: `docker-cleanup.sh` (smart, preserves running containers) + `docker-cleanup-manage.sh` (weekly cron)
+
+**MCP wrappers**: Cross-platform launcher pattern. Mac uses .sh, Windows uses .ps1. Dynamic CONFIG_DIR resolution with multi-machine fallbacks.
+
+## Patterns & Conventions
+
+1. **Graceful failures** — `set -uo pipefail` without `set -e`. safe_copy returns 0 on error.
+2. **Hostname-based routing** — CONFIG_DIR, git config, SSH config, alias loading all keyed on hostname.
+3. **Mac is source of truth** — Cursor/MCP never pulled from Windows. Windows gets transformed copies.
+4. **Backup rotation** — 5 timestamped backups per file, oldest auto-removed.
+5. **Validation before copy** — JSON/YAML/plist/shell syntax checked before deployment.
+6. **Stale file cleanup** — Claude commands/templates/scripts dirs remove files not in source.
+7. **MCP merge, not overwrite** — .claude.json mcpServers key updated, other keys preserved.
+8. **Platform guards** — IS_MAC/IS_WINDOWS booleans gate platform-specific logic.
+9. **CONFIG_DIR placeholder** — `__CONFIG_DIR__` in mcp-servers.json substituted at push time.
+10. **Lazy loading** — NVM only loaded when first invoked (shell startup performance).
+
+## Dependencies
+
+- **Required**: zsh, git, jq (JSON transforms)
+- **Recommended**: yq (YAML validation), plutil (plist, Mac-only), eza (ls replacement), fzf, zoxide, bat, glow
+- **Node tools**: nvm, npx (MCP servers)
+- **Python tools**: pyenv, uv/uvx (MCP servers)
+- **Mac-specific**: Homebrew, 1Password SSH agent
+- **Docker**: Docker CE on mikpc (with NVIDIA Container Toolkit), Docker Desktop on Mac
+
+## Gotchas
+
+1. duplo CONFIG_DIR is `chiefmikey/configs` not just `configs`
+2. Windows backups go to `~/.config/config-backups` (NTFS/Dropbox issues)
+3. WINDOWS_USER hardcoded to "wolfe"
+4. Port 3000 taken by AdGuard on wolfe-server — Open WebUI uses 3003
+5. WSL IP changes on restart — must run fix-ai-proxy.sh
+6. Perplexica config resets on restart — run configure.sh
+7. n8n data dirs need `chown 1000:1000`
+8. SCP broken on mikpc — use rsync
+9. Tailscale ACL blocks tag:wolfe from accessing other devices
+10. `docker compose up -d` doesn't recreate on .env changes — need `--force-recreate`
+
+## Open Questions
+
+- Should Tailscale ACL be fixed to allow tag:wolfe? Currently using LAN IP workaround.
+- Perplexica config persistence — could mount config volume instead of post-start script.
+- MCP registry.yaml and config.yaml/tools.yaml are empty — are these needed or auto-populated?
+- ~~`scripts/input/` was legacy dead code — removed 2026-03-02~~