mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-25 08:48:08 +02:00
docs: standardize ktx naming
This commit is contained in:
Andrey Avtomonov
parent
27afd6a3b0
commit
1f8c1089f6
41 changed files with 331 additions and 313 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,7 +276,7 @@ Code's `SKILL.md`.
|
|||
|
||||
## Command reference
|
||||
|
||||
Admin CLI skills call the same KTX CLI commands:
|
||||
Admin CLI skills call the same **ktx** CLI commands:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: Context Sources
|
|||
description: Ingest semantic context from dbt, MetricFlow, LookML, Metabase, Looker, and Notion.
|
||||
---
|
||||
|
||||
Context sources feed your existing analytics tooling into KTX. During ingestion, KTX extracts metadata from each source and uses a reconciliation agent to reconcile it with your existing semantic layer and knowledge base - preserving accepted edits rather than overwriting.
|
||||
Context sources feed your existing analytics tooling into **ktx**. During ingestion, **ktx** extracts metadata from each source and uses a reconciliation agent to reconcile it with your existing semantic layer and knowledge base - preserving accepted edits rather than overwriting.
|
||||
|
||||
All context sources are configured in `ktx.yaml` under `connections` with their respective `driver` value.
|
||||
|
||||
|
|
@ -198,7 +198,7 @@ This validates that LookML model `connection:` declarations match expectations,
|
|||
|
||||
## Metabase
|
||||
|
||||
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your KTX warehouse connections.
|
||||
Ingests dashboards, questions, and their underlying SQL queries from a Metabase instance. Maps Metabase databases to your **ktx** warehouse connections.
|
||||
|
||||
### What it provides
|
||||
|
||||
|
|
@ -217,7 +217,7 @@ connections:
|
|||
api_key_ref: env:METABASE_API_KEY
|
||||
mappings:
|
||||
databaseMappings:
|
||||
"3": postgres-main # Metabase DB ID → KTX connection
|
||||
"3": postgres-main # Metabase DB ID → ktx connection
|
||||
syncEnabled:
|
||||
"3": true
|
||||
syncMode: ONLY # Only ingest mapped databases
|
||||
|
|
@ -239,7 +239,7 @@ Generate an API key in Metabase: **Admin > Settings > Authentication > API Keys*
|
|||
|
||||
### Warehouse mapping
|
||||
|
||||
Metabase databases must be mapped to KTX connections so ingested context links to the correct warehouse:
|
||||
Metabase databases must be mapped to **ktx** connections so ingested context links to the correct warehouse:
|
||||
|
||||
```yaml
|
||||
mappings:
|
||||
|
|
@ -256,7 +256,7 @@ Find Metabase database IDs in **Admin > Databases** - the ID is in the URL when
|
|||
|
||||
## Looker
|
||||
|
||||
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your KTX warehouse connections.
|
||||
Ingests explores, looks, and dashboards from a Looker instance via the Looker API. Maps Looker connections to your **ktx** warehouse connections.
|
||||
|
||||
### What it provides
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ connections:
|
|||
client_secret_ref: env:LOOKER_CLIENT_SECRET
|
||||
mappings:
|
||||
connectionMappings:
|
||||
postgres_connection: postgres-main # Looker conn → KTX conn
|
||||
postgres_connection: postgres-main # Looker conn → ktx conn
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
|
@ -296,7 +296,7 @@ Generate API credentials in Looker: **Admin > Users > Edit > API Keys**.
|
|||
|
||||
### Warehouse mapping
|
||||
|
||||
Map Looker connection names to KTX connections so explores link to the correct warehouse:
|
||||
Map Looker connection names to **ktx** connections so explores link to the correct warehouse:
|
||||
|
||||
```yaml
|
||||
mappings:
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: Primary Sources
|
||||
description: Connect KTX to PostgreSQL, Snowflake, BigQuery, MySQL, SQL Server, or SQLite.
|
||||
description: Connect ktx to PostgreSQL, Snowflake, BigQuery, MySQL, SQL Server, or SQLite.
|
||||
---
|
||||
|
||||
KTX connects to your data warehouse or database to build schema context,
|
||||
**ktx** connects to your data warehouse or database to build schema context,
|
||||
discover relationships, and execute semantic layer queries. Each connection is
|
||||
defined in `ktx.yaml` under the `connections` key.
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ All connectors share these conventions:
|
|||
|
||||
- Sensitive values support `env:VAR_NAME` (read from environment) and
|
||||
`file:/path/to/secret` (read from file) references
|
||||
- Connections are read-only; KTX never writes to your database
|
||||
- Connections are read-only; **ktx** never writes to your database
|
||||
- Database ingest discovers tables, columns, types, and constraints
|
||||
automatically
|
||||
|
||||
|
|
@ -90,11 +90,11 @@ connections:
|
|||
### Query history
|
||||
|
||||
PostgreSQL query history mines real query patterns from `pg_stat_statements`.
|
||||
This helps KTX understand how your team actually queries the data.
|
||||
This helps **ktx** understand how your team actually queries the data.
|
||||
|
||||
**Requirements:**
|
||||
- `pg_stat_statements` extension enabled
|
||||
- `pg_read_all_stats` role granted to the KTX user
|
||||
- `pg_read_all_stats` role granted to the **ktx** user
|
||||
|
||||
**Config options:**
|
||||
|
||||
|
|
@ -224,7 +224,7 @@ For multiple datasets:
|
|||
| Environment variable | `credentials_json: env:BIGQUERY_CREDENTIALS_JSON` |
|
||||
|
||||
The project ID is extracted automatically from the service account JSON file.
|
||||
If you set `project_id` in `ktx.yaml`, KTX treats it as local descriptor and
|
||||
If you set `project_id` in `ktx.yaml`, **ktx** treats it as local descriptor and
|
||||
mapping metadata. The BigQuery connector still authenticates with the
|
||||
`project_id` inside `credentials_json`.
|
||||
|
||||
|
|
@ -426,7 +426,7 @@ url: sqlite:///path/to/db.sqlite
|
|||
|
||||
### Authentication
|
||||
|
||||
No authentication required - SQLite is file-based. The file must be readable by the process running KTX.
|
||||
No authentication required - SQLite is file-based. The file must be readable by the process running **ktx**.
|
||||
|
||||
### Features
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue