--help`. If something looks wrong or missing, say so explicitly.
- **Print every command you run and its exit code.** Terse, not silent.
- **Fail loudly with cause + fix.** When a command fails: capture the exact error, identify the cause, change something, retry. Never retry an unchanged command. Exceptions for *known soft-failures* are listed in Phase 4 - handle those without retrying.
-- **No LLM-based ingestion in this flow.** Only `--fast` ingest (schema-only). The user can run `--deep` later.
+- **No LLM-based ingestion in this flow.** Only `--fast` ingest. The user can run `--deep` later.
- **Platform-agnostic.** Detect the host OS first and pick the right install commands / path syntax. Anything path- or shell-specific must branch on OS.
# Authoritative docs
@@ -58,7 +58,7 @@ Ask the user (grouped if your harness supports it; otherwise sequentially):
- **Heads-up for the user**: even if they paste a literal URL, KTX will silently relocate it into `/.ktx/secrets/-url` and rewrite `ktx.yaml` to `url: file:…` - this is correct, secure behavior and not a bug.
- Schemas / datasets to include (postgres / sqlserver / snowflake / bigquery only).
- Optional `enabled_tables` allowlist if the user wants to scope ingest to specific tables.
-5. **BI / metadata sources** (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Default: none. Ask only if the user mentions them.
+5. **Context sources** (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Default: none. Ask only if the user mentions them.
## Phase 4 - Configure the project
@@ -90,11 +90,11 @@ Notes on the flags above:
- **You don't need `--skip-agents` in this flow.** The agent integration step
is opt-in: setup leaves it alone unless you pass `--agents --target
`.
-- **`--skip-sources`** is correct and is the documented way to leave BI/metadata sources unconfigured.
+- **`--skip-sources`** is correct and is the documented way to leave context sources unconfigured.
### Known soft-failure: `ktx setup` exits 1 after a successful fast build
-When you select a configuration that only does fast (schema-only) ingest, `ktx setup`'s final readiness verification fails with:
+When you select a configuration that only does fast ingest, `ktx setup`'s final readiness verification fails with:
```
KTX context build did not pass agent-readiness verification.
@@ -119,7 +119,7 @@ Use a YAML-aware editor (e.g. `uv run python -c "import yaml; …"`) - do not ha
## Phase 5 - Verify
-`ktx setup` already runs a fast schema ingest of every database connection it configures, so you do not need to re-ingest by default. For each configured connection:
+`ktx setup` already runs a fast ingest of every database connection it configures, so you do not need to re-ingest by default. For each configured connection:
```
ktx connection test # must exit 0
@@ -180,7 +180,7 @@ Verdict: ready
Then **Next steps** (copy-pasteable):
1. Enrich with AI descriptions and embeddings: `ktx ingest --deep` (several minutes per connection).
2. Add more connections later by rerunning this setup or via `ktx setup --database … --database-connection-id …`.
-3. Configure BI sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) - see `ktx setup --help` for `--source …` flags.
+3. Configure context sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) - see `ktx setup --help` for `--source …` flags.
4. Install agent integration: `ktx setup --agents --target ` (with optional `--global` for `claude-code`/`codex`).
5. Connect the agent / MCP: see docs at `https://docs.kaelio.com/ktx/`.
diff --git a/docs-site/content/docs/cli-reference/ktx-connection.mdx b/docs-site/content/docs/cli-reference/ktx-connection.mdx
index 5c4c5324..5348100b 100644
--- a/docs-site/content/docs/cli-reference/ktx-connection.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx
@@ -1,11 +1,12 @@
---
title: "ktx connection"
-description: "List and test configured data sources."
+description: "List and test configured database and context-source connections."
---
Inspect configured connections in your KTX project. Connections define how KTX
-reaches databases, warehouses, BI tools, source projects, and knowledge
-systems. Use `ktx setup` to add, remove, or reconfigure them.
+reaches primary sources (databases and warehouses) and context sources (BI
+tools, modeling projects, and knowledge systems). Use `ktx setup` to add,
+remove, or reconfigure them.
## Command signature
@@ -77,8 +78,8 @@ my-warehouse postgres
`ktx connection test ` performs a lightweight connection probe.
Native database connections report `Status: ok` when the connector probe
-passes. Source connectors report connector-specific details such as Metabase
-database count, Looker user, Notion bot, or Git repo URL.
+passes. Context-source connectors report connector-specific details such as
+Metabase database count, Looker user, Notion bot, or Git repo URL.
```text
Connection test passed: my-warehouse
@@ -102,7 +103,7 @@ configured connection and exit non-zero if any probe fails.
| Error | Cause | Recovery |
|-------|-------|----------|
-| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
+| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection |
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
-| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
+| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the context-source mapping selections |
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |
diff --git a/docs-site/content/docs/cli-reference/ktx-ingest.mdx b/docs-site/content/docs/cli-reference/ktx-ingest.mdx
index 49b176b5..3b664605 100644
--- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx
@@ -29,8 +29,8 @@ connection is selected.
| Flag | Description | Default |
|------|-------------|---------|
| `--all` | Ingest all configured connections (same as bare invocation) | `false` |
-| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` |
-| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` |
+| `--fast` | Use deterministic fast database ingest | Stored connection default, or `fast` |
+| `--deep` | Use deep database ingest with AI-generated descriptions, embeddings, and relationship evidence | Stored connection default, or `fast` |
| `--query-history` | Include database query-history usage patterns | Stored connection default |
| `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default |
| `--query-history-window-days ` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
@@ -48,14 +48,14 @@ connection is selected.
database connections. Query-history flags apply only to database connections
that support query history. The window flag applies to BigQuery and Snowflake;
Postgres reads the current `pg_stat_statements` aggregate data instead of a
-time-windowed history table. Query-history ingest runs after schema ingest and
+time-windowed history table. Query-history ingest runs after fast ingest and
requires deep ingest readiness.
When more than one connection is selected, database ingest runs first, then
-source ingest and memory updates run for source connections.
+context-source ingest and memory updates run for context-source connections.
Some ingest paths use the managed KTX Python runtime. Query-history ingest uses
-it for SQL analysis, and Looker source ingest uses it for Looker identifier
+it for SQL analysis, and Looker context-source ingest uses it for Looker identifier
parsing. In an interactive terminal, `ktx ingest` prompts before installing the
required runtime features. Use `--yes` to install them without prompting, or
use `--no-input` to fail fast with install guidance.
@@ -69,13 +69,13 @@ use `--no-input` to fail fast with install guidance.
# Build every configured connection (bare = --all)
ktx ingest
-# Build one database or source connection
+# Build one database or context-source connection
ktx ingest warehouse
-# Force deterministic database schema ingest
+# Force deterministic fast database ingest
ktx ingest warehouse --fast
-# Force AI-enriched database ingest
+# Force deep database ingest with AI enrichment
ktx ingest warehouse --deep
# Include query-history usage patterns
@@ -83,7 +83,7 @@ ktx ingest warehouse --deep --query-history
# Set the lookback window for BigQuery or Snowflake query history
ktx ingest warehouse --query-history-window-days 30
-# Build a source connection
+# Build a context-source connection
ktx ingest notion
# Capture inline text into memory
@@ -114,11 +114,11 @@ notion skipped skipped done done
Use `--json` when a script or agent needs the selected plan and per-target
results.
-## Inspect source ingest traces
+## Inspect context-source ingest traces
-Source ingest writes persistent JSONL traces for postmortem debugging. Plain
-ingest output prints the trace path near the report, run, and job identifiers
-when a trace is available:
+Context-source ingest writes persistent JSONL traces for postmortem debugging.
+Plain ingest output prints the trace path near the report, run, and job
+identifiers when a trace is available:
```text
Report: report-abc123
@@ -155,7 +155,7 @@ KTX_INGEST_TRACE_LEVEL=trace ktx ingest metabase
|-------|-------|----------|
| Connection not configured | The connection id is not present in `ktx.yaml` | Add the connection with `ktx setup` or update `ktx.yaml` |
| Deep readiness is missing | `--deep` or query history needs model, embedding, and scan-enrichment configuration | Run `ktx setup` or rerun with `--fast` |
-| Query history is unsupported | The selected database driver does not support query history | Run schema ingest without query-history flags |
+| Query history is unsupported | The selected database driver does not support query history | Run fast ingest without query-history flags |
| Python runtime is missing | The selected ingest target needs runtime-backed SQL analysis or source parsing | Accept the interactive prompt, rerun with `--yes`, or run the suggested `ktx admin runtime install` command |
-| Source options were ignored | Depth and query-history flags were supplied for a non-database source | Omit database-only flags when ingesting source connections |
+| Context-source options were ignored | Depth and query-history flags were supplied for a context-source connection | Omit database-only flags when ingesting context-source connections |
| Text ingest stops early | `--fail-fast` was used and one item failed | Fix the failed item or rerun without `--fail-fast` to collect all failures |
diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx
index e98a51e4..5b5519fa 100644
--- a/docs-site/content/docs/cli-reference/ktx-setup.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx
@@ -82,11 +82,11 @@ embedding credential source.
Setup prepares the managed Python runtime when your selected configuration
needs it. In the full setup flow, the runtime step runs after database and
-source setup and before the initial context build.
+context-source setup and before the initial context build.
KTX prepares the `core` runtime feature when query-history ingest, Looker
-source ingest, database introspection fallback, or daemon-backed context build
-paths need it. KTX prepares the `local-embeddings` runtime feature when you
+context-source ingest, database introspection fallback, or daemon-backed
+context build paths need it. KTX prepares the `local-embeddings` runtime feature when you
choose managed local `sentence-transformers` embeddings. Existing external
daemon URLs, such as `KTX_DAEMON_URL` or `KTX_SQL_ANALYSIS_URL`, satisfy the
matching dependency and skip managed runtime installation for that dependency.
@@ -134,25 +134,25 @@ Enabling query history makes deep ingest readiness matter for later
| Flag | Description |
|------|-------------|
-| `--source ` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
-| `--source-connection-id ` | Connection id for source setup |
+| `--source ` | Context-source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
+| `--source-connection-id ` | Connection id for context-source setup |
| `--source-path ` | Local source path for dbt, MetricFlow, or LookML |
| `--source-git-url ` | Git URL for dbt, MetricFlow, or LookML |
-| `--source-branch ` | Git branch for source setup |
-| `--source-subpath ` | Repo subpath for source setup |
+| `--source-branch ` | Git branch for context-source setup |
+| `--source-subpath ` | Repo subpath for context-source setup |
| `--source-auth-token-ref ` | `env:` or `file:` credential reference for source repo auth |
| `--source-url ` | Source service URL for Metabase or Looker |
| `--source-api-key-ref ` | `env:` or `file:` API key reference for Metabase or Notion |
| `--source-client-id ` | Looker client id |
| `--source-client-secret-ref ` | `env:` or `file:` Looker client secret reference |
-| `--source-warehouse-connection-id ` | Warehouse connection id used for source mapping |
+| `--source-warehouse-connection-id ` | Warehouse connection id used for context-source mapping |
| `--source-project-name ` | dbt project name override |
| `--source-profiles-path ` | dbt profiles path |
-| `--source-target ` | dbt target or source-specific mapping target |
+| `--source-target ` | dbt target or context-source-specific mapping target |
| `--metabase-database-id ` | Metabase database id to map |
| `--notion-crawl-mode ` | Notion crawl mode: `all_accessible` or `selected_roots` |
| `--notion-root-page-id ` | Notion root page id; repeatable |
-| `--skip-sources` | Mark optional source setup complete with no sources |
+| `--skip-sources` | Mark optional context-source setup complete with no sources |
Choose only one source location: `--source-path` or `--source-git-url`.
diff --git a/docs-site/content/docs/cli-reference/ktx-sl.mdx b/docs-site/content/docs/cli-reference/ktx-sl.mdx
index e0c6a101..c9754bdc 100644
--- a/docs-site/content/docs/cli-reference/ktx-sl.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-sl.mdx
@@ -1,6 +1,6 @@
---
title: "ktx sl"
-description: "List, search, validate, or query semantic-layer sources."
+description: "List, search, validate, or query semantic sources."
---
Interact with your project's semantic layer. Semantic sources are YAML
@@ -15,8 +15,8 @@ ktx sl validate [options]
ktx sl query [options]
```
-- Bare `ktx sl` lists semantic-layer sources.
-- `ktx sl ` searches semantic-layer sources (multi-word queries are
+- Bare `ktx sl` lists semantic sources.
+- `ktx sl ` searches semantic sources (multi-word queries are
joined with a space).
- `ktx sl validate` and `ktx sl query` remain as explicit subcommands.
@@ -24,10 +24,10 @@ ktx sl query [options]
| Subcommand | Description |
|-----------|-------------|
-| (none, no query) | List semantic-layer sources |
-| (none, with query) | Search semantic-layer sources |
-| `validate ` | Validate a semantic-layer source against the database schema |
-| `query` | Compile or execute a Semantic Query |
+| (none, no query) | List semantic sources |
+| (none, with query) | Search semantic sources |
+| `validate ` | Validate a semantic source against the database schema |
+| `query` | Compile or execute a semantic query |
## Options
@@ -51,7 +51,7 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id ` | KTX connection id | - |
-| `--query-file ` | JSON Semantic Query file | - |
+| `--query-file ` | JSON semantic query file | - |
| `--measure ` | Measure to query; repeatable (at least one required) | - |
| `--dimension ` | Dimension to include; repeatable | - |
| `--filter ` | Filter expression; repeatable | - |
@@ -66,7 +66,7 @@ ktx sl query [options]
| `--max-rows ` | Maximum rows to return when executing | - |
`sl query` requires at least one `--measure` unless `--query-file` is set.
-`--query-file` should point to a JSON Semantic Query object.
+`--query-file` should point to a JSON semantic query object.
## Examples
diff --git a/docs-site/content/docs/cli-reference/ktx.mdx b/docs-site/content/docs/cli-reference/ktx.mdx
index 65cdc5ff..8a17b217 100644
--- a/docs-site/content/docs/cli-reference/ktx.mdx
+++ b/docs-site/content/docs/cli-reference/ktx.mdx
@@ -4,7 +4,7 @@ description: "Root command map, global options, and project resolution for the K
---
The `ktx` CLI sets up local projects, builds agent-ready context, checks
-connections, queries semantic-layer sources, searches wiki pages, runs the MCP
+connections, queries semantic sources, searches wiki pages, runs the MCP
server, and manages the bundled Python runtime.
## Command signature
@@ -93,7 +93,7 @@ ktx ingest warehouse
# Build every configured connection
ktx ingest
-# Search semantic-layer sources and wiki pages
+# Search semantic sources and wiki pages
ktx sl "revenue"
ktx wiki "revenue recognition"
diff --git a/docs-site/content/docs/community/contributing.mdx b/docs-site/content/docs/community/contributing.mdx
index bf66f546..4939f7b9 100644
--- a/docs-site/content/docs/community/contributing.mdx
+++ b/docs-site/content/docs/community/contributing.mdx
@@ -3,7 +3,7 @@ title: Contributing
description: Contribute to KTX through code, docs, connectors, and examples.
---
-KTX is an open-source context layer for database agents. The project welcomes
+KTX is an open-source context layer for data agents. The project welcomes
focused contributions that improve setup, integrations, CLI behavior,
documentation, connector coverage, and examples.
@@ -24,7 +24,7 @@ documentation, connector coverage, and examples.
| CLI and setup | `packages/cli`, especially setup steps, command definitions, status checks, and smoke tests |
| Context engine | `packages/context`, including project config, ingest orchestration, and semantic search |
| Connectors | `packages/connector-*`, plus connector-specific tests and integration docs |
-| Python semantic layer | `python/ktx-sl` for planning and SQL generation |
+| Python semantic layer | `python/ktx-sl` for planning and SQL compilation |
| KTX daemon | `python/ktx-daemon` for the portable runtime API |
| Documentation | `docs-site/content/docs` for public docs and `docs-site/tests` for docs behavior |
@@ -97,7 +97,7 @@ packages/
connector-posthog/ # PostHog connector
python/
- ktx-sl/ # Semantic layer - grain-aware query planning and SQL generation
+ ktx-sl/ # Semantic layer - grain-aware query planning and SQL compilation
ktx-daemon/ # Daemon - portable API server around the semantic layer
examples/ # Example projects and fixtures
@@ -226,7 +226,7 @@ and statistics.
### Step 4: Wire it up
-Register the new connector driver in `packages/context` so the CLI and scan
+Register the new connector in `packages/context` so the CLI and scan
engine can instantiate it. Look at how existing connectors are registered for
the pattern.
diff --git a/docs-site/content/docs/concepts/context-as-code.mdx b/docs-site/content/docs/concepts/context-as-code.mdx
index 6636b700..b37b29c9 100644
--- a/docs-site/content/docs/concepts/context-as-code.mdx
+++ b/docs-site/content/docs/concepts/context-as-code.mdx
@@ -20,15 +20,15 @@ ingest decisions become files that can be reviewed, merged, and audited.
Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
-adapters, then reconciles them into local files.
+connectors, then reconciles them into local files.
```text
-source tools -> adapters -> reconciliation agent -> YAML + Markdown diffs
+context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs
```
| Step | What happens | Output |
|------|--------------|--------|
-| **Extract** | Adapters read models, metrics, questions, schemas, and docs | Structured metadata |
+| **Extract** | Connectors read models, metrics, questions, schemas, and docs | Structured metadata |
| **Reconcile** | The agent compares incoming facts with existing context | Create, update, skip, or flag |
| **Write** | KTX saves changed semantic sources and wiki pages | Reviewable project files |
@@ -88,7 +88,7 @@ context layer converge toward the team's current source of truth.
## Deterministic replay
-Every ingestion session records the adapter inputs, tool calls, LLM responses,
+Every ingestion session records the connector inputs, tool calls, LLM responses,
write decisions, and reasoning behind each change.
| Use case | What replay gives you |
diff --git a/docs-site/content/docs/concepts/semantic-layer-internals.mdx b/docs-site/content/docs/concepts/semantic-layer-internals.mdx
index f64836fe..78a36814 100644
--- a/docs-site/content/docs/concepts/semantic-layer-internals.mdx
+++ b/docs-site/content/docs/concepts/semantic-layer-internals.mdx
@@ -1,24 +1,24 @@
---
-title: Semantic Querying
-description: How KTX compiles a short Semantic Query into safe, dialect-correct SQL using a reviewed join graph.
+title: Semantic querying
+description: How KTX compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph.
---
import { SemanticLayerFlow } from "@/components/semantic-layer-flow";
KTX's semantic layer is a compiler that turns intent into SQL. The agent
declares _what_ it wants - measures, dimensions, filters - in a small
-Semantic Query. KTX figures out the _how_: which tables to join, what
+semantic query. KTX figures out the _how_: which tables to join, what
grain to aggregate at, how to keep fan-out from inflating measures, and
what dialect the warehouse speaks.
This page covers four mechanics:
-- The Semantic Query contract agents send to the compiler.
-- The planner steps that turn a Semantic Query into SQL.
+- The semantic query contract agents send to the compiler.
+- The planner steps that turn a semantic query into SQL.
- The join graph that backs those steps, and how it's built.
- The fan-out failure mode the compiler is designed to prevent.
-## Imperative SQL vs declarative Semantic Querying
+## Imperative SQL vs declarative semantic querying
Writing analytics SQL is imperative work. Every question forces the
agent to hold two things in mind at once: _what_ it wants - a measure, a
@@ -32,7 +32,7 @@ KTX's semantic layer separates those concerns:
- **You and KTX maintain the how.** Sources, joins, grain, measures, and
segments live in reviewable YAML - the analytical contract the team
agrees on, version-controlled.
-- **The agent declares the what.** It sends a Semantic Query and trusts
+- **The agent declares the what.** It sends a semantic query and trusts
the compiler to produce safe SQL.
The agent stops reasoning about plumbing. It states intent. KTX turns
@@ -40,9 +40,9 @@ that into SQL the warehouse can run.
@@ -65,7 +65,7 @@ context, find semantic-layer entities, compile trusted semantic queries, run
read-only SQL, and use the same tools through MCP.
- Generate SQL from approved metrics, joins, filters, and dimensions.
-- Explain metric provenance with wiki context and source evidence.
+- Explain metric provenance with wiki content and source evidence.
- Repair context through reviewable YAML and Markdown diffs.
- Work alongside dbt, MetricFlow, LookML, Looker, Metabase, Notion, and
supported databases.
diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 14fe476f..e43dbf29 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -117,7 +117,7 @@ The wizard walks you through everything KTX needs in one pass:
SQLite, PostgreSQL, MySQL, SQL Server, BigQuery, and Snowflake.
5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker,
Metabase, or Notion. You can skip and add them later.
-6. **Build** - runs the first ingest so semantic-layer sources and wiki pages
+6. **Build** - runs the first ingest so semantic sources and wiki pages
are ready for agents.
7. **Agent integration** - installs project-local rules for Claude Code,
Codex, Cursor, OpenCode, or universal `.agents`.
@@ -204,7 +204,7 @@ KTX writes plain files so people and agents can review changes in git.
|------|---------|
| `ktx.yaml` | Project configuration |
| `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml` - do not commit |
-| `semantic-layer/- {'KTX is an open-source context layer for database agents. It turns warehouse metadata, BI models, query history, docs, and approved metric definitions into reviewable files agents can search and execute.'} + {'KTX is an open-source context layer for data agents. It turns warehouse metadata, BI tool definitions, query history, docs, and approved metric definitions into reviewable files agents can search and execute.'}