From 27842e14a91233818715d792f798032a70b0cfe4 Mon Sep 17 00:00:00 2001
From: Luca Martial <48870843+luca-martial@users.noreply.github.com>
Date: Thu, 28 May 2026 05:58:08 -0400
Subject: [PATCH] docs: add context layer terminology (#226)

---
 AGENTS.md           | 20 ++++++++++++++++++++
 docs/terminology.md | 38 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 64ec2d4a..b5eccd67 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -323,6 +323,26 @@ use `PascalCase` without the suffix.
   source-code identifier, package/API name, or other literal value that must
   match the implementation.
 
+### Product Category Naming
+
+- **MUST**: Use **context layer** as the primary public category for **ktx**.
+  Preferred phrase: `context layer for data agents`.
+- **MUST**: Use **context engine** only as the secondary mechanism term for the
+  active system that builds, reconciles, validates, searches, and serves the
+  context layer.
+- **MUST**: Keep **semantic layer** as the narrower term for executable metric
+  definitions, semantic sources, joins, measures, and SQL compilation.
+- **MUST NOT**: Replace every `semantic layer` occurrence with `context layer`;
+  the semantic layer is one pillar inside the broader context layer.
+
+Preferred pattern:
+
+```md
+**ktx** is an open-source context layer for data agents. Its context engine
+ingests warehouse metadata, BI definitions, query history, docs, and approved
+metrics, then turns them into reviewable files agents can search and execute.
+```
+
 ### Terminology
 
 For canonical vocabulary used across docs, code, comments, CLI strings, and
diff --git a/docs/terminology.md b/docs/terminology.md
index 00be75e6..9da59456 100644
--- a/docs/terminology.md
+++ b/docs/terminology.md
@@ -21,6 +21,41 @@ in prose when ambiguity is possible. Always qualify:
 Bare `source` is allowed only inside a section that has already established its
 referent (e.g., body of a `Semantic sources` page, or `sourceName` as a CLI arg).
 
+## Context Layer and Context Engine
+
+Use **context layer** as the primary category term for what **ktx** provides to
+data agents.
+
+Use **context engine** as the secondary mechanism term for how **ktx** builds,
+maintains, validates, and serves that layer.
+
+| Concept | Use | Do not use |
+|---|---|---|
+| The whole **ktx** product category | **context layer** / **context layer for data agents** | knowledge layer, agent memory |
+| The active system that builds and maintains context | **context engine** | context layer when describing ingest/reconciliation internals |
+| The durable reviewed surface agents use | **context layer** | context engine |
+| The compiler pillar for executable metrics and joins | **semantic layer** | context layer when specifically discussing SQL compilation |
+| Prose/business knowledge files | **wiki** / **wiki pages** | wiki context |
+
+### Usage rules
+
+- Use **context layer** in taglines, page titles, meta descriptions, docs
+  introductions, comparison pages, and first-paragraph definitions.
+- Use **context engine** when describing active behavior: ingesting evidence,
+  reconciling changes, validating references, maintaining files, search, CLI,
+  and MCP serving.
+- Keep **semantic layer** for the narrower YAML/compiler surface: semantic
+  sources, measures, joins, dimensions, filters, SQL compilation, and semantic
+  queries.
+- Do not use **context engine** as the primary replacement for the whole
+  product. It sounds like runtime infrastructure; **context layer** better
+  describes the durable YAML and Markdown surface users review in git.
+- Do not use **context layer** when the sentence is specifically about the
+  compiler. Example: write "the semantic layer compiles semantic queries to
+  SQL," not "the context layer compiles semantic queries to SQL."
+- Default lowercase in prose: `context layer`, `context engine`, `semantic
+  layer`. Title case only in page titles, headings, nav labels, and UI labels.
+
 ## Canonical vocabulary
 
 | Concept | Use | Do not use |
@@ -31,7 +66,8 @@ referent (e.g., body of a `Semantic sources` page, or `sourceName` as a CLI arg)
 | The connected database | **primary source** / **database connection** | data source |
 | Analytics-tooling integration | **context source** / **context-source connection** | BI source, BI model, metadata source, source tool |
 | YAML file describing a table | **semantic source** | semantic-layer source, model file, bare "source file" |
-| The whole **ktx** surface | **context layer** (lowercase in prose) | "Context Layer" in prose |
+| The whole **ktx** surface | **context layer** / **context layer for data agents** (lowercase in prose) | "Context Layer" in prose, knowledge layer, agent memory |
+| The active system that builds and maintains context | **context engine** (lowercase in prose) | context layer when describing ingest/reconciliation internals |
 | The compiler pillar | **semantic layer** (lowercase in prose) | "Semantic Layer" in prose |
 | The query payload | **semantic query** (lowercase in prose) | "Semantic Query" |
 | The MCP layer | **MCP server** (the server), **MCP tools** (the functions) | "ktx MCP" as a standalone noun |