From 17647a436a323ea0d2f04c64a6564a3d79c6951f Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Wed, 20 May 2026 17:33:38 +0200 Subject: [PATCH] docs: standardize ktx naming (#187) * docs: align KTX terminology * docs: standardize ktx naming --- AGENTS.md | 37 ++++++--- README.md | 46 +++++------ docs-site/app/global.css | 4 +- docs-site/app/layout.config.tsx | 2 +- docs-site/app/layout.tsx | 4 +- docs-site/components/logo.tsx | 4 +- docs-site/components/product-mechanics.tsx | 10 +-- docs-site/components/semantic-layer-flow.tsx | 40 ++++----- docs-site/components/terminal-preview.tsx | 4 +- docs-site/content/agents-setup.md | 34 ++++---- .../docs/ai-resources/agent-instructions.mdx | 12 +-- .../docs/ai-resources/agent-quickstart.mdx | 10 +-- .../docs/ai-resources/markdown-access.mdx | 4 +- .../docs/ai-resources/prompt-recipes.mdx | 20 ++--- .../content/docs/cli-reference/ktx-admin.mdx | 20 ++--- .../docs/cli-reference/ktx-connection.mdx | 17 ++-- .../content/docs/cli-reference/ktx-ingest.mdx | 48 +++++------ .../content/docs/cli-reference/ktx-mcp.mdx | 10 +-- .../content/docs/cli-reference/ktx-setup.mdx | 40 ++++----- .../content/docs/cli-reference/ktx-sl.mdx | 24 +++--- .../content/docs/cli-reference/ktx-sql.mdx | 4 +- .../content/docs/cli-reference/ktx-status.mdx | 8 +- .../content/docs/cli-reference/ktx-wiki.mdx | 8 +- docs-site/content/docs/cli-reference/ktx.mdx | 12 +-- .../content/docs/community/contributing.mdx | 20 ++--- docs-site/content/docs/community/support.mdx | 12 +-- .../content/docs/concepts/context-as-code.mdx | 20 ++--- .../concepts/semantic-layer-internals.mdx | 44 +++++----- .../docs/concepts/the-context-layer.mdx | 39 ++++----- .../docs/getting-started/introduction.mdx | 30 +++---- .../docs/getting-started/quickstart.mdx | 30 +++---- .../content/docs/guides/building-context.mdx | 36 ++++---- .../content/docs/guides/llm-configuration.mdx | 10 +-- .../content/docs/guides/serving-agents.mdx | 22 ++--- .../content/docs/guides/writing-context.mdx | 4 +- .../docs/integrations/agent-clients.mdx | 82 +++++++++---------- .../docs/integrations/context-sources.mdx | 22 ++--- .../docs/integrations/primary-sources.mdx | 18 ++-- docs-site/content/docs/meta.json | 2 +- docs-site/lib/llm-docs.ts | 22 ++--- docs-site/next-env.d.ts | 2 +- .../images/ingestion-flow-transparent.svg | 8 +- .../tests/product-mechanics-content.test.mjs | 12 +-- 43 files changed, 438 insertions(+), 419 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f6ce3d98..32c7a624 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/README.md b/README.md index af3961fd..35e75470 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,24 @@

- KTX + ktx

- The context layer for analytics agents + The context layer for data agents

npm version Codecov Tests - Documentation - Join the KTX Slack community + Documentation + Join the ktx Slack community License Y Combinator P25

--- -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.

- KTX ingestion flow from source systems through validation to wiki and semantic-layer outputs + ktx ingestion flow from source systems through validation to wiki and semantic-layer outputs

## 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 | @@ -106,13 +106,13 @@ Agent integration ready: yes (codex:project) | `ktx ingest ` | Build context for one connection | | `ktx ingest --text "..."` | Capture free-form notes into memory | | `ktx ingest --file notes.md --connection-id ` | Capture a text file into memory | -| `ktx sl` | List semantic-layer sources | -| `ktx sl "revenue"` | Search semantic-layer sources | +| `ktx sl` | List semantic sources | +| `ktx sl "revenue"` | Search semantic sources | | `ktx sl validate --connection-id ` | Validate a semantic source | | `ktx sl query --measure --format sql` | Compile semantic-layer SQL | | `ktx sql --connection "select 1"` | Execute read-only SQL | | `ktx wiki` | List local wiki pages | -| `ktx wiki "revenue definition"` | Search local wiki context | +| `ktx wiki "revenue definition"` | Search local wiki pages | | `ktx mcp` | Show MCP daemon status | | `ktx mcp start` | Start the local MCP server for agent clients | @@ -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`. diff --git a/docs-site/app/global.css b/docs-site/app/global.css index d0f7ac21..b9124304 100644 --- a/docs-site/app/global.css +++ b/docs-site/app/global.css @@ -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; diff --git a/docs-site/app/layout.config.tsx b/docs-site/app/layout.config.tsx index 93b5c45b..3245ab09 100644 --- a/docs-site/app/layout.config.tsx +++ b/docs-site/app/layout.config.tsx @@ -19,7 +19,7 @@ export const baseOptions: BaseLayoutProps = { }, { type: "icon", - label: "Join the KTX Slack community", + label: "Join the ktx Slack community", icon: , text: "Slack", url: "https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ", diff --git a/docs-site/app/layout.tsx b/docs-site/app/layout.tsx index 230fd232..35e6c7de 100644 --- a/docs-site/app/layout.tsx +++ b/docs-site/app/layout.tsx @@ -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.", diff --git a/docs-site/components/logo.tsx b/docs-site/components/logo.tsx index 44ab7144..afc926a8 100644 --- a/docs-site/components/logo.tsx +++ b/docs-site/components/logo.tsx @@ -17,10 +17,10 @@ export function Logo() {
- KTX + ktx [] = [ { - title: "Source adapters", + title: "Source connectors", body: "Read each configured system in its native shape.", }, { @@ -105,7 +105,7 @@ const stageData: Omit[] = [ }, { title: "Reconciliation", - body: "Merge new evidence with the context that already exists.", + body: "Reconcile new evidence with the context that already exists.", }, { title: "Validation", @@ -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

- 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.

@@ -519,7 +519,7 @@ export function ProductMechanics() {

diff --git a/docs-site/components/semantic-layer-flow.tsx b/docs-site/components/semantic-layer-flow.tsx index b6d06dbf..b62d291f 100644 --- a/docs-site/components/semantic-layer-flow.tsx +++ b/docs-site/components/semantic-layer-flow.tsx @@ -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,8 +208,8 @@ const slQuery: SlQueryNode = { position: { x: RIGHT_LANE_X, y: SL_QUERY_Y }, data: { variant: "slQuery", - badge: "With KTX", - title: "Agent sends a Semantic Query", + badge: "With ktx", + title: "Agent sends a semantic query", caption: "Names the measures, dimensions, segments, and filters it wants. No SQL, no joins.", code: `{ @@ -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 ( @@ -429,37 +429,37 @@ const edges = [ source: "agent", target: "sl-query", type: "default" as const, - label: "sends Semantic Query", + label: "sends semantic query", labelBgPadding: [6, 3] as [number, number], labelBgBorderRadius: 4, 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({ {children} @@ -842,7 +842,7 @@ function EngineNodeView({ data }: NodeProps) { >

diff --git a/docs-site/components/terminal-preview.tsx b/docs-site/components/terminal-preview.tsx index d430c4ac..d5997125 100644 --- a/docs-site/components/terminal-preview.tsx +++ b/docs-site/components/terminal-preview.tsx @@ -15,7 +15,7 @@ export function TerminalPreview() { ktx setup
-
◆ Welcome to KTX setup
+
◆ Welcome to ktx setup
│
◇{" "} @@ -43,7 +43,7 @@ export function TerminalPreview() { enriching schema · detecting relationships · ingesting dbt
-
✓ KTX context is ready for agents.
+
✓ ktx context is ready for agents.
${" "} diff --git a/docs-site/content/agents-setup.md b/docs-site/content/agents-setup.md index 4fcaeb3f..4933ff10 100644 --- a/docs-site/content/agents-setup.md +++ b/docs-site/content/agents-setup.md @@ -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 schema 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 @@ -9,12 +9,12 @@ Set up KTX from scratch end-to-end as a fully autonomous, agent-driven replaceme - **Verify against docs, never guess.** CLI flags, config keys, and command names must come from the docs or from `ktx --help`. If something looks wrong or missing, say so explicitly. - **Print every command you run and its exit code.** Terse, not silent. - **Fail loudly with cause + fix.** When a command fails: capture the exact error, identify the cause, change something, retry. Never retry an unchanged command. Exceptions for *known soft-failures* are listed in Phase 4 - handle those without retrying. -- **No LLM-based ingestion in this flow.** Only `--fast` ingest (schema-only). The user can run `--deep` later. +- **No LLM-based ingestion in this flow.** Only `--fast` ingest. The user can run `--deep` later. - **Platform-agnostic.** Detect the host OS first and pick the right install commands / path syntax. Anything path- or shell-specific must branch on OS. # Authoritative docs -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 --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 --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,10 +55,10 @@ 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 `/.ktx/secrets/-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 `/.ktx/secrets/-url` and rewrite `ktx.yaml` to `url: file:…` - this is correct, secure behavior and not a bug. - Schemas / datasets to include (postgres / sqlserver / snowflake / bigquery only). - Optional `enabled_tables` allowlist if the user wants to scope ingest to specific tables. -5. **BI / metadata sources** (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Default: none. Ask only if the user mentions them. +5. **Context sources** (dbt, Metabase, Looker, LookML, MetricFlow, Notion). Default: none. Ask only if the user mentions them. ## Phase 4 - Configure the project @@ -90,14 +90,14 @@ Notes on the flags above: - **You don't need `--skip-agents` in this flow.** The agent integration step is opt-in: setup leaves it alone unless you pass `--agents --target `. -- **`--skip-sources`** is correct and is the documented way to leave BI/metadata sources unconfigured. +- **`--skip-sources`** is correct and is the documented way to leave context sources unconfigured. ### Known soft-failure: `ktx setup` exits 1 after a successful fast build -When you select a configuration that only does fast (schema-only) ingest, `ktx setup`'s final readiness verification fails with: +When you select a configuration that only does fast ingest, `ktx setup`'s final readiness verification fails with: ``` -KTX context build did not pass agent-readiness verification. +ktx context build did not pass agent-readiness verification. : deep database context has not completed. ``` @@ -119,7 +119,7 @@ Use a YAML-aware editor (e.g. `uv run python -c "import yaml; …"`) - do not ha ## Phase 5 - Verify -`ktx setup` already runs a fast schema ingest of every database connection it configures, so you do not need to re-ingest by default. For each configured connection: +`ktx setup` already runs a fast ingest of every database connection it configures, so you do not need to re-ingest by default. For each configured connection: ``` ktx connection test # must exit 0 @@ -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:/health` → expect HTTP 200 with `{"status":"healthy",…}`. 4. `curl -sS -X POST http://127.0.0.1:/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:` 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:` 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: LLM: / Embeddings: / -Runtime: managed Python ✓ (if the KTX daemon was started) +Runtime: managed Python ✓ (if the ktx daemon was started) Connections: - () status=ok schemas=[…] tables= @@ -180,7 +180,7 @@ Verdict: ready Then **Next steps** (copy-pasteable): 1. Enrich with AI descriptions and embeddings: `ktx ingest --deep` (several minutes per connection). 2. Add more connections later by rerunning this setup or via `ktx setup --database … --database-connection-id …`. -3. Configure BI sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) - see `ktx setup --help` for `--source …` flags. +3. Configure context sources (dbt, Metabase, Looker, LookML, MetricFlow, Notion) - see `ktx setup --help` for `--source …` flags. 4. Install agent integration: `ktx setup --agents --target ` (with optional `--global` for `claude-code`/`codex`). 5. Connect the agent / MCP: see docs at `https://docs.kaelio.com/ktx/`. @@ -198,4 +198,4 @@ End with a single line: `RESULT: PASS` or `RESULT: FAIL - `. - 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. diff --git a/docs-site/content/docs/ai-resources/agent-instructions.mdx b/docs-site/content/docs/ai-resources/agent-instructions.mdx index 67efa21c..37ee6ba9 100644 --- a/docs-site/content/docs/ai-resources/agent-instructions.mdx +++ b/docs-site/content/docs/ai-resources/agent-instructions.mdx @@ -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. ``` diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx index 0d49ab00..6a47f56f 100644 --- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx +++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx @@ -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. diff --git a/docs-site/content/docs/ai-resources/markdown-access.mdx b/docs-site/content/docs/ai-resources/markdown-access.mdx index 12bb7456..99fb1295 100644 --- a/docs-site/content/docs/ai-resources/markdown-access.mdx +++ b/docs-site/content/docs/ai-resources/markdown-access.mdx @@ -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 diff --git a/docs-site/content/docs/ai-resources/prompt-recipes.mdx b/docs-site/content/docs/ai-resources/prompt-recipes.mdx index 6498fc1d..c2a9f282 100644 --- a/docs-site/content/docs/ai-resources/prompt-recipes.mdx +++ b/docs-site/content/docs/ai-resources/prompt-recipes.mdx @@ -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: . 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: . 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: . 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: . 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. ``` diff --git a/docs-site/content/docs/cli-reference/ktx-admin.mdx b/docs-site/content/docs/cli-reference/ktx-admin.mdx index 966eac5a..54ac5f84 100644 --- a/docs-site/content/docs/cli-reference/ktx-admin.mdx +++ b/docs-site/content/docs/cli-reference/ktx-admin.mdx @@ -19,9 +19,9 @@ ktx admin [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 diff --git a/docs-site/content/docs/cli-reference/ktx-connection.mdx b/docs-site/content/docs/cli-reference/ktx-connection.mdx index 5c4c5324..36185d68 100644 --- a/docs-site/content/docs/cli-reference/ktx-connection.mdx +++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx @@ -1,11 +1,12 @@ --- title: "ktx connection" -description: "List and test configured data sources." +description: "List and test configured database and context-source connections." --- -Inspect configured connections in your KTX project. Connections define how KTX -reaches databases, warehouses, BI tools, source projects, and knowledge -systems. Use `ktx setup` to add, remove, or reconfigure them. +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. ## Command signature @@ -77,8 +78,8 @@ my-warehouse postgres `ktx connection test ` performs a lightweight connection probe. Native database connections report `Status: ok` when the connector probe -passes. Source connectors report connector-specific details such as Metabase -database count, Looker user, Notion bot, or Git repo URL. +passes. Context-source connectors report connector-specific details such as +Metabase database count, Looker user, Notion bot, or Git repo URL. ```text Connection test passed: my-warehouse @@ -102,7 +103,7 @@ configured connection and exit non-zero if any probe fails. | Error | Cause | Recovery | |-------|-------|----------| -| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection | +| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection | | Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection | -| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections | +| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the context-source mapping selections | | Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids | diff --git a/docs-site/content/docs/cli-reference/ktx-ingest.mdx b/docs-site/content/docs/cli-reference/ktx-ingest.mdx index 49b176b5..d4e06881 100644 --- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx +++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx @@ -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 ` ingests one configured connection. -- `ktx ingest --text "..."` (or `--file `) captures notes into KTX +- `ktx ingest --text "..."` (or `--file `) captures notes into **ktx** memory instead of ingesting a connection. Database connections run before context-source connections when more than one @@ -29,14 +29,14 @@ connection is selected. | Flag | Description | Default | |------|-------------|---------| | `--all` | Ingest all configured connections (same as bare invocation) | `false` | -| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` | -| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` | +| `--fast` | Use deterministic fast database ingest | Stored connection default, or `fast` | +| `--deep` | Use deep database ingest with AI-generated descriptions, embeddings, and relationship evidence | Stored connection default, or `fast` | | `--query-history` | Include database query-history usage patterns | Stored connection default | | `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default | | `--query-history-window-days ` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default | -| `--text ` | Capture inline text into KTX memory; repeatable | `[]` | -| `--file ` | Capture a text file into KTX memory; use `-` for stdin; repeatable | `[]` | -| `--connection-id ` | KTX connection id to tag captured text/file notes | - | +| `--text ` | Capture inline text into **ktx** memory; repeatable | `[]` | +| `--file ` | Capture a text file into **ktx** memory; use `-` for stdin; repeatable | `[]` | +| `--connection-id ` | **ktx** connection id to tag captured text/file notes | - | | `--user-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` | @@ -48,14 +48,14 @@ connection is selected. database connections. Query-history flags apply only to database connections that support query history. The window flag applies to BigQuery and Snowflake; Postgres reads the current `pg_stat_statements` aggregate data instead of a -time-windowed history table. Query-history ingest runs after schema ingest and +time-windowed history table. Query-history ingest runs after fast ingest and requires deep ingest readiness. When more than one connection is selected, database ingest runs first, then -source ingest and memory updates run for source connections. +context-source ingest and memory updates run for context-source connections. -Some ingest paths use the managed KTX Python runtime. Query-history ingest uses -it for SQL analysis, and Looker source ingest uses it for Looker identifier +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 use `--no-input` to fail fast with install guidance. @@ -69,13 +69,13 @@ use `--no-input` to fail fast with install guidance. # Build every configured connection (bare = --all) ktx ingest -# Build one database or source connection +# Build one database or context-source connection ktx ingest warehouse -# Force deterministic database schema ingest +# Force deterministic fast database ingest ktx ingest warehouse --fast -# Force AI-enriched database ingest +# Force deep database ingest with AI enrichment ktx ingest warehouse --deep # Include query-history usage patterns @@ -83,7 +83,7 @@ ktx ingest warehouse --deep --query-history # Set the lookback window for BigQuery or Snowflake query history ktx ingest warehouse --query-history-window-days 30 -# Build a source connection +# Build a context-source connection ktx ingest notion # Capture inline text into memory @@ -114,11 +114,11 @@ notion skipped skipped done done Use `--json` when a script or agent needs the selected plan and per-target results. -## Inspect source ingest traces +## Inspect context-source ingest traces -Source ingest writes persistent JSONL traces for postmortem debugging. Plain -ingest output prints the trace path near the report, run, and job identifiers -when a trace is available: +Context-source ingest writes persistent JSONL traces for postmortem debugging. +Plain ingest output prints the trace path near the report, run, and job +identifiers when a trace is available: ```text Report: report-abc123 @@ -141,7 +141,7 @@ jq -c '. | {at, level, phase, event, durationMs, data, error}' \ .ktx/ingest-traces//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: @@ -155,7 +155,7 @@ KTX_INGEST_TRACE_LEVEL=trace ktx ingest metabase |-------|-------|----------| | Connection not configured | The connection id is not present in `ktx.yaml` | Add the connection with `ktx setup` or update `ktx.yaml` | | Deep readiness is missing | `--deep` or query history needs model, embedding, and scan-enrichment configuration | Run `ktx setup` or rerun with `--fast` | -| Query history is unsupported | The selected database driver does not support query history | Run schema ingest without query-history flags | +| Query history is unsupported | The selected database driver does not support query history | Run fast ingest without query-history flags | | Python runtime is missing | The selected ingest target needs runtime-backed SQL analysis or source parsing | Accept the interactive prompt, rerun with `--yes`, or run the suggested `ktx admin runtime install` command | -| Source options were ignored | Depth and query-history flags were supplied for a non-database source | Omit database-only flags when ingesting source connections | +| Context-source options were ignored | Depth and query-history flags were supplied for a context-source connection | Omit database-only flags when ingesting context-source connections | | Text ingest stops early | `--fail-fast` was used and one item failed | Fix the failed item or rerun without `--fail-fast` to collect all failures | diff --git a/docs-site/content/docs/cli-reference/ktx-mcp.mdx b/docs-site/content/docs/cli-reference/ktx-mcp.mdx index 9f0dd189..79c6c949 100644 --- a/docs-site/content/docs/cli-reference/ktx-mcp.mdx +++ b/docs-site/content/docs/cli-reference/ktx-mcp.mdx @@ -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 [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 ` | +| 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 ` | | Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--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 | diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx index e98a51e4..87fcddaa 100644 --- a/docs-site/content/docs/cli-reference/ktx-setup.mdx +++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx @@ -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 ` | 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 ` | LLM model ID or backend model alias to validate and save | | `--anthropic-api-key-env ` | Environment variable containing the Anthropic API key | | `--anthropic-api-key-file ` | File containing the Anthropic API key | @@ -75,18 +75,18 @@ of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts | `--embedding-api-key-file ` | 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 Setup prepares the managed Python runtime when your selected configuration needs it. In the full setup flow, the runtime step runs after database and -source setup and before the initial context build. +context-source setup and before the initial context build. -KTX prepares the `core` runtime feature when query-history ingest, Looker -source ingest, database introspection fallback, or daemon-backed context build -paths need it. KTX prepares the `local-embeddings` runtime feature when you +**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 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 ` | 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. @@ -134,25 +134,25 @@ Enabling query history makes deep ingest readiness matter for later | Flag | Description | |------|-------------| -| `--source ` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` | -| `--source-connection-id ` | Connection id for source setup | +| `--source ` | Context-source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` | +| `--source-connection-id ` | Connection id for context-source setup | | `--source-path ` | Local source path for dbt, MetricFlow, or LookML | | `--source-git-url ` | Git URL for dbt, MetricFlow, or LookML | -| `--source-branch ` | Git branch for source setup | -| `--source-subpath ` | Repo subpath for source setup | +| `--source-branch ` | Git branch for context-source setup | +| `--source-subpath ` | Repo subpath for context-source setup | | `--source-auth-token-ref ` | `env:` or `file:` credential reference for source repo auth | | `--source-url ` | Source service URL for Metabase or Looker | | `--source-api-key-ref ` | `env:` or `file:` API key reference for Metabase or Notion | | `--source-client-id ` | Looker client id | | `--source-client-secret-ref ` | `env:` or `file:` Looker client secret reference | -| `--source-warehouse-connection-id ` | Warehouse connection id used for source mapping | +| `--source-warehouse-connection-id ` | Warehouse connection id used for context-source mapping | | `--source-project-name ` | dbt project name override | | `--source-profiles-path ` | dbt profiles path | -| `--source-target ` | dbt target or source-specific mapping target | +| `--source-target ` | dbt target or context-source-specific mapping target | | `--metabase-database-id ` | Metabase database id to map | | `--notion-crawl-mode ` | Notion crawl mode: `all_accessible` or `selected_roots` | | `--notion-root-page-id ` | Notion root page id; repeatable | -| `--skip-sources` | Mark optional source setup complete with no sources | +| `--skip-sources` | Mark optional context-source setup complete with no sources | Choose only one source location: `--source-path` or `--source-git-url`. @@ -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) ``` diff --git a/docs-site/content/docs/cli-reference/ktx-sl.mdx b/docs-site/content/docs/cli-reference/ktx-sl.mdx index e0c6a101..2dfba7ab 100644 --- a/docs-site/content/docs/cli-reference/ktx-sl.mdx +++ b/docs-site/content/docs/cli-reference/ktx-sl.mdx @@ -1,6 +1,6 @@ --- title: "ktx sl" -description: "List, search, validate, or query semantic-layer sources." +description: "List, search, validate, or query semantic sources." --- Interact with your project's semantic layer. Semantic sources are YAML @@ -15,8 +15,8 @@ ktx sl validate [options] ktx sl query [options] ``` -- Bare `ktx sl` lists semantic-layer sources. -- `ktx sl ` searches semantic-layer sources (multi-word queries are +- Bare `ktx sl` lists semantic sources. +- `ktx sl ` searches semantic sources (multi-word queries are joined with a space). - `ktx sl validate` and `ktx sl query` remain as explicit subcommands. @@ -24,10 +24,10 @@ ktx sl query [options] | Subcommand | Description | |-----------|-------------| -| (none, no query) | List semantic-layer sources | -| (none, with query) | Search semantic-layer sources | -| `validate ` | Validate a semantic-layer source against the database schema | -| `query` | Compile or execute a Semantic Query | +| (none, no query) | List semantic sources | +| (none, with query) | Search semantic sources | +| `validate ` | Validate a semantic source against the database schema | +| `query` | Compile or execute a semantic query | ## Options @@ -35,7 +35,7 @@ ktx sl query [options] | Flag | Description | Default | |------|-------------|---------| -| `--connection-id ` | Filter by KTX connection id | - | +| `--connection-id ` | Filter by **ktx** connection id | - | | `--limit ` | Maximum search results (search mode only) | - | | `--output ` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` | | `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` | @@ -44,14 +44,14 @@ ktx sl query [options] | Flag | Description | Default | |------|-------------|---------| -| `--connection-id ` | KTX connection id (required) | - | +| `--connection-id ` | **ktx** connection id (required) | - | ### `sl query` | Flag | Description | Default | |------|-------------|---------| -| `--connection-id ` | KTX connection id | - | -| `--query-file ` | JSON Semantic Query file | - | +| `--connection-id ` | **ktx** connection id | - | +| `--query-file ` | JSON semantic query file | - | | `--measure ` | Measure to query; repeatable (at least one required) | - | | `--dimension ` | Dimension to include; repeatable | - | | `--filter ` | Filter expression; repeatable | - | @@ -66,7 +66,7 @@ ktx sl query [options] | `--max-rows ` | Maximum rows to return when executing | - | `sl query` requires at least one `--measure` unless `--query-file` is set. -`--query-file` should point to a JSON Semantic Query object. +`--query-file` should point to a JSON semantic query object. ## Examples diff --git a/docs-site/content/docs/cli-reference/ktx-sql.mdx b/docs-site/content/docs/cli-reference/ktx-sql.mdx index ae4c9990..d78864e2 100644 --- a/docs-site/content/docs/cli-reference/ktx-sql.mdx +++ b/docs-site/content/docs/cli-reference/ktx-sql.mdx @@ -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 ` | KTX database connection id. Required. | - | +| `-c`, `--connection ` | **ktx** database connection id. Required. | - | | `--max-rows ` | Maximum rows to return. Must be between `1` and `10000`. | `1000` | | `--output ` | Output mode: `pretty`, `plain` (TSV), or `json`. | `pretty` | | `--json` | Shortcut for `--output=json` (overrides `--output`). | `false` | diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index c6a1b715..17c07a09 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -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 | diff --git a/docs-site/content/docs/cli-reference/ktx-wiki.mdx b/docs-site/content/docs/cli-reference/ktx-wiki.mdx index aac60a07..2d52d5af 100644 --- a/docs-site/content/docs/cli-reference/ktx-wiki.mdx +++ b/docs-site/content/docs/cli-reference/ktx-wiki.mdx @@ -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 ` 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: diff --git a/docs-site/content/docs/cli-reference/ktx.mdx b/docs-site/content/docs/cli-reference/ktx.mdx index 65cdc5ff..010100d8 100644 --- a/docs-site/content/docs/cli-reference/ktx.mdx +++ b/docs-site/content/docs/cli-reference/ktx.mdx @@ -1,10 +1,10 @@ --- 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 -connections, queries semantic-layer sources, searches wiki pages, runs the MCP +connections, queries semantic sources, searches wiki pages, runs the MCP server, and manages the bundled Python runtime. ## Command signature @@ -13,7 +13,7 @@ server, and manages the bundled Python runtime. ktx [global-options] ``` -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 ` | KTX project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. | +| `--project-dir ` | **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 ` 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. @@ -93,7 +93,7 @@ ktx ingest warehouse # Build every configured connection ktx ingest -# Search semantic-layer sources and wiki pages +# Search semantic sources and wiki pages ktx sl "revenue" ktx wiki "revenue recognition" diff --git a/docs-site/content/docs/community/contributing.mdx b/docs-site/content/docs/community/contributing.mdx index bf66f546..10b12fe0 100644 --- a/docs-site/content/docs/community/contributing.mdx +++ b/docs-site/content/docs/community/contributing.mdx @@ -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 database agents. The project welcomes +**ktx** is an open-source context layer for data agents. The project welcomes focused contributions that improve setup, integrations, CLI behavior, documentation, connector coverage, and examples. @@ -24,13 +24,13 @@ documentation, connector coverage, and examples. | CLI and setup | `packages/cli`, especially setup steps, command definitions, status checks, and smoke tests | | Context engine | `packages/context`, including project config, ingest orchestration, and semantic search | | Connectors | `packages/connector-*`, plus connector-specific tests and integration docs | -| Python semantic layer | `python/ktx-sl` for planning and SQL generation | -| KTX daemon | `python/ktx-daemon` for the portable runtime API | +| Python semantic layer | `python/ktx-sl` for planning and SQL compilation | +| **ktx** daemon | `python/ktx-daemon` for the portable runtime API | | Documentation | `docs-site/content/docs` for public docs and `docs-site/tests` for docs behavior | ## 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 @@ -97,7 +97,7 @@ packages/ connector-posthog/ # PostHog connector python/ - ktx-sl/ # Semantic layer - grain-aware query planning and SQL generation + ktx-sl/ # Semantic layer - grain-aware query planning and SQL compilation ktx-daemon/ # Daemon - portable API server around the semantic layer examples/ # Example projects and fixtures @@ -226,7 +226,7 @@ and statistics. ### Step 4: Wire it up -Register the new connector driver in `packages/context` so the CLI and scan +Register the new connector in `packages/context` so the CLI and scan engine can instantiate it. Look at how existing connectors are registered for the pattern. @@ -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 | |------------|--------------------| diff --git a/docs-site/content/docs/community/support.mdx b/docs-site/content/docs/community/support.mdx index d53e168c..1aac5057 100644 --- a/docs-site/content/docs/community/support.mdx +++ b/docs-site/content/docs/community/support.mdx @@ -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`. diff --git a/docs-site/content/docs/concepts/context-as-code.mdx b/docs-site/content/docs/concepts/context-as-code.mdx index 6636b700..c1f1b2ff 100644 --- a/docs-site/content/docs/concepts/context-as-code.mdx +++ b/docs-site/content/docs/concepts/context-as-code.mdx @@ -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,20 +19,20 @@ 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 -adapters, then reconciles them into local files. +Notion, warehouse metadata, and analyst notes. **ktx** reads those inputs through +connectors, then reconciles them into local files. ```text -source tools -> adapters -> reconciliation agent -> YAML + Markdown diffs +context sources -> connectors -> reconciliation agent -> YAML + Markdown diffs ``` | Step | What happens | Output | |------|--------------|--------| -| **Extract** | Adapters read models, metrics, questions, schemas, and docs | Structured metadata | +| **Extract** | Connectors read models, metrics, questions, schemas, and docs | Structured metadata | | **Reconcile** | The agent compares incoming facts with existing context | Create, update, skip, or flag | -| **Write** | KTX saves changed semantic sources and wiki pages | Reviewable project files | +| **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 @@ -88,7 +88,7 @@ context layer converge toward the team's current source of truth. ## Deterministic replay -Every ingestion session records the adapter inputs, tool calls, LLM responses, +Every ingestion session records the connector inputs, tool calls, LLM responses, write decisions, and reasoning behind each change. | Use case | What replay gives you | @@ -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 | diff --git a/docs-site/content/docs/concepts/semantic-layer-internals.mdx b/docs-site/content/docs/concepts/semantic-layer-internals.mdx index f64836fe..c5c183b0 100644 --- a/docs-site/content/docs/concepts/semantic-layer-internals.mdx +++ b/docs-site/content/docs/concepts/semantic-layer-internals.mdx @@ -1,24 +1,24 @@ --- -title: Semantic Querying -description: How KTX compiles a short Semantic Query into safe, dialect-correct SQL using a reviewed join graph. +title: Semantic querying +description: How ktx compiles a short semantic query into safe, dialect-correct SQL using a reviewed join graph. --- import { SemanticLayerFlow } from "@/components/semantic-layer-flow"; -KTX's semantic layer is a compiler that turns intent into SQL. The agent +**ktx**'s semantic layer is a compiler that turns intent into SQL. The agent declares _what_ it wants - measures, dimensions, filters - in a small -Semantic Query. KTX figures out the _how_: which tables to join, what +semantic query. **ktx** figures out the _how_: which tables to join, what grain to aggregate at, how to keep fan-out from inflating measures, and what dialect the warehouse speaks. This page covers four mechanics: -- The Semantic Query contract agents send to the compiler. -- The planner steps that turn a Semantic Query into SQL. +- The semantic query contract agents send to the compiler. +- The planner steps that turn a semantic query into SQL. - The join graph that backs those steps, and how it's built. - The fan-out failure mode the compiler is designed to prevent. -## Imperative SQL vs declarative Semantic Querying +## Imperative SQL vs declarative semantic querying Writing analytics SQL is imperative work. Every question forces the agent to hold two things in mind at once: _what_ it wants - a measure, a @@ -27,28 +27,28 @@ 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 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. -## The Semantic Query contract +## The semantic query contract -A Semantic Query is the JSON payload the agent sends. Every field is optional +A semantic query is the JSON payload the agent sends. Every field is optional except `measures`, and column references are fully qualified (`source.column`) so the compiler never has to guess where a name came 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,12 +71,12 @@ 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 -The planner is a deterministic pipeline. Each Semantic Query runs through the +The planner is a deterministic pipeline. Each semantic query runs through the same ordered steps before any SQL is emitted. 1. **Resolve refs.** Qualify bare column names, look up pre-defined @@ -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//` holds scan evidence from your warehouse: @@ -327,14 +327,14 @@ 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. | Agent task | Relevant section | Next page | |------------|------------------|-----------| -| Explain the Semantic Query shape | The Semantic Query contract | [ktx sl](/docs/cli-reference/ktx-sl) | +| 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) | diff --git a/docs-site/content/docs/concepts/the-context-layer.mdx b/docs-site/content/docs/concepts/the-context-layer.mdx index 9f5e3689..af2a6bdb 100644 --- a/docs-site/content/docs/concepts/the-context-layer.mdx +++ b/docs-site/content/docs/concepts/the-context-layer.mdx @@ -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.

@@ -121,7 +121,8 @@ caveat stays anchored to the definition it explains.

{"Behind the scenes. "} - {"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 "} + {"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 "} {"Context as Code"} {" for how that audit trail flows into review."}
@@ -156,7 +157,7 @@ joins: ``` For how the compiler walks the join graph, handles fan-out, and transpiles -dialects, read [Semantic Querying](/docs/concepts/semantic-layer-internals). +dialects, read [Semantic querying](/docs/concepts/semantic-layer-internals). ## Wiki pages @@ -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 database agent wrote a plausible but wrong query | Database access isn't enough | [Writing Context](/docs/guides/writing-context) | +| 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) | diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 2bf6e9b1..c9ec7407 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -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

- {'KTX is an open-source context layer for database agents. It turns warehouse metadata, BI models, query history, docs, and approved metric definitions into reviewable files agents can search and execute.'} + {'ktx is an open-source context layer for data agents. It turns warehouse metadata, BI tool definitions, query history, docs, and approved metric definitions into reviewable files agents can search and execute.'}

-## 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,12 +60,12 @@ 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. - Generate SQL from approved metrics, joins, filters, and dimensions. -- Explain metric provenance with wiki context and source evidence. +- Explain metric provenance with wiki content and source evidence. - Repair context through reviewable YAML and Markdown diffs. - Work alongside dbt, MetricFlow, LookML, Looker, Metabase, Notion, and supported databases. @@ -77,7 +77,7 @@ best first step for users; contributor setup lives in the community docs. - Install KTX, run setup, build context, and connect an agent. + Install **ktx**, run setup, build context, and connect an agent. 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. - Complete flag and subcommand reference for every KTX command. + Complete flag and subcommand reference for every **ktx** command. 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 diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx index 14fe476f..0971eaaf 100644 --- a/docs-site/content/docs/getting-started/quickstart.mdx +++ b/docs-site/content/docs/getting-started/quickstart.mdx @@ -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?
- 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`.
@@ -54,7 +54,7 @@ If you're a coding assistant choosing a docs route, start with the
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{' '} agent setup Markdown prompt {' '} @@ -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 @@ -117,12 +117,12 @@ The wizard walks you through everything KTX needs in one pass: SQLite, PostgreSQL, MySQL, SQL Server, BigQuery, and Snowflake. 5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker, Metabase, or Notion. You can skip and add them later. -6. **Build** - runs the first ingest so semantic-layer sources and wiki pages +6. **Build** - runs the first ingest so semantic sources and wiki pages are ready for agents. 7. **Agent integration** - installs project-local rules for Claude Code, Codex, Cursor, OpenCode, or universal `.agents`. -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,19 +192,19 @@ 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 | |------|---------| | `ktx.yaml` | Project configuration | | `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml` - do not commit | -| `semantic-layer//*.yaml` | Semantic sources for SQL generation | +| `semantic-layer//*.yaml` | Semantic sources for SQL compilation | | `wiki/global/*.md` | Shared business context and metric definitions | | `.claude/skills/ktx/`, `.agents/skills/ktx/`, `.cursor/rules/ktx.mdc`, `.opencode/commands/ktx.md` | Installed agent rules | diff --git a/docs-site/content/docs/guides/building-context.mdx b/docs-site/content/docs/guides/building-context.mdx index b1d5ed36..d6d58053 100644 --- a/docs-site/content/docs/guides/building-context.mdx +++ b/docs-site/content/docs/guides/building-context.mdx @@ -1,10 +1,10 @@ --- title: Building Context -description: Build and refresh KTX context from databases, source tools, 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-layer 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,12 +34,12 @@ 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 | |------|----------|--------------| -| `--fast` | First setup, quick refreshes, CI smoke checks | Deterministic schema ingest with tables, columns, types, constraints, and row counts | -| `--deep` | Agent-ready context for real analysis | Fast ingest plus AI-enriched descriptions, embeddings, relationship evidence, and optional query history | +| `--fast` | First setup, quick refreshes, CI smoke checks | Deterministic fast ingest with tables, columns, types, constraints, and row counts | +| `--deep` | Agent-ready context for real analysis | Fast ingest plus deep enrichment with descriptions, embeddings, relationship evidence, and optional query history | Examples: @@ -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 @@ -83,10 +83,10 @@ Context-source connections pull metadata from dbt, BI tools, Notion, and other configured systems. Pass one connection id or `--all`. ```bash -# Build one source connection +# Build one context-source connection ktx ingest dbt_main -# Build every configured database and source connection +# Build every configured database and context-source connection ktx ingest --all ``` @@ -101,8 +101,8 @@ Supported source types: | `metabase` | Metabase API | Questions, dashboards, table metadata, and mappings | | `notion` | Notion API | Wiki pages and business knowledge | -Source ingest writes semantic-layer YAML and wiki Markdown, merging with local -edits. +Context-source ingest writes semantic source YAML and wiki Markdown, reconciling +with local edits. ## Text ingest @@ -126,12 +126,12 @@ Useful flags: |------|-------------| | `--text ` | Capture inline text into memory; repeatable | | `--file ` | Capture a text file (or `-` for stdin) into memory; repeatable | -| `--connection-id ` | Attach the captured memory to a KTX connection | +| `--connection-id ` | Attach the captured memory to a **ktx** connection | | `--user-id ` | Attribute capture to a user scope, default `local-cli` | | `--json` | Print structured output | | `--fail-fast` | Stop after the first failed text/file item | -Use text ingest for small, high-signal documents. Prefer configured source +Use text ingest for small, high-signal documents. Prefer configured context-source ingest for Notion, dbt, Metabase, and similar systems. ## Output and artifacts @@ -146,8 +146,8 @@ Typical generated files: | Path | Created by | Purpose | |------|------------|---------| -| `semantic-layer//*.yaml` | Database and source ingest | Queryable semantic source definitions | -| `wiki/global/*.md` | Source, text, and memory ingest | Shared business definitions and notes | +| `semantic-layer//*.yaml` | Database and context-source ingest | Queryable semantic source definitions | +| `wiki/global/*.md` | Context-source, text, and memory ingest | Shared business definitions and notes | | `wiki/user//*.md` | Text and memory ingest | User-scoped context | | `.ktx/setup/context-build.json` | Setup context build | Resume and readiness state for setup | @@ -177,7 +177,7 @@ ktx wiki "revenue" --json --limit 10 |---------|--------------|----------| | Connection not configured | The connection id is missing from `ktx.yaml` | Add it with `ktx setup` | | Deep readiness is missing | LLM or embeddings are not setup-ready | Run `ktx setup`, or rerun with `--fast` | -| Query history is unsupported | The selected database driver does not expose query history | Run schema ingest without query-history flags | -| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection | -| Source flags have no effect | Depth and query-history flags were supplied for a source connector | Use those flags only for database connections | +| Query history is unsupported | The selected database driver does not expose query history | Run fast ingest without query-history flags | +| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection | +| Context-source flags have no effect | Depth and query-history flags were supplied for a context-source connector | Use those flags only for database connections | | Text ingest stops early | `--fail-fast` stopped on the first failed item | Fix the item or rerun without `--fail-fast` | diff --git a/docs-site/content/docs/guides/llm-configuration.mdx b/docs-site/content/docs/guides/llm-configuration.mdx index 7e86cf96..880df24e 100644 --- a/docs-site/content/docs/guides/llm-configuration.mdx +++ b/docs-site/content/docs/guides/llm-configuration.mdx @@ -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 diff --git a/docs-site/content/docs/guides/serving-agents.mdx b/docs-site/content/docs/guides/serving-agents.mdx index df6eba2a..4c1ced4b 100644 --- a/docs-site/content/docs/guides/serving-agents.mdx +++ b/docs-site/content/docs/guides/serving-agents.mdx @@ -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 @@ -103,7 +103,7 @@ ktx wiki --json ktx wiki "revenue recognition" --json --limit 10 ``` -Search wiki context for business definitions, metric caveats, process rules, and +Search the wiki for business definitions, metric caveats, process rules, and non-obvious terms. ### Context refresh @@ -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 ` and `ktx wiki ` 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 ` and restart the agent session | -| Agent command cannot find the project | Agent is running outside the KTX directory | Add `--project-dir ` 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 ` and restart the agent session | +| Agent command cannot find the project | Agent is running outside the **ktx** directory | Add `--project-dir ` 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 `, 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 | diff --git a/docs-site/content/docs/guides/writing-context.mdx b/docs-site/content/docs/guides/writing-context.mdx index 066c4dea..e4ac70c0 100644 --- a/docs-site/content/docs/guides/writing-context.mdx +++ b/docs-site/content/docs/guides/writing-context.mdx @@ -44,7 +44,7 @@ Use this order for most context changes: Semantic sources are YAML files for queryable tables or custom SQL. They define agent-facing measures, dimensions, segments, joins, and grain. -Source files live at: +Semantic source files live at: ```text semantic-layer//.yaml @@ -259,7 +259,7 @@ ktx sl query \ ## Wiki pages -Wiki pages hold context that does not belong in one source file: policies, +Wiki pages hold context that does not belong in one semantic source: policies, caveats, vocabulary, freshness, known issues, and source-of-truth notes. Wiki files live under: diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx index 9f1ad659..23430e0c 100644 --- a/docs-site/content/docs/integrations/agent-clients.mdx +++ b/docs-site/content/docs/integrations/agent-clients.mdx @@ -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,16 +276,16 @@ 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 | |---------|-------------| | `ktx status --json` | Return project setup and context readiness | | `ktx wiki --json` | Search wiki pages | -| `ktx sl --json` | List semantic-layer sources | -| `ktx sl --json` | Search semantic-layer sources | +| `ktx sl --json` | List semantic sources | +| `ktx sl --json` | Search semantic sources | | `ktx sl validate --connection-id ` | Validate semantic source definitions | -| `ktx sl query --format json` | Execute a Semantic Query when semantic compute is configured | +| `ktx sl query --format json` | Execute a semantic query when semantic compute is configured | ### Security constraints diff --git a/docs-site/content/docs/integrations/context-sources.mdx b/docs-site/content/docs/integrations/context-sources.mdx index 15137056..213f5a3d 100644 --- a/docs-site/content/docs/integrations/context-sources.mdx +++ b/docs-site/content/docs/integrations/context-sources.mdx @@ -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 an LLM agent to reconcile it with your existing semantic layer and knowledge base - merging intelligently 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. @@ -27,7 +27,7 @@ LookML uses top-level `repoUrl`, and MetricFlow uses nested | Field | Required | Description | |-------|----------|-------------| -| `driver` | Yes | Source adapter: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` | +| `driver` | Yes | Source connector: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` | | `source_dir` | For local file sources | Absolute or project-relative source directory | | `repo_url` | For Git-hosted dbt sources | Git repository URL | | `repoUrl` | For Git-hosted LookML sources | Git repository URL | @@ -88,7 +88,7 @@ connections: ### What gets ingested - YAML semantic sources generated from dbt schema files -- One work unit per model file (for projects with >25 YAML files) or all at once for smaller projects +- One work unit per semantic source (for projects with >25 YAML files) or all at once for smaller projects - Column descriptions, tests, and relationships are preserved --- @@ -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: @@ -316,7 +316,7 @@ Ingests pages and databases from a Notion workspace as wiki pages. Useful for ca - Wiki pages synthesized from Notion content - Page hierarchy and relationships -- Database schemas (when Notion databases describe data sources) +- Database schemas (when Notion databases describe primary sources) - Semantic clustering for organized ingestion ### Connection config @@ -378,7 +378,7 @@ Create an integration at [notion.so/my-integrations](https://www.notion.so/my-in | Error or symptom | Likely cause | Recovery | |------------------|--------------|----------| -| Adapter cannot read source files | `source_dir`, `repo_url`, `repoUrl`, `metricflow.repoUrl`, `branch`, or `path` is wrong | Verify the path locally or clone the repo manually with the same credentials | +| Connector cannot read source files | `source_dir`, `repo_url`, `repoUrl`, `metricflow.repoUrl`, `branch`, or `path` is wrong | Verify the path locally or clone the repo manually with the same credentials | | Private repo/API authentication fails | Token env var or secret file is missing | Export the env var or update `auth_token_ref` to a readable file | | Ingest creates duplicate context | Existing source names or wiki pages do not match imported terminology | Review the diff, rename duplicates, and add wiki pages with canonical names | | Notion ingest skips pages | Integration lacks access or root ids are missing | Share pages with the Notion integration and set `root_page_ids` or use `all_accessible` carefully | diff --git a/docs-site/content/docs/integrations/primary-sources.mdx b/docs-site/content/docs/integrations/primary-sources.mdx index 28ff4559..da916339 100644 --- a/docs-site/content/docs/integrations/primary-sources.mdx +++ b/docs-site/content/docs/integrations/primary-sources.mdx @@ -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:** @@ -109,7 +109,7 @@ This helps KTX understand how your team actually queries the data. ### Dialect notes -- SQL generation uses `LIMIT/OFFSET` pagination +- SQL compilation uses `LIMIT/OFFSET` pagination - Named parameters converted to positional (`$1`, `$2`, ...) - Supports `COUNT(*) FILTER (WHERE ...)` for null analysis - Full support for PostgreSQL types: `uuid`, `jsonb`, `timestamptz`, `numeric`, `text[]`, etc. @@ -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 @@ -458,4 +458,4 @@ No authentication required - SQLite is file-based. The file must be readable by | Database ingest returns no tables | Schema, database, or project filter is wrong, or the user lacks metadata permissions | Verify the schema list and grant metadata read permissions | | Query history is empty | Query history extension or warehouse history view is unavailable | Enable the warehouse-specific history feature, then rerun `ktx ingest --query-history` or `ktx setup` | | Column statistics are missing | Connector cannot access stats tables or the warehouse does not expose them | Grant stats permissions where supported; otherwise rely on fast schema context | -| Semantic Query execution fails | Connection is missing, unreachable, or query execution is disabled | Run `ktx connection test ` and check the `ktx sl query` flags | +| Semantic query execution fails | Connection is missing, unreachable, or query execution is disabled | Run `ktx connection test ` and check the `ktx sl query` flags | diff --git a/docs-site/content/docs/meta.json b/docs-site/content/docs/meta.json index 6fbee965..983af245 100644 --- a/docs-site/content/docs/meta.json +++ b/docs-site/content/docs/meta.json @@ -1,6 +1,6 @@ { "root": true, - "title": "KTX", + "title": "ktx", "pages": [ "getting-started", "concepts", diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts index f821ca30..7ed338a0 100644 --- a/docs-site/lib/llm-docs.ts +++ b/docs-site/lib/llm-docs.ts @@ -44,23 +44,23 @@ export function buildLlmsTxt() { return `- [${label}](${absoluteUrl(markdownUrl)}): ${description}`; }; - return `# KTX + return `# ktx -> Agent-native context layer for analytics engineering and database agents. +> 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", ); } diff --git a/docs-site/next-env.d.ts b/docs-site/next-env.d.ts index c4b7818f..9edff1c7 100644 --- a/docs-site/next-env.d.ts +++ b/docs-site/next-env.d.ts @@ -1,6 +1,6 @@ /// /// -import "./.next/dev/types/routes.d.ts"; +import "./.next/types/routes.d.ts"; // NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. diff --git a/docs-site/public/images/ingestion-flow-transparent.svg b/docs-site/public/images/ingestion-flow-transparent.svg index 3eebd91e..86356d6b 100644 --- a/docs-site/public/images/ingestion-flow-transparent.svg +++ b/docs-site/public/images/ingestion-flow-transparent.svg @@ -1,6 +1,6 @@ - KTX ingestion flow - Source systems flow through source adapters, context builder, reconciliation, and validation to create wiki Markdown and semantic-layer YAML outputs. + ktx ingestion flow + Source systems flow through source connectors, context builder, reconciliation, and validation to create wiki Markdown and semantic-layer YAML outputs. @@ -135,7 +135,7 @@ 1 - Source adapters + Source connectors Read each configured system in its native shape. @@ -198,7 +198,7 @@ auto-maintained Metrics, joins, tables, dimensions, filters, and - segments that KTX can validate and compile into + segments that ktx can validate and compile into SQL. diff --git a/docs-site/tests/product-mechanics-content.test.mjs b/docs-site/tests/product-mechanics-content.test.mjs index d0f1cb0c..5cce9001 100644 --- a/docs-site/tests/product-mechanics-content.test.mjs +++ b/docs-site/tests/product-mechanics-content.test.mjs @@ -22,8 +22,8 @@ test("docs introduction frames the concept before showing product mechanics", as assert.match(introduction, //); 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(""); const useCaseIndex = introduction.indexOf("## Use it for"); const heroSource = introduction.slice(0, mechanicsIndex); @@ -68,7 +68,7 @@ test("product mechanics component explains ingestion outputs", async () => { "BI tools", "Modeling code", "Docs and notes", - "Source adapters", + "Source connectors", "Context builder", "Reconciliation", "Validation", @@ -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/);