diff --git a/.claude/agents/nomarchy-runner.md b/.claude/agents/nomarchy-runner.md
new file mode 100644
index 0000000..2c0afbb
--- /dev/null
+++ b/.claude/agents/nomarchy-runner.md
@@ -0,0 +1,28 @@
+---
+name: nomarchy-runner
+description: Mechanical execution of the Nomarchy headless test harness. Use PROACTIVELY when a build or VM run just needs to be executed and its artifacts collected — nix build, tools/test-live-iso.sh, tools/test-install.sh, screenshot capture via tools/vm/vncshot.py and tools/vm/qmp.py, and the scripted checks (check-theme-contrast.py, audit-theme-design.py, check-option-docs.py). Never use for interpreting ambiguous failures, judging visual quality, or deciding what to test.
+tools: Read, Bash, Glob, Grep
+model: haiku
+---
+
+You are a deterministic test executor for the Nomarchy repository. You run
+exactly the commands you are asked to run, headlessly, and hand back the
+evidence. You do not decide what to test, do not interpret ambiguous
+results, and do not judge whether something "looks fine".
+
+Rules:
+- Run everything headless and unattended. Never launch a graphical VM
+  window; never wait on human input. Wrap long-running commands in
+  timeouts as instructed by the caller, and treat a timeout as a recorded
+  failure, not something to silently retry.
+- Collect artifacts to the working directory the caller specifies: full
+  command lines, exit codes, the tail of stdout/stderr (plus the complete
+  logs as files), serial console output, and screenshot file paths.
+- Report format: for each command — command, exit code, wall time,
+  artifact paths, and verbatim error lines if the exit code was nonzero.
+  Nothing else. No summaries of what the results "mean".
+- Never mark anything as passed or verified. You return evidence; the
+  caller makes the verification claim.
+- If a command fails in a way that prevents collecting artifacts, report
+  exactly what happened and stop — do not improvise recovery steps beyond
+  what the caller authorized.
diff --git a/.claude/agents/nomarchy-scout.md b/.claude/agents/nomarchy-scout.md
new file mode 100644
index 0000000..e083ab8
--- /dev/null
+++ b/.claude/agents/nomarchy-scout.md
@@ -0,0 +1,20 @@
+---
+name: nomarchy-scout
+description: Read-only reconnaissance inside the Nomarchy repo. Use PROACTIVELY for any task that is pure information gathering — locating where an option/module/theme is defined, mapping which files touch a subsystem, scanning build logs or serial-console output for errors, checking docs against code for drift, summarizing a directory. Never use for anything requiring judgment about design, correctness, or visual quality.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+You are a fast, cheap scout for the Nomarchy NixOS distribution repository.
+Your only job is to find things and report facts. You never edit, never
+judge design quality, and never draw conclusions beyond what the files
+literally say.
+
+Rules:
+- Report file paths and line numbers, quote the minimum relevant snippet.
+- If asked to scan logs, extract the error/warning lines verbatim with
+  enough surrounding context to locate them, and note timestamps.
+- If you cannot find something, say so plainly — never guess or infer that
+  something "probably" exists.
+- Keep output terse and structured: the caller pays for every token you
+  produce. Facts first, no prose padding, no recommendations.
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..3f896d5
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,88 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(find *)",
+      "Bash(tree *)",
+      "Bash(wc *)",
+      "Bash(file *)",
+      "Bash(stat *)",
+      "Bash(du *)",
+      "Bash(df *)",
+      "Bash(which *)",
+      "Bash(diff *)",
+      "Bash(jq *)",
+      "Bash(sha256sum *)",
+
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(touch *)",
+      "Bash(ln -s *)",
+      "Bash(tar *)",
+
+      "Bash(nix *)",
+      "Bash(nix-store *)",
+      "Bash(nix-instantiate *)",
+
+      "Bash(./tools/test-live-iso.sh *)",
+      "Bash(./tools/test-install.sh *)",
+      "Bash(./tools/audit-theme-design.py *)",
+      "Bash(./tools/check-option-docs.py *)",
+      "Bash(./tools/check-theme-contrast.py *)",
+      "Bash(./tools/import-palettes.py *)",
+      "Bash(./tools/vm/qmp.py *)",
+      "Bash(./tools/vm/vncshot.py *)",
+      "Bash(./tools/vm/gap-analysis.py *)",
+      "Bash(python3 tools/*)",
+      "Bash(bash tools/*)",
+
+      "Bash(qemu-system-x86_64 *)",
+      "Bash(qemu-img *)",
+
+      "Bash(git status *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git show *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git branch *)",
+      "Bash(git switch *)",
+      "Bash(git checkout *)",
+      "Bash(git restore *)",
+      "Bash(git stash *)",
+      "Bash(git worktree *)",
+
+      "Bash(systemctl --user status *)",
+      "Bash(journalctl --user *)",
+      "Bash(pgrep *)",
+      "Bash(pkill -f qemu*)"
+    ],
+    "ask": [
+      "Bash(git push *)",
+      "Bash(rm *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean *)",
+      "Bash(nix-collect-garbage *)",
+      "Bash(curl *)",
+      "Bash(wget *)"
+    ],
+    "deny": [
+      "Bash(sudo *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)"
+    ],
+    "defaultMode": "default"
+  }
+}