mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-07 11:02:11 +02:00
docs(docs-site): separate docs-agent resources
This commit is contained in:
Luca Martial
parent
966627a68b
commit
f1909b47c6
15 changed files with 209 additions and 326 deletions
40
docs-site/content/docs/ai-resources/agent-instructions.mdx
Normal file
40
docs-site/content/docs/ai-resources/agent-instructions.mdx
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: Agent Instructions
|
||||
description: Suggested instructions for coding assistants that need to read and cite KTX docs.
|
||||
---
|
||||
|
||||
Use these instructions when a coding assistant needs to answer questions from the KTX documentation.
|
||||
|
||||
```text
|
||||
When answering KTX docs questions:
|
||||
|
||||
1. Start with https://ktx.dev/llms.txt.
|
||||
2. Fetch the smallest relevant Markdown page from the index.
|
||||
3. Prefer /docs/<path>.md over rendered HTML.
|
||||
4. Use https://ktx.dev/llms-full.txt only when the task needs broad docs context.
|
||||
5. Quote commands exactly from docs pages.
|
||||
6. If docs and local repository behavior disagree, say what differs and prefer local verified output for code changes.
|
||||
```
|
||||
|
||||
## What this is for
|
||||
|
||||
This page is for documentation consumption only:
|
||||
|
||||
- answering questions about KTX
|
||||
- finding the right docs page
|
||||
- citing setup or CLI guidance
|
||||
- helping an assistant avoid stale or invented commands
|
||||
|
||||
It does not describe local tool configuration.
|
||||
|
||||
## Minimal project prompt
|
||||
|
||||
```text
|
||||
You are helping with KTX. Read https://ktx.dev/llms.txt first, then fetch only the Markdown pages needed for the task. Do not scrape the rendered docs site when a .md route exists.
|
||||
```
|
||||
|
||||
## Repository prompt
|
||||
|
||||
```text
|
||||
Before editing KTX docs, read /llms.txt and the affected .md docs pages. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and any changed .md routes.
|
||||
```
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: Agent Quickstart
|
||||
description: A task-first route for coding agents that need to understand or operate KTX.
|
||||
description: A task-first route for coding agents that need to understand KTX docs.
|
||||
---
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
## First read
|
||||
|
||||
|
|
@ -15,58 +15,36 @@ Agents should start with the smallest source that answers the task:
|
|||
|
||||
## 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) |
|
||||
| User asks the agent to explain... | Read first | Then read |
|
||||
|------------------------------------|------------|-----------|
|
||||
| What KTX does | [Introduction](/docs/getting-started/introduction) | [The Context Layer](/docs/concepts/the-context-layer) |
|
||||
| How to start from a checkout | [Quickstart](/docs/getting-started/quickstart) | [ktx setup](/docs/cli-reference/ktx-setup) |
|
||||
| How to check project readiness | [ktx status](/docs/cli-reference/ktx-status) | [Quickstart](/docs/getting-started/quickstart) |
|
||||
| How context gets built | [Building Context](/docs/guides/building-context) | [ktx ingest](/docs/cli-reference/ktx-ingest) |
|
||||
| How semantic YAML works | [Writing Context](/docs/guides/writing-context) | [ktx sl](/docs/cli-reference/ktx-sl) |
|
||||
| How machine-readable CLI output is shaped | [ktx agent](/docs/cli-reference/ktx-agent) | [Markdown Access](/docs/ai-resources/markdown-access) |
|
||||
|
||||
## Operating workflow
|
||||
|
||||
Use this workflow when the user asks an assistant to help inside a local KTX project:
|
||||
Use this workflow when the user asks an assistant to answer a KTX docs question:
|
||||
|
||||
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.
|
||||
1. Read [`/llms.txt`](/llms.txt).
|
||||
2. Pick the smallest relevant `.md` page.
|
||||
3. Use [`/llms-full.txt`](/llms-full.txt) only if the answer needs multiple sections of the docs.
|
||||
4. Quote commands exactly from the docs page.
|
||||
5. If a command affects a local project, ask the user before assuming credentials or live services are available.
|
||||
|
||||
## Safe command sequence
|
||||
|
||||
For a new local checkout:
|
||||
## Docs lookup from a shell
|
||||
|
||||
```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
|
||||
curl https://ktx.dev/llms.txt
|
||||
curl https://ktx.dev/docs/getting-started/quickstart.md
|
||||
```
|
||||
|
||||
## 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.
|
||||
- Do not invent CLI flags. Fetch the relevant CLI reference page.
|
||||
- Do not scrape rendered HTML when a `.md` route exists.
|
||||
- Do not assume docs lookup requires agent-client configuration.
|
||||
- Do not include credentials or secrets in prompts, URLs, or copied docs snippets.
|
||||
- When docs and local CLI behavior disagree, prefer the local CLI output and mention the mismatch.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: AI Resources
|
||||
description: Machine-readable docs, prompt recipes, and agent setup paths for coding assistants using KTX.
|
||||
description: Machine-readable docs and prompt recipes for coding assistants reading KTX documentation.
|
||||
---
|
||||
|
||||
Use this section when a coding assistant, IDE agent, or automation system needs to understand KTX docs or work in a KTX project.
|
||||
Use this section when a coding assistant, IDE agent, or automation system needs to understand the KTX documentation.
|
||||
|
||||
> **Documentation index**
|
||||
>
|
||||
|
|
@ -15,9 +15,8 @@ Use this section when a coding assistant, IDE agent, or automation system needs
|
|||
|------|---------------|
|
||||
| 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) |
|
||||
| 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) |
|
||||
| Decide whether you need docs access or product MCP integration | [Docs vs Product MCP](/docs/ai-resources/mcp-boundaries) |
|
||||
|
||||
## Available resources
|
||||
|
||||
|
|
@ -26,15 +25,8 @@ Use this section when a coding assistant, IDE agent, or automation system needs
|
|||
| [`/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).
|
||||
| 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 |
|
||||
|
||||
## Agent usage notes
|
||||
|
||||
|
|
@ -43,4 +35,4 @@ 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.
|
||||
4. Use page-level copy actions when the user wants the exact Markdown or MDX source.
|
||||
|
|
|
|||
|
|
@ -1,66 +0,0 @@
|
|||
---
|
||||
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).
|
||||
|
|
@ -32,7 +32,7 @@ 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
|
||||
https://ktx.dev/docs/guides/building-context.md
|
||||
```
|
||||
|
||||
Requests that ask for Markdown can also use the normal docs URL with `Accept: text/markdown`:
|
||||
|
|
@ -57,6 +57,14 @@ Markdown responses are designed for agent consumption:
|
|||
- Tables stay as Markdown tables.
|
||||
- Missing docs pages return a plain-text `404` instead of silently falling back to HTML.
|
||||
|
||||
## Page actions
|
||||
|
||||
Rendered docs pages include page-level actions near the title:
|
||||
|
||||
- **Copy MD** copies the generated Markdown for the current page.
|
||||
- **View MD** opens the generated Markdown route.
|
||||
- **Copy MDX** copies the source MDX for the current page.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
| Mistake | Better path |
|
||||
|
|
@ -64,4 +72,4 @@ Markdown responses are designed for agent consumption:
|
|||
| 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 |
|
||||
| Copying rendered text by hand | Use **Copy MD** or **Copy MDX** from the page actions |
|
||||
|
|
|
|||
|
|
@ -1,62 +0,0 @@
|
|||
---
|
||||
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.
|
||||
|
|
@ -5,8 +5,7 @@
|
|||
"index",
|
||||
"agent-quickstart",
|
||||
"markdown-access",
|
||||
"ktx-skills",
|
||||
"prompt-recipes",
|
||||
"mcp-boundaries"
|
||||
"agent-instructions",
|
||||
"prompt-recipes"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -17,22 +17,22 @@ Read https://ktx.dev/llms.txt first. Then fetch only the KTX Markdown pages need
|
|||
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
|
||||
## Find a command
|
||||
|
||||
```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.
|
||||
Find the correct KTX command for this task: <task>. Start with /llms.txt, then fetch the smallest relevant CLI reference .md page. Quote the exact command and flags from the docs.
|
||||
```
|
||||
|
||||
## Build context
|
||||
## Explain setup
|
||||
|
||||
```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.
|
||||
Explain how to set up KTX for this repo. Read /docs/getting-started/quickstart.md and the relevant CLI reference pages. Summarize prerequisites, commands, generated files, and any credentials the user must provide manually.
|
||||
```
|
||||
|
||||
## Investigate an analytics question
|
||||
## Compare concepts
|
||||
|
||||
```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.
|
||||
Explain the difference between these KTX concepts: <concepts>. Start from /llms.txt, fetch the relevant concept and guide pages as Markdown, and answer with links to the source pages.
|
||||
```
|
||||
|
||||
## Review semantic changes
|
||||
|
|
@ -41,20 +41,14 @@ Use KTX to answer this analytics question: <question>. Discover connections and
|
|||
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
|
||||
## Copy exact docs source
|
||||
|
||||
```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.
|
||||
Open the relevant KTX docs page and use the page action to copy the generated Markdown or source MDX. Preserve code fences and tables exactly.
|
||||
```
|
||||
|
||||
## 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.
|
||||
Update the KTX docs for agent readability. Keep AI Resources focused on docs consumption. After editing, verify /llms.txt, /llms-full.txt, and the affected .md routes.
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue