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

docs(docs-site): add agent notes across docs

Browse source
This commit is contained in:
Luca Martial 2026-05-11 16:44:31 -07:00
parent 885072d2a9
commit f3f8aa613b
8 changed files with 146 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -10,6 +10,25 @@ KTX integrates with coding agents through two channels that can be used independ
Run `ktx setup` and select your agent targets, or configure manually using the snippets below.
## Agent setup matrix
Use this table to choose the setup path before editing client-specific files.
| Target | Project-scoped files | Global install | Recommended mode | Reload needed |
|--------|----------------------|----------------|------------------|---------------|
| Claude Code | `.claude/skills/ktx/SKILL.md`, `.mcp.json` | Yes | Both CLI skill and MCP | Skill reload is automatic; MCP starts on first use |
| Cursor | `.cursor/rules/ktx.mdc`, `.cursor/mcp.json` | No | Both CLI rule and MCP | Reload the Cursor window after MCP config changes |
| Codex | `.agents/skills/ktx/SKILL.md`, `.agents/mcp/ktx.json` | Yes | Both CLI skill and MCP | Start a new session after global skill changes |
| OpenCode | `.opencode/commands/ktx.md`, `.opencode/mcp.json` | No | Both CLI command and MCP | Restart OpenCode after config changes |
The safest generated command is:
```bash
ktx setup --agents --target codex --agent-install-mode both --project
```
Replace `codex` with `claude-code`, `cursor`, `opencode`, or `universal`.
## Claude Code
### Install via `ktx setup`
@ -277,3 +296,13 @@ All agent clients connect to the same KTX MCP server. The server exposes these t
| Global install | Yes | No | Yes | No |
| Config location | `.mcp.json` | `.cursor/mcp.json` | `.agents/mcp/ktx.json` | `.opencode/mcp.json` |
| Skills location | `.claude/skills/` | `.cursor/rules/` | `.agents/skills/` | `.opencode/commands/` |
## Common errors
| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| Agent cannot start MCP server | The config points to a missing `ktx` binary | Run `pnpm run link:dev`, rerun `ktx setup --agents`, or use an absolute command path |
| Agent sees MCP tools but queries fail | Server args omit `--semantic-compute` | Add `--semantic-compute`; add `--execute-queries` only when read-only execution is intended |
| Agent reads the wrong KTX project | `--project-dir` or `KTX_PROJECT_DIR` points at another directory | Regenerate project-scoped config from the intended project directory |
| CLI skill commands return non-JSON output | The generated command omitted `--json` or an agent changed it | Restore the generated skill/rule and ensure every `ktx agent` command includes `--json` |
| Cursor or OpenCode does not show new tools | The client has not reloaded its MCP config | Reload the app window or restart the agent client |

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

@ -7,6 +7,29 @@ Context sources feed your existing analytics tooling into KTX. During ingestion,
All context sources are configured in `ktx.yaml` under `connections` with their respective `driver` value.
## Ingestion workflow
Agents should configure and ingest context sources in this order:
1. Add the context source connection in `ktx.yaml` or with `ktx setup`.
2. Store tokens as `env:NAME` or `file:/path/to/secret`.
3. Run `ktx ingest <connectionId>` for one source or `ktx ingest --all`.
4. Check progress with `ktx ingest status --json`.
5. Review generated `semantic-layer/` YAML and `knowledge/` Markdown files in git.
6. Validate changed semantic sources with `ktx sl validate`.
## Shared source fields
| Field | Required | Description |
|-------|----------|-------------|
| `driver` | Yes | Source adapter: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` |
| `readonly` | Strongly recommended | Marks the source as read-only for KTX |
| `source_dir` | For local file sources | Absolute or project-relative source directory |
| `repo_url` | For Git-hosted sources | Git repository URL |
| `branch` | No | Git branch to read |
| `path` | No | Subdirectory inside a monorepo |
| `auth_token_ref` | For private APIs/repos | `env:NAME` or `file:/path/to/secret` token reference |
## dbt
Ingests schema definitions, model descriptions, column metadata, and test coverage from a dbt project.
@ -351,3 +374,13 @@ Create an integration at [notion.so/my-integrations](https://www.notion.so/my-in
- Notion is knowledge-only — it does not produce semantic layer sources
- Rate limits apply; large workspaces may require multiple ingestion runs
- `last_successful_cursor` is auto-managed for incremental sync
## Common errors
| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| Adapter cannot read source files | `source_dir`, `repo_url`, `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 knowledge pages do not match imported terminology | Review the diff, rename duplicates, and add knowledge 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 |
| Generated semantic sources fail validation | Tool metadata does not match the live warehouse schema | Map BI/source databases to primary warehouse connections and rerun validation |

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

@ -11,6 +11,20 @@ All connectors share these conventions:
- Connections are read-only — KTX never writes to your database
- Schema scanning discovers tables, columns, types, and constraints automatically
## Connection field reference
Agents should prefer environment or file references over literal secrets.
| Field | Required | Applies to | Description |
|-------|----------|------------|-------------|
| `driver` | Yes | all connections | Connector driver such as `postgres`, `snowflake`, `bigquery`, `clickhouse`, `mysql`, `sqlserver`, or `sqlite` |
| `url` | One of the connection methods | URL-style connectors | Database URL, `env:NAME`, or `file:/path/to/secret` |
| `host`, `port`, `database`, `username`, `password` | One of the connection methods | PostgreSQL, MySQL, ClickHouse, SQL Server | Field-by-field connection values |
| `schema` or `schemas` | No | schema-aware warehouses | Single schema or list of schemas to scan |
| `readonly` | Strongly recommended | all primary sources | Marks the connection as read-only in KTX config |
| `historicSql` | No | supported warehouses | Enables query-history ingestion when the warehouse supports it |
| `path` | Yes for path-style SQLite | SQLite | Local SQLite database path or `env:NAME` reference |
## PostgreSQL
The most full-featured connector. Supports schema introspection, foreign key detection, column statistics, and historic SQL via `pg_stat_statements`.
@ -488,3 +502,13 @@ No authentication required — SQLite is file-based. The file must be readable b
- SQLite type affinity system: `TEXT`, `NUMERIC`, `INTEGER`, `REAL`, `BLOB`
- Foreign key enforcement requires explicit `PRAGMA foreign_keys = ON`
- In-memory databases supported with `path: ":memory:"` (for testing)
## Common errors
| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| Connection URL appears in git diff | A literal credential URL was written to `ktx.yaml` | Replace it with `env:NAME` or `file:/path/to/secret` and rotate exposed credentials |
| Scan returns no tables | Schema/database/project filter is wrong or the user lacks metadata permissions | Verify the schema list and grant metadata read permissions |
| Historic SQL is empty | Query history extension or warehouse history view is unavailable | Enable the warehouse-specific history feature, then rerun scan or 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 structural scan output |
| SQL execution fails through agents | Connection is missing, unreachable, or execution is disabled in the server | Run `ktx connection test <id>` and check `ktx serve` flags |