mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-28 08:49:38 +02:00
docs: revamp resource and integration sections (#104)
This commit is contained in:
Luca Martial
GitHub
parent
f8db99811a
commit
17653e24f5
7 changed files with 221 additions and 26 deletions
|
|
@ -7,7 +7,46 @@ KTX integrates with coding agents through CLI skills and command files. These
|
|||
files teach agents to call public `ktx` commands directly from the terminal for
|
||||
semantic-layer context and wiki knowledge.
|
||||
|
||||
Run `ktx setup` and select your agent targets, or configure manually using the snippets below.
|
||||
Run `ktx setup` and select your agent targets, or configure manually using the
|
||||
snippets below. Setup pins generated skill files to the KTX CLI path that
|
||||
created them, so agents do not need `ktx` on `PATH`.
|
||||
|
||||
## Install with setup
|
||||
|
||||
```bash
|
||||
ktx setup --agents
|
||||
```
|
||||
|
||||
Use `--target` for one target:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target codex
|
||||
```
|
||||
|
||||
Use `--global` only with `claude-code` or `codex`:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target claude-code --global
|
||||
ktx setup --agents --target codex --global
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Generated files
|
||||
|
||||
| Target | Project-scoped files | Global files |
|
||||
|--------|----------------------|--------------|
|
||||
| Claude Code | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` | `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
||||
| Codex | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` | `$CODEX_HOME/skills/ktx/SKILL.md`, `$CODEX_HOME/instructions/ktx.md` |
|
||||
| Cursor | `.cursor/rules/ktx.mdc` | Not supported |
|
||||
| OpenCode | `.opencode/commands/ktx.md` | Not supported |
|
||||
| Universal `.agents` | `.agents/skills/ktx/SKILL.md` | Not supported |
|
||||
|
||||
Skill files list pinned `ktx` commands. Rule files tell the agent when KTX is
|
||||
appropriate, such as data schemas, metrics, dimensions, database structure, and
|
||||
SQL questions.
|
||||
|
||||
## Claude Code
|
||||
|
||||
|
|
@ -15,11 +54,12 @@ Run `ktx setup` and select your agent targets, or configure manually using the s
|
|||
|
||||
During setup, select **Claude Code** from the agent targets. KTX writes:
|
||||
|
||||
| Mode | File |
|
||||
|------|------|
|
||||
| CLI skills | `.claude/skills/ktx/SKILL.md` |
|
||||
| Scope | Files |
|
||||
|-------|-------|
|
||||
| Project | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
|
||||
| Global | `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
||||
|
||||
Both project-scoped and global installations are supported. Global installs write to `~/.claude/skills/ktx/SKILL.md`.
|
||||
Both project-scoped and global installations are supported.
|
||||
|
||||
### Manual CLI skills configuration
|
||||
|
||||
|
|
@ -42,6 +82,7 @@ Available commands:
|
|||
### Workflow tips
|
||||
|
||||
- Claude Code discovers skills automatically from `.claude/skills/`.
|
||||
- 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.
|
||||
|
||||
|
|
@ -76,11 +117,13 @@ Create `.cursor/rules/ktx.mdc` with the same content structure as the Claude Cod
|
|||
|
||||
During setup, select **Codex** from the agent targets. KTX writes:
|
||||
|
||||
| Mode | File |
|
||||
|------|------|
|
||||
| CLI skills | `.agents/skills/ktx/SKILL.md` |
|
||||
| Scope | Files |
|
||||
|-------|-------|
|
||||
| Project | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
||||
| Global | `$CODEX_HOME/skills/ktx/SKILL.md`, `$CODEX_HOME/instructions/ktx.md` |
|
||||
|
||||
Both project-scoped and global installations are supported. Global installs write to `$CODEX_HOME/skills/ktx/SKILL.md` (defaults to `~/.codex/skills/ktx/SKILL.md`).
|
||||
Both project-scoped and global installations are supported. `CODEX_HOME`
|
||||
defaults to `~/.codex`.
|
||||
|
||||
### Manual CLI skills configuration
|
||||
|
||||
|
|
@ -90,6 +133,7 @@ Create `.agents/skills/ktx/SKILL.md` with the same content structure as Claude C
|
|||
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
|
@ -143,4 +187,5 @@ All supported agent clients call the same KTX CLI commands:
|
|||
|---|---|---|---|---|
|
||||
| CLI skills | Yes | Yes (.mdc) | Yes | Yes |
|
||||
| Global install | Yes | No | Yes | No |
|
||||
| Config location | `.claude/skills/ktx/SKILL.md` | `.cursor/rules/ktx.mdc` | `.agents/skills/ktx/SKILL.md` | `.opencode/commands/ktx.md` |
|
||||
| Rule or instruction file | `.claude/rules/ktx.md` | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` |
|
||||
| Skill file | `.claude/skills/ktx/SKILL.md` | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |
|
||||
|
|
|
|||
70
docs-site/content/docs/integrations/index.mdx
Normal file
70
docs-site/content/docs/integrations/index.mdx
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: Integrations
|
||||
description: Connect KTX to warehouses, analytics tools, and coding agents.
|
||||
---
|
||||
|
||||
KTX integrations bring trusted context into an analytics project and make that
|
||||
context available to coding agents through the CLI. Start with `ktx setup` when
|
||||
you want the guided flow, then use the integration reference pages for exact
|
||||
configuration fields, generated files, and manual setup.
|
||||
|
||||
## Integration types
|
||||
|
||||
| Type | What it connects | Start here |
|
||||
|------|------------------|------------|
|
||||
| Primary sources | Warehouses and databases that KTX scans for schemas, constraints, row counts, and optional query history | [Primary Sources](/docs/integrations/primary-sources) |
|
||||
| Context sources | Existing analytics and knowledge tools such as dbt, MetricFlow, LookML, Metabase, Looker, and Notion | [Context Sources](/docs/integrations/context-sources) |
|
||||
| Agent clients | Claude Code, Codex, Cursor, OpenCode, and universal `.agents` consumers | [Agent Clients](/docs/integrations/agent-clients) |
|
||||
|
||||
## Recommended setup flow
|
||||
|
||||
Use this order for a new project:
|
||||
|
||||
1. Run `ktx setup` from the analytics project directory.
|
||||
2. Configure an LLM backend and embeddings so KTX can enrich and search context.
|
||||
3. Add at least one primary source connection.
|
||||
4. Add optional context sources that describe the same warehouse or business domain.
|
||||
5. Build context during setup, or run `ktx ingest <connectionId>` later.
|
||||
6. Install agent integration with `ktx setup --agents` when the context is ready.
|
||||
|
||||
For repeatable setup, pass `--project-dir`, `--no-input`, and the relevant
|
||||
automation flags documented in [`ktx setup`](/docs/cli-reference/ktx-setup).
|
||||
|
||||
## What setup writes
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `ktx.yaml` | Main project configuration for providers, embeddings, connections, source mappings, query history, and setup state |
|
||||
| `.ktx/secrets/*` | Local file-backed secrets when you choose file references during setup |
|
||||
| `semantic-layer/<connection-id>/` | YAML semantic sources generated by database and source ingestion |
|
||||
| `wiki/` | Markdown business context, definitions, and ingested knowledge |
|
||||
| `.ktx/agents/install-manifest.json` | Manifest of agent integration files installed by `ktx setup --agents` |
|
||||
| Agent client files | Skills, rules, or commands that teach agents when and how to call KTX |
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
# Start or resume the guided flow
|
||||
ktx setup
|
||||
|
||||
# Add or refresh every configured integration
|
||||
ktx ingest --all
|
||||
|
||||
# Refresh one configured warehouse, source, or knowledge integration
|
||||
ktx ingest warehouse
|
||||
|
||||
# Install one project-scoped agent target
|
||||
ktx setup --agents --target codex
|
||||
|
||||
# Check whether integrations are ready
|
||||
ktx status
|
||||
```
|
||||
|
||||
## Choosing docs
|
||||
|
||||
Read [Primary Sources](/docs/integrations/primary-sources) when you need
|
||||
database driver fields, authentication formats, query history support, or
|
||||
warehouse-specific notes. Read [Context Sources](/docs/integrations/context-sources)
|
||||
when you need source adapter fields, repository authentication, BI tool mapping,
|
||||
or Notion crawl options. Read [Agent Clients](/docs/integrations/agent-clients)
|
||||
when you need generated file locations or manual agent configuration.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"title": "Integrations",
|
||||
"defaultOpen": true,
|
||||
"pages": ["primary-sources", "context-sources", "agent-clients"]
|
||||
"pages": ["index", "primary-sources", "context-sources", "agent-clients"]
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue