mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-13 08:15:14 +02:00
docs(docs-site): add AI resources for agents
This commit is contained in:
Luca Martial
parent
81c7e60fef
commit
966627a68b
13 changed files with 461 additions and 7 deletions
72
docs-site/content/docs/ai-resources/agent-quickstart.mdx
Normal file
72
docs-site/content/docs/ai-resources/agent-quickstart.mdx
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
title: Agent Quickstart
|
||||
description: A task-first route for coding agents that need to understand or operate KTX.
|
||||
---
|
||||
|
||||
This page is for coding assistants working with KTX docs or a KTX project. It is not the product integration guide for connecting KTX to an agent client. For that, use [Serving Agents](/docs/guides/serving-agents) and [Agent Clients](/docs/integrations/agent-clients).
|
||||
|
||||
## First read
|
||||
|
||||
Agents should start with the smallest source that answers the task:
|
||||
|
||||
1. [`/llms.txt`](/llms.txt) - discover the docs and preferred entry points.
|
||||
2. The relevant per-page Markdown URL, for example `/docs/getting-started/quickstart.md`.
|
||||
3. [`/llms-full.txt`](/llms-full.txt) - use only when the task needs broad context across many pages.
|
||||
|
||||
## Task router
|
||||
|
||||
| User asks the agent to... | Read first | Then use |
|
||||
|---------------------------|------------|----------|
|
||||
| Explain what KTX does | [Introduction](/docs/getting-started/introduction) | [The Context Layer](/docs/concepts/the-context-layer) |
|
||||
| Set up KTX from a checkout | [Quickstart](/docs/getting-started/quickstart) | [ktx setup](/docs/cli-reference/ktx-setup) |
|
||||
| Check whether a project is ready | [ktx status](/docs/cli-reference/ktx-status) | `ktx status` |
|
||||
| Build or refresh context | [Building Context](/docs/guides/building-context) | `ktx setup context build` |
|
||||
| Edit semantic YAML or knowledge pages | [Writing Context](/docs/guides/writing-context) | `ktx sl validate` and `ktx wiki ...` |
|
||||
| Query KTX through machine-readable commands | [ktx agent](/docs/cli-reference/ktx-agent) | `ktx agent ... --json` |
|
||||
| Connect an agent client to a KTX project | [Serving Agents](/docs/guides/serving-agents) | [Agent Clients](/docs/integrations/agent-clients) |
|
||||
|
||||
## Operating workflow
|
||||
|
||||
Use this workflow when the user asks an assistant to help inside a local KTX project:
|
||||
|
||||
1. Confirm the project root by finding `ktx.yaml`.
|
||||
2. Run `ktx status` or `ktx agent context --json`.
|
||||
3. Read the docs page that matches the next task.
|
||||
4. Prefer semantic-layer commands before direct SQL.
|
||||
5. Use `--json` for agent CLI commands and parse stdout as JSON.
|
||||
6. Keep generated changes reviewable: semantic YAML, knowledge Markdown, and config files should appear as normal git diffs.
|
||||
|
||||
## Safe command sequence
|
||||
|
||||
For a new local checkout:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm run setup:dev
|
||||
pnpm run link:dev
|
||||
ktx setup
|
||||
ktx status
|
||||
```
|
||||
|
||||
For an existing KTX project:
|
||||
|
||||
```bash
|
||||
ktx status
|
||||
ktx agent context --json
|
||||
ktx agent tools --json
|
||||
```
|
||||
|
||||
For semantic-layer exploration:
|
||||
|
||||
```bash
|
||||
ktx agent sl list --json
|
||||
ktx agent wiki search "revenue definition" --json --limit 5
|
||||
```
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not invent connection ids. Discover them with `ktx status`, `ktx connection list`, or `ktx agent context --json`.
|
||||
- Do not execute SQL unless the user asked for data and a bounded row limit is set.
|
||||
- Do not edit `.ktx/secrets/*` or commit local secret files.
|
||||
- Do not treat docs access as product MCP integration. Product MCP is only for connecting an agent client to a local KTX project.
|
||||
- When docs and local CLI behavior disagree, prefer the local CLI output and mention the mismatch.
|
||||
46
docs-site/content/docs/ai-resources/index.mdx
Normal file
46
docs-site/content/docs/ai-resources/index.mdx
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
title: AI Resources
|
||||
description: Machine-readable docs, prompt recipes, and agent setup paths for coding assistants using KTX.
|
||||
---
|
||||
|
||||
Use this section when a coding assistant, IDE agent, or automation system needs to understand KTX docs or work in a KTX project.
|
||||
|
||||
> **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.
|
||||
|
||||
## Choose the right path
|
||||
|
||||
| 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) |
|
||||
| Install or inspect KTX skill/rule files for an agent client | [KTX Skills](/docs/ai-resources/ktx-skills) |
|
||||
| Copy prompts for common agent workflows | [Prompt Recipes](/docs/ai-resources/prompt-recipes) |
|
||||
| Decide whether you need docs access or product MCP integration | [Docs vs Product MCP](/docs/ai-resources/mcp-boundaries) |
|
||||
|
||||
## 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 |
|
||||
| `ktx setup --agents` | Project-scoped skills, rules, commands, and MCP config for supported agent clients |
|
||||
| `ktx agent ... --json` | Machine-readable CLI commands for agents that operate through a shell |
|
||||
| `ktx serve --mcp stdio` | Product MCP server for agents that need to use KTX context in a local project |
|
||||
|
||||
## Important distinction
|
||||
|
||||
The **AI Resources** section is for agents that need to read the KTX docs or help a user operate a KTX project.
|
||||
|
||||
The product-facing integration path is different: if you want Claude Code, Cursor, Codex, or OpenCode to query your KTX semantic layer, read [Serving Agents](/docs/guides/serving-agents) and [Agent Clients](/docs/integrations/agent-clients).
|
||||
|
||||
## Agent usage notes
|
||||
|
||||
When an assistant is unsure where to begin, use this 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 [Docs vs Product MCP](/docs/ai-resources/mcp-boundaries) before configuring MCP.
|
||||
66
docs-site/content/docs/ai-resources/ktx-skills.mdx
Normal file
66
docs-site/content/docs/ai-resources/ktx-skills.mdx
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: KTX Skills
|
||||
description: Install project-scoped KTX skills, rules, and commands for supported coding agents.
|
||||
---
|
||||
|
||||
KTX skills teach coding agents how to call KTX safely from a project. They are generated by `ktx setup` so the files can include the right project directory, local CLI path, and supported access mode.
|
||||
|
||||
## Install generated skills
|
||||
|
||||
Install skills, rules, commands, and MCP config for a project:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --agent-install-mode both --project
|
||||
```
|
||||
|
||||
Install for one target:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target codex --agent-install-mode both --project
|
||||
```
|
||||
|
||||
Supported targets:
|
||||
|
||||
| Target | Skill or rule path | MCP config path |
|
||||
|--------|--------------------|-----------------|
|
||||
| Claude Code | `.claude/skills/ktx/SKILL.md` | `.mcp.json` |
|
||||
| Cursor | `.cursor/rules/ktx.mdc` | `.cursor/mcp.json` |
|
||||
| Codex | `.agents/skills/ktx/SKILL.md` | `.agents/mcp/ktx.json` |
|
||||
| OpenCode | `.opencode/commands/ktx.md` | `.opencode/mcp.json` |
|
||||
|
||||
## What the skill should teach
|
||||
|
||||
A KTX skill should tell the agent to:
|
||||
|
||||
- Discover project state with `ktx agent context --json`.
|
||||
- Discover available tools with `ktx agent tools --json`.
|
||||
- Use semantic-layer commands before direct SQL.
|
||||
- Search knowledge pages before answering business-definition questions.
|
||||
- Parse stdout as JSON for `ktx agent` commands.
|
||||
- Treat non-zero exit codes as failed tool calls.
|
||||
- Keep SQL execution bounded with `--max-rows`.
|
||||
|
||||
## Inspect generated files
|
||||
|
||||
After setup, review the generated file before relying on it:
|
||||
|
||||
```bash
|
||||
cat .agents/skills/ktx/SKILL.md
|
||||
cat .mcp.json
|
||||
```
|
||||
|
||||
Use the client-specific paths from the table above for Claude Code, Cursor, Codex, or OpenCode.
|
||||
|
||||
## Global installs
|
||||
|
||||
Claude Code and Codex support global skill installs. Use global installs when you want KTX instructions available across projects:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target codex --global
|
||||
```
|
||||
|
||||
Project-scoped installs are safer for teams because the generated files live next to the project and can be reviewed in git.
|
||||
|
||||
## Relationship to agent integration
|
||||
|
||||
Skills are instructions for the coding assistant. Product integration is the runtime path that lets the assistant query a KTX project through CLI or MCP. For runtime setup, read [Serving Agents](/docs/guides/serving-agents) and [Agent Clients](/docs/integrations/agent-clients).
|
||||
67
docs-site/content/docs/ai-resources/markdown-access.mdx
Normal file
67
docs-site/content/docs/ai-resources/markdown-access.mdx
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
title: Markdown Access
|
||||
description: Fetch KTX docs as llms.txt, llms-full.txt, or per-page Markdown.
|
||||
---
|
||||
|
||||
KTX docs are available as plain Markdown so assistants do not need to parse the rendered HTML site.
|
||||
|
||||
## Index
|
||||
|
||||
Fetch the curated index:
|
||||
|
||||
```text
|
||||
https://ktx.dev/llms.txt
|
||||
```
|
||||
|
||||
Use this file to discover high-value pages, task-specific entry points, and Markdown URLs.
|
||||
|
||||
## Full corpus
|
||||
|
||||
Fetch the complete docs corpus:
|
||||
|
||||
```text
|
||||
https://ktx.dev/llms-full.txt
|
||||
```
|
||||
|
||||
Use this when an assistant needs broad context across setup, concepts, CLI reference, integrations, and troubleshooting. Prefer the smaller per-page Markdown route for narrow tasks.
|
||||
|
||||
## Per-page Markdown
|
||||
|
||||
Every docs page has a Markdown route:
|
||||
|
||||
```text
|
||||
https://ktx.dev/docs/getting-started/quickstart.md
|
||||
https://ktx.dev/docs/cli-reference/ktx-agent.md
|
||||
https://ktx.dev/docs/guides/serving-agents.md
|
||||
```
|
||||
|
||||
Requests that ask for Markdown can also use the normal docs URL with `Accept: text/markdown`:
|
||||
|
||||
```bash
|
||||
curl -H "Accept: text/markdown" https://ktx.dev/docs/getting-started/quickstart
|
||||
```
|
||||
|
||||
## Recommended retrieval order
|
||||
|
||||
1. Fetch `/llms.txt`.
|
||||
2. Select one or two relevant page Markdown URLs.
|
||||
3. Fetch `/llms-full.txt` only when page-level docs are not enough.
|
||||
|
||||
## Output contract
|
||||
|
||||
Markdown responses are designed for agent consumption:
|
||||
|
||||
- Frontmatter is removed.
|
||||
- Each page includes a title, description, canonical URL, and Markdown URL.
|
||||
- Code blocks stay as code blocks.
|
||||
- Tables stay as Markdown tables.
|
||||
- Missing docs pages return a plain-text `404` instead of silently falling back to HTML.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Better path |
|
||||
|---------|-------------|
|
||||
| Scraping the HTML page for a docs answer | Fetch the `.md` route instead |
|
||||
| Loading `/llms-full.txt` for a single CLI flag lookup | Fetch the relevant CLI reference page |
|
||||
| Treating `/llms.txt` as complete documentation | Use it as an index, then fetch linked pages |
|
||||
| Assuming docs Markdown configures the product MCP server | Read [Docs vs Product MCP](/docs/ai-resources/mcp-boundaries) first |
|
||||
62
docs-site/content/docs/ai-resources/mcp-boundaries.mdx
Normal file
62
docs-site/content/docs/ai-resources/mcp-boundaries.mdx
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: Docs vs Product MCP
|
||||
description: Understand the difference between reading KTX docs and connecting an agent to a KTX project.
|
||||
---
|
||||
|
||||
There are two agent-facing surfaces in KTX. Keep them separate.
|
||||
|
||||
## Docs access
|
||||
|
||||
Docs access helps an assistant learn KTX:
|
||||
|
||||
- `/llms.txt`
|
||||
- `/llms-full.txt`
|
||||
- `/docs/<path>.md`
|
||||
- prompt recipes
|
||||
- generated skills that point agents toward the right docs and commands
|
||||
|
||||
Use docs access when the task is to explain KTX, look up command flags, write docs, or plan a setup.
|
||||
|
||||
## Product MCP integration
|
||||
|
||||
Product MCP integration lets an agent operate a KTX project:
|
||||
|
||||
- list database connections
|
||||
- search knowledge pages
|
||||
- read and validate semantic sources
|
||||
- compile semantic-layer queries
|
||||
- optionally execute read-only SQL with row limits
|
||||
- trigger scans and ingests
|
||||
|
||||
Use product MCP when the task is to connect Claude Code, Cursor, Codex, OpenCode, or another client to a local KTX project.
|
||||
|
||||
The product MCP entry point is:
|
||||
|
||||
```bash
|
||||
ktx serve --mcp stdio
|
||||
```
|
||||
|
||||
Most users should configure it through:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --agent-install-mode both --project
|
||||
```
|
||||
|
||||
## Which page should an agent read?
|
||||
|
||||
| Need | Read |
|
||||
|------|------|
|
||||
| Understand KTX docs or choose the next page | [AI Resources](/docs/ai-resources) |
|
||||
| Operate KTX from a coding assistant | [Agent Quickstart](/docs/ai-resources/agent-quickstart) |
|
||||
| Fetch docs in machine-readable form | [Markdown Access](/docs/ai-resources/markdown-access) |
|
||||
| Install generated skill or rule files | [KTX Skills](/docs/ai-resources/ktx-skills) |
|
||||
| Expose a KTX project to agent tools | [Serving Agents](/docs/guides/serving-agents) |
|
||||
| Configure Claude Code, Cursor, Codex, or OpenCode | [Agent Clients](/docs/integrations/agent-clients) |
|
||||
|
||||
## Agent rule
|
||||
|
||||
If the user asks to "read the docs" or "understand KTX", use Markdown docs access.
|
||||
|
||||
If the user asks to "connect my agent", "query my semantic layer", or "use KTX tools from Cursor/Claude/Codex", use product MCP integration.
|
||||
|
||||
Do not configure product MCP just to answer a documentation question.
|
||||
12
docs-site/content/docs/ai-resources/meta.json
Normal file
12
docs-site/content/docs/ai-resources/meta.json
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
{
|
||||
"title": "AI Resources",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"agent-quickstart",
|
||||
"markdown-access",
|
||||
"ktx-skills",
|
||||
"prompt-recipes",
|
||||
"mcp-boundaries"
|
||||
]
|
||||
}
|
||||
60
docs-site/content/docs/ai-resources/prompt-recipes.mdx
Normal file
60
docs-site/content/docs/ai-resources/prompt-recipes.mdx
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: Prompt Recipes
|
||||
description: Copyable prompts for common KTX agent workflows.
|
||||
---
|
||||
|
||||
Use these prompts when asking a coding assistant to work with KTX. Replace project names, connection ids, and business terms with your own values.
|
||||
|
||||
## Learn the docs
|
||||
|
||||
```text
|
||||
Read https://ktx.dev/llms.txt first. Then fetch only the KTX Markdown pages needed for this task. Do not scrape rendered HTML unless no Markdown route exists.
|
||||
```
|
||||
|
||||
## Set up a project
|
||||
|
||||
```text
|
||||
Set up KTX in this repository. Start by reading /docs/ai-resources/agent-quickstart.md and /docs/getting-started/quickstart.md. Use pnpm, not npm. After setup, run ktx status and summarize which steps are complete, which files changed, and what still needs credentials or user input.
|
||||
```
|
||||
|
||||
## Check readiness
|
||||
|
||||
```text
|
||||
Check whether this KTX project is ready for agents. Find the project root, run ktx status and ktx agent context --json, then explain any missing setup step with the exact command to fix it.
|
||||
```
|
||||
|
||||
## Build context
|
||||
|
||||
```text
|
||||
Refresh KTX context for this project. Read the Building Context guide first. Run the smallest safe command that updates scans or ingests, monitor status, and report the semantic-layer and knowledge-page files that changed.
|
||||
```
|
||||
|
||||
## Investigate an analytics question
|
||||
|
||||
```text
|
||||
Use KTX to answer this analytics question: <question>. Discover connections and sources first. Search knowledge pages for the business terms in the question. Prefer ktx agent sl query over direct SQL. Execute only if the project allows it and max rows are bounded.
|
||||
```
|
||||
|
||||
## Review semantic changes
|
||||
|
||||
```text
|
||||
Review the KTX semantic-layer and knowledge changes in this branch. Check that measures have clear definitions, joins use valid keys, hidden/internal columns are not exposed to agents, and validation passes. List concrete file and line issues first.
|
||||
```
|
||||
|
||||
## Connect an agent client
|
||||
|
||||
```text
|
||||
Connect this KTX project to <Claude Code/Cursor/Codex/OpenCode>. This is product integration, not docs access. Read /docs/guides/serving-agents.md and /docs/integrations/agent-clients.md, then generate the project-scoped setup with ktx setup --agents.
|
||||
```
|
||||
|
||||
## Troubleshoot MCP
|
||||
|
||||
```text
|
||||
Troubleshoot why my agent cannot use KTX MCP tools. First distinguish docs access from product MCP integration. Then inspect the generated MCP config, verify the ktx command path, run ktx status, and check whether --semantic-compute and --execute-queries are appropriate for the task.
|
||||
```
|
||||
|
||||
## Update docs
|
||||
|
||||
```text
|
||||
Update the KTX docs for agent readability. Preserve the distinction between AI Resources for coding assistants and Serving Agents/Agent Clients for product integration. After editing, verify /llms.txt, /llms-full.txt, and the affected .md routes.
|
||||
```
|
||||
|
|
@ -39,6 +39,9 @@ If you've ever watched an agent confidently generate a query that joins on the w
|
|||
<Card title="Quickstart" href="/docs/getting-started/quickstart">
|
||||
Set up KTX and build your first context in under 10 minutes.
|
||||
</Card>
|
||||
<Card title="AI Resources" href="/docs/ai-resources">
|
||||
Machine-readable docs, prompt recipes, and agent setup paths for coding assistants.
|
||||
</Card>
|
||||
<Card title="Concepts" href="/docs/concepts/the-context-layer">
|
||||
Understand what a context layer is, why agents need one, and how KTX compares to other semantic layers.
|
||||
</Card>
|
||||
|
|
@ -56,6 +59,7 @@ If you've ever watched an agent confidently generate a query that joins on the w
|
|||
## Next steps
|
||||
|
||||
- **Get hands-on** — follow the [Quickstart](/docs/getting-started/quickstart) to set up KTX with your own database in under 10 minutes.
|
||||
- **Help a coding agent use the docs** — start with [AI Resources](/docs/ai-resources) or fetch [`/llms.txt`](/llms.txt).
|
||||
- **Understand the theory** — read [The Context Layer](/docs/concepts/the-context-layer) to learn why schema access alone breaks on real analytics and how KTX addresses it.
|
||||
|
||||
## Agent usage notes
|
||||
|
|
@ -64,9 +68,11 @@ Use this page as the high-level routing document for KTX docs.
|
|||
|
||||
| Agent task | Read next |
|
||||
|------------|-----------|
|
||||
| Discover machine-readable docs | [AI Resources](/docs/ai-resources) |
|
||||
| Learn how a coding assistant should approach KTX | [Agent Quickstart](/docs/ai-resources/agent-quickstart) |
|
||||
| Set up a new KTX project | [Quickstart](/docs/getting-started/quickstart) |
|
||||
| Explain what problem KTX solves | [The Context Layer](/docs/concepts/the-context-layer) |
|
||||
| Scan a database and ingest metadata | [Building Context](/docs/guides/building-context) |
|
||||
| Edit semantic sources or knowledge pages | [Writing Context](/docs/guides/writing-context) |
|
||||
| Connect KTX to an agent client | [Serving Agents](/docs/guides/serving-agents) |
|
||||
| Connect KTX product tools to an agent client | [Serving Agents](/docs/guides/serving-agents) |
|
||||
| Look up exact command flags | [CLI Reference](/docs/cli-reference/ktx-setup) |
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: Set up KTX and build your first context in under 10 minutes.
|
|||
|
||||
This guide walks you through `ktx setup` — an interactive wizard that configures your LLM provider, connects your database, optionally ingests from your existing tools, builds context, and installs agent integration.
|
||||
|
||||
If you are a coding assistant trying to decide how to read KTX docs or operate an existing project, start with the [Agent Quickstart](/docs/ai-resources/agent-quickstart). This page is the human setup walkthrough. Agent client integration details live in [Serving Agents](/docs/guides/serving-agents) and [Agent Clients](/docs/integrations/agent-clients).
|
||||
|
||||
## Workflow summary
|
||||
|
||||
Use this sequence when an agent needs to set up KTX from a fresh checkout:
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ description: Expose your context to Claude Code, Cursor, Codex, and other coding
|
|||
|
||||
Once you've built and refined your context, the final step is exposing it to coding agents. KTX provides two channels: an **MCP server** for persistent integration with tools like Claude Code and Cursor, and **CLI commands** for direct terminal access.
|
||||
|
||||
This page is about product integration: connecting an agent client to a local KTX project so it can use KTX tools. If an assistant only needs to read or reason about the documentation, use [AI Resources](/docs/ai-resources) instead.
|
||||
|
||||
## Agent workflow summary
|
||||
|
||||
Agents should use KTX in this order:
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@ KTX integrates with coding agents through two channels that can be used independ
|
|||
- **MCP server** — A persistent Model Context Protocol server that exposes KTX tools (semantic queries, knowledge search, SQL execution) directly to the agent
|
||||
- **CLI skills** — Command definitions that teach the agent how to invoke KTX via the terminal
|
||||
|
||||
This is the product integration page for connecting an agent client to a KTX project. For documentation access, `/llms.txt`, prompt recipes, and the agent-facing docs quickstart, use [AI Resources](/docs/ai-resources).
|
||||
|
||||
Run `ktx setup` and select your agent targets, or configure manually using the snippets below.
|
||||
|
||||
## Agent setup matrix
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
"title": "KTX",
|
||||
"pages": [
|
||||
"getting-started",
|
||||
"ai-resources",
|
||||
"concepts",
|
||||
"guides",
|
||||
"integrations",
|
||||
|
|
|
|||
|
|
@ -39,7 +39,8 @@ export function buildLlmsTxt() {
|
|||
const link = (url: string, label: string, fallbackDescription: string) => {
|
||||
const page = byUrl.get(url);
|
||||
const description = page?.description ?? fallbackDescription;
|
||||
return `- [${label}](${url}): ${description}`;
|
||||
const markdownUrl = page?.markdownUrl ?? `${url}.md`;
|
||||
return `- [${label}](${markdownUrl}): ${description}`;
|
||||
};
|
||||
|
||||
return `# KTX
|
||||
|
|
@ -48,19 +49,31 @@ export function buildLlmsTxt() {
|
|||
|
||||
KTX provides semantic-layer files, warehouse scans, knowledge pages, provenance, and agent-facing tools that help coding agents answer analytics questions without inventing metrics or joins.
|
||||
|
||||
## 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/mcp-boundaries", "Docs vs Product MCP", "Choose docs access or product integration correctly")}
|
||||
|
||||
## Start Here
|
||||
|
||||
${link("/docs/getting-started/introduction", "Introduction", "What KTX is and who it is for")}
|
||||
${link("/docs/getting-started/quickstart", "Quickstart", "Set up KTX and build your first context")}
|
||||
${link("/docs/guides/serving-agents", "Serving Agents", "Expose KTX context through MCP and CLI tools")}
|
||||
${link("/docs/guides/writing-context", "Writing Context", "Write semantic sources and knowledge pages")}
|
||||
|
||||
## Machine-Readable Documentation
|
||||
|
||||
- [Full documentation](/llms-full.txt): All docs pages in one plain-text markdown response
|
||||
- [Quickstart markdown](/docs/getting-started/quickstart.md): Raw markdown for the setup guide
|
||||
- [Agent CLI markdown](/docs/cli-reference/ktx-agent.md): Raw markdown for machine-readable agent commands
|
||||
- [Serving Agents markdown](/docs/guides/serving-agents.md): Raw markdown for MCP and CLI workflows
|
||||
- [Markdown access guide](/docs/ai-resources/markdown-access.md): How to fetch llms.txt, llms-full.txt, and per-page Markdown
|
||||
- [Quickstart markdown](/docs/getting-started/quickstart.md): Human setup walkthrough
|
||||
- [Agent CLI markdown](/docs/cli-reference/ktx-agent.md): Machine-readable agent commands
|
||||
|
||||
## Product Integration
|
||||
|
||||
Use these pages only when the task is to connect an agent client to a KTX project. For documentation lookup, use the AI Resources pages above.
|
||||
|
||||
${link("/docs/guides/serving-agents", "Serving Agents", "Expose KTX context through MCP and CLI tools")}
|
||||
${link("/docs/integrations/agent-clients", "Agent Clients", "Configure Claude Code, Cursor, Codex, and OpenCode")}
|
||||
|
||||
## CLI Reference
|
||||
|
||||
|
|
@ -72,9 +85,12 @@ ${link("/docs/cli-reference/ktx-connection", "ktx connection", "Connection manag
|
|||
|
||||
## Integrations
|
||||
|
||||
${link("/docs/integrations/agent-clients", "Agent Clients", "Configure Claude Code, Cursor, Codex, and OpenCode")}
|
||||
${link("/docs/integrations/primary-sources", "Primary Sources", "Connect KTX to databases and warehouses")}
|
||||
${link("/docs/integrations/context-sources", "Context Sources", "Ingest dbt, LookML, Metabase, Looker, MetricFlow, and Notion")}
|
||||
|
||||
## All Documentation
|
||||
|
||||
${buildPageIndex(pages)}
|
||||
`;
|
||||
}
|
||||
|
||||
|
|
@ -103,3 +119,43 @@ function normalizeMarkdown(markdown: string) {
|
|||
.trim()
|
||||
.replace(/\n{3,}/g, "\n\n");
|
||||
}
|
||||
|
||||
function buildPageIndex(pages: LlmDocsPage[]) {
|
||||
const grouped = new Map<string, LlmDocsPage[]>();
|
||||
|
||||
for (const page of pages) {
|
||||
const category = page.slug[0] ?? "general";
|
||||
grouped.set(category, [...(grouped.get(category) ?? []), page]);
|
||||
}
|
||||
|
||||
return [...grouped.entries()]
|
||||
.map(([category, categoryPages]) => {
|
||||
const links = categoryPages
|
||||
.map((page) => {
|
||||
const description = page.description ? `: ${page.description}` : "";
|
||||
return `- [${page.title}](${page.markdownUrl})${description}`;
|
||||
})
|
||||
.join("\n");
|
||||
|
||||
return `### ${formatCategoryName(category)}
|
||||
|
||||
${links}`;
|
||||
})
|
||||
.join("\n\n");
|
||||
}
|
||||
|
||||
function formatCategoryName(category: string) {
|
||||
const labels: Record<string, string> = {
|
||||
"ai-resources": "AI Resources",
|
||||
"cli-reference": "CLI Reference",
|
||||
};
|
||||
|
||||
if (labels[category]) {
|
||||
return labels[category];
|
||||
}
|
||||
|
||||
return category
|
||||
.split("-")
|
||||
.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
|
||||
.join(" ");
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue