klappy · klappy · Apr 19, 2026 · Apr 19, 2026
diff --git a/canon/principles/consistency-same-pattern-every-time.md b/canon/principles/consistency-same-pattern-every-time.md
@@ -33,7 +33,7 @@ The moment a server introduces a special case for a specific knowledge base, it
 
 - **"But for THIS knowledge base we need..."** The most common consistency smell. Every special-case argument sounds reasonable in isolation. Collectively, they make the server opinionated.
 - **Domain terms in server code.** If the server source contains words like "Bible," "pastoral," "legal," or any domain-specific vocabulary, it has acquired knowledge it shouldn't have.
-- **Different behavior for different `canon_url` values.** If the server checks which repo it's serving and adjusts behavior accordingly, consistency is violated. The server should be blind to content.
+- **Different behavior for different `knowledge_base_url` values.** If the server checks which repo it's serving and adjusts behavior accordingly, consistency is violated. The server should be blind to content.
 - **Onboarding friction for new knowledge bases.** If adding a new KB requires server-side configuration, custom endpoints, or domain-specific setup beyond pointing at a repo URL, the interface isn't consistent.
 - **Tools that work with one KB but break with another.** If an agent workflow built against the software canon fails when pointed at the theology KB, the interface promised consistency it didn't deliver.
 

diff --git a/docs/examples/project-instructions-template.md b/docs/examples/project-instructions-template.md
@@ -32,7 +32,7 @@ The template is model-agnostic. It works for Claude, GPT, Gemini, Llama, or any
 
 1. Copy the template below into your project's system prompt / project instructions field. In Claude.ai, that's **Project Instructions**. In Claude Code, it's `CLAUDE.md`. In Cursor, it's your rules file. In a custom system prompt, it's wherever the prompt lives.
 2. Add your own credentials block at the bottom if your workflow requires the AI to use tokens — GitHub PATs, API keys, or whatever your project uses. This template's real version includes a GitHub PAT scoped to the project repos. **Do not publish credentials; this example has them omitted.**
-3. The `canon_url` in your oddkit MCP server configuration determines which canon is fetched. The `klappy://` URIs in the template assume the klappy.dev canon; if you point at your own canon repo, the same URIs will resolve against yours, or you can rewrite them to match your canon's structure.
+3. The `knowledge_base_url` in your oddkit MCP server configuration determines which canon is fetched. The `klappy://` URIs in the template assume the klappy.dev canon; if you point at your own canon repo, the same URIs will resolve against yours, or you can rewrite them to match your canon's structure.
 
 ---
 

diff --git a/docs/oddkit/IMPL-catalog-recent.md b/docs/oddkit/IMPL-catalog-recent.md
@@ -134,7 +134,7 @@ When `sort_by` is omitted, the response is unchanged — backward compatible.
 2. **Full metadata, not cherry-picked fields.** The `metadata` object in each article is the complete parsed frontmatter — the same data `include_metadata: true` returns on search and get. No field filtering. Consumers decide what to use.
 3. **Documents without dates sort last.** Not all documents have a `date` field. Those without it appear at the end of the sorted list, not at the beginning.
 4. **Limit caps response size.** Without a limit, a sorted catalog of 400+ documents would be unwieldy. The default of 10 serves the most common use case.
-5. **Respect canon_url.** The temporal discovery works with branch overrides. `catalog({ sort_by: "date", limit: 10, canon_url: "...branch..." })` returns the 10 newest articles on that branch.
+5. **Respect knowledge_base_url.** The temporal discovery works with branch overrides. `catalog({ sort_by: "date", limit: 10, knowledge_base_url: "...branch..." })` returns the 10 newest articles on that branch.
 
 ---
 
@@ -161,7 +161,7 @@ When `sort_by` is omitted, the response is unchanged — backward compatible.
 
 **klappy.dev site — "What's new on this branch?"**
 ```
-catalog({ sort_by: "date", limit: 15, canon_url: "https://raw.githubusercontent.com/klappy/klappy.dev/e0007-proactive-posture" })
+catalog({ sort_by: "date", limit: 15, knowledge_base_url: "https://raw.githubusercontent.com/klappy/klappy.dev/e0007-proactive-posture" })
 ```
 
 **Agent — "What was added in E0007?"**

diff --git a/docs/oddkit/tools/oddkit_catalog.md b/docs/oddkit/tools/oddkit_catalog.md
@@ -44,7 +44,7 @@ This tool answers both "what exists?" (default mode) and "give me everything" (w
 {
   "type": "object",
   "properties": {
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
     },

diff --git a/docs/oddkit/tools/oddkit_challenge.md b/docs/oddkit/tools/oddkit_challenge.md
@@ -48,7 +48,7 @@ This tool operationalizes the epistemic challenge constraint (`klappy://canon/ep
       "enum": ["exploration", "planning", "execution"],
       "description": "Optional. Epistemic mode for proportional challenge."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override."
     }

diff --git a/docs/oddkit/tools/oddkit_cleanup_storage.md b/docs/oddkit/tools/oddkit_cleanup_storage.md
@@ -39,7 +39,7 @@ This tool evolved from the former `invalidate_cache` action, which was a correct
 {
   "type": "object",
   "properties": {
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. If not provided, uses the default configured canon repository."
     }

diff --git a/docs/oddkit/tools/oddkit_encode.md b/docs/oddkit/tools/oddkit_encode.md
@@ -48,7 +48,7 @@ This tool operationalizes the canon constraint that epistemic decisions must be
       "type": "string",
       "description": "Optional. Supporting context — goal, phase, alternatives considered, or constraints."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override."
     }

diff --git a/docs/oddkit/tools/oddkit_gate.md b/docs/oddkit/tools/oddkit_gate.md
@@ -47,7 +47,7 @@ This tool operationalizes two canon constraints: boundary transitions require de
       "type": "string",
       "description": "Optional. What has been decided so far — prior decisions, artifacts, or evidence."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override."
     }

diff --git a/docs/oddkit/tools/oddkit_get.md b/docs/oddkit/tools/oddkit_get.md
@@ -42,7 +42,7 @@ The content hash is a short, stable identifier derived from the document's conte
       "type": "string",
       "description": "A klappy:// URI identifying the document to fetch (e.g., 'klappy://canon/values/axioms')."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
     }

diff --git a/docs/oddkit/tools/oddkit_orient.md b/docs/oddkit/tools/oddkit_orient.md
@@ -42,7 +42,7 @@ This tool applies the epistemic modes defined in Canon (`klappy://canon/epistemi
       "type": "string",
       "description": "The goal, idea, or situation to assess. Describe what you are trying to achieve or understand."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
     }

diff --git a/docs/oddkit/tools/oddkit_search.md b/docs/oddkit/tools/oddkit_search.md
@@ -45,7 +45,7 @@ Results include both hits (ranked document summaries with scores) and evidence (
       "type": "string",
       "description": "Natural language query or tags to search for. Describe what you are looking for in plain language."
     },
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
     }

diff --git a/docs/oddkit/tools/oddkit_version.md b/docs/oddkit/tools/oddkit_version.md
@@ -38,7 +38,7 @@ The baseline URL indicates the remote source of truth. When OddKit behavior seem
 {
   "type": "object",
   "properties": {
-    "canon_url": {
+    "knowledge_base_url": {
       "type": "string",
       "description": "Optional. GitHub repo URL for canon override. Defaults to the configured baseline."
     }

diff --git a/docs/oddkit/tools/telemetry_public.md b/docs/oddkit/tools/telemetry_public.md
@@ -81,7 +81,7 @@ Dataset name: `oddkit_telemetry`
 | blob3 | tool_name | oddkit action name (empty for non-tool events) | `"orient"`, `"search"` |
 | blob4 | consumer_label | Best-effort caller identity | `"Claude-User"`, `"Deno/2.1.4"` |
 | blob5 | consumer_source | How label was resolved | `"x-oddkit-client"`, `"user-agent"` |
-| blob6 | canon_url | Which repo is being served (from tool args or env default) | `"https://github.com/klappy/klappy.dev"` |
+| blob6 | knowledge_base_url | Which knowledge base is being served (from tool args or env default) | `"https://github.com/klappy/klappy.dev"` |
 | blob7 | document_uri | For `get` calls, the URI requested (empty otherwise) | `"klappy://canon/principles/vodka-architecture"` |
 | blob8 | worker_version | oddkit version string | `"0.16.0"` |
 
@@ -119,9 +119,9 @@ GROUP BY consumer, source ORDER BY calls DESC LIMIT 20
 
 ### Knowledge bases served (the adoption signal)
 ```sql
-SELECT blob6 AS canon_url, SUM(_sample_interval) AS calls
+SELECT blob6 AS knowledge_base_url, SUM(_sample_interval) AS calls
 FROM oddkit_telemetry WHERE blob1 = 'tool_call'
-GROUP BY canon_url ORDER BY calls DESC
+GROUP BY knowledge_base_url ORDER BY calls DESC
 ```
 
 ### Daily trend