klappy · klappy · Feb 13, 2026 · Feb 13, 2026
diff --git a/docs/oddkit/IMPL-A-explain-mode-annotation.md b/docs/oddkit/IMPL-A-explain-mode-annotation.md
@@ -6,11 +6,16 @@ exposure: internal
 tier: 3
 voice: neutral
 stability: evolving
+status: superseded
 tags: ["oddkit", "implementation", "epistemic-modes"]
 ---
 
 # Implementation Instruction Set A
 
+**Superseded (E0005.1):** The `explain` action described here was never implemented as a standalone tool. The concept of epistemic mode annotation is handled by `oddkit_orient`, which returns `current_mode` and `mode_confidence` in every response.
+
+---
+
 ## Lightly annotate oddkit explain output with detected epistemic mode
 
 ---

diff --git a/docs/oddkit/IMPL-B-mode-headers.md b/docs/oddkit/IMPL-B-mode-headers.md
@@ -6,11 +6,16 @@ exposure: internal
 tier: 3
 voice: neutral
 stability: evolving
+status: superseded
 tags: ["oddkit", "implementation", "epistemic-modes"]
 ---
 
 # Implementation Instruction Set B
 
+**Superseded (E0005.1):** Mode headers described here were not implemented. Explicit mode declaration is handled by the `declared_mode` parameter in `oddkit_orient`.
+
+---
+
 ## Add optional epistemic mode headers in conversations
 
 ---

diff --git a/docs/oddkit/IMPL-content-addressed-caching.md b/docs/oddkit/IMPL-content-addressed-caching.md
@@ -6,12 +6,17 @@ exposure: internal
 tier: 2
 voice: neutral
 stability: evolving
+status: implemented
 tags: ["oddkit", "implementation", "caching", "content-addressed", "anti-cache-lying"]
 derives_from: "odd/constraint/anti-cache-lying.md"
 ---
 
 # Implementation: Replace TTL Caching with Content-Addressed Storage in OddKit
 
+**Implemented:** Content-addressed caching with commit-SHA-keyed storage is live in oddkit v0.14.0. The `invalidate_cache` action was replaced by `cleanup_storage`, which is storage hygiene only — never required for correctness.
+
+---
+
 > OddKit's TTL-based baseline cache must be replaced with commit-SHA-keyed immutable storage. The current strategy served stale canon for days undetected and its `invalidate_cache` action only cleared `.zip` files (see `docs/incidents/oddkit-stale-cache-2026-02.md`). The target: on every session's first request, fetch the current commit SHA (one lightweight call), use it as the storage namespace, serve from storage only when the SHA matches, and fetch fresh when it doesn't. No TTL. No staleness window. No flush for correctness. `invalidate_cache` becomes orphan cleanup or is removed entirely.
 
 ---

diff --git a/docs/oddkit/epistemic-instructions.md b/docs/oddkit/epistemic-instructions.md
@@ -13,7 +13,7 @@ oddkit is a compliance surface, not an epistemic engine.
 
 oddkit MUST:
 
-- obey the Epistemic Contract (`odd://contract/epistemic-contract`)
+- obey the Epistemic Contract (`odd/contract/epistemic-contract.md`, URI: `odd://contract/epistemic-contract`)
 - derive behavior from documented artifacts
 - surface which rule authorized a move
 - refuse to act when prerequisites are unmet

diff --git a/docs/oddkit/modes.md b/docs/oddkit/modes.md
@@ -6,6 +6,7 @@ exposure: nav
 tier: 2
 voice: neutral
 stability: evolving
+epoch: E0005
 tags: ["oddkit", "agents", "epistemic-modes"]
 ---
 
@@ -17,7 +18,8 @@ tags: ["oddkit", "agents", "epistemic-modes"]
 
 This document depends on:
 
-- **Canon: Epistemic Modes**
+- **Canon: Epistemic Modes** — `canon/definitions/epistemic-modes.md`
+- **Canon: Axioms** — `canon/values/axioms.md` (values-first grounding for mode behavior)
 
 If Canon changes, this document must adapt.
 
@@ -61,13 +63,13 @@ Refusals MUST cite the epistemic reason, not a tool limitation.
 
 ## Interaction with Other oddkit Capabilities
 
-- **Librarian** respects mode by:
+- **Search / Get / Catalog** (`oddkit_search`, `oddkit_get`, `oddkit_catalog`) respects mode by:
   - preferring governing docs in Planning
   - allowing broader sources in Exploration
 
-- **Validation** triggers only in Execution
+- **Validate** (`oddkit_validate`) triggers only in Execution
 
-- **Promotions** occur only after repeated Execution outcomes
+- ~~**Promotions**~~ — Historical concept from the lane era; not present in the current oddkit action set.
 
 ---
 

diff --git a/docs/oddkit/prompts/epistemic-guide.md b/docs/oddkit/prompts/epistemic-guide.md
@@ -15,7 +15,7 @@ tags: ["oddkit", "prompt", "mcp", "epistemics", "guide", "orchestration"]
 
 ## Description
 
-This MCP prompt composes four epistemic tools — `oddkit_orient`, `oddkit_challenge`, `oddkit_gate`, and `oddkit_encode` — into a coherent guidance flow. It turns a chat assistant into a sparring partner that helps users think clearly, avoid premature commitment, and make durable decisions.
+OddKit exposes 12 tools organized in four clusters. This MCP prompt specifically orchestrates the four epistemic core tools — `oddkit_orient`, `oddkit_challenge`, `oddkit_gate`, and `oddkit_encode` — into a coherent guidance flow. It turns a chat assistant into a sparring partner that helps users think clearly, avoid premature commitment, and make durable decisions. The remaining tools (discovery, implementation bookends, maintenance) are used directly by agents and documented below.
 
 The prompt does not replace the tools. Models that never read this prompt can still call each tool independently and get useful results. This prompt is an optimization layer for models that support MCP prompts — it sequences tool calls, interprets combined results, and maintains epistemic continuity across a conversation.
 
@@ -34,6 +34,40 @@ You operate inside an Outcomes-Driven Development (ODD) system. Knowledge must b
 | `oddkit_gate` | Check transition readiness | Before any phase change. Evaluates boundary exit and entry conditions. |
 | `oddkit_encode` | Record durable decisions | After a decision is reached. Captures what was decided, rejected, and why. |
 
+## Full Tool Surface
+
+OddKit exposes 12 actions organized in four clusters. This prompt orchestrates the epistemic core, but agents should be aware of the full surface:
+
+### Discovery — Finding and Retrieving Canon
+
+| Tool | Purpose |
+|------|---------|
+| `oddkit_search` | Semantic search by meaning — find docs without knowing paths |
+| `oddkit_get` | Fetch a specific document by URI — returns full content |
+| `oddkit_catalog` | List all docs with counts, categories, and start-here suggestions |
+
+Most agent sessions start here. Use search when exploring, get when you have a URI, catalog for corpus overview.
+
+### Epistemic Core — Reasoning About What You Find
+
+The four tools above — orient, challenge, gate, encode. See [The Four Tools](#the-four-tools) and [Flow](#flow) for orchestration details.
+
+### Implementation Bookends — Before and After Coding
+
+| Tool | Purpose |
+|------|---------|
+| `oddkit_preflight` | Pre-implementation check: relevant docs, constraints, definition of done |
+| `oddkit_validate` | Post-implementation check: verify completion claim against required artifacts |
+
+Preflight before implementing. Validate before claiming done. These are mandatory per AGENTS.md.
+
+### System Maintenance
+
+| Tool | Purpose |
+|------|---------|
+| `oddkit_version` | Current version and baseline URL — diagnostic |
+| `oddkit_cleanup_storage` | Storage hygiene — clears orphaned cache data (never required for correctness) |
+
 ## Flow
 
 ### 1. Orient First
@@ -111,6 +145,7 @@ Encourage the user to name what was rejected and why. The most durable records i
 - Choose between valid options
 - Override human judgment
 - Replace domain expertise with process
+- Orchestrate discovery or implementation tools — those are used directly by agents
 - Add ceremony for its own sake
 
 The guide clears the epistemic path. The user walks it.

diff --git a/docs/oddkit/tools/oddkit_catalog.md b/docs/oddkit/tools/oddkit_catalog.md
@@ -0,0 +1,81 @@
+---
+uri: oddkit://tools/catalog
+title: "oddkit_catalog"
+audience: operators
+exposure: nav
+tier: 2
+voice: neutral
+stability: evolving
+tags: ["oddkit", "tool", "epistemics", "catalog", "discovery", "navigation"]
+---
+
+# oddkit_catalog
+
+> List all available documentation with counts, categories, and start-here suggestions.
+
+## Description
+
+`oddkit_catalog` provides a high-level map of the entire documentation corpus. It returns total document counts, a breakdown between canon and baseline, the full set of categories (derived from tags), and a curated list of start-here entry points for new users or agents.
+
+This tool answers the question "what exists?" without returning any document content. It is the right starting point when orienting in an unfamiliar repo or verifying corpus shape after structural changes. For actual document content, follow up with `oddkit_search` (by topic) or `oddkit_get` (by URI).
+
+## When to Use
+
+- Understanding the size and shape of the documentation corpus
+- Finding entry points when starting work in an unfamiliar repo
+- Verifying document counts after structural changes or migrations
+- Discovering available categories before running a targeted search
+- Orienting a new agent to the repo's documentation landscape
+
+## Tool Definition
+
+**Name:** `oddkit_catalog`
+
+**Description:** Lists available documentation with categories, counts, and start-here suggestions. Returns total document counts (canon vs. baseline), category distribution from tags, and curated entry points. Use to understand corpus shape, find starting points, or verify doc counts. Does not return document content — use search or get for that.
+
+### Input Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "canon_url": {
+      "type": "string",
+      "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
+    }
+  },
+  "required": []
+}
+```
+
+### Response Shape
+
+```json
+{
+  "action": "catalog",
+  "result": {
+    "total": "number — total documents in the corpus",
+    "canon": "number — documents classified as canon",
+    "baseline": "number — documents from the baseline (remote main branch)",
+    "categories": [
+      "string — category names derived from document tags"
+    ],
+    "start_here": [
+      "string — file paths recommended as entry points"
+    ]
+  }
+}
+```
+
+## Behavioral Rules
+
+1. **Return counts and categories, not content.** Catalog provides structural metadata only. For document content, use `oddkit_search` or `oddkit_get`.
+2. **Start-here docs are curated entry points.** These are documents explicitly marked as starting points for new users or agents. They represent the recommended reading order for orientation.
+3. **Categories reflect tag distribution.** The categories list is derived from frontmatter tags across all indexed documents. It represents what the corpus covers, not a fixed taxonomy.
+4. **Report canon vs. baseline breakdown.** The distinction between canon (immutable governing documents) and baseline (all indexed documents from remote main) is always surfaced.
+5. **Lightweight and side-effect free.** Catalog reads index metadata only. It does not modify state, fetch document content, or trigger reindexing.
+
+## Canon References
+
+- `klappy://canon/README` — Canon root document, typically appears in start-here suggestions
+- `klappy://canon/epistemic-modes` — Epistemic modes that inform how agents orient using catalog results
diff --git a/docs/oddkit/tools/oddkit_challenge.md b/docs/oddkit/tools/oddkit_challenge.md
@@ -39,56 +39,51 @@ This tool operationalizes the epistemic challenge constraint (`klappy://canon/ep
 {
   "type": "object",
   "properties": {
-    "claim": {
+    "input": {
       "type": "string",
       "description": "The claim, assumption, or proposal to challenge. State it as the claimant would."
     },
-    "claim_type": {
+    "mode": {
       "type": "string",
-      "enum": ["assertion", "assumption", "proposal", "completion_claim", "scope_decision"],
-      "description": "Optional. The nature of what is being challenged. Helps calibrate proportional pressure."
+      "enum": ["exploration", "planning", "execution"],
+      "description": "Optional. Epistemic mode for proportional challenge."
     },
-    "context": {
+    "canon_url": {
       "type": "string",
-      "description": "Optional. Surrounding context — current mode, prior decisions, relevant constraints, or evidence already gathered."
-    },
-    "stakes": {
-      "type": "string",
-      "enum": ["low", "moderate", "high", "irreversible"],
-      "description": "Optional. How consequential this claim is. Higher stakes trigger more rigorous challenge. Defaults to moderate."
+      "description": "Optional. GitHub repo URL for canon override."
     }
   },
-  "required": ["claim"]
+  "required": ["input"]
 }
 ```
 
-### Response Shape
+### Response Shape (Observed)
 
 ```json
 {
-  "challenged": "string — restated version of the claim being tested",
-  "tensions": [
-    {
-      "source": "string — canon reference, prior decision, or evidence that creates tension",
-      "description": "string — what the tension is",
-      "type": "contradiction | gap | drift | scope_mismatch | weak_evidence"
-    }
-  ],
-  "missing_evidence": [
-    {
-      "what": "string — evidence that would strengthen or refute the claim",
-      "smallest_artifact": "string — the cheapest artifact that would increase certainty"
-    }
-  ],
-  "risks": [
-    {
-      "risk": "string — an unexamined risk exposed by the challenge",
-      "severity": "low | moderate | high",
-      "mitigation": "string — what would reduce this risk"
-    }
-  ],
-  "next_step": "string — one actionable step to increase certainty",
-  "posture": "SUPPORTED | INSUFFICIENT_EVIDENCE | CONTESTED"
+  "action": "challenge",
+  "result": {
+    "status": "CHALLENGED",
+    "claim_type": "string — inferred type: observation | assertion | assumption | proposal",
+    "tensions": [
+      "string — tensions with canon or prior decisions"
+    ],
+    "missing_prerequisites": [
+      "string — evidence or prerequisites not yet provided"
+    ],
+    "challenges": [
+      "string — specific questions that would need answers to proceed"
+    ],
+    "suggested_reframings": [
+      "string — alternative framings that would be stronger"
+    ],
+    "canon_constraints": [
+      {
+        "citation": "string — file path#Section Name",
+        "quote": "string — relevant excerpt from canon"
+      }
+    ]
+  }
 }
 ```