docs: audit handbook + README, add beginner section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mcp-tool-shop

README.md

@@ -263,7 +263,7 @@ The core matching, merging, and validation modules are pure functions with no si
 | Threat | Mitigation |
 |--------|------------|
 | Malformed frontmatter input | `parseFrontmatter()` returns `null` on invalid input — no exceptions, no eval |
-| Prototype pollution | Hand-rolled parser uses plain object literals, no `JSON.parse` of untrusted nested structures |
+| Prototype pollution | Hand-rolled parser uses plain object literals, no recursive merge of untrusted input |
 | Index with bad data | `validateIndex()` catches structural issues before they propagate |
 | Regex DoS | No user-supplied regex — patterns are matched as plain string lookups |
 

site/src/content/docs/handbook/beginners.md

@@ -116,6 +116,8 @@ console.log("On-demand:", plan.onDemand.map(m => m.entry.id));
 console.log("Token cost:", plan.preloadTokens, "preload +", plan.onDemandTokens, "on-demand");
 ```
 
+`planLoad` calls the resolver behind the scenes, which looks for index files at four canonical paths: `~/.ai-loadout/index.json` (global), `$AI_LOADOUT_ORG` (org), `<cwd>/.claude/loadout/index.json` (project), and `$AI_LOADOUT_SESSION` (session). Missing layers are normal -- most setups only use the project layer. If no index is found anywhere, the plan returns empty arrays.
+
 ### 5. Validate your index
 
 ```bash
@@ -124,6 +126,38 @@ ai-loadout validate .claude/loadout/index.json
 
 This checks for structural issues: missing fields, duplicate IDs, non-kebab-case IDs, domain entries without keywords, summaries over 120 characters, and negative budget values.
 
+Add `--json` for machine-readable output:
+
+```bash
+ai-loadout validate .claude/loadout/index.json --json
+```
+
+You can also run `ai-loadout --help` to see all available commands, or `ai-loadout --version` to confirm which version is installed.
+
+### 6. Write a payload file with frontmatter
+
+Create the file referenced by your entry's `path` field. Include frontmatter so that the routing metadata lives with the content:
+
+```markdown
+---
+id: testing-rules
+keywords: [test, jest, vitest, coverage]
+patterns: [test_suite]
+priority: domain
+triggers:
+  task: true
+  plan: true
+  edit: false
+---
+
+# Testing Conventions
+
+All code must have tests. Minimum coverage: 80%.
+Use vitest for unit tests...
+```
+
+The frontmatter is the source of truth for routing. The index is derived from it. If they ever drift, `ai-loadout validate` catches the mismatch.
+
 ## Common Mistakes
 
 **Putting everything at `core` priority.** Core entries are always loaded regardless of the task. If you make everything core, you lose the benefit of on-demand routing. Reserve core for truly non-negotiable rules (3-5 entries max).

site/src/content/docs/handbook/concepts.md

@@ -45,7 +45,7 @@ The default is `{ task: true, plan: true, edit: false }`. These are advisory —
 
 ## Keyword Matching
 
-The matcher tokenizes the task description into lowercase words (stripping non-alphanumeric characters and filtering single-character tokens), then compares against each entry's `keywords` array:
+The matcher tokenizes the task description into lowercase words (replacing non-alphanumeric characters with spaces, splitting on whitespace, and filtering out single-character tokens), then compares against each entry's `keywords` array:
 
 1. For each keyword, split it on spaces/hyphens and check if all words are present in the task tokens
 2. Calculate **overlap proportion** = matched keywords / total entry keywords

site/src/content/docs/handbook/reference.md

@@ -23,7 +23,7 @@ const plan = planLoad("fix the CI workflow");
 interface LoadPlan {
   preload: MatchResult[];              // eager entries — load immediately
   onDemand: MatchResult[];             // lazy entries — load when needed
-  manual: LoadoutEntry[];              // never auto-loaded
+  manual: LoadoutEntry[];              // manual-priority entries + unmatched domain entries
   provenance: Record<string, string>;  // entryId → source layer
   budget: Budget;
   conflicts: MergeConflict[];
@@ -33,7 +33,7 @@ interface LoadPlan {
 }
 ```
 
-Resolves all layers (global → org → project → session), matches the task, and separates entries by load mode.
+Resolves all layers (global → org → project → session), matches the task, and separates entries by load mode. The `manual` array includes both entries with `manual` priority and any domain entries that did not match the current task (score below the 0.1 threshold).
 
 ---
 

site/src/site-config.ts

@@ -91,7 +91,7 @@ export const config: SiteConfig = {
       kind: 'api',
       id: 'api',
       title: 'API Reference',
-      subtitle: 'Six exports. That\'s it.',
+      subtitle: 'Clean exports for matching, resolving, and observability.',
       apis: [
         {
           name: 'matchLoadout(task, index)',