mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
docs: remove section overview pages (#130)
This commit is contained in:
Luca Martial
GitHub
parent
e64da5a85d
commit
d60d83e595
11 changed files with 37 additions and 148 deletions
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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/<path>.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).
|
||||
|
|
@ -2,7 +2,6 @@
|
|||
"title": "AI Resources",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"agent-quickstart",
|
||||
"markdown-access",
|
||||
"agent-instructions",
|
||||
|
|
|
|||
|
|
@ -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] <command>
|
||||
```
|
||||
|
||||
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 <path>` 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
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
"title": "CLI Reference",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"ktx",
|
||||
"ktx-setup",
|
||||
"ktx-connection",
|
||||
"ktx-ingest",
|
||||
|
|
|
|||
|
|
@ -67,10 +67,10 @@ Server.
|
|||
<Card title="Writing Context" href="/docs/guides/writing-context">
|
||||
Edit semantic-layer YAML and wiki Markdown safely.
|
||||
</Card>
|
||||
<Card title="CLI Reference" href="/docs/cli-reference/ktx-setup">
|
||||
<Card title="CLI Reference" href="/docs/cli-reference/ktx">
|
||||
Complete flag and subcommand reference for every KTX command.
|
||||
</Card>
|
||||
<Card title="AI Resources" href="/docs/ai-resources">
|
||||
<Card title="Agent Quickstart" href="/docs/ai-resources/agent-quickstart">
|
||||
Machine-readable docs and agent-facing setup notes.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
|
|
|||
|
|
@ -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 <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, 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/<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": ["index", "primary-sources", "context-sources", "agent-clients"]
|
||||
"pages": ["primary-sources", "context-sources", "agent-clients"]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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")}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue