diff --git a/docs-site/content/docs/ai-resources/index.mdx b/docs-site/content/docs/ai-resources/index.mdx index be315453..37bae650 100644 --- a/docs-site/content/docs/ai-resources/index.mdx +++ b/docs-site/content/docs/ai-resources/index.mdx @@ -1,22 +1,37 @@ --- title: AI Resources -description: Machine-readable docs and prompt recipes for coding assistants reading KTX documentation. +description: Machine-readable docs, retrieval paths, and prompt recipes for coding assistants using KTX documentation. --- -Use this section when a coding assistant, IDE agent, or automation system needs to understand the KTX documentation. +Use this section when a coding assistant, IDE agent, or automation system needs +to read, cite, or update KTX documentation. These resources are optimized for +retrieval: agents can fetch small Markdown pages, use the full corpus only when +needed, and copy prompts that point them at current setup and CLI behavior. > **Documentation index** > -> Start with [`/llms.txt`](/llms.txt) to discover the available docs. Use [`/llms-full.txt`](/llms-full.txt) when the assistant needs the complete docs corpus in one Markdown response. +> Start with [`/llms.txt`](/llms.txt) to discover the available docs. Use +> [`/llms-full.txt`](/llms-full.txt) when the assistant needs the complete docs +> corpus in one Markdown response. -## Choose the right path +## What agents can do + +| Need | Recommended path | +|------|------------------| +| Find the right setup or CLI page | Fetch [`/llms.txt`](/llms.txt), then read the smallest matching `.md` page | +| Answer a setup question | Read [Agent Quickstart](/docs/ai-resources/agent-quickstart), then [Quickstart](/docs/getting-started/quickstart) or [ktx setup](/docs/cli-reference/ktx-setup) | +| Quote a command or flag | Read the matching [CLI Reference](/docs/cli-reference) page as Markdown | +| Update docs in this repo | Use [Agent Instructions](/docs/ai-resources/agent-instructions) and verify generated Markdown routes after editing | +| Reuse a prompt | Copy from [Prompt Recipes](/docs/ai-resources/prompt-recipes) | + +## Section map | Goal | Use this page | |------|---------------| -| Tell a coding assistant how to approach KTX docs | [Agent Quickstart](/docs/ai-resources/agent-quickstart) | -| Fetch docs as Markdown instead of HTML | [Markdown Access](/docs/ai-resources/markdown-access) | -| Add lightweight instructions to an assistant prompt | [Agent Instructions](/docs/ai-resources/agent-instructions) | -| Copy prompts for common agent workflows | [Prompt Recipes](/docs/ai-resources/prompt-recipes) | +| Give an assistant a task-first route through the docs | [Agent Quickstart](/docs/ai-resources/agent-quickstart) | +| Fetch docs as Markdown instead of rendered HTML | [Markdown Access](/docs/ai-resources/markdown-access) | +| Add lightweight KTX docs guidance to a system prompt | [Agent Instructions](/docs/ai-resources/agent-instructions) | +| Copy prompts for setup, command lookup, and docs editing | [Prompt Recipes](/docs/ai-resources/prompt-recipes) | ## Available resources @@ -26,13 +41,24 @@ Use this section when a coding assistant, IDE agent, or automation system needs | [`/llms-full.txt`](/llms-full.txt) | Complete docs corpus in one plain-text Markdown response | | `/docs/.md` | Per-page Markdown for any docs page | | Page-level actions | Copy Markdown, view Markdown, or copy MDX from rendered docs pages | -| Prompt recipes | Reusable prompts for docs lookup, setup help, and docs editing | +| Prompt recipes | Reusable prompts for docs lookup, setup help, command discovery, and docs editing | ## Agent usage notes -When an assistant is unsure where to begin, use this order: +When an assistant is unsure where to begin, use this retrieval order: 1. Read [`/llms.txt`](/llms.txt). -2. Fetch the specific Markdown page for the task. -3. Use [Agent Quickstart](/docs/ai-resources/agent-quickstart) to choose the next command or page. -4. Use page-level copy actions when the user wants the exact Markdown or MDX source. +2. Fetch one or two specific Markdown pages for the task. +3. Use [Agent Quickstart](/docs/ai-resources/agent-quickstart) to choose the + next command, guide, or CLI reference page. +4. Use [`/llms-full.txt`](/llms-full.txt) only when the answer requires broad + context across setup, integrations, concepts, and CLI reference. +5. Use page-level copy actions when the user wants exact generated Markdown or + source MDX. + +## Boundaries + +AI Resources explain how agents consume the docs. To install KTX into an +agent client, use [Agent Clients](/docs/integrations/agent-clients). To set up a +project, use [Quickstart](/docs/getting-started/quickstart) or +[`ktx setup`](/docs/cli-reference/ktx-setup). diff --git a/docs-site/content/docs/community/contributing.mdx b/docs-site/content/docs/community/contributing.mdx index 0434d159..ac960395 100644 --- a/docs-site/content/docs/community/contributing.mdx +++ b/docs-site/content/docs/community/contributing.mdx @@ -77,7 +77,7 @@ python/ examples/ # Example projects and fixtures scripts/ # Workspace scripts (benchmarks, verification, release) -docs/ # Documentation site (Fumadocs) +docs-site/ # Documentation site (Fumadocs) ``` All TypeScript packages are ESM (`"type": "module"`) and use `NodeNext` module resolution. The Python projects use `pyproject.toml` for dependency management. diff --git a/docs-site/content/docs/community/index.mdx b/docs-site/content/docs/community/index.mdx new file mode 100644 index 00000000..25518bc8 --- /dev/null +++ b/docs-site/content/docs/community/index.mdx @@ -0,0 +1,54 @@ +--- +title: Community +description: Contribute to KTX through code, docs, connectors, and examples. +--- + +KTX is an open-source context layer for database agents. The project welcomes +focused contributions that improve setup, integrations, CLI behavior, +documentation, connector coverage, and examples. + +## Where to start + +| Goal | Start here | +|------|------------| +| Prepare a local development checkout | [Contributing](/docs/community/contributing#development-setup) | +| Understand the workspace layout | [Repository structure](/docs/community/contributing#repository-structure) | +| Run verification before a pull request | [Running tests](/docs/community/contributing#running-tests) | +| Add a database connector | [Adding a connector](/docs/community/contributing#adding-a-connector) | +| Update docs for a user-visible CLI or setup change | [PR guidelines](/docs/community/contributing#pr-guidelines) | + +## Contribution areas + +| Area | Good first context | +|------|--------------------| +| 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 | +| Python 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 loop + +```bash +pnpm install +uv sync --all-groups +pnpm run setup:dev +pnpm run link:dev +ktx-dev status +``` + +Use `ktx-dev` for local CLI testing after linking the development binary. Use +the published `ktx` command when you are testing the released package in a +separate analytics project. + +## Before submitting + +1. Keep the change focused on one behavior, connector, doc area, or workflow. +2. Run the smallest tests that cover the changed surface. +3. Run broader checks when changing shared exports, setup state, or generated files. +4. Update `docs-site/content/docs/` when user-visible setup, CLI, configuration, or integration behavior changes. +5. Do not commit local secrets, generated build output, virtualenvs, dependency directories, or local databases. + +For complete contributor setup and verification commands, read +[Contributing](/docs/community/contributing). diff --git a/docs-site/content/docs/community/meta.json b/docs-site/content/docs/community/meta.json index 0f97320e..a9988c4e 100644 --- a/docs-site/content/docs/community/meta.json +++ b/docs-site/content/docs/community/meta.json @@ -1,5 +1,5 @@ { "title": "Community", "defaultOpen": true, - "pages": ["contributing"] + "pages": ["index", "contributing"] } diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx index 6f7e7660..de628197 100644 --- a/docs-site/content/docs/integrations/agent-clients.mdx +++ b/docs-site/content/docs/integrations/agent-clients.mdx @@ -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 | diff --git a/docs-site/content/docs/integrations/index.mdx b/docs-site/content/docs/integrations/index.mdx new file mode 100644 index 00000000..8f77a624 --- /dev/null +++ b/docs-site/content/docs/integrations/index.mdx @@ -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 ` 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//` | 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. diff --git a/docs-site/content/docs/integrations/meta.json b/docs-site/content/docs/integrations/meta.json index 70fe26ec..20dc642f 100644 --- a/docs-site/content/docs/integrations/meta.json +++ b/docs-site/content/docs/integrations/meta.json @@ -1,5 +1,5 @@ { "title": "Integrations", "defaultOpen": true, - "pages": ["primary-sources", "context-sources", "agent-clients"] + "pages": ["index", "primary-sources", "context-sources", "agent-clients"] }