apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-10 08:05:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: standardize ktx naming

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-20 17:32:15 +02:00
parent 27afd6a3b0
commit 1f8c1089f6
41 changed files with 331 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

37
AGENTS.md
View file

@ -1,6 +1,6 @@
# KTX Development Notes
# ktx Development Notes
KTX is a standalone open-source context layer for database agents. These
**ktx** is a standalone open-source context layer for database agents. These
instructions apply to all agents working in this repository (Codex, Claude,
Gemini, and similar tools). Do not assume an external app server, frontend,
database migrations, ORPC contracts, or `python-service/` layout exist here.
@ -22,9 +22,9 @@ database migrations, ORPC contracts, or `python-service/` layout exist here.
- **MUST**: Remove dead code; do not leave commented-out code, unused wrappers,
or empty directories.
- **MUST**: Keep package/public API changes intentional. Do not add compatibility
wrappers for old KTX names unless the user explicitly asks for a migration
wrappers for old **ktx** names unless the user explicitly asks for a migration
bridge.
- **MUST**: Treat KTX as having no public users unless the user says otherwise.
- **MUST**: Treat **ktx** as having no public users unless the user says otherwise.
Legacy support is not necessary by default; prefer clean breaking changes over
compatibility shims, migration bridges, or preserved stale behavior.
@ -40,7 +40,7 @@ database migrations, ORPC contracts, or `python-service/` layout exist here.
commit when the user asks to save work in progress.
- **MUST NOT**: Reintroduce external app conventions such as ORPC contracts,
NestJS controllers, frontend routes, `routeTree.gen.ts`, or app database
migration commands unless those systems are intentionally added to KTX later.
migration commands unless those systems are intentionally added to **ktx** later.
### Language Convention
@ -61,7 +61,7 @@ When rules conflict, follow this order:
## Repository Shape
KTX is a pnpm + uv workspace.
**ktx** is a pnpm + uv workspace.
- TypeScript packages: `packages/*`
- CLI package: `packages/cli`
@ -69,7 +69,7 @@ KTX is a pnpm + uv workspace.
- LLM package: `packages/llm`
- Database connectors: `packages/connector-*`
- Python semantic layer: `python/ktx-sl`
- KTX daemon: `python/ktx-daemon`
- **ktx** daemon: `python/ktx-daemon`
- Examples and fixtures: `examples/`
- Workspace scripts: `scripts/`
- Local agent skills and internal planning docs are private overlays. Do not
@ -134,7 +134,7 @@ shared contracts or package exports are affected.
test file
- TypeScript dead-code tooling/config changes: `pnpm run dead-code`
- Python semantic layer: `uv run pytest python/ktx-sl/tests -q`
- KTX daemon: `uv run pytest python/ktx-daemon/tests -q`
- **ktx** daemon: `uv run pytest python/ktx-daemon/tests -q`
- Python files: also run `uv run pre-commit run --files [FILES]` when
pre-commit is configured
@ -164,7 +164,7 @@ pnpm run test 2>&1 | tee /tmp/ktx-test-output.log
### Dead TypeScript Code Checks
KTX uses Biome for local unused-code linting and Knip for workspace graph
**ktx** uses Biome for local unused-code linting and Knip for workspace graph
analysis. These checks are intentionally part of CI and pre-commit because the
normal development workflow is agent-based.
@ -240,10 +240,27 @@ use `PascalCase` without the suffix.
- Prefer concrete commands, file paths, and acceptance criteria over broad
prose.
- When documenting examples, ensure referenced files and commands exist in the
standalone KTX tree.
standalone **ktx** tree.
- Remove or rewrite stale external app references unless the doc is explicitly
historical.
### Product Naming
- **MUST**: Write the product name as lowercase `ktx`.
- **MUST**: In Markdown prose, write `**ktx**` so the product name stays
visually distinct from surrounding text.
- **MUST**: Use code font for the CLI command, binary, package/path fragments,
configuration files, environment variables, source identifiers, and copied
terminal output, for example `ktx`, `ktx setup`, `ktx.yaml`,
`KTX_PROJECT_DIR`, and `.ktx/`.
- **MUST**: Use plain lowercase `ktx` in frontmatter, metadata, alt text,
headings, nav labels, badges, UI strings, and generated index strings where
Markdown emphasis is not rendered or would be visually noisy.
- **MUST NOT**: Write the bare all-caps spelling for the product name in docs prose.
Keep uppercase only when it is part of an exact environment variable,
source-code identifier, package/API name, or other literal value that must
match the implementation.
### Updating `docs-site/` After Code Changes
Before finishing a task, decide whether `docs-site/content/docs/` needs an

38
README.md
View file

@ -1,5 +1,5 @@
<h1 align="center">
<img src="assets/ktx-lockup.svg" alt="KTX" width="500" />
<img src="assets/ktx-lockup.svg" alt="ktx" width="500" />
</h1>
<h1 align="center">
@ -10,15 +10,15 @@
<a href="https://www.npmjs.com/package/@kaelio/ktx"><img src="https://img.shields.io/npm/v/@kaelio/ktx?style=flat-square&color=f97316" alt="npm version" /></a>
<a href="https://codecov.io/gh/Kaelio/ktx"><img src="https://codecov.io/gh/Kaelio/ktx/graph/badge.svg?branch=main" alt="Codecov" /></a>
<a href="https://github.com/Kaelio/ktx/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/Kaelio/ktx/ci.yml?branch=main&label=tests&style=flat-square" alt="Tests" /></a>
<a href="https://docs.kaelio.com/ktx/docs/"><img src="https://img.shields.io/badge/docs-KTX-22c55e?style=flat-square" alt="Documentation" /></a>
<a href="https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ"><img src="https://img.shields.io/badge/slack-join%20community-4A154B?style=flat-square&logo=slack&logoColor=white" alt="Join the KTX Slack community" /></a>
<a href="https://docs.kaelio.com/ktx/docs/"><img src="https://img.shields.io/badge/docs-ktx-22c55e?style=flat-square" alt="Documentation" /></a>
<a href="https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ"><img src="https://img.shields.io/badge/slack-join%20community-4A154B?style=flat-square&logo=slack&logoColor=white" alt="Join the ktx Slack community" /></a>
<a href="https://github.com/Kaelio/ktx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License" /></a>
<a href="https://www.ycombinator.com/companies?batch=P25"><img src="https://img.shields.io/badge/Y%20Combinator-P25-orange?style=flat-square" alt="Y Combinator P25" /></a>
</p>
---
KTX is a self-improving context layer that teaches agents how to query your
**ktx** is a self-improving context layer that teaches agents how to query your
warehouse accurately - from approved metric definitions, joinable columns, and
business knowledge it builds and maintains for you.
@ -26,9 +26,9 @@ Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and
SQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion.
Runs with your own LLM API keys or a Claude
Pro/Max subscription - no extra usage billing from KTX.
Pro/Max subscription - no extra usage billing from **ktx**.
## Why KTX
## Why ktx
General-purpose agents struggle on data tasks. They re-explore your warehouse
on every question, invent their own metric logic, and return numbers that
@ -37,7 +37,7 @@ don't match approved definitions.
Traditional semantic layers don't fix this. They demand constant manual
upkeep and don't absorb the rest of your company's knowledge.
KTX does both, automatically:
**ktx** does both, automatically:
- **Learns from company knowledge.** Ingests wiki content, organizes it,
removes duplicates, and flags contradictions for human review.
@ -55,13 +55,13 @@ Agents can run raw SQL when they need it, or compose semantic-layer queries
when they want approved metrics with reliable joins.
<p align="center">
<img src="docs-site/public/images/ingestion-flow-transparent.svg" alt="KTX ingestion flow from source systems through validation to wiki and semantic-layer outputs" width="900" />
<img src="docs-site/public/images/ingestion-flow-transparent.svg" alt="ktx ingestion flow from source systems through validation to wiki and semantic-layer outputs" width="900" />
</p>
## Agent Setup
Ask an agent such as Claude Code, Codex, Cursor, or OpenCode to install and
configure KTX from your project directory:
configure **ktx** from your project directory:
```text
Follow instructions from
@ -77,19 +77,19 @@ ktx setup
ktx status
```
`ktx setup` creates or resumes a local KTX project, configures providers and
`ktx setup` creates or resumes a local **ktx** project, configures providers and
connections, builds context, and installs agent integration.
Example `ktx status` output after setup:
```text
KTX project: /home/user/analytics
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
KTX context built: yes
ktx context built: yes
Agent integration ready: yes (codex:project)
```
@ -97,7 +97,7 @@ Agent integration ready: yes (codex:project)
| Command | Purpose |
|---------|---------|
| `ktx setup` | Create, resume, or update a KTX project |
| `ktx setup` | Create, resume, or update a **ktx** project |
| `ktx status` | Check project readiness |
| `ktx connection` | List configured connections |
| `ktx connection test` | Test every configured connection |
@ -135,7 +135,7 @@ Commit `ktx.yaml`, `semantic-layer/`, and `wiki/`. Keep `.ktx/` local.
## Agent Usage
Install KTX integration for Claude Code, Claude Desktop, Codex, Cursor,
Install **ktx** integration for Claude Code, Claude Desktop, Codex, Cursor,
OpenCode, and generic `.agents` clients:
```bash
@ -153,11 +153,11 @@ ktx wiki "refund policy" --json
ktx sl query --connection-id warehouse --measure orders.revenue --format sql
```
During setup, choose **Ask data questions with KTX MCP** for client agents.
Choose **Ask data questions + manage KTX with CLI commands** when an operator
During setup, choose **Ask data questions with ktx MCP** for client agents.
Choose **Ask data questions + manage ktx with CLI commands** when an operator
agent also needs pinned `ktx` admin commands.
After setup, KTX prints **Required before using agents** with the exact
After setup, **ktx** prints **Required before using agents** with the exact
commands to run. If the output includes `ktx mcp start --project-dir ...`, run
it before opening your agent. Claude Desktop uses its own launcher and prints
separate skill upload steps under `.ktx/agents/claude/`.
@ -198,7 +198,7 @@ pnpm run link:dev
ktx-dev --help
```
KTX is a pnpm + uv workspace:
**ktx** is a pnpm + uv workspace:
- TypeScript packages live in `packages/*`
- CLI source lives in `packages/cli`
@ -233,4 +233,4 @@ full guide on where to ask what.
## License
KTX is licensed under the Apache License, Version 2.0. See `LICENSE`.
**ktx** is licensed under the Apache License, Version 2.0. See `LICENSE`.

4
docs-site/app/global.css
View file

@ -9,7 +9,7 @@
}
/* ═══════════════════════════════════════════
KTX Light Theme - Warm Cream & Taupe
ktx Light Theme - Warm Cream & Taupe
═══════════════════════════════════════════ */
:root {
--color-fd-background: #faf9f6;
@ -42,7 +42,7 @@
}
/* ═══════════════════════════════════════════
KTX Dark Theme - Deep Ocean Slate
ktx Dark Theme - Deep Ocean Slate
═══════════════════════════════════════════ */
.dark {
--color-fd-background: #0f1719;

2
docs-site/app/layout.config.tsx
View file

@ -19,7 +19,7 @@ export const baseOptions: BaseLayoutProps = {
},
{
type: "icon",
label: "Join the KTX Slack community",
label: "Join the ktx Slack community",
icon: <SlackIcon />,
text: "Slack",
url: "https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ",

4
docs-site/app/layout.tsx
View file

@ -22,8 +22,8 @@ const geistMono = Geist_Mono({
export const metadata: Metadata = {
title: {
template: "%s | KTX Docs",
default: "KTX Docs",
template: "%s | ktx Docs",
default: "ktx Docs",
},
description:
"Open-source context infrastructure that makes agentic analytics reliable.",

4
docs-site/components/logo.tsx
View file

@ -17,10 +17,10 @@ export function Logo() {
</div>
<div className="flex flex-col items-start leading-none">
<span
className="text-[24px] font-semibold text-fd-foreground tracking-tight"
className="text-[42px] font-semibold text-fd-foreground tracking-tight"
style={{ fontFamily: "var(--font-display), var(--font-sans), sans-serif" }}
>
KTX
ktx
</span>
<span
className="mt-1 whitespace-nowrap text-[13px] font-medium text-fd-muted-foreground/80 tracking-tight"

6
docs-site/components/product-mechanics.tsx
View file

@ -125,7 +125,7 @@ const outputData: OutputNodeData[] = [
title: "Semantic layer",
path: "semantic-layer/*.yaml",
tags: ["structured", "executable", "auto-maintained"],
body: "Metrics, joins, tables, dimensions, filters, and segments that KTX can validate and compile into SQL.",
body: "Metrics, joins, tables, dimensions, filters, and segments that ktx can validate and compile into SQL.",
accent: "#3b82f6",
},
];
@ -511,7 +511,7 @@ export function ProductMechanics() {
How ingestion works
</h2>
<p className="mt-3 text-sm leading-6 text-fd-muted-foreground">
KTX ingests source evidence, reconciles it with your existing project,
ktx ingests source evidence, reconciles it with your existing project,
and produces durable context that agents can search, review, and
execute.
</p>
@ -519,7 +519,7 @@ export function ProductMechanics() {
<article
className="max-w-full min-w-0 overflow-hidden rounded-lg border border-fd-border bg-fd-card shadow-sm"
aria-label="KTX ingestion flow from source systems to durable context outputs"
aria-label="ktx ingestion flow from source systems to durable context outputs"
>
<div className="border-b border-fd-border bg-fd-muted/35 px-5 py-4">
<p className="text-xs font-semibold uppercase tracking-wide text-fd-primary">

36
docs-site/components/semantic-layer-flow.tsx
View file

@ -115,7 +115,7 @@ const WAREHOUSE_X = (CANVAS_W - WAREHOUSE_W) / 2;
const WAREHOUSE_Y = LANES_BOTTOM_Y + 56;
const MANUAL_STROKE = "#94a3b8";
const KTX_STROKE = "#0891b2";
const ktxStroke = "#0891b2";
const FIT_VIEW_OPTIONS = { padding: 0.05 };
const agent: AgentNode = {
@ -138,7 +138,7 @@ const manualSql: ManualSqlNode = {
position: { x: LEFT_LANE_X, y: LANE_TOP_Y },
data: {
variant: "manual",
badge: "Without KTX",
badge: "Without ktx",
title: "Agent writes the SQL",
caption:
"Stitches four tables, mixes grains, and ships numbers that won't match the dashboard.",
@ -208,7 +208,7 @@ const slQuery: SlQueryNode = {
position: { x: RIGHT_LANE_X, y: SL_QUERY_Y },
data: {
variant: "slQuery",
badge: "With KTX",
badge: "With ktx",
title: "Agent sends a semantic query",
caption:
"Names the measures, dimensions, segments, and filters it wants. No SQL, no joins.",
@ -282,7 +282,7 @@ const compiledSql: CompiledSqlNode = {
data: {
variant: "compiled",
badge: "Generated SQL",
title: "KTX returns dialect-correct SQL",
title: "ktx returns dialect-correct SQL",
caption:
"Pre-aggregates each fact at its own grain, then joins back on the shared dimension.",
code: `WITH orders_agg AS (
@ -435,31 +435,31 @@ const edges = [
labelStyle: {
fontSize: 12,
fontWeight: 600,
fill: KTX_STROKE,
fill: ktxStroke,
},
labelBgStyle: {
fill: "var(--color-fd-background)",
stroke: "var(--color-fd-border)",
strokeWidth: 1,
},
style: { stroke: KTX_STROKE, strokeWidth: 1.75 },
markerEnd: arrowMarker(KTX_STROKE),
style: { stroke: ktxStroke, strokeWidth: 1.75 },
markerEnd: arrowMarker(ktxStroke),
},
{
id: "slquery-engine",
source: "sl-query",
target: "engine",
type: "straight" as const,
style: { stroke: KTX_STROKE, strokeWidth: 1.75 },
markerEnd: arrowMarker(KTX_STROKE),
style: { stroke: ktxStroke, strokeWidth: 1.75 },
markerEnd: arrowMarker(ktxStroke),
},
{
id: "engine-compiled",
source: "engine",
target: "compiled-sql",
type: "straight" as const,
style: { stroke: KTX_STROKE, strokeWidth: 1.75 },
markerEnd: arrowMarker(KTX_STROKE),
style: { stroke: ktxStroke, strokeWidth: 1.75 },
markerEnd: arrowMarker(ktxStroke),
},
{
id: "compiled-warehouse",
@ -467,8 +467,8 @@ const edges = [
target: "warehouse",
targetHandle: "warehouse-compiled",
type: "straight" as const,
style: { stroke: KTX_STROKE, strokeWidth: 1.75 },
markerEnd: arrowMarker(KTX_STROKE),
style: { stroke: ktxStroke, strokeWidth: 1.75 },
markerEnd: arrowMarker(ktxStroke),
},
];
@ -530,7 +530,7 @@ function LaneBadge({
<span
className="h-1.5 w-1.5 rounded-full"
style={{
background: variant === "manual" ? MANUAL_STROKE : KTX_STROKE,
background: variant === "manual" ? MANUAL_STROKE : ktxStroke,
}}
/>
{children}
@ -842,7 +842,7 @@ function EngineNodeView({ data }: NodeProps<EngineNode>) {
>
<span
className="absolute inset-y-0 left-0 w-[3px] rounded-l-lg"
style={{ background: KTX_STROKE }}
style={{ background: ktxStroke }}
aria-hidden="true"
/>
<Handle type="target" position={Position.Top} className="!opacity-0" />
@ -908,7 +908,7 @@ function CompiledSqlNodeView({ data }: NodeProps<CompiledSqlNode>) {
>
<span
className="mt-[6px] h-1 w-1 flex-none rounded-full"
style={{ background: KTX_STROKE }}
style={{ background: ktxStroke }}
aria-hidden="true"
/>
<span>{note}</span>
@ -997,7 +997,7 @@ export function SemanticLayerFlow() {
>
<article
className="max-w-full min-w-0 overflow-hidden rounded-lg border border-fd-border bg-fd-card shadow-sm"
aria-label="From semantic query to executed SQL: contrast between agent-authored SQL and KTX-compiled SQL"
aria-label="From semantic query to executed SQL: contrast between agent-authored SQL and ktx-compiled SQL"
>
<div className="border-b border-fd-border bg-fd-muted/35 px-5 py-4">
<a
@ -1022,7 +1022,7 @@ export function SemanticLayerFlow() {
<p className="mt-2 max-w-3xl text-xs leading-5 text-fd-muted-foreground">
On the left, the agent works imperatively: chooses tables, writes
joins, picks the grain, and remembers each warehouse's dialect. On
the right, the agent only declares what it wants. KTX handles
the right, the agent only declares what it wants. ktx handles
every how.
</p>
</div>

4
docs-site/components/terminal-preview.tsx
View file

@ -15,7 +15,7 @@ export function TerminalPreview() {
<span className="term-cmd">ktx setup</span>
</div>
<div className="h-2" />
<div className="term-dim">◆ Welcome to KTX setup</div>
<div className="term-dim">◆ Welcome to ktx setup</div>
<div className="term-dim">│</div>
<div>
<span className="term-dim">◇</span>{" "}
@ -43,7 +43,7 @@ export function TerminalPreview() {
enriching schema · detecting relationships · ingesting dbt
</div>
<div className="h-2" />
<div className="term-ok">✓ KTX context is ready for agents.</div>
<div className="term-ok">✓ ktx context is ready for agents.</div>
<div className="h-2" />
<div>
<span className="term-prompt">$</span>{" "}

22
docs-site/content/agents-setup.md
View file

@ -1,6 +1,6 @@
# Goal
Set up KTX from scratch end-to-end as a fully autonomous, agent-driven replacement for the interactive `ktx setup` wizard. Detect the environment, install missing prerequisites, ask the user only for information you genuinely need (which connections to add, credentials), write a valid configuration, verify it works, and run a fast ingest. Keep the user updated throughout.
Set up **ktx** from scratch end-to-end as a fully autonomous, agent-driven replacement for the interactive `ktx setup` wizard. Detect the environment, install missing prerequisites, ask the user only for information you genuinely need (which connections to add, credentials), write a valid configuration, verify it works, and run a fast ingest. Keep the user updated throughout.
# Operating principles
@ -14,7 +14,7 @@ Set up KTX from scratch end-to-end as a fully autonomous, agent-driven replaceme
# Authoritative docs
KTX docs are served at `https://docs.kaelio.com/ktx/`. **Start by fetching `https://docs.kaelio.com/ktx/llms.txt`** to discover the docs map. Scan it for a "troubleshooting" entry - if one exists, read it **before** running install/setup so you can apply known fixes preemptively rather than after failing. If no troubleshooting page is listed (current state of the docs), proceed. Then fetch any other `.md` pages you need (setup, ingest, status, connection types). **Never invent CLI flags or config keys** - verify against the docs or `ktx --help` / `ktx <subcommand> --help`.
**ktx** docs are served at `https://docs.kaelio.com/ktx/`. **Start by fetching `https://docs.kaelio.com/ktx/llms.txt`** to discover the docs map. Scan it for a "troubleshooting" entry - if one exists, read it **before** running install/setup so you can apply known fixes preemptively rather than after failing. If no troubleshooting page is listed (current state of the docs), proceed. Then fetch any other `.md` pages you need (setup, ingest, status, connection types). **Never invent CLI flags or config keys** - verify against the docs or `ktx --help` / `ktx <subcommand> --help`.
> **Note on the `ktx status` JSON example in the docs.** The docs page for `ktx status` shows an example shaped like `{"title": "...", "checks": [...]}`. That example is outdated. The real CLI output uses a top-level `verdict` field plus a `connections[]` array - see Phase 5 for the canonical success criteria. Trust the shape in this prompt over the docs example.
@ -28,7 +28,7 @@ Determine the host OS (e.g. via `uname -s`, `process.platform`, or `$env:OS`). U
|------|---------------|----------------------|
| `uv` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` then re-source shell env | `irm https://astral.sh/uv/install.ps1 \| iex` |
| Node.js | use system / fnm / nvm - **do not** auto-install | use system / nvm-windows - **do not** auto-install |
| KTX CLI | `npm install -g …` (see Phase 2) | `npm install -g …` (see Phase 2) |
| **ktx** CLI | `npm install -g …` (see Phase 2) | `npm install -g …` (see Phase 2) |
If Node.js is missing, **stop and ask the user** to install it (https://nodejs.org/). Do not attempt to auto-install Node.
@ -38,7 +38,7 @@ Check each tool in order; install only if missing.
1. **Node.js** - run `node --version`. Require >= 22. If missing or older, stop and instruct the user.
2. **`uv`** - run `uv --version`. If missing, run the OS-appropriate install command, then re-source the shell environment (`export PATH="$HOME/.local/bin:$PATH"` on Linux/macOS) so `uv` is on `PATH`.
3. **KTX CLI** -
3. **ktx CLI** -
- Install ktx with `npm install -g @kaelio/ktx`
- Verify with `ktx --version`.
@ -55,7 +55,7 @@ Ask the user (grouped if your harness supports it; otherwise sequentially):
- Connection name (e.g. `warehouse`, `analytics`).
- Driver: one of `sqlite`, `postgres`, `mysql`, `sqlserver`, `bigquery`, `snowflake`.
- Connection URL/DSN (or service-account file for BigQuery). Accept `env:VAR_NAME` or `file:/abs/path` to avoid pasting raw secrets.
- **Heads-up for the user**: even if they paste a literal URL, KTX will silently relocate it into `<project>/.ktx/secrets/<connection>-url` and rewrite `ktx.yaml` to `url: file:…` - this is correct, secure behavior and not a bug.
- **Heads-up for the user**: even if they paste a literal URL, **ktx** will silently relocate it into `<project>/.ktx/secrets/<connection>-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. **Context sources** (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Default: none. Ask only if the user mentions them.
@ -97,7 +97,7 @@ Notes on the flags above:
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.
ktx context build did not pass agent-readiness verification.
<connection>: deep database context has not completed.
```
@ -146,7 +146,7 @@ Success requires (canonical shape - supersedes the example in the docs):
Do **not** run `--deep` ingest in this flow - that requires LLM time and is out of scope.
### Optional: directly probe the KTX daemon
### Optional: directly probe the ktx daemon
If the user asks for stronger verification that `sentence-transformers` is actually serving (not just that setup said "ok"), do all of:
@ -155,19 +155,19 @@ If the user asks for stronger verification that `sentence-transformers` is actua
3. `curl -sS http://127.0.0.1:<port>/health` → expect HTTP 200 with `{"status":"healthy",…}`.
4. `curl -sS -X POST http://127.0.0.1:<port>/embeddings/compute -H 'content-type: application/json' -d '{"text":"hello"}'` → expect `{"embedding": [...384 floats...]}`.
Discover the port from setup's log line `Started KTX daemon: http://127.0.0.1:<port>` or from the daemon's OpenAPI at `GET /openapi.json`. Note: the routes are `/health` and `/embeddings/compute` - not `/healthz` or `/embeddings`.
Discover the port from setup's log line `Started ktx daemon: http://127.0.0.1:<port>` or from the daemon's OpenAPI at `GET /openapi.json`. Note: the routes are `/health` and `/embeddings/compute` - not `/healthz` or `/embeddings`.
## Phase 6 - Final report
Print a structured report:
```
KTX SETUP COMPLETE
ktx SETUP COMPLETE
Project: <path>
LLM: <backend> / <model>
Embeddings: <backend> / <model>
Runtime: managed Python ✓ (if the KTX daemon was started)
Runtime: managed Python ✓ (if the ktx daemon was started)
Connections:
- <name> (<driver>) status=ok schemas=[…] tables=<N>
@ -198,4 +198,4 @@ End with a single line: `RESULT: PASS` or `RESULT: FAIL - <one-line reason>`.
- On failure: capture the error, fetch the relevant docs page, fix the cause, retry. Never retry an unchanged command.
- Known soft-failures (listed in Phase 4 and Phase 5) are not real failures - handle them as documented; do not retry or escalate.
- If you find a docs/CLI gap ("docs say X but CLI does Y"), call it out in the final report.
- Never commit credentials - KTX accepts `env:` and `file:` references; prefer those. KTX will also auto-relocate literal URLs into `.ktx/secrets/`, but that does not protect anyone who pasted the URL into chat history.
- Never commit credentials - **ktx** accepts `env:` and `file:` references; prefer those. **ktx** will also auto-relocate literal URLs into `.ktx/secrets/`, but that does not protect anyone who pasted the URL into chat history.

12
docs-site/content/docs/ai-resources/agent-instructions.mdx
View file

@ -1,12 +1,12 @@
---
title: Agent Instructions
description: Suggested instructions for coding assistants that need to read and cite KTX docs.
description: Suggested instructions for coding assistants that need to read and cite ktx docs.
---
Use these instructions when a coding assistant needs to answer questions from the KTX documentation.
Use these instructions when a coding assistant needs to answer questions from the **ktx** documentation.
```text
When answering KTX docs questions:
When answering ktx docs questions:
1. Start with https://docs.kaelio.com/ktx/llms.txt.
2. Fetch the smallest relevant Markdown page from the index.
@ -20,7 +20,7 @@ When answering KTX docs questions:
This page is for documentation consumption only:
- answering questions about KTX
- answering questions about **ktx**
- finding the right docs page
- citing setup or CLI guidance
- helping an assistant avoid stale or invented commands
@ -30,11 +30,11 @@ It does not describe local tool configuration.
## Minimal project prompt
```text
You are helping with KTX. Read https://docs.kaelio.com/ktx/llms.txt first, then fetch only the Markdown pages needed for the task. Do not scrape the rendered docs site when a .md route exists.
You are helping with ktx. Read https://docs.kaelio.com/ktx/llms.txt first, then fetch only the Markdown pages needed for the task. Do not scrape the rendered docs site when a .md route exists.
```
## Repository prompt
```text
Before editing KTX docs, read /llms.txt and the affected .md docs pages. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and any changed .md routes.
Before editing ktx docs, read /llms.txt and the affected .md docs pages. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and any changed .md routes.
```

10
docs-site/content/docs/ai-resources/agent-quickstart.mdx
View file

@ -1,13 +1,13 @@
---
title: Agent Quickstart
description: A task-first route for coding agents that need to understand KTX docs.
description: A task-first route for coding agents that need to understand ktx docs.
---
This page is for coding assistants reading or citing the KTX docs. It is intentionally limited to documentation lookup, docs navigation, and safe command discovery.
This page is for coding assistants reading or citing the **ktx** docs. It is intentionally limited to documentation lookup, docs navigation, and safe command discovery.
For Markdown endpoints, use [Markdown Access](/docs/ai-resources/markdown-access).
For reusable task prompts, use [Prompt Recipes](/docs/ai-resources/prompt-recipes).
To install KTX into an agent client, use [Agent Clients](/docs/integrations/agent-clients).
To install **ktx** into an agent client, use [Agent Clients](/docs/integrations/agent-clients).
## First read
@ -21,7 +21,7 @@ Agents should start with the smallest source that answers the task:
| User asks the agent to explain... | Read first | Then read |
|------------------------------------|------------|-----------|
| What KTX does | [Introduction](/docs/getting-started/introduction) | [The Context Layer](/docs/concepts/the-context-layer) |
| What **ktx** does | [Introduction](/docs/getting-started/introduction) | [The Context Layer](/docs/concepts/the-context-layer) |
| How to start from a checkout | [Quickstart](/docs/getting-started/quickstart) | [ktx setup](/docs/cli-reference/ktx-setup) |
| How to check project readiness | [ktx status](/docs/cli-reference/ktx-status) | [Quickstart](/docs/getting-started/quickstart) |
| How context gets built | [Building Context](/docs/guides/building-context) | [ktx ingest](/docs/cli-reference/ktx-ingest) |
@ -30,7 +30,7 @@ Agents should start with the smallest source that answers the task:
## Operating workflow
Use this workflow when the user asks an assistant to answer a KTX docs question:
Use this workflow when the user asks an assistant to answer a **ktx** docs question:
1. Read [`/llms.txt`](/llms.txt).
2. Pick the smallest relevant `.md` page.

4
docs-site/content/docs/ai-resources/markdown-access.mdx
View file

@ -1,9 +1,9 @@
---
title: Markdown Access
description: Fetch KTX docs as llms.txt, llms-full.txt, or per-page Markdown.
description: Fetch ktx docs as llms.txt, llms-full.txt, or per-page Markdown.
---
KTX docs are available as plain Markdown so assistants do not need to parse the rendered HTML site.
**ktx** docs are available as plain Markdown so assistants do not need to parse the rendered HTML site.
## Index

20
docs-site/content/docs/ai-resources/prompt-recipes.mdx
View file

@ -1,54 +1,54 @@
---
title: Prompt Recipes
description: Copyable prompts for common KTX agent workflows.
description: Copyable prompts for common ktx agent workflows.
---
Use these prompts when asking a coding assistant to work with KTX. Replace project names, connection ids, and business terms with your own values.
Use these prompts when asking a coding assistant to work with **ktx**. Replace project names, connection ids, and business terms with your own values.
## Learn the docs
```text
Read https://docs.kaelio.com/ktx/llms.txt first. Then fetch only the KTX Markdown pages needed for this task. Do not scrape rendered HTML unless no Markdown route exists.
Read https://docs.kaelio.com/ktx/llms.txt first. Then fetch only the ktx Markdown pages needed for this task. Do not scrape rendered HTML unless no Markdown route exists.
```
## Set up a project
```text
Set up KTX in this repository. Start by reading /docs/ai-resources/agent-quickstart.md and /docs/getting-started/quickstart.md. Install the published CLI with npm; use pnpm only when working from a KTX source checkout. After setup, run ktx status and summarize which steps are complete, which files changed, and what still needs credentials or user input.
Set up ktx in this repository. Start by reading /docs/ai-resources/agent-quickstart.md and /docs/getting-started/quickstart.md. Install the published CLI with npm; use pnpm only when working from a ktx source checkout. After setup, run ktx status and summarize which steps are complete, which files changed, and what still needs credentials or user input.
```
## Find a command
```text
Find the correct KTX command for this task: <task>. Start with /llms.txt, then fetch the smallest relevant CLI reference .md page. Quote the exact command and flags from the docs.
Find the correct ktx command for this task: <task>. Start with /llms.txt, then fetch the smallest relevant CLI reference .md page. Quote the exact command and flags from the docs.
```
## Explain setup
```text
Explain how to set up KTX for this repo. Read /docs/getting-started/quickstart.md and the relevant CLI reference pages. Summarize prerequisites, commands, generated files, and any credentials the user must provide manually.
Explain how to set up ktx for this repo. Read /docs/getting-started/quickstart.md and the relevant CLI reference pages. Summarize prerequisites, commands, generated files, and any credentials the user must provide manually.
```
## Compare concepts
```text
Explain the difference between these KTX concepts: <concepts>. Start from /llms.txt, fetch the relevant concept and guide pages as Markdown, and answer with links to the source pages.
Explain the difference between these ktx concepts: <concepts>. Start from /llms.txt, fetch the relevant concept and guide pages as Markdown, and answer with links to the source pages.
```
## Review semantic changes
```text
Review the KTX semantic-layer and knowledge changes in this branch. Check that measures have clear definitions, joins use valid keys, hidden/internal columns are not exposed to agents, and validation passes. List concrete file and line issues first.
Review the ktx semantic-layer and knowledge changes in this branch. Check that measures have clear definitions, joins use valid keys, hidden/internal columns are not exposed to agents, and validation passes. List concrete file and line issues first.
```
## Copy exact docs source
```text
Open the relevant KTX docs page and use the page action to copy the generated Markdown or source MDX. Preserve code fences and tables exactly.
Open the relevant ktx docs page and use the page action to copy the generated Markdown or source MDX. Preserve code fences and tables exactly.
```
## Update docs
```text
Update the KTX docs for agent readability. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and the affected .md routes.
Update the ktx docs for agent readability. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and the affected .md routes.
```

20
docs-site/content/docs/cli-reference/ktx-admin.mdx
View file

@ -19,9 +19,9 @@ ktx admin <subcommand> [options]
| Subcommand | Description |
|-----------|-------------|
| `init [directory]` | Initialize a Git-backed KTX project directory for maintenance scripts |
| `init [directory]` | Initialize a Git-backed **ktx** project directory for maintenance scripts |
| `schema` | Print a JSON Schema describing `ktx.yaml` |
| `runtime` | Install, start, stop, and inspect the KTX-managed Python runtime |
| `runtime` | Install, start, stop, and inspect the **ktx**-managed Python runtime |
| `reindex` | Sync local wiki and semantic-layer search indexes from disk |
## `admin init`
@ -44,8 +44,8 @@ directory. Use it from any directory to generate editor or agent schema files.
| Subcommand | Description |
|-----------|-------------|
| `install` | Install the bundled Python runtime wheel into the managed runtime |
| `start` | Start the KTX daemon |
| `stop` | Stop the KTX daemon |
| `start` | Start the **ktx** daemon |
| `stop` | Stop the **ktx** daemon |
| `status` | Show managed Python runtime status and readiness checks |
## `admin runtime` Options
@ -56,7 +56,7 @@ directory. Use it from any directory to generate editor or agent schema files.
| `--json` | Print JSON output for `status` | `false` |
| `--yes` | Accepted by `install` for scripted install commands | `false` |
| `--force` | Reinstall for `install`, or restart for `start` | `false` |
| `--all` | Stop all recorded or discoverable KTX daemon processes with `stop` | `false` |
| `--all` | Stop all recorded or discoverable **ktx** daemon processes with `stop` | `false` |
## Examples
@ -102,15 +102,15 @@ ktx admin reindex --output plain
ktx admin reindex --json
```
By default, KTX compares stored search text with the files on disk. It only
By default, **ktx** compares stored search text with the files on disk. It only
re-embeds changed rows and removes rows for files that no longer exist. With
`--force`, KTX clears each discovered scope first and then rebuilds it.
`--force`, **ktx** clears each discovered scope first and then rebuilds it.
When embeddings are not configured, KTX still writes lexical FTS rows and
prints an embeddings warning. If a scope fails, KTX keeps processing the
When embeddings are not configured, **ktx** still writes lexical FTS rows and
prints an embeddings warning. If a scope fails, **ktx** keeps processing the
remaining scopes and exits with code `1` after output is written. If the local
state database cannot open or the configured managed embedding runtime is
missing, KTX prints the error and exits with code `1`.
missing, **ktx** prints the error and exits with code `1`.
## Common errors

2
docs-site/content/docs/cli-reference/ktx-connection.mdx
View file

@ -3,7 +3,7 @@ title: "ktx connection"
description: "List and test configured database and context-source connections."
---
Inspect configured connections in your KTX project. Connections define how KTX
Inspect configured connections in your **ktx** project. Connections define how **ktx**
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.

18
docs-site/content/docs/cli-reference/ktx-ingest.mdx
View file

@ -1,10 +1,10 @@
---
title: "ktx ingest"
description: "Build or refresh KTX context, or capture text into KTX memory."
description: "Build or refresh ktx context, or capture text into ktx memory."
---
`ktx ingest` builds or refreshes KTX context from configured connections, and
can also capture free-form text into KTX memory. Database connections build
`ktx ingest` builds or refreshes **ktx** context from configured connections, and
can also capture free-form text into **ktx** memory. Database connections build
schema context. Context-source connections ingest metadata from tools such as
dbt, Looker, Metabase, MetricFlow, LookML, and Notion. Pass `--text` or
`--file` to capture inline text or text files into memory instead.
@ -18,7 +18,7 @@ ktx ingest [options] [connectionId]
- Bare `ktx ingest` (no positional, no `--all`) ingests every configured
connection.
- `ktx ingest <connectionId>` ingests one configured connection.
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into KTX
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into **ktx**
memory instead of ingesting a connection.
Database connections run before context-source connections when more than one
@ -34,9 +34,9 @@ connection is selected.
| `--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 <days>` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
| `--text <content>` | Capture inline text into KTX memory; repeatable | `[]` |
| `--file <path>` | Capture a text file into KTX memory; use `-` for stdin; repeatable | `[]` |
| `--connection-id <connectionId>` | KTX connection id to tag captured text/file notes | - |
| `--text <content>` | Capture inline text into **ktx** memory; repeatable | `[]` |
| `--file <path>` | Capture a text file into **ktx** memory; use `-` for stdin; repeatable | `[]` |
| `--connection-id <connectionId>` | **ktx** connection id to tag captured text/file notes | - |
| `--user-id <id>` | Memory user id for text/file capture attribution | `local-cli` |
| `--fail-fast` | Stop after the first failed text/file item | `false` |
| `--plain` | Print plain text output | `true` |
@ -54,7 +54,7 @@ requires deep ingest readiness.
When more than one connection is selected, database ingest runs first, then
context-source ingest and memory updates run for context-source connections.
Some ingest paths use the managed KTX Python runtime. Query-history ingest uses
Some ingest paths use the managed **ktx** Python runtime. Query-history ingest uses
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
@ -141,7 +141,7 @@ jq -c '. | {at, level, phase, event, durationMs, data, error}' \
.ktx/ingest-traces/<jobId>/trace.jsonl
```
KTX writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
**ktx** writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
`error`, `info`, `debug`, or `trace` before running ingest to change the trace
verbosity:

10
docs-site/content/docs/cli-reference/ktx-mcp.mdx
View file

@ -1,9 +1,9 @@
---
title: "ktx mcp"
description: "Run the KTX MCP HTTP server for agent clients."
description: "Run the ktx MCP HTTP server for agent clients."
---
`ktx mcp` starts, stops, inspects, and tails the local KTX MCP server for a KTX
`ktx mcp` starts, stops, inspects, and tails the local **ktx** MCP server for a **ktx**
project. Use it when an agent client connects through MCP instead of generated
CLI instructions.
@ -17,8 +17,8 @@ ktx mcp <subcommand> [options]
| Subcommand | Description |
|-----------|-------------|
| `start` | Start the KTX MCP HTTP server |
| `stop` | Stop the KTX MCP daemon |
| `start` | Start the **ktx** MCP HTTP server |
| `stop` | Stop the **ktx** MCP daemon |
| `status` | Show daemon status, URL, PID, token mode, and project path |
| `logs` | Print the daemon log |
@ -65,6 +65,6 @@ hosts and origins for browser clients.
| Error | Cause | Recovery |
|-------|-------|----------|
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or pass `--project-dir <path>` |
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a **ktx** project or pass `--project-dir <path>` |
| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |

22
docs-site/content/docs/cli-reference/ktx-setup.mdx
View file

@ -1,14 +1,14 @@
---
title: "ktx setup"
description: "Set up or resume a local KTX project."
description: "Set up or resume a local ktx project."
---
`ktx setup` is the guided configuration flow for a local KTX project. It can
`ktx setup` is the guided configuration flow for a local **ktx** project. It can
create or resume `ktx.yaml`, configure LLM and embedding providers, add
database and context-source connections, prepare required runtime features,
build initial context, and install agent integrations.
When you run bare `ktx` in an interactive terminal outside any KTX project, the
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
CLI starts this same setup flow. Inside an existing project, `ktx setup`
resumes from incomplete setup state or opens the setup menu.
@ -52,7 +52,7 @@ prompts.
| Flag | Description |
|------|-------------|
| `--llm-backend <backend>` | LLM backend: `anthropic`, `vertex`, or `claude-code` |
| `--llm-backend claude-code` | Use the local Claude Code session for KTX LLM calls |
| `--llm-backend claude-code` | Use the local Claude Code session for **ktx** LLM calls |
| `--llm-model <model>` | LLM model ID or backend model alias to validate and save |
| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
| `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
@ -75,7 +75,7 @@ of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts
| `--embedding-api-key-file <path>` | File containing the embedding provider API key |
| `--skip-embeddings` | Leave embedding setup incomplete |
`sentence-transformers` uses the KTX-managed Python runtime. Choose only one
`sentence-transformers` uses the **ktx**-managed Python runtime. Choose only one
embedding credential source.
### Runtime
@ -84,9 +84,9 @@ Setup prepares the managed Python runtime when your selected configuration
needs it. In the full setup flow, the runtime step runs after database and
context-source setup and before the initial context build.
KTX prepares the `core` runtime feature when query-history ingest, Looker
**ktx** prepares the `core` runtime feature when query-history ingest, Looker
context-source ingest, database introspection fallback, or daemon-backed
context build paths need it. KTX prepares the `local-embeddings` runtime feature when you
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.
@ -109,7 +109,7 @@ runtime features are missing.
| `--database-schema <schema>` | Database schema or dataset to include; repeatable |
| `--skip-databases` | Leave database setup incomplete |
KTX needs at least one database connection before it can build database
**ktx** needs at least one database connection before it can build database
context. Use `--skip-databases` only when intentionally leaving the project
incomplete.
@ -165,7 +165,7 @@ ktx setup
# Run setup for a specific project directory
ktx setup --project-dir ./analytics
# Use Claude Code with Opus for KTX LLM calls
# Use Claude Code with Opus for ktx LLM calls
ktx setup \
--project-dir ./analytics \
--llm-backend claude-code \
@ -211,14 +211,14 @@ Interactive setup renders prompts and progress messages. Use `ktx status` to
check setup and context readiness after setup exits.
```text
KTX project: /home/user/analytics
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
Runtime ready: yes (core)
KTX context built: yes
ktx context built: yes
Agent integration ready: yes (codex:project)
```

6
docs-site/content/docs/cli-reference/ktx-sl.mdx
View file

@ -35,7 +35,7 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | Filter by KTX connection id | - |
| `--connection-id <id>` | Filter by **ktx** connection id | - |
| `--limit <number>` | Maximum search results (search mode only) | - |
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
@ -44,13 +44,13 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | KTX connection id (required) | - |
| `--connection-id <id>` | **ktx** connection id (required) | - |
### `sl query`
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | KTX connection id | - |
| `--connection-id <id>` | **ktx** connection id | - |
| `--query-file <path>` | JSON semantic query file | - |
| `--measure <measure>` | Measure to query; repeatable (at least one required) | - |
| `--dimension <dimension>` | Dimension to include; repeatable | - |

4
docs-site/content/docs/cli-reference/ktx-sql.mdx
View file

@ -3,7 +3,7 @@ title: "ktx sql"
description: "Execute parser-validated read-only SQL against a configured connection."
---
Run read-only SQL against a database connection in your KTX project. The command
Run read-only SQL against a database connection in your **ktx** project. The command
validates the statement before execution and only accepts a single `SELECT` or
`WITH` query.
@ -22,7 +22,7 @@ JSON.
| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--connection <id>` | KTX database connection id. Required. | - |
| `-c`, `--connection <id>` | **ktx** database connection id. Required. | - |
| `--max-rows <n>` | Maximum rows to return. Must be between `1` and `10000`. | `1000` |
| `--output <mode>` | Output mode: `pretty`, `plain` (TSV), or `json`. | `pretty` |
| `--json` | Shortcut for `--output=json` (overrides `--output`). | `false` |

8
docs-site/content/docs/cli-reference/ktx-status.mdx
View file

@ -1,9 +1,9 @@
---
title: "ktx status"
description: "Check KTX setup and project readiness."
description: "Check ktx setup and project readiness."
---
Run the KTX readiness doctor. Inside a KTX project, this checks setup,
Run the **ktx** readiness doctor. Inside a **ktx** project, this checks setup,
project configuration, semantic search, query history, connections, and related
diagnostics. Outside a project, it checks local CLI setup readiness so you know
whether `ktx setup` can run.
@ -53,7 +53,7 @@ flow, then rerun `ktx status`.
```json
{
"title": "KTX project doctor",
"title": "ktx project doctor",
"checks": [
{
"id": "project-config",
@ -69,7 +69,7 @@ flow, then rerun `ktx status`.
| Error | Cause | Recovery |
|-------|-------|----------|
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a KTX project or set `KTX_PROJECT_DIR` for project checks |
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a **ktx** project or set `KTX_PROJECT_DIR` for project checks |
| Project config check fails | The project directory is missing or has an invalid `ktx.yaml` | Run `ktx setup` to resume setup |
| Schema validation fails | `ktx.yaml` does not match the current config schema | Run `ktx status --validate --json` for structured issue details, then edit `ktx.yaml` or rerun `ktx setup` |
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run `ktx setup` or inspect the check's `fix` field in JSON output |

8
docs-site/content/docs/cli-reference/ktx-wiki.mdx
View file

@ -3,7 +3,7 @@ title: "ktx wiki"
description: "List or search wiki pages."
---
List and search wiki pages in your KTX project. Wiki pages are Markdown
List and search wiki pages in your **ktx** project. Wiki pages are Markdown
documents that capture business definitions, rules, and gotchas. Agents search
them for context when answering questions about your data.
@ -30,9 +30,9 @@ Edit the Markdown files under `wiki/` directly, or ingest source content with
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
`ktx wiki <query>` uses hybrid search when `storage.search` is `sqlite-fts5`.
KTX combines lexical SQLite FTS5 matches, token matches, and semantic matches
**ktx** combines lexical SQLite FTS5 matches, token matches, and semantic matches
from wiki page embeddings stored in `.ktx/db.sqlite`. If embeddings are not
configured or the embedding backend is unavailable, KTX skips the semantic lane
configured or the embedding backend is unavailable, **ktx** skips the semantic lane
and keeps lexical and token results.
## Examples
@ -105,7 +105,7 @@ score rather than a percentage.
}
```
When you pass the global `--debug` flag, KTX writes search diagnostics to
When you pass the global `--debug` flag, **ktx** writes search diagnostics to
stderr and leaves stdout unchanged. This is useful with `--json` because stdout
stays machine-readable:

8
docs-site/content/docs/cli-reference/ktx.mdx
View file

@ -1,6 +1,6 @@
---
title: "ktx"
description: "Root command map, global options, and project resolution for the KTX CLI."
description: "Root command map, global options, and project resolution for the ktx CLI."
---
The `ktx` CLI sets up local projects, builds agent-ready context, checks
@ -13,7 +13,7 @@ server, and manages the bundled Python runtime.
ktx [global-options] <command>
```
When you run bare `ktx` in an interactive terminal outside any KTX project, the
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
CLI starts the same guided setup flow as `ktx setup`. Inside an existing
project, use command-specific help:
@ -66,7 +66,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
| Flag | Description |
|------|-------------|
| `--project-dir <path>` | KTX project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
| `--project-dir <path>` | **ktx** project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
| `--debug` | Print diagnostic dispatch and project-resolution details to stderr. |
| `-v`, `--version` | Show the CLI package name and version. |
| `-h`, `--help` | Show help for the current command. |
@ -74,7 +74,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
## Project resolution
Most commands are project-aware. Pass `--project-dir <path>` when scripting or
when you are outside the project directory. If you omit it, KTX checks
when you are outside the project directory. If you omit it, **ktx** checks
`KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back
to the current directory.

14
docs-site/content/docs/community/contributing.mdx
View file

@ -1,9 +1,9 @@
---
title: Contributing
description: Contribute to KTX through code, docs, connectors, and examples.
description: Contribute to ktx through code, docs, connectors, and examples.
---
KTX is an open-source context layer for data 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.
@ -25,12 +25,12 @@ documentation, connector coverage, and examples.
| 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 compilation |
| KTX daemon | `python/ktx-daemon` for the portable runtime API |
| **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 |
## Development setup
This page is for contributors working on the KTX repository. To install KTX for
This page is for contributors working on the **ktx** repository. To install **ktx** for
an analytics project, use the published
[`@kaelio/ktx`](https://www.npmjs.com/package/@kaelio/ktx) package in the
[Quickstart](/docs/getting-started/quickstart).
@ -80,7 +80,7 @@ changes.
## Repository structure
KTX is a pnpm + uv workspace. TypeScript packages live in `packages/`, Python
**ktx** is a pnpm + uv workspace. TypeScript packages live in `packages/`, Python
projects in `python/`.
```text
@ -264,8 +264,8 @@ approach.
## Agent usage notes
Use this page when an agent is modifying the KTX repository itself rather than
using KTX in an analytics project.
Use this page when an agent is modifying the **ktx** repository itself rather than
using **ktx** in an analytics project.
| Agent task | Command or section |
|------------|--------------------|

12
docs-site/content/docs/community/support.mdx
View file

@ -1,26 +1,26 @@
---
title: Community & Support
description: Join the KTX Slack community, report bugs, and get help.
description: Join the ktx Slack community, report bugs, and get help.
---
KTX is an open-source project. The community is where users, contributors, and
**ktx** is an open-source project. The community is where users, contributors, and
the core team trade questions, share patterns, and shape the roadmap.
## Where to go
| You want to... | Go here |
|----------------|---------|
| Ask a question or chat with the community | [KTX Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ) |
| Ask a question or chat with the community | [**ktx** Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ) |
| Report a bug or request a feature | [GitHub Issues](https://github.com/Kaelio/ktx/issues) |
| Read or contribute to the docs | [docs.kaelio.com/ktx](https://docs.kaelio.com/ktx/docs/) |
| Contribute code | [Contributing guide](/docs/community/contributing) |
## Slack
Join the KTX Slack to ask questions, share what you're building, and get help
Join the **ktx** Slack to ask questions, share what you're building, and get help
from maintainers and other users.
[**Join the KTX Slack →**](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)
[**Join the ktx Slack →**](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)
Slack is the right place for:
@ -41,7 +41,7 @@ searchable, get triaged, and stay attached to the eventual fix.
## Code of conduct
KTX follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
**ktx** follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
Be respectful, assume good intent, and keep discussion focused on the project.
Report conduct concerns to the maintainers in Slack or by email at
`support@kaelio.com`.

12
docs-site/content/docs/concepts/context-as-code.mdx
View file

@ -5,11 +5,11 @@ description: Treat analytics context like code - version it, review it, merge it
## The idea
dbt moved analytics transformations into git. KTX applies the same pattern to
dbt moved analytics transformations into git. **ktx** applies the same pattern to
analytics context: metric definitions, joins, business rules, wiki pages, and
ingest decisions become files that can be reviewed, merged, and audited.
| Before | With KTX |
| Before | With **ktx** |
|--------|----------|
| Context scattered across BI tools, chats, docs, and analyst memory | Context lives in YAML and Markdown |
| Agent changes are hard to inspect | Agent changes are git diffs |
@ -19,7 +19,7 @@ ingest decisions become files that can be reviewed, merged, and audited.
## Auto-ingestion
Most context already exists in dbt manifests, LookML, MetricFlow, Metabase,
Notion, warehouse metadata, and analyst notes. KTX reads those inputs through
Notion, warehouse metadata, and analyst notes. **ktx** reads those inputs through
connectors, then reconciles them into local files.
```text
@ -30,9 +30,9 @@ context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs
|------|--------------|--------|
| **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 |
| **Write** | **ktx** saves changed semantic sources and wiki pages | Reviewable project files |
Reconciliation is the key difference from a sync. KTX preserves accepted local
Reconciliation is the key difference from a sync. **ktx** preserves accepted local
edits, fills gaps, and surfaces conflicts instead of blindly overwriting files.
## The git workflow
@ -103,7 +103,7 @@ they are part of your team's review workflow.
## Agent usage notes
Use this page when an agent needs to explain review workflows, ingestion diffs,
replayability, or why KTX writes YAML and Markdown instead of hiding context in
replayability, or why **ktx** writes YAML and Markdown instead of hiding context in
a hosted service.
| Agent task | Relevant section | Next page |

26
docs-site/content/docs/concepts/semantic-layer-internals.mdx
View file

@ -1,13 +1,13 @@
---
title: Semantic querying
description: How KTX compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph.
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
**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.
@ -27,15 +27,15 @@ key links them, what grain to aggregate at, how to keep one fact from
inflating another, and what dialect the warehouse speaks. Plumbing on
top of intent, every query.
KTX's semantic layer separates those concerns:
**ktx**'s semantic layer separates those concerns:
- **You and KTX maintain the how.** Sources, joins, grain, measures, and
- **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 compiler to produce safe SQL.
The agent stops reasoning about plumbing. It states intent. KTX turns
The agent stops reasoning about plumbing. It states intent. **ktx** turns
that into SQL the warehouse can run.
<SemanticLayerFlow />
@ -48,7 +48,7 @@ except `measures`, and column references are fully qualified
from.
Notice what's _not_ in the payload: no `FROM`, no `JOIN`, no `GROUP BY`,
no `WITH`. The agent states what it wants. KTX picks the join path, the
no `WITH`. The agent states what it wants. **ktx** picks the join path, the
grain, the SQL shape, and the dialect.
| Field | Purpose |
@ -71,7 +71,7 @@ A typical agent call looks like this:
}
```
That payload is enough for KTX to plan and compile. The agent never
That payload is enough for **ktx** to plan and compile. The agent never
authors a join, a CTE, or a dialect-specific cast.
## What the planner does
@ -161,7 +161,7 @@ measures:
## Building and maintaining the graph
KTX builds the graph from evidence and accepted edits, not from runtime
**ktx** builds the graph from evidence and accepted edits, not from runtime
inference. Each input contributes a different kind of authority.
| Evidence | What it contributes |
@ -293,7 +293,7 @@ shared dimension. A naive query joins them all together first, so each
row from one fact is multiplied by the matching rows from the other.
Measures duplicate, numbers go wrong, and the agent doesn't notice.
KTX's planner detects the shape by grouping measures by their owning
**ktx**'s planner detects the shape by grouping measures by their owning
source. If more than one source contributes raw measures, the generator
switches to aggregate locality: each fact is pre-aggregated at its own
grain inside a CTE, and the CTEs are joined back to the dimension at the
@ -311,7 +311,7 @@ analyst would have written by hand.
## Where the context comes from
The planner is only as good as the YAML it reads. KTX builds and
The planner is only as good as the YAML it reads. **ktx** builds and
maintains that YAML for you.
- `raw-sources/<connection>/` holds scan evidence from your warehouse:
@ -327,7 +327,7 @@ current as the warehouse changes.
## Agent usage notes
Point an agent at this page when it needs to explain why KTX asks for
Point an agent at this page when it needs to explain why **ktx** asks for
grain, why a query was rejected as unsafe, or why the compiled SQL looks
different from what the agent first proposed.
@ -335,6 +335,6 @@ different from what the agent first proposed.
|------------|------------------|-----------|
| Explain the semantic query shape | The semantic query contract | [ktx sl](/docs/cli-reference/ktx-sl) |
| Describe what the planner does between query and SQL | What the planner does | [ktx sl](/docs/cli-reference/ktx-sl) |
| Explain why KTX asks for grain and relationship types | The join graph | [Writing context](/docs/guides/writing-context) |
| Explain why **ktx** asks for grain and relationship types | The join graph | [Writing context](/docs/guides/writing-context) |
| Diagnose duplicated measures after a join | Fan-out and aggregate locality | [ktx sl](/docs/cli-reference/ktx-sl) |
| Describe how semantic context stays current | Building and maintaining the graph | [Context as code](/docs/concepts/context-as-code) |

35
docs-site/content/docs/concepts/the-context-layer.mdx
View file

@ -1,6 +1,6 @@
---
title: The Context Layer
description: What a context layer is, why agents need one, and the YAML and Markdown surfaces KTX writes to disk.
description: What a context layer is, why agents need one, and the YAML and Markdown surfaces ktx writes to disk.
---
import { GitIcon } from "@/components/git-icon";
@ -11,7 +11,7 @@ can't tell an agent on its own: which metrics are canonical, which joins are
safe, what your team means by "active customer", and where every definition
came from.
KTX builds that layer as plain files - YAML, Markdown, and JSON - that agents
**ktx** builds that layer as plain files - YAML, Markdown, and JSON - that agents
can search and humans can review. This page covers what's in it, why agents
need it, and how it compares to other semantic tooling.
@ -35,14 +35,14 @@ Schema is a starting point, not a contract. The context layer is the contract.
## The two pillars
A KTX project has two committed surfaces, each tuned for a different question.
A **ktx** project has two committed surfaces, each tuned for a different question.
Structured data lives where it can be compiled. Prose lives where it can be
searched. Wiki pages cross-reference semantic sources by name, so every metric
caveat stays anchored to the definition it explains.
<figure
className="not-prose my-10 overflow-hidden rounded-lg border border-fd-border bg-fd-card shadow-sm"
aria-label="The two committed pillars of a KTX context layer"
aria-label="The two committed pillars of a ktx context layer"
>
<div className="border-b border-fd-border bg-fd-muted/35 px-5 py-4">
<p className="text-[11px] font-semibold uppercase tracking-[0.08em] text-fd-primary">
@ -121,7 +121,8 @@ caveat stays anchored to the definition it explains.
<figcaption className="border-t border-fd-border bg-fd-muted/25 px-5 py-3 text-[11.5px] leading-5 text-fd-muted-foreground">
<span className="font-medium text-fd-foreground">{"Behind the scenes. "}</span>
{"KTX also keeps scan snapshots and a per-run event log locally so every committed change is traceable to its evidence. You don't read or edit these files yourself - see "}
<strong className="font-medium text-fd-foreground">{"ktx"}</strong>
{" also keeps scan snapshots and a per-run event log locally so every committed change is traceable to its evidence. You don't read or edit these files yourself - see "}
<a href="/docs/concepts/context-as-code" className="font-medium underline">{"Context as Code"}</a>
{" for how that audit trail flows into review."}
</figcaption>
@ -189,7 +190,7 @@ a graph agents traverse. An agent that finds this page while searching for
executable definition, then walks `refs` to related policies without rerunning
search.
The graph only helps if the edges stay live. KTX validates references when
The graph only helps if the edges stay live. **ktx** validates references when
wiki pages are written and prunes `sl_refs` during ingest when their target
sources are deleted or their measures are renamed - so a stale page can never
quietly route an agent to a definition that no longer exists.
@ -206,7 +207,7 @@ The split between the two pillars is sharp:
If a fact changes how the SQL runs, it goes in YAML. If a human needs it to
trust the answer, it goes in Markdown.
## How KTX compares
## How ktx compares
Two adjacent product categories cover parts of this problem - but each leaves
a different gap.
@ -224,13 +225,13 @@ hand-written, and the layer doesn't learn from the warehouse, BI tools, or
query history that surround it. The business context that explains *why* a
definition exists usually lives somewhere else.
KTX bundles both surfaces - wiki for business context, semantic layer for
**ktx** bundles both surfaces - wiki for business context, semantic layer for
queryable definitions - and keeps them current by reading the data stack and
reconciling new evidence with the reviewed files. You get the breadth of a
knowledge tool and the SQL safety of a semantic layer, without rewriting
models every time the warehouse changes.
| Capability | Company brain | Semantic layer | KTX |
| Capability | Company brain | Semantic layer | **ktx** |
|------------|---------------|----------------|-----|
| **Surface** | Indexed docs and chats | Modeling language or runtime | YAML and Markdown files |
| **Data-stack awareness** | None - treats data tools as text | High for declared metrics, none for the surrounding warehouse | Built in: scans schemas, dbt, BI tools, and query history |
@ -238,14 +239,14 @@ models every time the warehouse changes.
| **SQL safety** | None - generates plausible text | Compiled, dialect-correct | Compiled with join-graph and fan-out handling |
| **Agent edit loop** | Text-only | Tied to the modeling workflow | First-class: patch files, validate, review diffs |
If you already use MetricFlow, LookML, dbt, or BI tools, KTX can ingest that
If you already use MetricFlow, LookML, dbt, or BI tools, **ktx** can ingest that
context and turn it into agent-readable files. You don't need to replace your
serving layer to give agents a better working surface.
## A KTX project on disk
## A ktx project on disk
A KTX project is a directory of readable files. Semantic sources and wiki
pages are committed to git; everything else KTX needs at runtime stays local
A **ktx** project is a directory of readable files. Semantic sources and wiki
pages are committed to git; everything else **ktx** needs at runtime stays local
and out of the repo.
```text
@ -268,13 +269,13 @@ agents read the updated source of truth.
## Agent usage notes
Use this page when an agent needs to explain why KTX exists, why schema-only
database access isn't enough, or how KTX differs from traditional semantic
Use this page when an agent needs to explain why **ktx** exists, why schema-only
database access isn't enough, or how **ktx** differs from traditional semantic
layers.
| Agent task | Relevant section | Next page |
|------------|------------------|-----------|
| Explain why a data agent wrote a plausible but wrong query | Database access isn't enough | [Writing Context](/docs/guides/writing-context) |
| Decide whether a fact belongs in YAML or Markdown | Semantic sources / Wiki pages | [Writing Context](/docs/guides/writing-context) |
| Compare KTX to another semantic layer | How KTX compares | [Primary Sources](/docs/integrations/primary-sources) |
| Explain reviewability and source of truth | A KTX project on disk | [Context as Code](/docs/concepts/context-as-code) |
| Compare **ktx** to another semantic layer | How ktx compares | [Primary Sources](/docs/integrations/primary-sources) |
| Explain reviewability and source of truth | A ktx project on disk | [Context as Code](/docs/concepts/context-as-code) |

28
docs-site/content/docs/getting-started/introduction.mdx
View file

@ -1,6 +1,6 @@
---
title: Introduction
description: KTX is an open-source, self-improving context layer for data agents.
description: ktx is an open-source, self-improving context layer for data agents.
---
import { ProductMechanics } from "@/components/product-mechanics";
@ -23,35 +23,35 @@ import { ProductMechanics } from "@/components/product-mechanics";
Make analytics context usable by agents
</h1>
<p className="mt-4 max-w-2xl text-lg text-fd-muted-foreground" style={{ lineHeight: '1.7' }}>
{'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.'}
{'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.'}
</p>
</div>
</div>
## Why KTX helps
## Why ktx helps
KTX gives agents a shared context workspace before they write SQL, answer a
**ktx** gives agents a shared context workspace before they write SQL, answer a
question, or update analytics definitions.
- **Context as code.** KTX writes wiki pages and semantic-layer definitions as
- **Context as code.** **ktx** writes wiki pages and semantic-layer definitions as
git-based files you can review, diff, and merge.
- **Self-improving ingest.** KTX reads warehouses, BI tools, modeling code,
- **Self-improving ingest.** **ktx** reads warehouses, BI tools, modeling code,
query history, and notes, then reconciles new evidence with accepted context.
- **Executable semantics.** Agents can use approved measures, joins, filters,
dimensions, and segments instead of rebuilding canonical SQL from scratch.
- **Agent-native access.** CLI and MCP tools let agents search context, compile
semantic queries, run read-only SQL, and propose updates.
KTX complements existing semantic layers by pairing metric definitions with the
**ktx** complements existing semantic layers by pairing metric definitions with the
surrounding business knowledge, caveats, provenance, and review workflow agents
need for data work.
## How KTX works
## How ktx works
KTX has two connected sides: it builds and maintains the context layer, then
**ktx** has two connected sides: it builds and maintains the context layer, then
serves that context to agents at runtime.
| Side | What KTX does |
| Side | What **ktx** does |
|------|---------------|
| **Ingest and auto-maintain knowledge** | Reads your data stack and company knowledge, reconciles new evidence with accepted context, and keeps changes to `semantic-layer/` plus `wiki/` as version-controlled diffs automatically. |
| **Serve agents at runtime** | Helps agents find the right wiki pages and semantic-layer entities, then compile or execute semantic queries through CLI and MCP tools. |
@ -60,7 +60,7 @@ serves that context to agents at runtime.
## Use it for
Use KTX when agents need more than raw database access. Agents can search wiki
Use **ktx** when agents need more than raw database access. Agents can search wiki
context, find semantic-layer entities, compile trusted semantic queries, run
read-only SQL, and use the same tools through MCP.
@ -77,7 +77,7 @@ best first step for users; contributor setup lives in the community docs.
<Cards>
<Card title="Quickstart" href="/docs/getting-started/quickstart">
Install KTX, run setup, build context, and connect an agent.
Install **ktx**, run setup, build context, and connect an agent.
</Card>
<Card title="The Context Layer" href="/docs/concepts/the-context-layer">
Understand why agents need more than schema access and raw SQL.
@ -89,7 +89,7 @@ best first step for users; contributor setup lives in the community docs.
Edit semantic-layer YAML and wiki Markdown safely.
</Card>
<Card title="CLI Reference" href="/docs/cli-reference/ktx">
Complete flag and subcommand reference for every KTX command.
Complete flag and subcommand reference for every **ktx** command.
</Card>
<Card title="Agent Quickstart" href="/docs/ai-resources/agent-quickstart">
Machine-readable docs and agent-facing setup notes.
@ -99,7 +99,7 @@ best first step for users; contributor setup lives in the community docs.
## Community
Have questions, want to share what you're building, or chat with maintainers?
Join the [KTX Slack community](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ).
Join the [**ktx** Slack community](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ).
For bug reports and feature requests, open a
[GitHub issue](https://github.com/Kaelio/ktx/issues). See
[Community & Support](/docs/community/support) for the full guide on where to

26
docs-site/content/docs/getting-started/quickstart.mdx
View file

@ -1,6 +1,6 @@
---
title: Quickstart
description: Install KTX, run setup, and connect your coding agent.
description: Install ktx, run setup, and connect your coding agent.
---
import { CopyButton } from "@/components/copy-button";
@ -26,7 +26,7 @@ If you're a coding assistant choosing a docs route, start with the
Need a warehouse to play with?
</div>
<div className="mt-2 text-base leading-relaxed text-fd-foreground">
Try KTX against a real data stack - Postgres, dbt, Metabase, and Notion
Try **ktx** against a real data stack - Postgres, dbt, Metabase, and Notion
pre-loaded with the Orbit demo corpus. The page lists demo credentials
you can paste straight into `ktx setup`.
</div>
@ -54,7 +54,7 @@ If you're a coding assistant choosing a docs route, start with the
</div>
<div className="mt-2 text-sm leading-6 text-fd-muted-foreground">
You can ask an agent such as Claude Code, Codex, Cursor, or OpenCode to
install and configure KTX for you. The{' '}
install and configure **ktx** for you. The{' '}
<a href="/ktx/docs/agents-setup.md" className="font-medium underline">
agent setup Markdown prompt
</a>{' '}
@ -93,7 +93,7 @@ Install the published package globally:
npm install -g @kaelio/ktx
```
KTX is open source. If you'd like to hack on it or run from a local checkout,
**ktx** is open source. If you'd like to hack on it or run from a local checkout,
the source lives at [github.com/kaelio/ktx](https://github.com/kaelio/ktx) -
see [Contributing](/docs/community/contributing) to get set up.
@ -105,7 +105,7 @@ From your project directory, run:
ktx setup
```
The wizard walks you through everything KTX needs in one pass:
The wizard walks you through everything **ktx** needs in one pass:
1. **Project** - creates or resumes `ktx.yaml` in the current directory.
2. **LLM** - picks a Claude backend. The default uses your local Claude Code
@ -122,7 +122,7 @@ The wizard walks you through everything KTX needs in one pass:
7. **Agent integration** - installs project-local rules for Claude Code,
Codex, Cursor, OpenCode, or universal `.agents`.
If you choose local `sentence-transformers` embeddings, KTX uses the managed
If you choose local `sentence-transformers` embeddings, **ktx** uses the managed
Python runtime. To prepare it before setup, run:
```bash
@ -141,10 +141,10 @@ Building schema context for warehouse
Running fast database ingest
```
If setup exits early, rerun `ktx setup` in the same directory. KTX keeps
If setup exits early, rerun `ktx setup` in the same directory. **ktx** keeps
progress under `.ktx/setup/` and resumes from the remaining work.
> **Note:** Running bare `ktx` in an interactive terminal outside a KTX
> **Note:** Running bare `ktx` in an interactive terminal outside a **ktx**
> project opens the same wizard. Inside a project, it opens a menu for
> resuming setup, connecting an agent, checking status, or exploring a
> pre-built demo project.
@ -158,13 +158,13 @@ ktx status
```
```text
KTX project: /home/user/analytics
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
KTX context built: yes
ktx context built: yes
Agent integration ready: yes (codex:project)
```
@ -173,7 +173,7 @@ For a structured check inside scripts, use `ktx status --json`.
When setup builds deep context, its final context check looks like:
```text
KTX context is ready for agents.
ktx context is ready for agents.
Databases:
warehouse: deep context complete
@ -192,13 +192,13 @@ ktx setup --agents
```
Claude Code and Codex also support global installs with `--global`. Agent
rules point at the KTX CLI path that created them, so agents don't need a
rules point at the **ktx** CLI path that created them, so agents don't need a
separate `ktx` binary on `PATH`. If the CLI path changes, rerun
`ktx setup --agents`.
## What setup writes
KTX writes plain files so people and agents can review changes in git.
**ktx** writes plain files so people and agents can review changes in git.
| Path | Purpose |
|------|---------|

12
docs-site/content/docs/guides/building-context.mdx
View file

@ -1,10 +1,10 @@
---
title: Building Context
description: Build and refresh KTX context from databases, context sources, query history, and text.
description: Build and refresh ktx context from databases, context sources, query history, and text.
---
Build context after `ktx setup` creates `ktx.yaml` and at least one database or
context-source connection. KTX writes local semantic sources and wiki
context-source connection. **ktx** writes local semantic sources and wiki
pages for agents to use before writing SQL.
## The build loop
@ -34,7 +34,7 @@ ktx ingest warehouse
ktx ingest --all
```
Depth controls how much context KTX builds:
Depth controls how much context **ktx** builds:
| Flag | Best for | What it does |
|------|----------|--------------|
@ -52,7 +52,7 @@ ktx ingest --all --deep
Deep ingest needs LLM and embedding readiness. Otherwise run `ktx setup` or use
`--fast`.
With `claude-code`, KTX agent loops can invoke only the KTX MCP tools for the
With `claude-code`, **ktx** agent loops can invoke only the **ktx** MCP tools for the
current run.
## Query history
@ -74,7 +74,7 @@ for one run.
## Relationship evidence
KTX scores relationship candidates during supported deep database ingest. The
**ktx** scores relationship candidates during supported deep database ingest. The
public CLI does not expose separate relationship review subcommands.
## Context-source ingest
@ -126,7 +126,7 @@ Useful flags:
|------|-------------|
| `--text <content>` | Capture inline text into memory; repeatable |
| `--file <path>` | Capture a text file (or `-` for stdin) into memory; repeatable |
| `--connection-id <connectionId>` | Attach the captured memory to a KTX connection |
| `--connection-id <connectionId>` | Attach the captured memory to a **ktx** connection |
| `--user-id <id>` | Attribute capture to a user scope, default `local-cli` |
| `--json` | Print structured output |
| `--fail-fast` | Stop after the first failed text/file item |

10
docs-site/content/docs/guides/llm-configuration.mdx
View file

@ -1,6 +1,6 @@
---
title: LLM configuration
description: Configure KTX LLM providers, model roles, and prompt caching.
description: Configure ktx LLM providers, model roles, and prompt caching.
---
Configure text generation, structured extraction, and ingest or memory loops in
@ -15,7 +15,7 @@ Set `llm.provider.backend` to one of these values:
- `vertex`: Use Vertex AI Anthropic models through Google Cloud credentials.
- `gateway`: Use AI Gateway-compatible Anthropic model ids.
- `claude-code`: Use your local Claude Code session through the Claude Agent
SDK. KTX strips provider-routing environment variables from child processes.
SDK. **ktx** strips provider-routing environment variables from child processes.
## Claude Code
@ -40,11 +40,11 @@ During setup, choose the backend interactively or pass the model in automation:
ktx setup --llm-backend claude-code --llm-model opus --no-input
```
For Claude Code, `sonnet`, `opus`, and `haiku` map to KTX defaults. Full Claude
For Claude Code, `sonnet`, `opus`, and `haiku` map to **ktx** defaults. Full Claude
model IDs are also accepted.
`claude-code` exposes only KTX MCP tools for the current agent loop. SDK init
metadata may still list host slash commands, skills, and subagents; KTX does not
`claude-code` exposes only **ktx** MCP tools for the current agent loop. SDK init
metadata may still list host slash commands, skills, and subagents; **ktx** does not
grant execution access to them.
## Prompt caching

20
docs-site/content/docs/guides/serving-agents.mdx
View file

@ -1,15 +1,15 @@
---
title: Serving Agents
description: Expose KTX context to Claude Code, Codex, Cursor, OpenCode, and custom agents.
description: Expose ktx context to Claude Code, Codex, Cursor, OpenCode, and custom agents.
---
KTX serves agents through the CLI and project-local instruction files. Agents
read generated rules, call KTX commands, inspect context files, and use JSON for
**ktx** serves agents through the CLI and project-local instruction files. Agents
read generated rules, call **ktx** commands, inspect context files, and use JSON for
structured results.
## Recommended setup
Run the agent install step from a KTX project:
Run the agent install step from a ktx project:
```bash
ktx setup --agents
@ -44,7 +44,7 @@ Installed files are recorded in `.ktx/agents/install-manifest.json`. Rerun
## Agent command set
All supported clients use the same command surface. Use `--project-dir` outside
the KTX project directory.
the **ktx** project directory.
### Readiness
@ -122,7 +122,7 @@ Use `--deep` only when LLM and embedding setup is ready.
Agents should:
- Run `ktx status --json` before using KTX context.
- Run `ktx status --json` before using **ktx** context.
- Use `ktx sl <query>` and `ktx wiki <query>` before writing SQL from memory.
- Inspect the relevant YAML or Markdown files after search returns candidates.
- Compile SQL with `ktx sl query --format sql` before executing.
@ -130,7 +130,7 @@ Agents should:
- Validate edited semantic sources with `ktx sl validate`.
- Keep generated context changes reviewable in git.
KTX is a local context layer with a CLI and plain project files. Do not assume a
**ktx** is a local context layer with a CLI and plain project files. Do not assume a
background server, ORPC route, frontend app, or external migration system.
## Manual setup
@ -144,7 +144,7 @@ Use manual setup for custom agents that can read project-local instructions.
```
2. Configure the agent to read `.agents/skills/ktx/SKILL.md`.
3. Open the agent in the KTX project directory.
3. Open the agent in the **ktx** project directory.
4. Ask it to run `ktx status --json` and summarize readiness.
For per-client notes, see [Agent Clients](/docs/integrations/agent-clients).
@ -153,8 +153,8 @@ For per-client notes, see [Agent Clients](/docs/integrations/agent-clients).
| Symptom | Likely cause | Recovery |
|---------|--------------|----------|
| Agent says KTX is unavailable | Agent did not load the generated instruction file | Rerun `ktx setup --agents --target <target>` and restart the agent session |
| Agent command cannot find the project | Agent is running outside the KTX directory | Add `--project-dir <path>` or open the agent in the project root |
| Agent says **ktx** is unavailable | Agent did not load the generated instruction file | Rerun `ktx setup --agents --target <target>` and restart the agent session |
| Agent command cannot find the project | Agent is running outside the **ktx** directory | Add `--project-dir <path>` or open the agent in the project root |
| Generated rules point at a missing CLI path | CLI was moved, rebuilt, or reinstalled | Rerun `ktx setup --agents` |
| Agent cannot find a metric | Context is missing or stale | Run `ktx sl <query>`, inspect source YAML, then refresh with `ktx ingest` if needed |
| Agent query returns too many rows | The command executed without a result cap | Require `--max-rows` for executed queries |

76
docs-site/content/docs/integrations/agent-clients.mdx
View file

@ -1,14 +1,14 @@
---
title: Agent Clients
description: Set up KTX with Claude Code, Claude Desktop, Cursor, Codex, and OpenCode.
description: Set up ktx with Claude Code, Claude Desktop, Cursor, Codex, and OpenCode.
---
KTX exposes context to end-user agents through MCP tools. The CLI remains the
**ktx** exposes context to end-user agents through MCP tools. The CLI remains the
admin surface for setup, ingest, status, daemon lifecycle, and debugging.
Run `ktx setup` and select your client agent targets, or configure manually
using the snippets below. Choose **Ask data questions with KTX MCP** for client
agents. Choose **Ask data questions + manage KTX with CLI commands** only when
using the snippets below. Choose **Ask data questions with ktx MCP** for client
agents. Choose **Ask data questions + manage ktx with CLI commands** only when
a developer or operator agent also needs pinned `ktx` admin commands.
## Install with setup
@ -39,19 +39,19 @@ ktx setup --agents --target claude-code --global
ktx setup --agents --target codex --global
```
KTX records installed files in `.ktx/agents/install-manifest.json`. That
**ktx** records installed files in `.ktx/agents/install-manifest.json`. That
manifest lets status checks report agent readiness and lets future cleanup
remove only files KTX installed.
remove only files **ktx** installed.
The interactive command asks two questions:
```txt
◆ What should agents be allowed to do with this KTX project?
│ ○ Ask data questions with KTX MCP
│ ○ Ask data questions + manage KTX with CLI commands
◆ What should agents be allowed to do with this ktx project?
│ ○ Ask data questions with ktx MCP
│ ○ Ask data questions + manage ktx with CLI commands
└
◆ Which agent targets should KTX install?
◆ Which agent targets should ktx install?
│ ◻ Claude Code
│ ◻ Claude Desktop
│ ◻ Codex
@ -65,29 +65,29 @@ When every selected target supports both project and global setup, the command
also asks where to install supported agent config:
```txt
◆ Where should KTX install supported agent config?
◆ Where should ktx install supported agent config?
│
│ KTX project: /path/to/your/ktx-project
│ ktx project: /path/to/your/ktx-project
│
│ ○ Project scope (KTX project directory)
│ ○ Project scope (ktx project directory)
│ ○ Global scope (user config)
└
```
## Generated files
KTX writes MCP client configuration and analytics guidance by default. It writes
admin CLI guidance only when you choose **Ask data questions + manage KTX with
**ktx** writes MCP client configuration and analytics guidance by default. It writes
admin CLI guidance only when you choose **Ask data questions + manage ktx with
CLI commands**.
After setup, KTX prints **Required before using agents**. Complete those steps
After setup, **ktx** prints **Required before using agents**. Complete those steps
before opening the configured agent. If it shows `ktx mcp start --project-dir ...`,
run that command before using Claude Code, Codex, Cursor, OpenCode, or generic
MCP clients. The same output also prints the matching `ktx mcp stop` command
for when you want to stop MCP later. Claude Desktop uses its own launcher and
prints separate skill upload steps.
| Target | Ask data questions with KTX MCP | Adds when agents can manage KTX with CLI |
| Target | Ask data questions with **ktx** MCP | Adds when agents can manage **ktx** with CLI |
|--------|------------------------------|---------------------------|
| Claude Code | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md` | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` stdio entry + `.ktx/agents/claude/ktx-analytics.zip` upload | Adds `.ktx/agents/claude/ktx.zip` upload |
@ -96,7 +96,7 @@ prints separate skill upload steps.
| OpenCode | Printed snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | `.opencode/commands/ktx.md` |
| Universal `.agents` | Printed MCP endpoint, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md` |
MCP config gives agents access to KTX context tools such as discovery,
MCP config gives agents access to **ktx** context tools such as discovery,
semantic-layer queries, wiki search, SQL execution, and memory ingest. The
analytics skill explains how to use those tools for semantic-layer-first
analysis. Optional admin skill and rule files list pinned CLI commands for
@ -106,7 +106,7 @@ developer or operator agents.
### Install via `ktx setup`
During setup, select **Claude Code** from the agent targets. KTX writes:
During setup, select **Claude Code** from the agent targets. **ktx** writes:
| Scope | Files |
|-------|-------|
@ -125,7 +125,7 @@ Create `.claude/skills/ktx/SKILL.md`:
```markdown title=".claude/skills/ktx/SKILL.md"
---
name: ktx
description: Use local KTX semantic context and wiki knowledge for this project.
description: Use local ktx semantic context and wiki knowledge for this project.
---
Available commands:
@ -140,8 +140,8 @@ Available commands:
- Claude Code discovers skills automatically from `.claude/skills/`.
- Claude Code reads MCP config from `.mcp.json` for project-scoped MCP tools.
- Claude rules in `.claude/rules/` tell Claude when KTX should be used.
- Global installation makes KTX available in all projects without per-project setup.
- Claude rules in `.claude/rules/` tell Claude when **ktx** should be used.
- Global installation makes **ktx** available in all projects without per-project setup.
- Keep generated skills committed only when your team wants project-local agent instructions in git.
---
@ -150,11 +150,11 @@ Available commands:
### Install via `ktx setup`
During setup, select **Cursor** from the agent targets. KTX writes:
During setup, select **Cursor** from the agent targets. **ktx** writes:
| Mode | File |
|------|------|
| Ask data questions with KTX MCP | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` |
| Ask data questions with **ktx** MCP | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` |
| Admin CLI rules | `.cursor/rules/ktx.mdc` |
Cursor supports project-scoped installation only.
@ -171,24 +171,24 @@ same markdown command definitions.
### Workflow tips
- Cursor rules in `.cursor/rules/` are automatically loaded into agent context.
- Project-scoped installs keep KTX command guidance close to the analytics context repository.
- Project-scoped installs keep **ktx** command guidance close to the analytics context repository.
---
## Claude Desktop
During setup, select **Claude Desktop** from the agent targets. KTX writes the
During setup, select **Claude Desktop** from the agent targets. **ktx** writes the
MCP server entry directly into Claude Desktop's config and prepares uploadable
Claude Desktop skill packages for the KTX workflows:
Claude Desktop skill packages for the **ktx** workflows:
- `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%AppData%/Claude/claude_desktop_config.json` (Windows) gets an
`mcpServers.ktx` entry that runs the KTX MCP server over stdio via a local
`mcpServers.ktx` entry that runs the **ktx** MCP server over stdio via a local
launcher shim at `.ktx/agents/claude/ktx-plugin-runner.sh`. The shim locates
a usable Node.js (Volta, NVM, Homebrew, system) so Claude Desktop can spawn
the server without needing `node` in PATH.
- `.ktx/agents/claude/ktx-analytics.zip` contains the `ktx-analytics` skill.
If you choose **Ask data questions + manage KTX with CLI commands**, KTX also
If you choose **Ask data questions + manage ktx with CLI commands**, **ktx** also
generates `.ktx/agents/claude/ktx.zip` with the admin `ktx` skill. Claude
Desktop requires each uploaded ZIP to contain exactly one skill folder.
@ -202,13 +202,13 @@ Upload each generated skill ZIP from Claude Desktop:
2. Click **+** > **Create skill** > **Upload a skill**.
3. Upload `.ktx/agents/claude/ktx-analytics.zip`.
4. If generated, upload `.ktx/agents/claude/ktx.zip`.
5. Toggle the uploaded KTX skills on.
5. Toggle the uploaded **ktx** skills on.
Claude Desktop does not introspect local stdio MCP servers, so the per-tool
"Connector"-style UI is not rendered for KTX. The tools are still callable
"Connector"-style UI is not rendered for **ktx**. The tools are still callable
from any Claude Desktop chat.
If you move the KTX checkout or project directory, rerun `ktx setup --agents`
If you move the **ktx** checkout or project directory, rerun `ktx setup --agents`
to refresh the absolute paths in `claude_desktop_config.json` and the launcher
shim, regenerate the skill ZIPs, then restart Claude Desktop and upload the new
ZIPs.
@ -219,7 +219,7 @@ ZIPs.
### Install via `ktx setup`
During setup, select **Codex** from the agent targets. KTX writes:
During setup, select **Codex** from the agent targets. **ktx** writes:
| Scope | Files |
|-------|-------|
@ -241,8 +241,8 @@ Code's `SKILL.md`.
- Set `CODEX_HOME` to customize the global installation directory.
- Codex shares the `.agents/` directory structure with the universal format.
- Codex instructions in `.codex/instructions/` tell Codex when KTX should be used.
- Global installation makes KTX available across all Codex sessions.
- Codex instructions in `.codex/instructions/` tell Codex when **ktx** should be used.
- Global installation makes **ktx** available across all Codex sessions.
---
@ -250,11 +250,11 @@ Code's `SKILL.md`.
### Install via `ktx setup`
During setup, select **OpenCode** from the agent targets. KTX writes:
During setup, select **OpenCode** from the agent targets. **ktx** writes:
| Mode | File |
|------|------|
| Ask data questions with KTX MCP | Snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` |
| Ask data questions with **ktx** MCP | Snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` |
| Admin CLI commands | `.opencode/commands/ktx.md` |
OpenCode supports project-scoped installation only.
@ -276,7 +276,7 @@ Code's `SKILL.md`.
## Command reference
Admin CLI skills call the same KTX CLI commands:
Admin CLI skills call the same **ktx** CLI commands:
| Command | Description |
|---------|-------------|

14
docs-site/content/docs/integrations/context-sources.mdx
View file

@ -3,7 +3,7 @@ title: Context Sources
description: Ingest semantic context from dbt, MetricFlow, LookML, Metabase, Looker, and Notion.
---
Context sources feed your existing analytics tooling into KTX. During ingestion, KTX extracts metadata from each source and uses a reconciliation agent to reconcile it with your existing semantic layer and knowledge base - preserving accepted edits rather than overwriting.
Context sources feed your existing analytics tooling into **ktx**. During ingestion, **ktx** extracts metadata from each source and uses a reconciliation agent to reconcile it with your existing semantic layer and knowledge base - preserving accepted edits rather than overwriting.
All context sources are configured in `ktx.yaml` under `connections` with their respective `driver` value.
@ -198,7 +198,7 @@ This validates that LookML model `connection:` declarations match expectations,
## Metabase
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your KTX warehouse connections.
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your **ktx** warehouse connections.
### What it provides
@ -217,7 +217,7 @@ connections:
api_key_ref: env:METABASE_API_KEY
mappings:
databaseMappings:
"3": postgres-main # Metabase DB ID → KTX connection
"3": postgres-main # Metabase DB ID → ktx connection
syncEnabled:
"3": true
syncMode: ONLY # Only ingest mapped databases
@ -239,7 +239,7 @@ Generate an API key in Metabase: **Admin > Settings > Authentication > API Keys*
### Warehouse mapping
Metabase databases must be mapped to KTX connections so ingested context links to the correct warehouse:
Metabase databases must be mapped to **ktx** connections so ingested context links to the correct warehouse:
```yaml
mappings:
@ -256,7 +256,7 @@ Find Metabase database IDs in **Admin > Databases** - the ID is in the URL when
## Looker
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your KTX warehouse connections.
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your **ktx** warehouse connections.
### What it provides
@ -276,7 +276,7 @@ connections:
client_secret_ref: env:LOOKER_CLIENT_SECRET
mappings:
connectionMappings:
postgres_connection: postgres-main # Looker conn → KTX conn
postgres_connection: postgres-main # Looker conn → ktx conn
```
### Authentication
@ -296,7 +296,7 @@ Generate API credentials in Looker: **Admin > Users > Edit > API Keys**.
### Warehouse mapping
Map Looker connection names to KTX connections so explores link to the correct warehouse:
Map Looker connection names to **ktx** connections so explores link to the correct warehouse:
```yaml
mappings:

14
docs-site/content/docs/integrations/primary-sources.mdx
View file

@ -1,9 +1,9 @@
---
title: Primary Sources
description: Connect KTX to PostgreSQL, Snowflake, BigQuery, MySQL, SQL Server, or SQLite.
description: Connect ktx to PostgreSQL, Snowflake, BigQuery, MySQL, SQL Server, or SQLite.
---
KTX connects to your data warehouse or database to build schema context,
**ktx** connects to your data warehouse or database to build schema context,
discover relationships, and execute semantic layer queries. Each connection is
defined in `ktx.yaml` under the `connections` key.
@ -16,7 +16,7 @@ All connectors share these conventions:
- Sensitive values support `env:VAR_NAME` (read from environment) and
`file:/path/to/secret` (read from file) references
- Connections are read-only; KTX never writes to your database
- Connections are read-only; **ktx** never writes to your database
- Database ingest discovers tables, columns, types, and constraints
automatically
@ -90,11 +90,11 @@ connections:
### Query history
PostgreSQL query history mines real query patterns from `pg_stat_statements`.
This helps KTX understand how your team actually queries the data.
This helps **ktx** understand how your team actually queries the data.
**Requirements:**
- `pg_stat_statements` extension enabled
- `pg_read_all_stats` role granted to the KTX user
- `pg_read_all_stats` role granted to the **ktx** user
**Config options:**
@ -224,7 +224,7 @@ For multiple datasets:
| Environment variable | `credentials_json: env:BIGQUERY_CREDENTIALS_JSON` |
The project ID is extracted automatically from the service account JSON file.
If you set `project_id` in `ktx.yaml`, KTX treats it as local descriptor and
If you set `project_id` in `ktx.yaml`, **ktx** treats it as local descriptor and
mapping metadata. The BigQuery connector still authenticates with the
`project_id` inside `credentials_json`.
@ -426,7 +426,7 @@ url: sqlite:///path/to/db.sqlite
### Authentication
No authentication required - SQLite is file-based. The file must be readable by the process running KTX.
No authentication required - SQLite is file-based. The file must be readable by the process running **ktx**.
### Features

2
docs-site/content/docs/meta.json
View file

@ -1,6 +1,6 @@
{
"root": true,
"title": "KTX",
"title": "ktx",
"pages": [
"getting-started",
"concepts",

20
docs-site/lib/llm-docs.ts
View file

@ -44,23 +44,23 @@ export function buildLlmsTxt() {
return `- [${label}](${absoluteUrl(markdownUrl)}): ${description}`;
};
return `# KTX
return `# ktx
> Agent-native context layer for analytics engineering and data agents.
KTX provides semantic-layer files, warehouse scans, wiki pages, provenance, and agent-facing tools that help coding agents answer analytics questions without inventing metrics or joins.
ktx provides semantic-layer files, warehouse scans, wiki pages, provenance, and agent-facing tools that help coding agents answer analytics questions without inventing metrics or joins.
## Agent Entry Points
${link("/docs/ai-resources/agent-quickstart", "Agent Quickstart", "Task-first route for coding assistants using KTX")}
${link("/docs/agents-setup", "Agent Setup", "Copy-pasteable prompt for agents installing and configuring KTX")}
${link("/docs/ai-resources/markdown-access", "Markdown Access", "Fetch KTX docs as llms.txt, llms-full.txt, or per-page Markdown")}
${link("/docs/ai-resources/agent-instructions", "Agent Instructions", "Suggested instructions for coding assistants that need to read and cite KTX docs")}
${link("/docs/ai-resources/agent-quickstart", "Agent Quickstart", "Task-first route for coding assistants using ktx")}
${link("/docs/agents-setup", "Agent Setup", "Copy-pasteable prompt for agents installing and configuring ktx")}
${link("/docs/ai-resources/markdown-access", "Markdown Access", "Fetch ktx docs as llms.txt, llms-full.txt, or per-page Markdown")}
${link("/docs/ai-resources/agent-instructions", "Agent Instructions", "Suggested instructions for coding assistants that need to read and cite ktx docs")}
## Start Here
${link("/docs/getting-started/introduction", "Introduction", "What KTX is and who it is for")}
${link("/docs/getting-started/quickstart", "Quickstart", "Set up KTX and build your first context")}
${link("/docs/getting-started/introduction", "Introduction", "What ktx is and who it is for")}
${link("/docs/getting-started/quickstart", "Quickstart", "Set up ktx and build your first context")}
${link("/docs/guides/writing-context", "Writing Context", "Write semantic sources and wiki pages")}
## Machine-Readable Documentation
@ -81,7 +81,7 @@ ${link("/docs/cli-reference/ktx-connection", "ktx connection", "Connection manag
## Integrations
${link("/docs/integrations/primary-sources", "Primary Sources", "Connect KTX to databases and warehouses")}
${link("/docs/integrations/primary-sources", "Primary Sources", "Connect ktx to databases and warehouses")}
${link("/docs/integrations/context-sources", "Context Sources", "Ingest dbt, LookML, Metabase, Looker, MetricFlow, and Notion")}
## All Documentation
@ -92,7 +92,7 @@ ${buildPageIndex(pages)}
export async function buildLlmsFullTxt() {
const rendered = await Promise.all(getLlmDocsPages().map(getPageMarkdown));
return [`# KTX Full Documentation`, `Source: ${siteOrigin}`, ...rendered].join(
return [`# ktx Full Documentation`, `Source: ${siteOrigin}`, ...rendered].join(
"\n\n---\n\n",
);
}

4
docs-site/public/images/ingestion-flow-transparent.svg
View file

@ -1,5 +1,5 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1346" height="1710" viewBox="0 0 1346 1710" role="img" aria-labelledby="title desc">
<title id="title">KTX ingestion flow</title>
<title id="title">ktx ingestion flow</title>
<desc id="desc">Source systems flow through source connectors, context builder, reconciliation, and validation to create wiki Markdown and semantic-layer YAML outputs.</desc>
<defs>
<filter id="card-shadow" x="-12%" y="-12%" width="124%" height="124%" color-interpolation-filters="sRGB">
@ -198,7 +198,7 @@
<text class="tag" x="228" y="24">auto-maintained</text>
</g>
<text class="body" x="24" y="194">Metrics, joins, tables, dimensions, filters, and</text>
<text class="body" x="24" y="222">segments that KTX can validate and compile into</text>
<text class="body" x="24" y="222">segments that ktx can validate and compile into</text>
<text class="body" x="24" y="250">SQL.</text>
</g>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

Before After
Before After

10
docs-site/tests/product-mechanics-content.test.mjs
View file

@ -22,8 +22,8 @@ test("docs introduction frames the concept before showing product mechanics", as
assert.match(introduction, /<ProductMechanics\s*\/>/);
const heroIndex = introduction.indexOf("Make analytics context");
const whyIndex = introduction.indexOf("## Why KTX");
const worksIndex = introduction.indexOf("## How KTX works");
const whyIndex = introduction.indexOf("## Why ktx helps");
const worksIndex = introduction.indexOf("## How ktx works");
const mechanicsIndex = introduction.indexOf("<ProductMechanics />");
const useCaseIndex = introduction.indexOf("## Use it for");
const heroSource = introduction.slice(0, mechanicsIndex);
@ -116,15 +116,15 @@ test("product mechanics component explains ingestion outputs", async () => {
assert.doesNotMatch(component, /raw-sources/);
assert.doesNotMatch(component, /\.ktx/);
assert.doesNotMatch(component, /Product mechanics/);
assert.doesNotMatch(component, /How KTX works/);
assert.doesNotMatch(component, /How ktx works/);
assert.doesNotMatch(component, /Runtime/);
assert.doesNotMatch(component, /A semantic compiler for analytics agents/);
assert.doesNotMatch(component, /KTX does more than retrieve Markdown/);
assert.doesNotMatch(component, /ktx does more than retrieve Markdown/);
assert.doesNotMatch(component, /Plain Markdown \+ RAG/);
assert.doesNotMatch(component, /comparisonRows/);
assert.doesNotMatch(component, /ComparisonTable/);
assert.doesNotMatch(component, /Not just retrieval/);
assert.doesNotMatch(component, /KTX works in two moments/);
assert.doesNotMatch(component, /ktx works in two moments/);
assert.doesNotMatch(component, /name: "Metabase and query history"/);
assert.doesNotMatch(component, /name: "dbt, MetricFlow, LookML"/);
assert.doesNotMatch(component, /MySQL/);