Update handbook: document resolver, runtime, CLI, observability

Index, getting-started, concepts, and reference pages now reflect
the full v1.4 API surface including planLoad, resolver, merge,
observability, and CLI commands.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mcp-tool-shop

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

@@ -1,6 +1,6 @@
 ---
 title: Concepts
-description: Dispatch tables, priority tiers, trigger phases, and the budget model.
+description: Dispatch tables, priorities, resolver, runtime, load modes, and the budget model.
 sidebar:
   order: 2
 ---
@@ -85,3 +85,44 @@ Content here...
 **Frontmatter is the source of truth.** The index is derived from it, not the other way around. If they drift, validation catches it.
 
 The frontmatter parser is hand-rolled — no YAML library, no `eval`, no prototype pollution vectors. It handles strings, inline arrays `[a, b]`, booleans, and one-level nested objects.
+
+## Load Modes
+
+Each matched entry gets a load mode that controls how it enters context:
+
+| Mode | Maps from | Behavior |
+|------|-----------|----------|
+| `eager` | `core` priority | Preloaded immediately — always in context |
+| `lazy` | `domain` priority | Available on demand — loaded when the task matches |
+| `manual` | `manual` priority | Never auto-loaded — requires explicit lookup |
+
+## The Resolver
+
+The resolver discovers and merges loadout indexes from a canonical layer stack:
+
+1. **global** — `~/.ai-loadout/index.json` (user-wide preferences)
+2. **org** — explicit path or `$AI_LOADOUT_ORG` (team conventions)
+3. **project** — `<cwd>/.claude/loadout/index.json` (repo contracts)
+4. **session** — explicit path or `$AI_LOADOUT_SESSION` (ephemeral overrides)
+
+Later layers win. Missing layers are normal — most setups only have project-level. The resolver never guesses; it looks in fixed places in a fixed order.
+
+## Merge Semantics
+
+When two layers define the same entry ID, the later layer overrides the earlier one. The merged index tracks **provenance** (which layer each entry came from) and **conflicts** (entries defined in multiple layers).
+
+## Agent Runtime
+
+The runtime wraps the full sequence: resolve layers → match task → separate by load mode. Agents integrate against one function:
+
+- **`planLoad(task)`** returns a `LoadPlan` with `preload` (eager), `onDemand` (lazy), and `manual` entries, plus provenance, budget, and token costs.
+
+This is the canonical agent-facing API. Everything else (resolve, merge, match, explain) is machinery that the runtime abstracts over.
+
+## Observability
+
+Usage events are recorded to an append-only JSONL log. This enables:
+
+- **Dead entry detection** — entries that have never been loaded
+- **Keyword overlap analysis** — routing ambiguities where multiple entries share keywords
+- **Budget drift** — comparing estimated vs. observed token costs

site/src/content/docs/handbook/getting-started.md

@@ -13,7 +13,8 @@ sidebar:
 ## Install
 
 ```bash
-npm install @mcptoolshop/ai-loadout
+npm install -g @mcptoolshop/ai-loadout   # CLI
+npm install @mcptoolshop/ai-loadout       # library
 ```
 
 ## Your first dispatch table
@@ -59,20 +60,29 @@ for (const { entry, score, matchedKeywords } of results) {
 // github-actions: 0.67 (matched: ci, workflow)
 ```
 
-## Validate your index
+## Plan a load (agent runtime)
+
+The primary agent-facing API — resolve layers, match task, decide what to load:
 
 ```typescript
-import { validateIndex } from "@mcptoolshop/ai-loadout";
+import { planLoad } from "@mcptoolshop/ai-loadout";
 
-const issues = validateIndex(index);
-if (issues.length > 0) {
-  for (const issue of issues) {
-    console.error(`[${issue.severity}] ${issue.code}: ${issue.message}`);
-    if (issue.hint) console.error(`  hint: ${issue.hint}`);
-  }
-}
+const plan = planLoad("fix the CI workflow");
+// plan.preload   — core entries, load immediately
+// plan.onDemand  — domain matches, load when needed
+// plan.manual    — available via explicit lookup only
+```
+
+## Use the CLI
+
+Resolve your layered loadouts and inspect entries:
+
+```bash
+ai-loadout resolve                       # show all layers and entries
+ai-loadout explain github-actions        # trace an entry's decision path
+ai-loadout budget .claude/rules/index.json  # token budget breakdown
 ```
 
 ## Next steps
 
-Read [Concepts](/ai-loadout/handbook/concepts/) to understand priority tiers, trigger phases, and the budget model.
+Read [Concepts](/ai-loadout/handbook/concepts/) to understand priority tiers, the resolver, and the agent runtime.

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

@@ -5,27 +5,29 @@ sidebar:
   order: 0
 ---
 
-Welcome to the AI Loadout handbook. This is the complete guide to using the dispatch table format, matching engine, and frontmatter spec.
+Welcome to the AI Loadout handbook. This is the complete guide to the Knowledge OS kernel — dispatch table, matching engine, hierarchical resolver, agent runtime contract, and CLI.
 
 ## What's inside
 
 - **[Getting Started](/ai-loadout/handbook/getting-started/)** — Install and first use
-- **[Concepts](/ai-loadout/handbook/concepts/)** — Dispatch tables, priorities, triggers, and budgets
+- **[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
 
 ## What is AI Loadout?
 
-AI Loadout is a context-aware knowledge router for AI agents. Instead of dumping entire instruction files into context every session, you keep a tiny dispatch table (always loaded) and route to topic-specific payloads on demand.
+AI Loadout is the kernel of the Knowledge OS stack — a context-aware knowledge router for AI agents. Instead of dumping entire instruction files into context every session, you keep a tiny dispatch table (always loaded) and route to topic-specific payloads on demand.
 
 Think of it like a game loadout — you equip the agent with exactly the knowledge it needs before each mission.
 
 The library provides:
 - A **dispatch table format** (`LoadoutIndex`) for structuring knowledge
 - A **keyword + pattern matcher** for routing tasks to payloads
+- A **hierarchical resolver** for merging indexes across layers (global → org → project → session)
+- An **agent runtime contract** (`planLoad`) — the canonical way agents consume loadouts
+- An **observability layer** — usage tracking, dead entry detection, budget analysis
+- A **CLI** for resolving, explaining, and analyzing loadouts
 - A **frontmatter spec** for embedding routing metadata in payload files
-- A **structural validator** for catching broken indexes early
-- A **token estimator** for budget dashboards
 
 Zero dependencies. Pure TypeScript. Works anywhere Node 20+ runs.