diff --git a/docs-site/app/docs/[[...slug]]/page.tsx b/docs-site/app/docs/[[...slug]]/page.tsx index f2b560e6..0b59743d 100644 --- a/docs-site/app/docs/[[...slug]]/page.tsx +++ b/docs-site/app/docs/[[...slug]]/page.tsx @@ -8,6 +8,7 @@ import { import { notFound } from "next/navigation"; import defaultMdxComponents from "fumadocs-ui/mdx"; import { CodeBlock } from "@/components/code-block"; +import { DocsPageActions } from "@/components/docs-page-actions"; export default async function Page(props: { params: Promise<{ slug?: string[] }>; @@ -22,6 +23,10 @@ export default async function Page(props: { {page.data.title} {page.data.description} + diff --git a/docs-site/components/docs-page-actions.tsx b/docs-site/components/docs-page-actions.tsx new file mode 100644 index 00000000..dd69cea3 --- /dev/null +++ b/docs-site/components/docs-page-actions.tsx @@ -0,0 +1,110 @@ +"use client"; + +import { useState } from "react"; + +type CopyState = "idle" | "copied" | "error"; + +type Props = { + markdownUrl: string; + mdxSource: string; +}; + +export function DocsPageActions({ markdownUrl, mdxSource }: Props) { + return ( +
+ + + View MD + + +
+ ); +} + +function CopyMarkdownButton({ markdownUrl }: { markdownUrl: string }) { + const [state, setState] = useState("idle"); + + const onClick = async () => { + try { + const response = await fetch(markdownUrl, { + headers: { Accept: "text/markdown" }, + }); + + if (!response.ok) { + throw new Error(`Failed to fetch ${markdownUrl}`); + } + + await navigator.clipboard.writeText(await response.text()); + flash(setState, "copied"); + } catch { + flash(setState, "error"); + } + }; + + return ( + + ); +} + +function CopyTextButton({ label, text }: { label: string; text: string }) { + const [state, setState] = useState("idle"); + + const onClick = async () => { + try { + await navigator.clipboard.writeText(text); + flash(setState, "copied"); + } catch { + flash(setState, "error"); + } + }; + + return ( + + ); +} + +function ActionButton({ + label, + onClick, + state, +}: { + label: string; + onClick: () => void; + state: CopyState; +}) { + return ( + + ); +} + +function labelForState(state: CopyState, label: string) { + if (state === "copied") return "Copied"; + if (state === "error") return "Copy failed"; + return label; +} + +function flash( + setState: (state: CopyState) => void, + state: Exclude, +) { + setState(state); + window.setTimeout(() => setState("idle"), 1500); +} diff --git a/docs-site/content/docs/ai-resources/agent-instructions.mdx b/docs-site/content/docs/ai-resources/agent-instructions.mdx new file mode 100644 index 00000000..56a10c21 --- /dev/null +++ b/docs-site/content/docs/ai-resources/agent-instructions.mdx @@ -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/.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. +``` diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx index 4ca39a1d..81bc3060 100644 --- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx +++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx @@ -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. diff --git a/docs-site/content/docs/ai-resources/index.mdx b/docs-site/content/docs/ai-resources/index.mdx index 034b46a5..be315453 100644 --- a/docs-site/content/docs/ai-resources/index.mdx +++ b/docs-site/content/docs/ai-resources/index.mdx @@ -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/.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. diff --git a/docs-site/content/docs/ai-resources/ktx-skills.mdx b/docs-site/content/docs/ai-resources/ktx-skills.mdx deleted file mode 100644 index aa9d5048..00000000 --- a/docs-site/content/docs/ai-resources/ktx-skills.mdx +++ /dev/null @@ -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). diff --git a/docs-site/content/docs/ai-resources/markdown-access.mdx b/docs-site/content/docs/ai-resources/markdown-access.mdx index 983733f3..cb83c70f 100644 --- a/docs-site/content/docs/ai-resources/markdown-access.mdx +++ b/docs-site/content/docs/ai-resources/markdown-access.mdx @@ -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 | diff --git a/docs-site/content/docs/ai-resources/mcp-boundaries.mdx b/docs-site/content/docs/ai-resources/mcp-boundaries.mdx deleted file mode 100644 index a0b8d7ac..00000000 --- a/docs-site/content/docs/ai-resources/mcp-boundaries.mdx +++ /dev/null @@ -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/.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. diff --git a/docs-site/content/docs/ai-resources/meta.json b/docs-site/content/docs/ai-resources/meta.json index 3a570808..ff555283 100644 --- a/docs-site/content/docs/ai-resources/meta.json +++ b/docs-site/content/docs/ai-resources/meta.json @@ -5,8 +5,7 @@ "index", "agent-quickstart", "markdown-access", - "ktx-skills", - "prompt-recipes", - "mcp-boundaries" + "agent-instructions", + "prompt-recipes" ] } diff --git a/docs-site/content/docs/ai-resources/prompt-recipes.mdx b/docs-site/content/docs/ai-resources/prompt-recipes.mdx index efed2282..c25da2b4 100644 --- a/docs-site/content/docs/ai-resources/prompt-recipes.mdx +++ b/docs-site/content/docs/ai-resources/prompt-recipes.mdx @@ -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: . 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: . 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: . 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: . 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 . 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. ``` diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 537e4d23..1624b1f9 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -40,7 +40,7 @@ If you've ever watched an agent confidently generate a query that joins on the w Set up KTX and build your first context in under 10 minutes. - Machine-readable docs, prompt recipes, and agent setup paths for coding assistants. + Machine-readable docs and prompt recipes for coding assistants. Understand what a context layer is, why agents need one, and how KTX compares to other semantic layers. @@ -74,5 +74,4 @@ Use this page as the high-level routing document for KTX docs. | 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 product tools to an agent client | [Serving Agents](/docs/guides/serving-agents) | | Look up exact command flags | [CLI Reference](/docs/cli-reference/ktx-setup) | diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx index c6a56d54..91a17d05 100644 --- a/docs-site/content/docs/getting-started/quickstart.mdx +++ b/docs-site/content/docs/getting-started/quickstart.mdx @@ -5,7 +5,7 @@ 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). +If you are a coding assistant trying to decide which KTX docs page to read, start with the [Agent Quickstart](/docs/ai-resources/agent-quickstart). This page is the human setup walkthrough. ## Workflow summary diff --git a/docs-site/content/docs/guides/serving-agents.mdx b/docs-site/content/docs/guides/serving-agents.mdx index 99ad1203..9b0b19c7 100644 --- a/docs-site/content/docs/guides/serving-agents.mdx +++ b/docs-site/content/docs/guides/serving-agents.mdx @@ -5,20 +5,6 @@ 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: - -1. Discover connections with `connection_list` or `ktx agent context --json`. -2. Discover semantic sources with `sl_list_sources` or `ktx agent sl list --json`. -3. Search knowledge with `knowledge_search` or `ktx agent wiki search`. -4. Query through the semantic layer with `sl_query` or `ktx agent sl query`. -5. Execute SQL only when execution is explicitly enabled and row limits are set. - -Use the semantic layer first for analytics questions. Direct SQL is a fallback for read-only inspection, not the default path. - ## MCP Server The MCP (Model Context Protocol) server gives agents structured access to your entire context layer — semantic sources, knowledge pages, scans, and ingestion — through a standard tool-calling interface. @@ -99,27 +85,6 @@ When an agent connects via MCP, it can call these tools: | `memory_capture` | Capture knowledge and semantic updates from a conversation | | `memory_capture_status` | Check the status of a memory capture run | -### Tool input reference - -| Tool | Required inputs | Optional inputs | Output shape | -|------|-----------------|-----------------|--------------| -| `connection_list` | none | none | JSON list of configured connections | -| `connection_test` | `connectionId` | none | JSON test result with driver metadata or an error | -| `sl_list_sources` | none | `connectionId`, `query` | JSON list of semantic source summaries | -| `sl_read_source` | `sourceName`, `connectionId` | none | YAML source content and metadata | -| `sl_write_source` | `sourceName`, `connectionId`, source YAML or delete operation | none | Write result and validation details | -| `sl_validate` | `sourceName`, `connectionId` | none | Validation result with schema and join issues | -| `sl_query` | `connectionId`, measures or query payload | dimensions, filters, segments, order, limit, execute, maxRows | Compiled SQL, query plan, and rows when execution is enabled | -| `knowledge_search` | `query` | `limit`, `userId` | Ranked knowledge results with summaries | -| `knowledge_read` | `pageId` or key | `userId` | Full Markdown knowledge page | -| `knowledge_write` | key, summary, content | tags, refs, semantic-layer refs, scope, userId | Write result | -| `scan_trigger` | `connectionId`, mode | daemon URLs, dry-run options | Scan run id and status | -| `scan_status` | `runId` | none | Scan progress and current state | -| `scan_report` | `runId` | none | Completed scan report | -| `ingest_trigger` | connection/source adapter selection | limits and introspection URLs | Ingest run id and status | -| `ingest_status` | `runId` | none | Ingest progress, work units, and diff summary | -| `memory_capture` | conversation input | model and user options | Memory capture run id | - ### How agents use these tools A typical agent interaction flows like this: @@ -132,16 +97,6 @@ A typical agent interaction flows like this: Agents should use the semantic layer for analytics questions because it enforces correct joins, grain-aware aggregation, and consistent metric definitions. If SQL execution is enabled, KTX only allows read-only SQL with row limits. -### Workflow: answer an analytics question through MCP - -1. `connection_list` — choose the relevant warehouse connection. -2. `sl_list_sources` with a search query — find candidate semantic sources. -3. `knowledge_search` with the user's business terms — find metric definitions and caveats. -4. `sl_read_source` for each candidate source — inspect measures, dimensions, joins, and grain. -5. `sl_query` with `execute: false` — compile SQL and inspect the generated query. -6. `sl_query` with `execute: true` and a bounded `maxRows` — execute only when the user asked for data and execution is enabled. -7. Cite the semantic source and knowledge pages used in the answer. - ## CLI Commands For agents that work through the terminal rather than MCP, KTX provides a set of machine-readable commands under `ktx agent`. These return JSON output designed for programmatic consumption. @@ -194,28 +149,6 @@ ktx agent sql execute --json \ --max-rows 500 ``` -### CLI input reference - -| Command | Required inputs | Optional inputs | Output | -|---------|-----------------|-----------------|--------| -| `ktx agent tools --json` | `--json` | none | JSON list of available agent commands | -| `ktx agent context --json` | `--json` | none | JSON project context and readiness state | -| `ktx agent sl list --json` | `--json` | `--connection-id`, `--query` | JSON semantic source list | -| `ktx agent sl read --json --connection-id ` | source name, `--json`, `--connection-id` | none | JSON payload containing source YAML | -| `ktx agent sl query --json --connection-id --query-file ` | `--json`, `--connection-id`, `--query-file` | `--execute`, `--max-rows` | JSON compiled query, SQL, plan, and optional rows | -| `ktx agent wiki search --json` | query, `--json` | `--limit` | JSON ranked knowledge results | -| `ktx agent wiki read --json` | page id, `--json` | none | JSON full knowledge page | -| `ktx agent sql execute --json --connection-id --sql-file --max-rows ` | `--json`, `--connection-id`, `--sql-file`, `--max-rows` | none | JSON rows and execution metadata | - -### Workflow: answer an analytics question through CLI - -1. `ktx agent context --json` — verify the KTX project is ready for agents. -2. `ktx agent sl list --json --query "revenue"` — find semantic sources related to the question. -3. `ktx agent wiki search "revenue recognition" --json --limit 5` — retrieve business definitions. -4. Write a query JSON file with measures, dimensions, filters, and limits. -5. `ktx agent sl query --json --connection-id my-postgres --query-file query.json` — compile and inspect SQL. -6. Add `--execute --max-rows 100` only when the user needs rows and execution is allowed. - ### When to use CLI vs MCP | | MCP | CLI | @@ -272,13 +205,3 @@ The agents step auto-detects installed tools and generates the right configurati ``` After configuration, the agent can immediately start calling KTX tools — listing sources, searching knowledge, and querying your semantic layer. - -## Common errors - -| Error or symptom | Likely cause | Recovery | -|------------------|--------------|----------| -| Agent cannot find the MCP server | Agent config points to a missing `ktx` binary or wrong project directory | Run `ktx setup --agents` again, then verify the generated MCP config contains the intended `KTX_PROJECT_DIR` | -| MCP tools list but semantic queries fail | `--semantic-compute` was not enabled or the daemon URL is wrong | Start `ktx serve --mcp stdio --semantic-compute` or set `--semantic-compute-url` to the running daemon | -| Query execution is rejected | The MCP server was started without `--execute-queries` or the SQL is not read-only | Restart with `--execute-queries` only when execution is intended, and keep `maxRows` bounded | -| `ktx agent` command exits without JSON | `--json` was omitted | Re-run the command with `--json`; all `ktx agent` subcommands require it | -| SQL execution exceeds limits | `--max-rows` is missing or too high | Re-run with an explicit value from 1 to 1000 | diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx index 5647162f..088dbba4 100644 --- a/docs-site/content/docs/integrations/agent-clients.mdx +++ b/docs-site/content/docs/integrations/agent-clients.mdx @@ -8,29 +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 - -Use this table to choose the setup path before editing client-specific files. - -| Target | Project-scoped files | Global install | Recommended mode | Reload needed | -|--------|----------------------|----------------|------------------|---------------| -| Claude Code | `.claude/skills/ktx/SKILL.md`, `.mcp.json` | Yes | Both CLI skill and MCP | Skill reload is automatic; MCP starts on first use | -| Cursor | `.cursor/rules/ktx.mdc`, `.cursor/mcp.json` | No | Both CLI rule and MCP | Reload the Cursor window after MCP config changes | -| Codex | `.agents/skills/ktx/SKILL.md`, `.agents/mcp/ktx.json` | Yes | Both CLI skill and MCP | Start a new session after global skill changes | -| OpenCode | `.opencode/commands/ktx.md`, `.opencode/mcp.json` | No | Both CLI command and MCP | Restart OpenCode after config changes | - -The safest generated command is: - -```bash -ktx setup --agents --target codex --agent-install-mode both --project -``` - -Replace `codex` with `claude-code`, `cursor`, `opencode`, or `universal`. - ## Claude Code ### Install via `ktx setup` @@ -298,13 +277,3 @@ All agent clients connect to the same KTX MCP server. The server exposes these t | Global install | Yes | No | Yes | No | | Config location | `.mcp.json` | `.cursor/mcp.json` | `.agents/mcp/ktx.json` | `.opencode/mcp.json` | | Skills location | `.claude/skills/` | `.cursor/rules/` | `.agents/skills/` | `.opencode/commands/` | - -## Common errors - -| Error or symptom | Likely cause | Recovery | -|------------------|--------------|----------| -| Agent cannot start MCP server | The config points to a missing `ktx` binary | Run `pnpm run link:dev`, rerun `ktx setup --agents`, or use an absolute command path | -| Agent sees MCP tools but queries fail | Server args omit `--semantic-compute` | Add `--semantic-compute`; add `--execute-queries` only when read-only execution is intended | -| Agent reads the wrong KTX project | `--project-dir` or `KTX_PROJECT_DIR` points at another directory | Regenerate project-scoped config from the intended project directory | -| CLI skill commands return non-JSON output | The generated command omitted `--json` or an agent changed it | Restore the generated skill/rule and ensure every `ktx agent` command includes `--json` | -| Cursor or OpenCode does not show new tools | The client has not reloaded its MCP config | Reload the app window or restart the agent client | diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts index fd0bbf40..8bc39008 100644 --- a/docs-site/lib/llm-docs.ts +++ b/docs-site/lib/llm-docs.ts @@ -53,7 +53,8 @@ KTX provides semantic-layer files, warehouse scans, knowledge pages, provenance, ${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")} +${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")} ## Start Here @@ -68,13 +69,6 @@ ${link("/docs/guides/writing-context", "Writing Context", "Write semantic source - [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 ${link("/docs/cli-reference/ktx-setup", "ktx setup", "Interactive project setup")}