diff --git a/README.md b/README.md index e058b828..be4027e6 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,7 @@ uv run pytest -q ## Docs - [Quickstart](docs-site/content/docs/getting-started/quickstart.mdx) -- [CLI Reference](docs-site/content/docs/cli-reference/index.mdx) +- [CLI Reference](docs-site/content/docs/cli-reference/ktx.mdx) - [Building Context](docs-site/content/docs/guides/building-context.mdx) - [Contributing](docs-site/content/docs/community/contributing.mdx) diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx index 6fd6e5ac..0d49ab00 100644 --- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx +++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx @@ -5,6 +5,10 @@ description: A task-first route for coding agents that need to understand KTX do This page is for coding assistants reading or citing the KTX docs. It is intentionally limited to documentation lookup, docs navigation, and safe command discovery. +For Markdown endpoints, use [Markdown Access](/docs/ai-resources/markdown-access). +For reusable task prompts, use [Prompt Recipes](/docs/ai-resources/prompt-recipes). +To install KTX into an agent client, use [Agent Clients](/docs/integrations/agent-clients). + ## First read Agents should start with the smallest source that answers the task: diff --git a/docs-site/content/docs/ai-resources/index.mdx b/docs-site/content/docs/ai-resources/index.mdx deleted file mode 100644 index 37bae650..00000000 --- a/docs-site/content/docs/ai-resources/index.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: AI Resources -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 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. - -## 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 | -|------|---------------| -| 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 - -| Resource | What it gives agents | -|----------|----------------------| -| [`/llms.txt`](/llms.txt) | Curated index of high-value KTX docs and Markdown endpoints | -| [`/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, command discovery, and docs editing | - -## Agent usage notes - -When an assistant is unsure where to begin, use this retrieval order: - -1. Read [`/llms.txt`](/llms.txt). -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/ai-resources/meta.json b/docs-site/content/docs/ai-resources/meta.json index ff555283..a925bf37 100644 --- a/docs-site/content/docs/ai-resources/meta.json +++ b/docs-site/content/docs/ai-resources/meta.json @@ -2,7 +2,6 @@ "title": "AI Resources", "defaultOpen": true, "pages": [ - "index", "agent-quickstart", "markdown-access", "agent-instructions", diff --git a/docs-site/content/docs/cli-reference/index.mdx b/docs-site/content/docs/cli-reference/ktx.mdx similarity index 78% rename from docs-site/content/docs/cli-reference/index.mdx rename to docs-site/content/docs/cli-reference/ktx.mdx index 2b681cba..937d2529 100644 --- a/docs-site/content/docs/cli-reference/index.mdx +++ b/docs-site/content/docs/cli-reference/ktx.mdx @@ -1,13 +1,29 @@ --- -title: "Overview" -description: "Command map and shared options for the KTX CLI." +title: "ktx" +description: "Root command map, global options, and project resolution for the KTX CLI." --- The `ktx` CLI sets up local projects, builds agent-ready context, checks connections, queries semantic-layer sources, searches wiki pages, runs the MCP server, and manages the bundled Python runtime. -## Command Map +## Command signature + +```bash +ktx [global-options] +``` + +When you run bare `ktx` in an interactive terminal outside any KTX project, the +CLI starts the same guided setup flow as `ktx setup`. Inside an existing +project, use command-specific help: + +```bash +ktx --help +ktx setup --help +ktx ingest --help +``` + +## Command map ```text ktx @@ -45,7 +61,7 @@ ktx The public context-build entrypoint is `ktx ingest [connectionId]` or `ktx ingest --all`. -## Global Options +## Global options | Flag | Description | |------|-------------| @@ -54,14 +70,14 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or | `-v`, `--version` | Show the CLI package name and version. | | `-h`, `--help` | Show help for the current command. | -## Project Resolution +## Project resolution Most commands are project-aware. Pass `--project-dir ` when scripting or when you are outside the project directory. If you omit it, KTX checks `KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back to the current directory. -## Common Workflows +## Common workflows ```bash # Start or resume setup diff --git a/docs-site/content/docs/cli-reference/meta.json b/docs-site/content/docs/cli-reference/meta.json index 6757e5bc..6385c7d4 100644 --- a/docs-site/content/docs/cli-reference/meta.json +++ b/docs-site/content/docs/cli-reference/meta.json @@ -2,7 +2,7 @@ "title": "CLI Reference", "defaultOpen": true, "pages": [ - "index", + "ktx", "ktx-setup", "ktx-connection", "ktx-ingest", diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 72891d99..499d25a0 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -67,10 +67,10 @@ Server. Edit semantic-layer YAML and wiki Markdown safely. - + Complete flag and subcommand reference for every KTX command. - + Machine-readable docs and agent-facing setup notes. diff --git a/docs-site/content/docs/integrations/index.mdx b/docs-site/content/docs/integrations/index.mdx deleted file mode 100644 index 92a677aa..00000000 --- a/docs-site/content/docs/integrations/index.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -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, and query history | -| `.ktx/secrets/*` | Local file-backed secrets when you choose file references during setup | -| `.ktx/setup/*` | Local setup progress and context-build state | -| `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 20dc642f..70fe26ec 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": ["index", "primary-sources", "context-sources", "agent-clients"] + "pages": ["primary-sources", "context-sources", "agent-clients"] } diff --git a/docs-site/content/docs/integrations/primary-sources.mdx b/docs-site/content/docs/integrations/primary-sources.mdx index 00cc39aa..4b09c3a6 100644 --- a/docs-site/content/docs/integrations/primary-sources.mdx +++ b/docs-site/content/docs/integrations/primary-sources.mdx @@ -7,6 +7,11 @@ 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. +For analytics tools and knowledge systems such as dbt, MetricFlow, LookML, +Metabase, Looker, and Notion, use [Context Sources](/docs/integrations/context-sources). +For Claude Code, Codex, Cursor, OpenCode, and other agent clients, use +[Agent Clients](/docs/integrations/agent-clients). + All connectors share these conventions: - Sensitive values support `env:VAR_NAME` (read from environment) and diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts index 561f73e0..9ef474a3 100644 --- a/docs-site/lib/llm-docs.ts +++ b/docs-site/lib/llm-docs.ts @@ -52,7 +52,6 @@ KTX provides semantic-layer files, warehouse scans, wiki pages, provenance, and ## Agent Entry Points -${link("/docs/ai-resources", "AI Resources", "Machine-readable docs, prompt recipes, and agent setup paths")} ${link("/docs/ai-resources/agent-quickstart", "Agent Quickstart", "Task-first route for coding assistants using KTX")} ${link("/docs/ai-resources/markdown-access", "Markdown Access", "Fetch KTX docs as llms.txt, llms-full.txt, or per-page Markdown")} ${link("/docs/ai-resources/agent-instructions", "Agent Instructions", "Suggested instructions for coding assistants that need to read and cite KTX docs")} @@ -73,6 +72,7 @@ ${link("/docs/guides/writing-context", "Writing Context", "Write semantic source ## CLI Reference +${link("/docs/cli-reference/ktx", "ktx", "Root command map and global options")} ${link("/docs/cli-reference/ktx-setup", "ktx setup", "Interactive project setup")} ${link("/docs/cli-reference/ktx-sl", "ktx sl", "Semantic-layer commands")} ${link("/docs/cli-reference/ktx-wiki", "ktx wiki", "Wiki page commands")}