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

@@ -226,17 +226,26 @@ import type {
   Frontmatter,
   MatchResult,
   ValidationIssue,
-  Priority,       // "core" | "domain" | "manual"
-  Triggers,       // { task, plan, edit }
-  LoadMode,       // "eager" | "lazy" | "manual"
+  Priority,          // "core" | "domain" | "manual"
+  Triggers,          // { task, plan, edit }
+  LoadMode,          // "eager" | "lazy" | "manual"
   Budget,
   UsageEvent,
   MergeConflict,
   MergedIndex,
-  LoadPlan,
-  ResolvedLoadout,
-  EntryExplanation,
-  IssueSeverity,    // "error" | "warning"
+  LoadPlan,          // returned by planLoad()
+  ResolvedLoadout,   // returned by resolveLoadout()
+  EntryExplanation,  // returned by explainEntry()
+  IssueSeverity,     // "error" | "warning"
+  RuntimeOptions,    // options for planLoad / recordLoad / manualLookup
+  ResolveOptions,    // options for resolveLoadout / discoverLayers
+  UsageSummary,      // returned by summarizeUsage()
+  DeadEntry,         // returned by findDeadEntries()
+  KeywordOverlap,    // returned by findKeywordOverlaps()
+  BudgetBreakdown,   // returned by analyzeBudget()
+  DiscoveredLayer,   // a layer found and loaded by the resolver
+  SearchedLayer,     // a layer search location and its result
+  EntryDefinition,   // one layer's version of a specific entry
 } from "@mcptoolshop/ai-loadout";
 ```
 

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

@@ -130,7 +130,7 @@ This checks for structural issues: missing fields, duplicate IDs, non-kebab-case
 
 **Forgetting keywords on domain entries.** Domain entries with no keywords can never be matched by the matcher. The `validate` command catches this as an error (`EMPTY_KEYWORDS`).
 
-**Using regex in patterns.** The `patterns` field contains named intents like `"ci_pipeline"` -- they are matched as plain string lookups against the underscore-split words, not as regular expressions. A pattern of `"ci_pipeline"` matches a task containing the word "ci" or "pipeline."
+**Using regex in patterns.** The `patterns` field contains named intents like `"ci_pipeline"` -- they are not regular expressions. The matcher splits each pattern on `_` and checks if **any** of those words appear in the task. A pattern of `"ci_pipeline"` matches a task containing the word "ci" or "pipeline." A matching pattern adds a +0.2 bonus to the entry's score.
 
 **Huge payloads behind a single entry.** If one payload is 5,000 tokens and others are 200, the budget becomes misleading. Break large payloads into focused sub-topics with separate entries.
 

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

@@ -9,8 +9,11 @@ sidebar:
 
 A `LoadoutIndex` is the central data structure. It contains:
 
+- **version** — the schema version (currently `"1.0.0"`)
+- **generated** — ISO 8601 timestamp of when the index was generated
 - **entries** — an array of `LoadoutEntry` objects, each describing one knowledge payload
 - **budget** — token estimates for context planning
+- **lazyLoad** (optional) — when `true`, signals that payloads should not be pre-loaded by consumers
 
 The index is designed to be always-loaded alongside a lean instruction file. Payloads are loaded on demand when the matcher finds a hit.
 
@@ -42,12 +45,15 @@ The default is `{ task: true, plan: true, edit: false }`. These are advisory —
 
 ## Keyword Matching
 
-The matcher tokenizes the task description into lowercase words, then compares against each entry's `keywords` array:
+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:
 
-1. Calculate **overlap proportion** = matched keywords / total entry keywords
-2. Add **pattern bonus** (+0.2) if any entry pattern appears in the task
-3. Cap the score at 1.0
-4. Sort results by score descending, then by token cost ascending (lighter payloads first on ties)
+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
+3. For patterns, split each on `_` and check if **any** word appears in the task tokens
+4. Add **pattern bonus** (+0.2) if any entry pattern matched
+5. Cap the score at 1.0
+6. Exclude domain entries below the minimum score threshold (0.1)
+7. Sort results by score descending, then by token cost ascending (lighter payloads first on ties)
 
 ## The Budget Model
 

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

@@ -9,11 +9,11 @@ Welcome to the AI Loadout handbook. This is the complete guide to the Knowledge
 
 ## What's inside
 
+- **[Beginners Guide](/ai-loadout/handbook/beginners/)** — New to AI Loadout? Start here
 - **[Getting Started](/ai-loadout/handbook/getting-started/)** — Install and first use
 - **[Concepts](/ai-loadout/handbook/concepts/)** — Dispatch tables, priorities, resolver, runtime, and budgets
 - **[API Reference](/ai-loadout/handbook/reference/)** — Every export documented
 - **[Security](/ai-loadout/handbook/security/)** — Attack surface and threat model
-- **[Beginners Guide](/ai-loadout/handbook/beginners/)** — New to AI Loadout? Start here
 
 ## What is AI Loadout?
 

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

@@ -74,7 +74,9 @@ const { merged, layers, searched } = resolveLoadout();
 
 ### discoverLayers(opts?)
 
-Discover canonical layer locations and load any that exist. Lower-level than `resolveLoadout`.
+Discover canonical layer locations and load any that exist. Lower-level than `resolveLoadout`. Missing layers are normal -- most setups only have project-level. Malformed files are treated the same as missing.
+
+**Returns:** `{ layers: DiscoveredLayer[], searched: SearchedLayer[] }`
 
 ---
 
@@ -142,20 +144,69 @@ const entry = lookupEntry("github-actions", index);
 
 ### recordUsage(event, path) / readUsage(path) / summarizeUsage(events)
 
-Append-only JSONL usage log. `recordUsage` appends, `readUsage` loads, `summarizeUsage` groups by entry.
+Append-only JSONL usage log. `recordUsage` appends a single event, `readUsage` loads all events (silently skipping malformed lines), `summarizeUsage` groups events by entry ID sorted by load count descending.
+
+**`summarizeUsage` returns:** `UsageSummary[]`
+
+```typescript
+interface UsageSummary {
+  entryId: string;
+  loadCount: number;
+  totalTokens: number;
+  lastLoaded: string;       // ISO 8601
+  triggers: string[];       // unique triggers that caused loads
+  modes: Set<string>;       // unique load modes used
+}
+```
 
 ### findDeadEntries(index, events)
 
-Find entries that have never been loaded. Returns entries sorted by token cost (biggest waste first).
+Find entries that have never been loaded. Core entries are excluded since they always load. Returns entries sorted by token cost descending (biggest waste first).
+
+**Returns:** `DeadEntry[]`
+
+```typescript
+interface DeadEntry {
+  entry: LoadoutEntry;
+  reason: string;
+}
+```
 
 ### findKeywordOverlaps(index)
 
-Find keywords shared between entries — routing ambiguities.
+Find keywords shared between entries — routing ambiguities. Results sorted by overlap count descending.
+
+**Returns:** `KeywordOverlap[]`
+
+```typescript
+interface KeywordOverlap {
+  keyword: string;
+  entries: string[];  // entry IDs sharing this keyword
+}
+```
 
 ### analyzeBudget(index, usage?)
 
 Token budget breakdown by priority tier, with observed-vs-estimated comparison when usage data is available.
 
+**Returns:** `BudgetBreakdown`
+
+```typescript
+interface BudgetBreakdown {
+  totalTokens: number;
+  coreTokens: number;
+  domainTokens: number;
+  manualTokens: number;
+  coreEntries: number;
+  domainEntries: number;
+  manualEntries: number;
+  avgDomainSize: number;
+  largestEntry: { id: string; tokens: number } | null;
+  smallestEntry: { id: string; tokens: number } | null;
+  observedAvg: number | null;
+}
+```
+
 ---
 
 ## Merge
@@ -218,22 +269,44 @@ All commands support `--json` for scripting. Resolver commands accept `--project
 
 ```typescript
 import type {
+  // Core data model
   LoadoutEntry,      // Single entry in the dispatch table
   LoadoutIndex,      // The full dispatch table (entries + budget)
   Frontmatter,       // Parsed from payload file headers
-  MatchResult,       // Returned by matchLoadout()
-  ValidationIssue,   // Returned by validateIndex()
   Priority,          // "core" | "domain" | "manual"
   Triggers,          // { task, plan, edit }
   LoadMode,          // "eager" | "lazy" | "manual"
   Budget,            // Token budget model
+
+  // Matching
+  MatchResult,       // Returned by matchLoadout()
+
+  // Validation
+  ValidationIssue,   // Returned by validateIndex()
+  IssueSeverity,     // "error" | "warning"
+
+  // Usage & observability
   UsageEvent,        // Append-only usage log entry
+  UsageSummary,      // Returned by summarizeUsage()
+  DeadEntry,         // Returned by findDeadEntries()
+  KeywordOverlap,    // Returned by findKeywordOverlaps()
+  BudgetBreakdown,   // Returned by analyzeBudget()
+
+  // Merge
   MergeConflict,     // Entry defined in multiple layers
   MergedIndex,       // LoadoutIndex + provenance + conflicts
-  LoadPlan,          // Returned by planLoad()
+
+  // Resolver
+  DiscoveredLayer,   // A layer found and loaded by the resolver
+  SearchedLayer,     // A layer search location and its result
   ResolvedLoadout,   // Returned by resolveLoadout()
   EntryExplanation,  // Returned by explainEntry()
-  IssueSeverity,     // "error" | "warning"
+  EntryDefinition,   // One layer's version of a specific entry
+  ResolveOptions,    // Options for resolveLoadout / discoverLayers
+
+  // Agent runtime
+  LoadPlan,          // Returned by planLoad()
+  RuntimeOptions,    // Options for planLoad / recordLoad / manualLookup
 } from "@mcptoolshop/ai-loadout";
 ```
 
@@ -243,3 +316,5 @@ import type {
 import { DEFAULT_TRIGGERS } from "@mcptoolshop/ai-loadout";
 // { task: true, plan: true, edit: false }
 ```
+
+`DEFAULT_TRIGGERS` provides the default trigger values applied when frontmatter omits the `triggers` field.