mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-01 08:59:39 +02:00
docs: standardize ktx naming (#187)
* docs: align KTX terminology * docs: standardize ktx naming
This commit is contained in:
Andrey Avtomonov
GitHub
parent
2f70861a18
commit
17647a436a
43 changed files with 438 additions and 419 deletions
|
|
@ -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 <query> --json` | Search wiki pages |
|
||||
| `ktx sl --json` | List semantic-layer sources |
|
||||
| `ktx sl <query> --json` | Search semantic-layer sources |
|
||||
| `ktx sl --json` | List semantic sources |
|
||||
| `ktx sl <query> --json` | Search semantic sources |
|
||||
| `ktx sl validate <source> --connection-id <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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 <connectionId> --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 <id>` and check the `ktx sl query` flags |
|
||||
| Semantic query execution fails | Connection is missing, unreachable, or query execution is disabled | Run `ktx connection test <id>` and check the `ktx sl query` flags |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue