From 8fdf578148ce43c0614a510b578ea33e2c85ef36 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:30:47 -0700 Subject: [PATCH 01/12] docs: design agent-friendly docs site --- ...6-05-11-agent-friendly-docs-site-design.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-11-agent-friendly-docs-site-design.md diff --git a/docs/superpowers/specs/2026-05-11-agent-friendly-docs-site-design.md b/docs/superpowers/specs/2026-05-11-agent-friendly-docs-site-design.md new file mode 100644 index 00000000..69784f5e --- /dev/null +++ b/docs/superpowers/specs/2026-05-11-agent-friendly-docs-site-design.md @@ -0,0 +1,171 @@ +# Agent-Friendly Docs Site Design + +## Goal + +Make `docs-site` easier for coding agents and LLM readers to discover, ingest, +and use. The work applies the Vercel Academy agent-friendly docs patterns to the +KTX documentation site while preserving the current Fumadocs + Next.js +architecture. + +Success means agents can: + +- Discover the documentation from well-known root files. +- Fetch all documentation in one plain-text response. +- Fetch any docs page as markdown without parsing the HTML UI. +- Follow CLI, MCP, setup, integration, and semantic-layer workflows from + structured examples. +- Recover from common setup and command failures using explicit troubleshooting + notes. + +## Current State + +`docs-site` is a Next 15 app using Fumadocs. Source pages live under +`docs-site/content/docs`, and rendered docs are served under `/docs`. + +The site currently has good human-facing MDX pages, but it does not expose: + +- `/llms.txt` +- `/llms-full.txt` +- raw markdown routes such as `/docs/getting-started/quickstart.md` +- markdown content negotiation + +Many docs pages already use tables and code blocks, but the structure is not +consistently optimized for literal agent parsing. CLI and agent-facing pages are +the highest-priority content because agents are most likely to copy commands and +JSON examples directly. + +## Design + +### Machine-readable access + +Add a small LLM docs utility layer inside `docs-site`: + +- `docs-site/lib/llm-docs.ts` + - Converts Fumadocs pages to raw or LLM-readable markdown. + - Builds a stable ordered list of docs pages from `source.getPages()`. + - Produces the `llms.txt` index content. + - Produces the `llms-full.txt` bundled content. + +Add routes: + +- `docs-site/app/llms.txt/route.ts` + - Returns `text/plain; charset=utf-8`. + - Includes `# KTX`, a blockquote summary, a short description, and sections + linking to key docs, markdown docs, CLI reference pages, integration pages, + and `/llms-full.txt`. + +- `docs-site/app/llms-full.txt/route.ts` + - Returns `text/plain; charset=utf-8`. + - Concatenates all docs pages in source order. + - Prefixes each page with a stable heading and canonical `/docs/...` URL. + +- `docs-site/app/llms.mdx/docs/[[...slug]]/route.ts` + - Returns one docs page as `text/markdown; charset=utf-8`. + - Uses the same slug shape as `/docs/[[...slug]]`. + - Returns 404 for unknown pages. + +Add a Next rewrite in `docs-site/next.config.mjs`: + +- `/docs/:path*.md` rewrites to `/llms.mdx/docs/:path*` + +Add a markdown negotiation proxy for `/docs/...` requests: + +- Requests whose `Accept` header prefers markdown are rewritten to the matching + LLM markdown route. +- Normal browser requests continue to render the existing Fumadocs UI. +- The proxy must leave `/llms.txt`, `/llms-full.txt`, assets, and non-docs + routes unchanged. + +### Content rewrite pass + +Rewrite the existing MDX content in a bounded, high-impact pass. The intent is +not to expand every page; it is to make every page more literal and consistent +for agents. + +Apply these patterns across docs: + +- Put command signatures in fenced code blocks. +- Use tables for flags, options, inputs, outputs, supported values, and + environment variables. +- Use realistic values in copy-paste examples. +- Show complete expected command output when output shape matters. +- Add explicit "Common errors" or "Recovery" sections for workflows where a + command can fail for predictable reasons. +- Add workflow sections that chain commands in the order an agent should use + them. +- Avoid placeholders that an agent could copy literally, unless the placeholder + is clearly marked as a value to replace. + +Priority pages: + +1. `getting-started/quickstart.mdx` + - Add a compact workflow summary. + - Make prerequisites and generated files explicit. + - Add troubleshooting for missing API keys, failed connection tests, daemon + startup, and unbuilt context. + +2. `guides/serving-agents.mdx` + - Treat MCP tools and `ktx agent` commands as agent-facing API references. + - Add tool/command input tables, output expectations, safety constraints, and + workflows for answering analytics questions. + +3. `guides/writing-context.mdx` + - Add semantic-source schema tables. + - Add workflows for listing, reading, editing, validating, querying, and + writing wiki knowledge. + +4. `cli-reference/*.mdx` + - Normalize every command page to: command signature, subcommands table, + option tables, examples, output modes, common errors, and related workflows + where useful. + +5. `integrations/agent-clients.mdx`, `integrations/primary-sources.mdx`, and + `integrations/context-sources.mdx` + - Normalize integration setup sections into structured config tables, + copy-paste examples, authentication requirements, and recovery notes. + +6. Concept and benchmark pages + - Keep narrative content, but add compact "Agent usage notes" where it helps + agents decide when to read or cite the page. + +### Documentation boundaries + +The first pass should not introduce a separate public docs tree or a generated +API reference system. It should work with the existing MDX source files and +Fumadocs loader. + +Do not add stale compatibility aliases or rename KTX concepts. Keep examples +aligned with commands and files that exist in the standalone KTX repository. + +### Testing + +Verification commands: + +- `pnpm --filter ktx-docs build` +- `pnpm --filter ktx-docs exec tsc --noEmit` after generated Fumadocs source + files exist. +- Route checks against a local docs server: + - `GET /llms.txt` returns 200 and `text/plain`. + - `GET /llms-full.txt` returns 200 and `text/plain`. + - `GET /docs/getting-started/quickstart.md` returns 200 and + `text/markdown`. + - unknown markdown docs paths return 404. + +For content checks, inspect the generated markdown responses to confirm they +contain: + +- realistic command examples, +- tables, +- full output examples where documented, +- workflow sections, +- recovery/error sections. + +## Acceptance Criteria + +- `/llms.txt` gives agents a concise index with links to key KTX docs and + `/llms-full.txt`. +- `/llms-full.txt` returns all docs content in source order as plain text. +- Every Fumadocs page can be fetched through a `.md` URL. +- High-priority docs pages use consistent agent-friendly structure. +- The docs site builds successfully. +- Verification results and any skipped checks are reported clearly. From b440c7509218013a3d6079aa09184e3bae04968a Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:38:15 -0700 Subject: [PATCH 02/12] docs: plan agent-friendly docs site --- .../2026-05-11-agent-friendly-docs-site.md | 411 ++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-11-agent-friendly-docs-site.md diff --git a/docs/superpowers/plans/2026-05-11-agent-friendly-docs-site.md b/docs/superpowers/plans/2026-05-11-agent-friendly-docs-site.md new file mode 100644 index 00000000..0f2eea70 --- /dev/null +++ b/docs/superpowers/plans/2026-05-11-agent-friendly-docs-site.md @@ -0,0 +1,411 @@ +# Agent-Friendly Docs Site Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make `docs-site` discoverable and readable by coding agents through `llms.txt`, bundled markdown, per-page markdown routes, markdown negotiation, and stricter agent-friendly docs content. + +**Architecture:** Keep the existing Next 15 + Fumadocs app. Add a small `lib/llm-docs.ts` module that reads Fumadocs pages and builds machine-readable markdown responses, then expose those responses through route handlers and a markdown negotiation proxy. Rewrite existing MDX pages in place so the rendered UI and machine-readable routes share one source of truth. + +**Tech Stack:** Next.js 15 App Router, Fumadocs, MDX, TypeScript, pnpm, Node 22. + +--- + +### Task 1: Machine-Readable Docs Routes + +**Files:** +- Create: `docs-site/lib/llm-docs.ts` +- Create: `docs-site/app/llms.txt/route.ts` +- Create: `docs-site/app/llms-full.txt/route.ts` +- Create: `docs-site/app/llms.mdx/docs/[[...slug]]/route.ts` +- Modify: `docs-site/next.config.mjs` + +- [ ] **Step 1: Add the LLM docs utility** + +Create `docs-site/lib/llm-docs.ts` with functions that: + +```ts +import { source } from "@/lib/source"; + +const SITE_ORIGIN = "https://ktx.dev"; + +export type LlmDocsPage = { + title: string; + description?: string; + url: string; + markdownUrl: string; + slug: string[]; + getMarkdown: () => Promise; +}; + +export function getLlmDocsPages(): LlmDocsPage[] { + return source.getPages().map((page) => ({ + title: page.data.title, + description: page.data.description, + url: page.url, + markdownUrl: `${page.url}.md`, + slug: page.slugs, + getMarkdown: async () => normalizeMarkdown(await page.data.getText("raw")), + })); +} + +export function getLlmDocsPage(slug: string[] | undefined) { + const page = source.getPage(slug); + if (!page) return null; + + return { + title: page.data.title, + description: page.data.description, + url: page.url, + markdownUrl: `${page.url}.md`, + slug: page.slugs, + getMarkdown: async () => normalizeMarkdown(await page.data.getText("raw")), + } satisfies LlmDocsPage; +} + +export async function getPageMarkdown(page: LlmDocsPage) { + const body = await page.getMarkdown(); + const description = page.description ? `\n\n> ${page.description}` : ""; + + return `# ${page.title}${description}\n\nCanonical URL: ${page.url}\nMarkdown URL: ${page.markdownUrl}\n\n${body}`; +} + +export function buildLlmsTxt() { + const pages = getLlmDocsPages(); + const byUrl = new Map(pages.map((page) => [page.url, page])); + const link = (url: string, label: string, fallbackDescription: string) => { + const page = byUrl.get(url); + const description = page?.description ?? fallbackDescription; + return `- [${label}](${url}): ${description}`; + }; + + return `# KTX + +> Agent-native context layer for analytics engineering and database agents. + +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. + +## 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 + +## CLI Reference + +${link("/docs/cli-reference/ktx-setup", "ktx setup", "Interactive project setup")} +${link("/docs/cli-reference/ktx-agent", "ktx agent", "Machine-readable commands for coding agents")} +${link("/docs/cli-reference/ktx-sl", "ktx sl", "Semantic-layer commands")} +${link("/docs/cli-reference/ktx-wiki", "ktx wiki", "Knowledge page commands")} +${link("/docs/cli-reference/ktx-connection", "ktx connection", "Connection management commands")} + +## 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")} +`; +} + +export async function buildLlmsFullTxt() { + const pages = getLlmDocsPages(); + const rendered = await Promise.all(pages.map(getPageMarkdown)); + return [`# KTX Full Documentation`, `Source: ${SITE_ORIGIN}`, ...rendered].join("\n\n---\n\n"); +} + +function normalizeMarkdown(markdown: string) { + return markdown.trim().replace(/\n{3,}/g, "\n\n"); +} +``` + +- [ ] **Step 2: Add route handlers** + +Create route files: + +```ts +import { buildLlmsTxt } from "@/lib/llm-docs"; + +export const dynamic = "force-static"; + +export function GET() { + return new Response(buildLlmsTxt(), { + headers: { "Content-Type": "text/plain; charset=utf-8" }, + }); +} +``` + +```ts +import { buildLlmsFullTxt } from "@/lib/llm-docs"; + +export const dynamic = "force-static"; + +export async function GET() { + return new Response(await buildLlmsFullTxt(), { + headers: { "Content-Type": "text/plain; charset=utf-8" }, + }); +} +``` + +```ts +import { getLlmDocsPage, getPageMarkdown } from "@/lib/llm-docs"; +import { notFound } from "next/navigation"; + +export const dynamic = "force-static"; + +export async function GET( + _request: Request, + props: { params: Promise<{ slug?: string[] }> }, +) { + const params = await props.params; + const page = getLlmDocsPage(params.slug); + if (!page) notFound(); + + return new Response(await getPageMarkdown(page), { + headers: { "Content-Type": "text/markdown; charset=utf-8" }, + }); +} + +export function generateStaticParams() { + return getLlmDocsPages().map((page) => ({ slug: page.slug })); +} +``` + +- [ ] **Step 3: Add `.md` rewrite** + +Modify `docs-site/next.config.mjs`: + +```js +import { createMDX } from "fumadocs-mdx/next"; + +const withMDX = createMDX(); + +/** @type {import('next').NextConfig} */ +const config = { + async rewrites() { + return [ + { + source: "/docs/:path*.md", + destination: "/llms.mdx/docs/:path*", + }, + ]; + }, +}; + +export default withMDX(config); +``` + +- [ ] **Step 4: Build check** + +Run: `pnpm --filter ktx-docs build` + +Expected: Next build completes and static routes include `llms.txt`, `llms-full.txt`, and the LLM markdown route. + +### Task 2: Markdown Negotiation + +**Files:** +- Create: `docs-site/proxy.ts` + +- [ ] **Step 1: Add markdown negotiation proxy** + +Create `docs-site/proxy.ts`: + +```ts +import { isMarkdownPreferred, rewritePath } from "fumadocs-core/negotiation"; +import { NextResponse, type NextRequest } from "next/server"; + +const { rewrite } = rewritePath("/docs/*path", "/llms.mdx/docs/*path"); + +export function proxy(request: NextRequest) { + if (!isMarkdownPreferred(request)) { + return NextResponse.next(); + } + + const rewrittenPath = rewrite(request.nextUrl.pathname); + if (!rewrittenPath) { + return NextResponse.next(); + } + + return NextResponse.rewrite(new URL(rewrittenPath, request.nextUrl)); +} + +export const config = { + matcher: ["/docs/:path*"], +}; +``` + +- [ ] **Step 2: Verify build** + +Run: `pnpm --filter ktx-docs build` + +Expected: Build passes with the proxy included. + +### Task 3: Agent-Friendly High-Priority Guides + +**Files:** +- Modify: `docs-site/content/docs/getting-started/quickstart.mdx` +- Modify: `docs-site/content/docs/guides/serving-agents.mdx` +- Modify: `docs-site/content/docs/guides/writing-context.mdx` + +- [ ] **Step 1: Rewrite quickstart structure** + +Add sections for: + +- Workflow summary +- Generated files +- Common errors and recovery + +Keep existing setup detail, but make each command block copy-pasteable and each expected output complete enough for agents to recognize success. + +- [ ] **Step 2: Rewrite Serving Agents as API reference** + +Add tables for MCP tool inputs and CLI command inputs. Add workflows: + +- Answer an analytics question through MCP +- Answer an analytics question through CLI +- Safely execute SQL with row limits + +- [ ] **Step 3: Rewrite Writing Context with schemas and workflows** + +Add semantic-source field tables, knowledge-page field tables, and workflows: + +- Inspect a source +- Edit and validate a source +- Query through the semantic layer +- Write and search a knowledge page + +- [ ] **Step 4: Build check** + +Run: `pnpm --filter ktx-docs build` + +Expected: MDX compiles without syntax errors. + +### Task 4: CLI Reference Normalization + +**Files:** +- Modify: `docs-site/content/docs/cli-reference/*.mdx` + +- [ ] **Step 1: Normalize every CLI page** + +For each CLI reference page, ensure this structure exists: + +```md +## Command signature + +```bash +ktx [subcommand] [options] +``` + +## Subcommands + +| Subcommand | Description | +|---|---| + +## Options + +| Flag | Type | Required | Description | Default | +|---|---|---|---|---| + +## Examples + +```bash +ktx --real-flag realistic-value +``` + +## Output + +```text +complete expected output shape +``` + +## Common errors + +| Error | Cause | Recovery | +|---|---|---| +``` + +Only add sections that are relevant to the command; do not invent output for commands whose output is intentionally interactive. + +- [ ] **Step 2: Build check** + +Run: `pnpm --filter ktx-docs build` + +Expected: MDX compiles without syntax errors. + +### Task 5: Integration and Concept Page Polish + +**Files:** +- Modify: `docs-site/content/docs/integrations/agent-clients.mdx` +- Modify: `docs-site/content/docs/integrations/primary-sources.mdx` +- Modify: `docs-site/content/docs/integrations/context-sources.mdx` +- Modify: `docs-site/content/docs/concepts/*.mdx` +- Modify: `docs-site/content/docs/benchmarks/link-detection.mdx` + +- [ ] **Step 1: Normalize integrations** + +Add structured sections for supported values, config snippets, authentication, generated files, and recovery notes. Keep existing examples aligned with current KTX commands. + +- [ ] **Step 2: Add agent usage notes** + +For concept and benchmark pages, add a compact `## Agent usage notes` section that tells agents when the page is relevant and which concrete page to read next. + +- [ ] **Step 3: Build check** + +Run: `pnpm --filter ktx-docs build` + +Expected: MDX compiles without syntax errors. + +### Task 6: Route Verification and Final Checks + +**Files:** +- No required source changes unless verification finds a bug. + +- [ ] **Step 1: Run production build** + +Run: `pnpm --filter ktx-docs build` + +Expected: Build succeeds. + +- [ ] **Step 2: Run TypeScript check** + +Run: `pnpm --filter ktx-docs exec tsc --noEmit` + +Expected: TypeScript exits successfully. + +- [ ] **Step 3: Start local server** + +Run: `pnpm --filter ktx-docs start` + +Expected: Server starts on an available port. + +- [ ] **Step 4: Verify machine-readable routes** + +Run: + +```bash +curl -i http://localhost:3000/llms.txt +curl -i http://localhost:3000/llms-full.txt +curl -i http://localhost:3000/docs/getting-started/quickstart.md +curl -i -H "Accept: text/markdown" http://localhost:3000/docs/getting-started/quickstart +curl -i http://localhost:3000/docs/not-a-page.md +``` + +Expected: + +- `/llms.txt`: `200`, `Content-Type: text/plain; charset=utf-8` +- `/llms-full.txt`: `200`, `Content-Type: text/plain; charset=utf-8` +- `/docs/getting-started/quickstart.md`: `200`, `Content-Type: text/markdown; charset=utf-8` +- `/docs/getting-started/quickstart` with `Accept: text/markdown`: `200`, `Content-Type: text/markdown; charset=utf-8` +- `/docs/not-a-page.md`: `404` + +- [ ] **Step 5: Inspect final diff** + +Run: `git diff --stat && git diff --check` + +Expected: Diff contains only docs-site and plan changes, with no whitespace errors. From dfa4651ebc8a237478ffb65a670948108f846878 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:40:34 -0700 Subject: [PATCH 03/12] feat(docs-site): add agent-readable docs routes --- docs-site/app/llms-full.txt/route.ts | 11 ++ .../app/llms.mdx/docs/[[...slug]]/route.ts | 27 +++++ docs-site/app/llms.txt/route.ts | 11 ++ docs-site/lib/llm-docs.ts | 101 ++++++++++++++++++ docs-site/middleware.ts | 51 +++++++++ docs-site/next.config.mjs | 11 +- 6 files changed, 211 insertions(+), 1 deletion(-) create mode 100644 docs-site/app/llms-full.txt/route.ts create mode 100644 docs-site/app/llms.mdx/docs/[[...slug]]/route.ts create mode 100644 docs-site/app/llms.txt/route.ts create mode 100644 docs-site/lib/llm-docs.ts create mode 100644 docs-site/middleware.ts diff --git a/docs-site/app/llms-full.txt/route.ts b/docs-site/app/llms-full.txt/route.ts new file mode 100644 index 00000000..0edf170c --- /dev/null +++ b/docs-site/app/llms-full.txt/route.ts @@ -0,0 +1,11 @@ +import { buildLlmsFullTxt } from "@/lib/llm-docs"; + +export const dynamic = "force-static"; + +export async function GET() { + return new Response(await buildLlmsFullTxt(), { + headers: { + "Content-Type": "text/plain; charset=utf-8", + }, + }); +} diff --git a/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts b/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts new file mode 100644 index 00000000..e4cd9e4a --- /dev/null +++ b/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts @@ -0,0 +1,27 @@ +import { + getLlmDocsPage, + getLlmDocsPages, + getPageMarkdown, +} from "@/lib/llm-docs"; +import { notFound } from "next/navigation"; + +export const dynamic = "force-static"; + +export async function GET( + _request: Request, + props: { params: Promise<{ slug?: string[] }> }, +) { + const params = await props.params; + const page = getLlmDocsPage(params.slug); + if (!page) notFound(); + + return new Response(await getPageMarkdown(page), { + headers: { + "Content-Type": "text/markdown; charset=utf-8", + }, + }); +} + +export function generateStaticParams() { + return getLlmDocsPages().map((page) => ({ slug: page.slug })); +} diff --git a/docs-site/app/llms.txt/route.ts b/docs-site/app/llms.txt/route.ts new file mode 100644 index 00000000..7b65782a --- /dev/null +++ b/docs-site/app/llms.txt/route.ts @@ -0,0 +1,11 @@ +import { buildLlmsTxt } from "@/lib/llm-docs"; + +export const dynamic = "force-static"; + +export function GET() { + return new Response(buildLlmsTxt(), { + headers: { + "Content-Type": "text/plain; charset=utf-8", + }, + }); +} diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts new file mode 100644 index 00000000..4e7d024d --- /dev/null +++ b/docs-site/lib/llm-docs.ts @@ -0,0 +1,101 @@ +import { source } from "@/lib/source"; + +const siteOrigin = "https://ktx.dev"; + +export type LlmDocsPage = { + title: string; + description?: string; + url: string; + markdownUrl: string; + slug: string[]; + getMarkdown: () => Promise; +}; + +export function getLlmDocsPages(): LlmDocsPage[] { + return source.getPages().map(toLlmDocsPage); +} + +export function getLlmDocsPage(slug: string[] | undefined) { + const page = source.getPage(slug); + return page ? toLlmDocsPage(page) : null; +} + +export async function getPageMarkdown(page: LlmDocsPage) { + const description = page.description ? `\n\n> ${page.description}` : ""; + const body = await page.getMarkdown(); + + return normalizeMarkdown(`# ${page.title}${description} + +Canonical URL: ${page.url} +Markdown URL: ${page.markdownUrl} + +${body} +`); +} + +export function buildLlmsTxt() { + const pages = getLlmDocsPages(); + const byUrl = new Map(pages.map((page) => [page.url, page])); + const link = (url: string, label: string, fallbackDescription: string) => { + const page = byUrl.get(url); + const description = page?.description ?? fallbackDescription; + return `- [${label}](${url}): ${description}`; + }; + + return `# KTX + +> Agent-native context layer for analytics engineering and database agents. + +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. + +## 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 + +## CLI Reference + +${link("/docs/cli-reference/ktx-setup", "ktx setup", "Interactive project setup")} +${link("/docs/cli-reference/ktx-agent", "ktx agent", "Machine-readable commands for coding agents")} +${link("/docs/cli-reference/ktx-sl", "ktx sl", "Semantic-layer commands")} +${link("/docs/cli-reference/ktx-wiki", "ktx wiki", "Knowledge page commands")} +${link("/docs/cli-reference/ktx-connection", "ktx connection", "Connection management commands")} + +## 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")} +`; +} + +export async function buildLlmsFullTxt() { + const rendered = await Promise.all(getLlmDocsPages().map(getPageMarkdown)); + return [`# KTX Full Documentation`, `Source: ${siteOrigin}`, ...rendered].join( + "\n\n---\n\n", + ); +} + +function toLlmDocsPage(page: ReturnType[number]) { + return { + title: page.data.title, + description: page.data.description, + url: page.url, + markdownUrl: `${page.url}.md`, + slug: page.slugs, + getMarkdown: async () => normalizeMarkdown(page.data.content), + } satisfies LlmDocsPage; +} + +function normalizeMarkdown(markdown: string) { + return markdown.trim().replace(/\n{3,}/g, "\n\n"); +} diff --git a/docs-site/middleware.ts b/docs-site/middleware.ts new file mode 100644 index 00000000..4e06ea8b --- /dev/null +++ b/docs-site/middleware.ts @@ -0,0 +1,51 @@ +import { NextResponse, type NextRequest } from "next/server"; + +const markdownMimeTypes = new Set([ + "text/markdown", + "text/x-markdown", + "application/markdown", +]); + +export function middleware(request: NextRequest) { + if (!isMarkdownPreferred(request.headers.get("accept"))) { + return NextResponse.next(); + } + + const { pathname } = request.nextUrl; + if (!pathname.startsWith("/docs/") || pathname.endsWith(".md")) { + return NextResponse.next(); + } + + const rewriteUrl = request.nextUrl.clone(); + rewriteUrl.pathname = `/llms.mdx${pathname}`; + + return NextResponse.rewrite(rewriteUrl); +} + +export const config = { + matcher: ["/docs/:path*"], +}; + +function isMarkdownPreferred(acceptHeader: string | null) { + if (!acceptHeader) return false; + + const accepted = acceptHeader + .split(",") + .map((entry, index) => { + const [type = "", ...parameters] = entry.trim().split(";"); + const quality = parameters + .map((parameter) => parameter.trim()) + .find((parameter) => parameter.startsWith("q=")); + + return { + type: type.toLowerCase(), + quality: quality ? Number.parseFloat(quality.slice(2)) : 1, + index, + }; + }) + .filter((entry) => Number.isFinite(entry.quality) && entry.quality > 0) + .sort((a, b) => b.quality - a.quality || a.index - b.index); + + const preferred = accepted[0]?.type; + return preferred ? markdownMimeTypes.has(preferred) : false; +} diff --git a/docs-site/next.config.mjs b/docs-site/next.config.mjs index d07746eb..8b28486f 100644 --- a/docs-site/next.config.mjs +++ b/docs-site/next.config.mjs @@ -3,6 +3,15 @@ import { createMDX } from "fumadocs-mdx/next"; const withMDX = createMDX(); /** @type {import('next').NextConfig} */ -const config = {}; +const config = { + async rewrites() { + return [ + { + source: "/docs/:path*.md", + destination: "/llms.mdx/docs/:path*", + }, + ]; + }, +}; export default withMDX(config); From 9580bd243d115a2e23bebf890b20cca73146bf15 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:42:08 -0700 Subject: [PATCH 04/12] docs(docs-site): make core guides agent-friendly --- .../docs/getting-started/quickstart.mdx | 40 ++++++++++ .../content/docs/guides/serving-agents.mdx | 75 +++++++++++++++++++ .../content/docs/guides/writing-context.mdx | 71 ++++++++++++++++++ docs-site/lib/llm-docs.ts | 6 +- 4 files changed, 191 insertions(+), 1 deletion(-) diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx index 7df3a611..1913c925 100644 --- a/docs-site/content/docs/getting-started/quickstart.mdx +++ b/docs-site/content/docs/getting-started/quickstart.mdx @@ -5,6 +5,20 @@ 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. +## Workflow summary + +Use this sequence when an agent needs to set up KTX from a fresh checkout: + +1. `pnpm install` — install workspace dependencies. +2. `pnpm run setup:dev` — build local packages and prepare the development CLI. +3. `pnpm run link:dev` — link the `ktx` command for local use. +4. `ktx setup` — create or resume a KTX project. +5. `ktx status` — verify project readiness. +6. `ktx sl list` — confirm semantic-layer sources are available. +7. `ktx sl query ... --format sql` — compile a semantic query without executing it. + +The setup wizard is stateful. If it exits before completion, rerun `ktx setup` in the same project directory to resume from the first incomplete step. + ## Prerequisites - **Node.js 22+** and **pnpm** @@ -198,6 +212,20 @@ Then select which agents to install for: **MCP mode** writes an MCP server configuration (e.g., `.mcp.json`) that lets the agent call KTX tools like `sl_query`, `knowledge_search`, and `sl_write_source` over the Model Context Protocol. +## Generated files + +KTX writes project state as plain files so agents can inspect and edit changes in git. + +| Path | Created by | Purpose | +|------|------------|---------| +| `ktx.yaml` | `ktx setup` | Main project configuration: connections, LLM settings, embeddings, and context sources | +| `.ktx/secrets/*` | `ktx setup` when file-backed secrets are selected | Local secret files referenced from `ktx.yaml`; do not commit these | +| `semantic-layer//*.yaml` | context build, ingestion, or `ktx sl write` | Semantic source definitions agents use for SQL generation | +| `knowledge/global/*.md` | ingestion or `ktx wiki write --scope global` | Shared business context and metric definitions | +| `knowledge/user//*.md` | `ktx wiki write --scope user` | User-scoped notes for one agent/user context | +| `.mcp.json`, `.cursor/mcp.json`, `.agents/mcp/ktx.json`, `.opencode/mcp.json` | agent integration setup | MCP server configuration for supported agent clients | +| `.claude/skills/ktx/SKILL.md`, `.agents/skills/ktx/SKILL.md` | CLI-mode agent integration setup | Agent instructions for calling `ktx agent` commands | + ## Verify it worked Check your project status: @@ -247,6 +275,18 @@ ktx sl query \ --execute --max-rows 10 ``` +## Common errors + +| Error or symptom | Likely cause | Recovery | +|------------------|--------------|----------| +| `ktx: command not found` | The local CLI has not been linked | Run `pnpm run setup:dev` and `pnpm run link:dev` from the KTX checkout, then open a new shell | +| LLM health check fails | Missing, invalid, or unauthorized Anthropic API key | Export `ANTHROPIC_API_KEY` or rerun `ktx setup` and choose the file-backed secret option | +| OpenAI embedding check fails | `OPENAI_API_KEY` is missing when OpenAI embeddings are selected | Export `OPENAI_API_KEY`, or rerun setup and choose local sentence-transformers embeddings | +| Local embeddings hang or fail | The Python daemon cannot start or the local model runtime is unavailable | Run `uv sync --all-groups`, then start `ktx-daemon serve-http --host 127.0.0.1 --port 8765` and rerun setup | +| Database connection test fails | Credentials, network access, warehouse, database, or schema value is wrong | Test the same URL with the database's native client, then rerun `ktx connection add ... --force` or rerun setup | +| `KTX context built: no` in `ktx status` | Setup saved configuration but did not build context | Run `ktx setup context build` or rerun `ktx setup` and choose to build context now | +| Agent integration is incomplete | Setup skipped the agents step or the target was not installed | Run `ktx setup --agents --target codex --agent-install-mode both --project` using the target you need | + ## Next steps - **Build more context** — learn about [scanning](/docs/guides/building-context), relationship detection, and ingestion workflows in the Building Context guide. diff --git a/docs-site/content/docs/guides/serving-agents.mdx b/docs-site/content/docs/guides/serving-agents.mdx index 9b0b19c7..78cb75a1 100644 --- a/docs-site/content/docs/guides/serving-agents.mdx +++ b/docs-site/content/docs/guides/serving-agents.mdx @@ -5,6 +5,18 @@ 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. +## 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. @@ -85,6 +97,27 @@ 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: @@ -97,6 +130,16 @@ 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. @@ -149,6 +192,28 @@ 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 | @@ -205,3 +270,13 @@ 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/guides/writing-context.mdx b/docs-site/content/docs/guides/writing-context.mdx index d70a5f3c..3f0e3fbd 100644 --- a/docs-site/content/docs/guides/writing-context.mdx +++ b/docs-site/content/docs/guides/writing-context.mdx @@ -5,6 +5,17 @@ description: Write and refine semantic sources and knowledge pages. After building context through scanning and ingestion, you'll want to refine it — edit semantic sources to match your business logic, add knowledge pages that capture tribal knowledge, and query your data through the semantic layer to verify everything works. +## Agent workflow summary + +Agents should refine context in this order: + +1. `ktx sl list --json` — discover available sources and connection ids. +2. `ktx sl read --connection-id ` — inspect the current YAML. +3. Edit the source YAML directly or use `ktx sl write`. +4. `ktx sl validate --connection-id ` — verify columns, joins, and table references. +5. `ktx sl query ... --format sql` — compile a representative query without executing it. +6. `ktx wiki search ...` and `ktx wiki write ...` — add business context that does not belong in schema YAML. + ## Semantic Sources Semantic sources are YAML files that describe your tables, columns, measures, and joins. They're the core of the context layer — the structured definitions that agents use to generate correct SQL. @@ -108,6 +119,26 @@ Key fields: | `segments` | No | Named filter conditions | | `inherits_columns_from` | No | Inherit column metadata from a manifest entry | +Source component fields: + +| Component | Field | Required | Description | +|-----------|-------|----------|-------------| +| Column | `name` | Yes | Column identifier as used in SQL expressions | +| Column | `type` | Yes | Agent-facing type: `string`, `number`, `time`, or `boolean` | +| Column | `role` | No | Special role such as `time` for default time dimensions | +| Column | `visibility` | No | `public`, `internal`, or `hidden` | +| Column | `description` | Strongly recommended | Human-readable business meaning | +| Measure | `name` | Yes | Queryable metric name | +| Measure | `expr` | Yes | SQL aggregation expression at the source grain | +| Measure | `filter` | No | SQL predicate applied only to this measure | +| Measure | `description` | Strongly recommended | Definition agents can cite and compare | +| Segment | `name` | Yes | Reusable filter name | +| Segment | `expr` | Yes | SQL predicate for the segment | +| Join | `to` | Yes | Target semantic source name | +| Join | `on` | Yes | SQL join condition using source names or aliases | +| Join | `relationship` | Yes | `many_to_one`, `one_to_many`, or `one_to_one` | +| Join | `alias` | No | Query alias for repeated or clearer joins | + Column visibility controls what agents see: | Visibility | Behavior | @@ -192,6 +223,16 @@ Query flags: The query planner is grain-aware — it understands the cardinality of joins and avoids chasm traps (double-counting caused by many-to-many fan-outs). When you query measures that span multiple sources, KTX generates sub-queries at the correct grain before joining. +### Workflow: edit and validate a source + +1. `ktx sl read orders --connection-id my-postgres > /tmp/orders.yaml` — capture the current definition. +2. Edit `/tmp/orders.yaml` to add columns, measures, joins, or descriptions. +3. `ktx sl write orders --connection-id my-postgres --yaml "$(cat /tmp/orders.yaml)"` — write the updated source. +4. `ktx sl validate orders --connection-id my-postgres` — check the definition against the live schema. +5. `ktx sl query --connection-id my-postgres --measure total_revenue --dimension order_date --format sql` — compile a representative query. + +If validation fails, fix the YAML before asking an agent to use the source. Common validation failures are missing columns, invalid join targets, and measure expressions that reference fields outside the source. + ## Knowledge Pages Knowledge pages are Markdown files that capture business context — definitions, rules, gotchas, and anything an agent needs to understand beyond what the schema tells it. @@ -250,6 +291,18 @@ Write flags: | `--ref ` | Reference to external resources (repeatable) | | `--sl-ref ` | Link to a semantic source (repeatable) | +Knowledge page fields: + +| Field | Required | Description | +|-------|----------|-------------| +| Key | Yes | Stable page identifier passed to `ktx wiki read` | +| Summary | Yes | Short text shown in search results | +| Content | Yes | Full Markdown business context | +| Scope | No | `global` for shared context or `user` for user-scoped notes | +| Tags | No | Search and organization labels | +| External refs | No | Links or identifiers for source-of-truth systems | +| Semantic-layer refs | No | Source names the page explains or constrains | + You can also create and edit knowledge pages directly as Markdown files in the `knowledge/` directory. ### Listing pages @@ -271,3 +324,21 @@ ktx wiki search "revenue recognition" ``` Search uses both full-text matching and semantic similarity — it finds relevant pages even when the exact terms don't match. Agents call this automatically when they need business context to answer a question. + +### Workflow: add searchable business context + +1. Search first: `ktx wiki search "order status definitions"`. +2. If no page already covers the rule, write a page with `ktx wiki write`. +3. Include a concise `--summary`; agents see this before loading full content. +4. Add `--tag` values for the business area and `--sl-ref` values for related semantic sources. +5. Search again with the user's likely wording to confirm the page is discoverable. + +## Common errors + +| Error or symptom | Likely cause | Recovery | +|------------------|--------------|----------| +| `ktx sl validate` reports a missing column | YAML references a column that is absent from the scanned table | Run a fresh scan or update the YAML to match the warehouse schema | +| Query compilation double-counts a measure | Join relationship or grain is missing or wrong | Add `grain` and explicit `relationship` values, then validate and recompile | +| Agent cannot find a metric | Measure name or description does not match business terminology | Add a measure description and a knowledge page with common synonyms | +| Knowledge search misses a page | Summary and tags do not include likely user wording | Rewrite the summary and add relevant tags, then search again | +| `ktx sl write` changes are hard to review | Large YAML was passed inline | Edit the source file directly or write from a temporary file, then review the git diff | diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts index 4e7d024d..59ebbcda 100644 --- a/docs-site/lib/llm-docs.ts +++ b/docs-site/lib/llm-docs.ts @@ -97,5 +97,9 @@ function toLlmDocsPage(page: ReturnType[number]) { } function normalizeMarkdown(markdown: string) { - return markdown.trim().replace(/\n{3,}/g, "\n\n"); + return markdown + .trim() + .replace(/^---\n[\s\S]*?\n---\n?/, "") + .trim() + .replace(/\n{3,}/g, "\n\n"); } From 885072d2a966b8459a76a8fb9bf02db7694cd23a Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:43:08 -0700 Subject: [PATCH 05/12] docs(docs-site): normalize CLI references for agents --- .../content/docs/cli-reference/ktx-agent.mdx | 24 ++++++++++++++++- .../docs/cli-reference/ktx-connection.mdx | 27 ++++++++++++++++++- .../content/docs/cli-reference/ktx-dev.mdx | 21 ++++++++++++++- .../content/docs/cli-reference/ktx-ingest.mdx | 27 ++++++++++++++++++- .../content/docs/cli-reference/ktx-scan.mdx | 26 +++++++++++++++++- .../content/docs/cli-reference/ktx-serve.mdx | 25 ++++++++++++++++- .../content/docs/cli-reference/ktx-setup.mdx | 26 +++++++++++++++++- .../content/docs/cli-reference/ktx-sl.mdx | 27 ++++++++++++++++++- .../content/docs/cli-reference/ktx-status.mdx | 25 ++++++++++++++++- .../content/docs/cli-reference/ktx-wiki.mdx | 27 ++++++++++++++++++- 10 files changed, 245 insertions(+), 10 deletions(-) diff --git a/docs-site/content/docs/cli-reference/ktx-agent.mdx b/docs-site/content/docs/cli-reference/ktx-agent.mdx index 6b60d0d0..cdc4ceac 100644 --- a/docs-site/content/docs/cli-reference/ktx-agent.mdx +++ b/docs-site/content/docs/cli-reference/ktx-agent.mdx @@ -7,7 +7,7 @@ Hidden commands that provide machine-readable JSON output for coding agents. The All `ktx agent` subcommands require `--json` and produce structured JSON output on stdout. -## Usage +## Command signature ```bash ktx agent --json [options] @@ -124,3 +124,25 @@ ktx agent sql execute --json \ --sql-file /tmp/query.sql \ --max-rows 500 ``` + +## Output + +Every `ktx agent` command writes JSON to stdout and diagnostic text to stderr. Agents should parse stdout as JSON and treat a non-zero exit code as a failed tool call. + +```json +{ + "ok": true, + "data": { + "type": "agent-response" + } +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Missing JSON output | `--json` was omitted | Re-run the same subcommand with `--json` | +| Unknown connection id | The requested connection is not configured in `ktx.yaml` | Call `ktx agent context --json` or `ktx connection list` to discover valid ids | +| Query file cannot be read | `--query-file` points to a missing or invalid JSON file | Write the query payload to a real file and pass its absolute path | +| SQL execution rejected | SQL is not read-only or `--max-rows` is missing | Use semantic-layer queries first; for direct SQL, pass read-only SQL and an explicit row limit | diff --git a/docs-site/content/docs/cli-reference/ktx-connection.mdx b/docs-site/content/docs/cli-reference/ktx-connection.mdx index 77458901..31a79736 100644 --- a/docs-site/content/docs/cli-reference/ktx-connection.mdx +++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx @@ -5,7 +5,7 @@ description: "Add, list, test, and map data sources." Manage database and source connections in your KTX project. Connections define how KTX reaches your data warehouse, BI tools, and context sources. -## Usage +## Command signature ```bash ktx connection [options] @@ -147,3 +147,28 @@ ktx connection mapping refresh metabase-prod --auto-accept # Pick Notion root pages interactively ktx connection notion pick my-notion ``` + +## Output + +Interactive commands render prompts and status text. Commands with `--json` return machine-readable JSON suitable for scripts and agents. + +```json +{ + "connections": [ + { + "id": "my-warehouse", + "driver": "postgres", + "readonly": false + } + ] +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx connection add ... --force` | +| Literal credentials rejected | KTX avoids writing raw secrets to `ktx.yaml` by default | Use `env:NAME` or `file:/path/to/secret`; use `--allow-literal-credentials` only for local throwaway projects | +| Mapping validation fails | BI database mappings do not point at valid warehouse connections | Run `ktx connection mapping refresh --auto-accept`, then set invalid mappings explicitly | +| Notion pick cannot run non-interactively | `--no-input` was used without root page or database ids | Pass `--root-page-id`, `--root-database-id`, or `--root-data-source-id` with `--no-input` | diff --git a/docs-site/content/docs/cli-reference/ktx-dev.mdx b/docs-site/content/docs/cli-reference/ktx-dev.mdx index 2187c846..f4d98163 100644 --- a/docs-site/content/docs/cli-reference/ktx-dev.mdx +++ b/docs-site/content/docs/cli-reference/ktx-dev.mdx @@ -5,7 +5,7 @@ description: "Low-level diagnostics, scans, adapter commands, and mapping tools. Hidden commands for low-level project management, diagnostics, direct adapter control, and shell completion. Most users interact with these through higher-level commands like [`ktx ingest`](/docs/cli-reference/ktx-ingest) and [`ktx setup`](/docs/cli-reference/ktx-setup), but `ktx dev` provides direct access when you need fine-grained control. -## Usage +## Command signature ```bash ktx dev [options] @@ -145,3 +145,22 @@ ktx dev completion zsh # Install zsh completions ktx dev completion zsh --install ``` + +## Output + +`ktx dev` commands are diagnostic and may print plain text, JSON, or visual reports depending on the selected flags. + +| Mode | How to request it | Use case | +|------|-------------------|----------| +| Plain text | `--plain` or default diagnostic output | Human-readable terminal inspection | +| JSON | `--json` | Agent parsing and automation | +| Visual report | `--viz` | Interactive memory-flow and ingest debugging | + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Doctor reports missing runtime pieces | Packages, Python environment, or linked CLI are not ready | Run `pnpm install`, `pnpm run setup:dev`, and `uv sync --all-groups` | +| Ingest run cannot find adapter | `--adapter` does not match a supported source adapter | Use configured source names from `ktx.yaml` or run higher-level `ktx ingest` | +| Replay/report file cannot be read | The report path is wrong or the run id is not stored locally | Run `ktx dev ingest status --json` to discover stored run ids and report files | +| Visual output fails in CI | TUI rendering requires an interactive terminal | Use `--plain --no-input` or `--json --no-input` | diff --git a/docs-site/content/docs/cli-reference/ktx-ingest.mdx b/docs-site/content/docs/cli-reference/ktx-ingest.mdx index 82d65e11..8ce9d9a5 100644 --- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx +++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx @@ -5,7 +5,7 @@ description: "Build and refresh context from configured sources." Ingest context from your configured sources — dbt, Looker, Metabase, MetricFlow, LookML, or Notion. The ingest process extracts metadata from your tools, then uses an LLM agent to reconcile it with existing context, writing semantic sources and knowledge pages to your project. -## Usage +## Command signature ```bash ktx ingest [connectionId] [options] @@ -68,3 +68,28 @@ ktx ingest status --json ## Low-level ingest commands For adapter-level control, use `ktx dev ingest`. See [`ktx dev`](/docs/cli-reference/ktx-dev) for the full low-level ingest surface including `run`, `status`, `watch`, and `replay` with output mode options (`--plain`, `--json`, `--viz`). + +## Output + +Ingest run commands print progress and create a stored ingest report. `ktx ingest status --json` returns the run state, adapter, connection, and summary information. + +```json +{ + "runId": "ingest-local-abc123", + "status": "completed", + "connectionId": "dbt-main", + "summary": { + "semanticSourcesChanged": 4, + "knowledgePagesChanged": 2 + } +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| No eligible sources | `ktx.yaml` has no configured context source for ingest | Add a source with `ktx setup` or `ktx connection add`, then rerun ingest | +| Ingest needs credentials | The source adapter requires API or git access | Configure the referenced environment variable or secret file | +| Latest run not found | No ingest run has been started in this project | Run `ktx ingest ` or `ktx ingest --all` first | +| Report watch fails in a non-interactive shell | Visual report needs a terminal | Use `ktx ingest status --json` for agent and CI workflows | diff --git a/docs-site/content/docs/cli-reference/ktx-scan.mdx b/docs-site/content/docs/cli-reference/ktx-scan.mdx index 34ad2190..0c37eccb 100644 --- a/docs-site/content/docs/cli-reference/ktx-scan.mdx +++ b/docs-site/content/docs/cli-reference/ktx-scan.mdx @@ -7,7 +7,7 @@ Discover your database schema — tables, columns, types, constraints, and relat Scan commands live under `ktx dev scan`. See also the [Building Context](/docs/guides/building-context) guide for a walkthrough. -## Usage +## Command signature ```bash ktx dev scan [options] @@ -143,3 +143,27 @@ ktx dev scan relationship-calibration --accept-threshold 0.9 --review-threshold # Get threshold advice based on review decisions ktx dev scan relationship-thresholds ``` + +## Output + +Scan commands write scan artifacts under the KTX project directory and print status or report summaries. Use `--json` on report and relationship commands when an agent needs structured output. + +```json +{ + "runId": "scan-local-abc123", + "status": "completed", + "mode": "structural", + "changes": { + "tablesAdded": 42 + } +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Scan cannot connect | Connection credentials or network access are invalid | Run `ktx connection test ` and update the connection before scanning | +| Enriched scan cannot describe columns | LLM credentials are missing or invalid | Complete LLM setup with `ktx setup` before enriched scans | +| Relationship apply writes nothing | No accepted candidates match the provided run id or candidate ids | Inspect `ktx dev scan relationships --status accepted` first | +| Calibration is not ready | Too few reviewed relationship labels exist | Review and accept/reject more candidates, then rerun calibration | diff --git a/docs-site/content/docs/cli-reference/ktx-serve.mdx b/docs-site/content/docs/cli-reference/ktx-serve.mdx index 0f394b33..ec0d2b28 100644 --- a/docs-site/content/docs/cli-reference/ktx-serve.mdx +++ b/docs-site/content/docs/cli-reference/ktx-serve.mdx @@ -5,7 +5,7 @@ description: "Run the MCP stdio server." Start a Model Context Protocol (MCP) server that exposes your KTX project's context to coding agents. The server runs over stdio and provides tools for querying semantic sources, searching knowledge, managing connections, and running ingests. -## Usage +## Command signature ```bash ktx serve --mcp stdio [options] @@ -49,3 +49,26 @@ ktx serve --mcp stdio --project-dir /path/to/my-project ## Agent integration The MCP server is typically configured through `ktx setup --agents` rather than started manually. See the [Serving Agents](/docs/guides/serving-agents) guide and [Agent Clients](/docs/integrations/agent-clients) integration page for per-tool configuration. + +## Output + +`ktx serve --mcp stdio` communicates through MCP messages on stdio. It is meant to be launched by an agent client, not read directly by a human terminal session. + +```json +{ + "command": "ktx", + "args": ["serve", "--mcp", "stdio", "--semantic-compute", "--execute-queries"], + "env": { + "KTX_PROJECT_DIR": "/home/user/analytics" + } +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Agent cannot start server | The agent config cannot find the `ktx` binary | Run `pnpm run link:dev` or use an absolute command path in the agent config | +| Semantic tools are unavailable | Server was started without `--semantic-compute` | Add `--semantic-compute` or `--semantic-compute-url` to the server args | +| Query execution is denied | Server was started without `--execute-queries` | Add `--execute-queries` only for trusted projects where read-only execution is intended | +| Context resolves to wrong project | `KTX_PROJECT_DIR` is missing or points elsewhere | Set `KTX_PROJECT_DIR` to the project containing the intended `ktx.yaml` | diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx index 943033b5..d09c2f28 100644 --- a/docs-site/content/docs/cli-reference/ktx-setup.mdx +++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx @@ -5,7 +5,7 @@ description: "Set up or resume a local KTX project." Interactive wizard that walks you through configuring LLM credentials, embeddings, database connections, context sources, and agent integrations. When run without flags in a directory that has no `ktx.yaml`, it launches the full guided flow. When run in an existing project, it resumes from the first incomplete step. -## Usage +## Command signature ```bash ktx setup [options] @@ -173,3 +173,27 @@ ktx setup context watch # Run the packaged demo ktx setup demo ``` + +## Output + +Interactive setup renders prompts and progress messages. `ktx setup status` is the best command for agents because it summarizes readiness in one response. + +```text +KTX project: /home/user/analytics +Project ready: yes +LLM ready: yes (claude-sonnet-4-6) +Embeddings ready: yes (text-embedding-3-small) +Primary sources configured: yes (postgres-warehouse) +Context sources configured: yes (dbt-main) +KTX context built: yes +Agent integration ready: yes (codex:project) +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Setup resumes an unexpected project | `KTX_PROJECT_DIR` or nearest `ktx.yaml` points to another directory | Pass `--project-dir ` explicitly | +| Health check for model fails | Provider key or model id is invalid | Set the correct environment variable or secret file and rerun setup | +| Setup cannot run in CI | Interactive prompts need a TTY | Use `--yes --no-input` with explicit flags for required values | +| Agent integration missing | Setup skipped the agents step | Run `ktx setup --agents --target --agent-install-mode both` | diff --git a/docs-site/content/docs/cli-reference/ktx-sl.mdx b/docs-site/content/docs/cli-reference/ktx-sl.mdx index 8fccf3a2..4ec7bdd1 100644 --- a/docs-site/content/docs/cli-reference/ktx-sl.mdx +++ b/docs-site/content/docs/cli-reference/ktx-sl.mdx @@ -5,7 +5,7 @@ description: "List, read, validate, query, or write semantic-layer sources." Interact with your project's semantic layer. Semantic sources are YAML definitions that describe your tables, columns, measures, joins, and grain — the vocabulary agents use to generate correct SQL. -## Usage +## Command signature ```bash ktx sl [options] @@ -120,3 +120,28 @@ ktx sl query \ --execute \ --max-rows 1000 ``` + +## Output + +Semantic-layer commands return human-readable output by default. Use `--json` or `--format json` when an agent needs structured output; use `--format sql` to inspect generated SQL before execution. + +```json +{ + "sql": "SELECT orders.status, SUM(orders.total_amount) AS total_revenue FROM public.orders GROUP BY orders.status", + "rows": [ + { + "orders.status": "completed", + "total_revenue": 125000 + } + ] +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Source not found | Source name or connection id is wrong | Run `ktx sl list --json` and retry with an exact source name and connection id | +| Validation fails | YAML references missing columns, invalid joins, or invalid SQL expressions | Fix the source YAML and rerun `ktx sl validate` | +| Query compile fails | Measure, dimension, filter, or segment name is invalid | Read the source with `ktx sl read`, then retry using declared fields | +| Execution returns too many rows | `--max-rows` is missing or too high | Add `--max-rows` with a bounded value before executing | diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index 2b1e8f34..31a7d113 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -5,7 +5,7 @@ description: "Show current project status." Print the current setup status of your KTX project — which steps are complete, which need attention, and whether the project is ready for agents. -## Usage +## Command signature ```bash ktx status [options] @@ -26,3 +26,26 @@ ktx status # Get status as JSON (useful for scripting) ktx status --json ``` + +## Output + +`ktx status` prints readiness for each setup area. Agents should use `ktx status --json` when they need to branch on readiness state. + +```json +{ + "projectReady": true, + "llmReady": true, + "embeddingsReady": true, + "primarySourcesConfigured": true, + "contextBuilt": true, + "agentIntegrationReady": true +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or set `KTX_PROJECT_DIR` | +| Project ready is false | One or more setup steps are incomplete | Run `ktx setup` to resume setup | +| Agent integration ready is false | No agent target has been installed | Run `ktx setup --agents --target ` | diff --git a/docs-site/content/docs/cli-reference/ktx-wiki.mdx b/docs-site/content/docs/cli-reference/ktx-wiki.mdx index d2376e51..a709ac07 100644 --- a/docs-site/content/docs/cli-reference/ktx-wiki.mdx +++ b/docs-site/content/docs/cli-reference/ktx-wiki.mdx @@ -5,7 +5,7 @@ description: "List, read, search, or write knowledge pages." Manage knowledge pages in your KTX project. Knowledge pages are Markdown documents that capture business definitions, rules, and gotchas. Agents search them for context when answering questions about your data. -## Usage +## Command signature ```bash ktx wiki [options] @@ -90,3 +90,28 @@ ktx wiki write data-freshness \ --content "The orders table refreshes every 15 minutes..." \ --ref "https://wiki.example.com/data-pipelines" ``` + +## Output + +Wiki commands print local knowledge pages and search results. Agents should search first, then read the most relevant page by key. + +```json +{ + "results": [ + { + "key": "revenue-definitions", + "summary": "Canonical revenue metric definitions", + "score": 0.92 + } + ] +} +``` + +## Common errors + +| Error | Cause | Recovery | +|-------|-------|----------| +| Search returns no results | The query terms do not match summaries, tags, or content | Retry with business synonyms, then create a page if the knowledge is missing | +| Read fails for a key | The page key is wrong or scoped to a different user | Run `ktx wiki list` or search again to get the exact key | +| Write fails due to missing fields | `--summary` or `--content` was omitted | Pass both fields, and keep the summary short enough for search results | +| Agent writes duplicate pages | It did not search existing pages first | Always run `ktx wiki search` before `ktx wiki write` | From f3f8aa613b9aac35b87ef34b9f6784e493132363 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:44:31 -0700 Subject: [PATCH 06/12] docs(docs-site): add agent notes across docs --- .../docs/benchmarks/link-detection.mdx | 11 +++++++ .../content/docs/community/contributing.mdx | 14 ++++++++ .../content/docs/concepts/context-as-code.mdx | 11 +++++++ .../docs/concepts/the-context-layer.mdx | 11 +++++++ .../docs/getting-started/introduction.mdx | 13 ++++++++ .../docs/integrations/agent-clients.mdx | 29 ++++++++++++++++ .../docs/integrations/context-sources.mdx | 33 +++++++++++++++++++ .../docs/integrations/primary-sources.mdx | 24 ++++++++++++++ 8 files changed, 146 insertions(+) diff --git a/docs-site/content/docs/benchmarks/link-detection.mdx b/docs-site/content/docs/benchmarks/link-detection.mdx index 142cc197..feb2f3f1 100644 --- a/docs-site/content/docs/benchmarks/link-detection.mdx +++ b/docs-site/content/docs/benchmarks/link-detection.mdx @@ -5,6 +5,17 @@ description: How KTX's relationship detection performs on real-world schemas. KTX infers foreign key relationships between tables even when the database declares no primary keys or foreign key constraints. This is critical for analytics warehouses, where constraints are rarely enforced. This page documents the methodology, scoring pipeline, and a reproducible benchmark you can run yourself. +## Agent usage notes + +Use this page when an agent needs to explain, tune, or verify relationship detection. + +| Agent task | Relevant section | Command | +|------------|------------------|---------| +| Explain why KTX inferred a join | Detection pipeline | `ktx dev scan relationships --status all` | +| Decide whether to accept or reject a candidate | Scoring and threshold configuration | `ktx dev scan relationships --accept ` | +| Tune thresholds from reviewed decisions | Broader benchmark suite and calibration | `ktx dev scan relationship-thresholds --connection ` | +| Reproduce the bundled benchmark | Reproducing the benchmark | `pnpm run relationships:verify-orbit` | + ## What this measures Most analytics warehouses — Snowflake, BigQuery, Redshift — don't enforce referential integrity constraints. Tables like `fct_product_events` reference `dim_accounts` by convention (`account_id` → `id`), but nothing in the schema says so. diff --git a/docs-site/content/docs/community/contributing.mdx b/docs-site/content/docs/community/contributing.mdx index 598ac5a9..8feb86c9 100644 --- a/docs-site/content/docs/community/contributing.mdx +++ b/docs-site/content/docs/community/contributing.mdx @@ -220,3 +220,17 @@ Before submitting a pull request: 5. **Don't commit artifacts** — `node_modules/`, `.venv/`, `dist/`, coverage output, and local databases should not be committed. For larger features or architectural changes, open an issue first to discuss the approach. + +## Agent usage notes + +Use this page when an agent is modifying the KTX repository itself rather than using KTX in an analytics project. + +| Agent task | Command or section | +|------------|--------------------| +| Prepare the workspace | `pnpm install`, `pnpm run setup:dev`, `uv sync --all-groups` | +| Verify TypeScript changes | `pnpm run type-check`, `pnpm run test`, or package-filtered equivalents | +| Verify Python changes | `uv run pytest -q` and `uv run pre-commit run --files ` | +| Add a connector | Adding a connector | +| Check style expectations | Code conventions | + +Common recovery path: if a check fails because generated files or local runtimes are missing, run the setup commands first. If a check fails because of a real type, lint, or test error, fix the source file and rerun the smallest failing check before broadening verification. diff --git a/docs-site/content/docs/concepts/context-as-code.mdx b/docs-site/content/docs/concepts/context-as-code.mdx index 152b54ce..4ee25d88 100644 --- a/docs-site/content/docs/concepts/context-as-code.mdx +++ b/docs-site/content/docs/concepts/context-as-code.mdx @@ -80,3 +80,14 @@ This matters for three reasons. **Reproducibility.** Because ingestion sessions are recorded as structured transcripts (tool calls and responses, not just logs), they can be replayed for testing and validation. If you change your ingestion configuration or upgrade the LLM, you can replay previous sessions to see how the output would differ. This gives you a safety net for changes that affect how context is generated. The transcript is stored with local ingest run state and can be reviewed or replayed when you need to audit a decision. Commit the resulting YAML and Markdown changes; commit reports or transcripts only when they are part of your team's review workflow. + +## Agent usage notes + +Use this page when an agent needs to explain review workflows, ingestion diffs, replayability, or why KTX writes YAML and Markdown instead of hiding context in a hosted service. + +| Agent task | Relevant section | Next page | +|------------|------------------|-----------| +| Explain how generated context should be reviewed | The git workflow | [Building Context](/docs/guides/building-context) | +| Diagnose why ingestion changed a semantic source | Auto-ingestion and Deterministic replay | [ktx ingest](/docs/cli-reference/ktx-ingest) | +| Explain how context improves over time | Feedback loops | [Link Detection](/docs/benchmarks/link-detection) | +| Tell a user what to commit | The git workflow | [Writing Context](/docs/guides/writing-context) | diff --git a/docs-site/content/docs/concepts/the-context-layer.mdx b/docs-site/content/docs/concepts/the-context-layer.mdx index 3a3ab9b4..64a17730 100644 --- a/docs-site/content/docs/concepts/the-context-layer.mdx +++ b/docs-site/content/docs/concepts/the-context-layer.mdx @@ -145,3 +145,14 @@ my-project/ Semantic sources and knowledge pages are committed to git. The SQLite database holds ephemeral state — scan results, embedding indexes, session logs — and is git-ignored. If you delete it, KTX rebuilds it on the next run. This means your analytics context travels with your code. You can fork it, branch it, review it in a PR, and merge it with the same tools you use for dbt models. There's no sync problem between a remote server and your local state. There's no migration to run. The files are the source of truth. + +## Agent usage notes + +Use this page when an agent needs to explain why KTX exists, why schema-only database access is not enough, or how KTX differs from MetricFlow, Cube, Malloy, and traditional semantic layers. + +| Agent task | Relevant section | Next page | +|------------|------------------|-----------| +| Explain why a database agent made a plausible but wrong query | The problem | [Writing Context](/docs/guides/writing-context) | +| Decide whether a metric belongs in YAML or Markdown | What a context layer is | [Writing Context](/docs/guides/writing-context) | +| Compare KTX to another semantic layer | How KTX compares | [Primary Sources](/docs/integrations/primary-sources) | +| Explain reviewability and source of truth | The plain-files philosophy | [Context as Code](/docs/concepts/context-as-code) | diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 827cdff5..e074f021 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -57,3 +57,16 @@ If you've ever watched an agent confidently generate a query that joins on the w - **Get hands-on** — follow the [Quickstart](/docs/getting-started/quickstart) to set up KTX with your own database in under 10 minutes. - **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 + +Use this page as the high-level routing document for KTX docs. + +| Agent task | Read next | +|------------|-----------| +| 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) | +| Look up exact command flags | [CLI Reference](/docs/cli-reference/ktx-setup) | diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx index 088dbba4..75a06cb1 100644 --- a/docs-site/content/docs/integrations/agent-clients.mdx +++ b/docs-site/content/docs/integrations/agent-clients.mdx @@ -10,6 +10,25 @@ KTX integrates with coding agents through two channels that can be used independ 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` @@ -277,3 +296,13 @@ 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/content/docs/integrations/context-sources.mdx b/docs-site/content/docs/integrations/context-sources.mdx index 49f387f3..02554e08 100644 --- a/docs-site/content/docs/integrations/context-sources.mdx +++ b/docs-site/content/docs/integrations/context-sources.mdx @@ -7,6 +7,29 @@ Context sources feed your existing analytics tooling into KTX. During ingestion, All context sources are configured in `ktx.yaml` under `connections` with their respective `driver` value. +## Ingestion workflow + +Agents should configure and ingest context sources in this order: + +1. Add the context source connection in `ktx.yaml` or with `ktx setup`. +2. Store tokens as `env:NAME` or `file:/path/to/secret`. +3. Run `ktx ingest ` for one source or `ktx ingest --all`. +4. Check progress with `ktx ingest status --json`. +5. Review generated `semantic-layer/` YAML and `knowledge/` Markdown files in git. +6. Validate changed semantic sources with `ktx sl validate`. + +## Shared source fields + +| Field | Required | Description | +|-------|----------|-------------| +| `driver` | Yes | Source adapter: `dbt`, `metricflow`, `lookml`, `metabase`, `looker`, or `notion` | +| `readonly` | Strongly recommended | Marks the source as read-only for KTX | +| `source_dir` | For local file sources | Absolute or project-relative source directory | +| `repo_url` | For Git-hosted sources | Git repository URL | +| `branch` | No | Git branch to read | +| `path` | No | Subdirectory inside a monorepo | +| `auth_token_ref` | For private APIs/repos | `env:NAME` or `file:/path/to/secret` token reference | + ## dbt Ingests schema definitions, model descriptions, column metadata, and test coverage from a dbt project. @@ -351,3 +374,13 @@ Create an integration at [notion.so/my-integrations](https://www.notion.so/my-in - Notion is knowledge-only — it does not produce semantic layer sources - Rate limits apply; large workspaces may require multiple ingestion runs - `last_successful_cursor` is auto-managed for incremental sync + +## Common errors + +| Error or symptom | Likely cause | Recovery | +|------------------|--------------|----------| +| Adapter cannot read source files | `source_dir`, `repo_url`, `branch`, or `path` is wrong | Verify the path locally or clone the repo manually with the same credentials | +| Private repo/API authentication fails | Token env var or secret file is missing | Export the env var or update `auth_token_ref` to a readable file | +| Ingest creates duplicate context | Existing source names or knowledge pages do not match imported terminology | Review the diff, rename duplicates, and add knowledge pages with canonical names | +| Notion ingest skips pages | Integration lacks access or root ids are missing | Share pages with the Notion integration and set `root_page_ids` or use `all_accessible` carefully | +| Generated semantic sources fail validation | Tool metadata does not match the live warehouse schema | Map BI/source databases to primary warehouse connections and rerun validation | diff --git a/docs-site/content/docs/integrations/primary-sources.mdx b/docs-site/content/docs/integrations/primary-sources.mdx index be71cba0..c36260d1 100644 --- a/docs-site/content/docs/integrations/primary-sources.mdx +++ b/docs-site/content/docs/integrations/primary-sources.mdx @@ -11,6 +11,20 @@ All connectors share these conventions: - Connections are read-only — KTX never writes to your database - Schema scanning discovers tables, columns, types, and constraints automatically +## Connection field reference + +Agents should prefer environment or file references over literal secrets. + +| Field | Required | Applies to | Description | +|-------|----------|------------|-------------| +| `driver` | Yes | all connections | Connector driver such as `postgres`, `snowflake`, `bigquery`, `clickhouse`, `mysql`, `sqlserver`, or `sqlite` | +| `url` | One of the connection methods | URL-style connectors | Database URL, `env:NAME`, or `file:/path/to/secret` | +| `host`, `port`, `database`, `username`, `password` | One of the connection methods | PostgreSQL, MySQL, ClickHouse, SQL Server | Field-by-field connection values | +| `schema` or `schemas` | No | schema-aware warehouses | Single schema or list of schemas to scan | +| `readonly` | Strongly recommended | all primary sources | Marks the connection as read-only in KTX config | +| `historicSql` | No | supported warehouses | Enables query-history ingestion when the warehouse supports it | +| `path` | Yes for path-style SQLite | SQLite | Local SQLite database path or `env:NAME` reference | + ## PostgreSQL The most full-featured connector. Supports schema introspection, foreign key detection, column statistics, and historic SQL via `pg_stat_statements`. @@ -488,3 +502,13 @@ No authentication required — SQLite is file-based. The file must be readable b - SQLite type affinity system: `TEXT`, `NUMERIC`, `INTEGER`, `REAL`, `BLOB` - Foreign key enforcement requires explicit `PRAGMA foreign_keys = ON` - In-memory databases supported with `path: ":memory:"` (for testing) + +## Common errors + +| Error or symptom | Likely cause | Recovery | +|------------------|--------------|----------| +| Connection URL appears in git diff | A literal credential URL was written to `ktx.yaml` | Replace it with `env:NAME` or `file:/path/to/secret` and rotate exposed credentials | +| Scan returns no tables | Schema/database/project filter is wrong or the user lacks metadata permissions | Verify the schema list and grant metadata read permissions | +| Historic SQL is empty | Query history extension or warehouse history view is unavailable | Enable the warehouse-specific history feature, then rerun scan or setup | +| Column statistics are missing | Connector cannot access stats tables or the warehouse does not expose them | Grant stats permissions where supported; otherwise rely on structural scan output | +| SQL execution fails through agents | Connection is missing, unreachable, or execution is disabled in the server | Run `ktx connection test ` and check `ktx serve` flags | From 838cf84649220a6dcbaef73df497bbe207a9cea3 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:45:44 -0700 Subject: [PATCH 07/12] fix(docs-site): return explicit markdown route 404 --- docs-site/app/llms.mdx/docs/[[...slug]]/route.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts b/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts index e4cd9e4a..1372d556 100644 --- a/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts +++ b/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts @@ -3,7 +3,6 @@ import { getLlmDocsPages, getPageMarkdown, } from "@/lib/llm-docs"; -import { notFound } from "next/navigation"; export const dynamic = "force-static"; @@ -13,7 +12,14 @@ export async function GET( ) { const params = await props.params; const page = getLlmDocsPage(params.slug); - if (!page) notFound(); + if (!page) { + return new Response("Documentation page not found.\n", { + status: 404, + headers: { + "Content-Type": "text/plain; charset=utf-8", + }, + }); + } return new Response(await getPageMarkdown(page), { headers: { From 81c7e60fefa2ed474d85cd4e2ee8ad6bc58f0d56 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 16:54:56 -0700 Subject: [PATCH 08/12] fix(docs-site): reset code block prose styles --- docs-site/app/global.css | 18 ++++++++++++++++++ docs-site/components/code-block.tsx | 6 +++--- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/docs-site/app/global.css b/docs-site/app/global.css index d9570d79..b1e3a4e9 100644 --- a/docs-site/app/global.css +++ b/docs-site/app/global.css @@ -188,6 +188,24 @@ pre { border-radius: 0 !important; } +.ktx-code code { + display: grid; + min-width: max-content; + padding: 0 !important; + border: 0 !important; + border-radius: 0 !important; + background: transparent !important; + font-size: inherit !important; + line-height: inherit !important; + color: inherit; +} + +.ktx-code .line { + display: block; + min-height: 1.7em; + padding-inline: 0 !important; +} + /* Neutralize the outer figure styling that our wrapper now owns */ figure:has(> .ktx-code), figure[data-rehype-pretty-code-figure]:has(.ktx-code) { diff --git a/docs-site/components/code-block.tsx b/docs-site/components/code-block.tsx index 37c7a44e..d8045a5c 100644 --- a/docs-site/components/code-block.tsx +++ b/docs-site/components/code-block.tsx @@ -60,7 +60,7 @@ export function CodeBlock(props: Props) { // Mode A — Terminal if (isTerminal) { return ( -
+
@@ -83,7 +83,7 @@ export function CodeBlock(props: Props) { // Mode B — VS Code tab (filename present) if (hasTitle) { return ( -
+
{title} @@ -99,7 +99,7 @@ export function CodeBlock(props: Props) { // Mode C — Minimal default return ( -
+
{language && {language}} 

From 966627a68be0fb168e0c01a568d8ca27af56e146 Mon Sep 17 00:00:00 2001
From: Luca Martial 
Date: Mon, 11 May 2026 17:20:11 -0700
Subject: [PATCH 09/12] docs(docs-site): add AI resources for agents

---
 .../docs/ai-resources/agent-quickstart.mdx    | 72 +++++++++++++++++++
 docs-site/content/docs/ai-resources/index.mdx | 46 ++++++++++++
 .../content/docs/ai-resources/ktx-skills.mdx  | 66 +++++++++++++++++
 .../docs/ai-resources/markdown-access.mdx     | 67 +++++++++++++++++
 .../docs/ai-resources/mcp-boundaries.mdx      | 62 ++++++++++++++++
 docs-site/content/docs/ai-resources/meta.json | 12 ++++
 .../docs/ai-resources/prompt-recipes.mdx      | 60 ++++++++++++++++
 .../docs/getting-started/introduction.mdx     |  8 ++-
 .../docs/getting-started/quickstart.mdx       |  2 +
 .../content/docs/guides/serving-agents.mdx    |  2 +
 .../docs/integrations/agent-clients.mdx       |  2 +
 docs-site/content/docs/meta.json              |  1 +
 docs-site/lib/llm-docs.ts                     | 68 ++++++++++++++++--
 13 files changed, 461 insertions(+), 7 deletions(-)
 create mode 100644 docs-site/content/docs/ai-resources/agent-quickstart.mdx
 create mode 100644 docs-site/content/docs/ai-resources/index.mdx
 create mode 100644 docs-site/content/docs/ai-resources/ktx-skills.mdx
 create mode 100644 docs-site/content/docs/ai-resources/markdown-access.mdx
 create mode 100644 docs-site/content/docs/ai-resources/mcp-boundaries.mdx
 create mode 100644 docs-site/content/docs/ai-resources/meta.json
 create mode 100644 docs-site/content/docs/ai-resources/prompt-recipes.mdx

diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx
new file mode 100644
index 00000000..4ca39a1d
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx
@@ -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.
diff --git a/docs-site/content/docs/ai-resources/index.mdx b/docs-site/content/docs/ai-resources/index.mdx
new file mode 100644
index 00000000..034b46a5
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/index.mdx
@@ -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/.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.
diff --git a/docs-site/content/docs/ai-resources/ktx-skills.mdx b/docs-site/content/docs/ai-resources/ktx-skills.mdx
new file mode 100644
index 00000000..aa9d5048
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/ktx-skills.mdx
@@ -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).
diff --git a/docs-site/content/docs/ai-resources/markdown-access.mdx b/docs-site/content/docs/ai-resources/markdown-access.mdx
new file mode 100644
index 00000000..983733f3
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/markdown-access.mdx
@@ -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 |
diff --git a/docs-site/content/docs/ai-resources/mcp-boundaries.mdx b/docs-site/content/docs/ai-resources/mcp-boundaries.mdx
new file mode 100644
index 00000000..a0b8d7ac
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/mcp-boundaries.mdx
@@ -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/.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
new file mode 100644
index 00000000..3a570808
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/meta.json
@@ -0,0 +1,12 @@
+{
+  "title": "AI Resources",
+  "defaultOpen": true,
+  "pages": [
+    "index",
+    "agent-quickstart",
+    "markdown-access",
+    "ktx-skills",
+    "prompt-recipes",
+    "mcp-boundaries"
+  ]
+}
diff --git a/docs-site/content/docs/ai-resources/prompt-recipes.mdx b/docs-site/content/docs/ai-resources/prompt-recipes.mdx
new file mode 100644
index 00000000..efed2282
--- /dev/null
+++ b/docs-site/content/docs/ai-resources/prompt-recipes.mdx
@@ -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: . 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 . 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.
+```
diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx
index e074f021..537e4d23 100644
--- a/docs-site/content/docs/getting-started/introduction.mdx
+++ b/docs-site/content/docs/getting-started/introduction.mdx
@@ -39,6 +39,9 @@ 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.
+  
   
     Understand what a context layer is, why agents need one, and how KTX compares to other semantic layers.
   
@@ -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) |
diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 1913c925..c6a56d54 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -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:
diff --git a/docs-site/content/docs/guides/serving-agents.mdx b/docs-site/content/docs/guides/serving-agents.mdx
index 78cb75a1..99ad1203 100644
--- a/docs-site/content/docs/guides/serving-agents.mdx
+++ b/docs-site/content/docs/guides/serving-agents.mdx
@@ -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:
diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx
index 75a06cb1..5647162f 100644
--- a/docs-site/content/docs/integrations/agent-clients.mdx
+++ b/docs-site/content/docs/integrations/agent-clients.mdx
@@ -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
diff --git a/docs-site/content/docs/meta.json b/docs-site/content/docs/meta.json
index 816b18d6..4b683d67 100644
--- a/docs-site/content/docs/meta.json
+++ b/docs-site/content/docs/meta.json
@@ -3,6 +3,7 @@
   "title": "KTX",
   "pages": [
     "getting-started",
+    "ai-resources",
     "concepts",
     "guides",
     "integrations",
diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts
index 59ebbcda..fd0bbf40 100644
--- a/docs-site/lib/llm-docs.ts
+++ b/docs-site/lib/llm-docs.ts
@@ -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();
+
+  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 = {
+    "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(" ");
+}

From f1909b47c69f4898b85f2af05ef2bcbb15782290 Mon Sep 17 00:00:00 2001
From: Luca Martial 
Date: Mon, 11 May 2026 19:35:46 -0700
Subject: [PATCH 10/12] docs(docs-site): separate docs-agent resources

---
 docs-site/app/docs/[[...slug]]/page.tsx       |   5 +
 docs-site/components/docs-page-actions.tsx    | 110 ++++++++++++++++++
 .../docs/ai-resources/agent-instructions.mdx  |  40 +++++++
 .../docs/ai-resources/agent-quickstart.mdx    |  68 ++++-------
 docs-site/content/docs/ai-resources/index.mdx |  20 +---
 .../content/docs/ai-resources/ktx-skills.mdx  |  66 -----------
 .../docs/ai-resources/markdown-access.mdx     |  12 +-
 .../docs/ai-resources/mcp-boundaries.mdx      |  62 ----------
 docs-site/content/docs/ai-resources/meta.json |   5 +-
 .../docs/ai-resources/prompt-recipes.mdx      |  24 ++--
 .../docs/getting-started/introduction.mdx     |   3 +-
 .../docs/getting-started/quickstart.mdx       |   2 +-
 .../content/docs/guides/serving-agents.mdx    |  77 ------------
 .../docs/integrations/agent-clients.mdx       |  31 -----
 docs-site/lib/llm-docs.ts                     |  10 +-
 15 files changed, 209 insertions(+), 326 deletions(-)
 create mode 100644 docs-site/components/docs-page-actions.tsx
 create mode 100644 docs-site/content/docs/ai-resources/agent-instructions.mdx
 delete mode 100644 docs-site/content/docs/ai-resources/ktx-skills.mdx
 delete mode 100644 docs-site/content/docs/ai-resources/mcp-boundaries.mdx

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 (
+    
+  );
+}
+
+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")}

From e79caa8fb991e8697b8b77a5f99637c74f9d09f9 Mon Sep 17 00:00:00 2001
From: Luca Martial 
Date: Mon, 11 May 2026 20:03:53 -0700
Subject: [PATCH 11/12] docs(docs-site): update AI resource URLs and nav order

---
 .../docs/ai-resources/agent-instructions.mdx  |  6 ++---
 .../docs/ai-resources/agent-quickstart.mdx    |  4 ++--
 .../docs/ai-resources/markdown-access.mdx     | 12 +++++-----
 .../docs/ai-resources/prompt-recipes.mdx      |  2 +-
 docs-site/content/docs/meta.json              |  2 +-
 docs-site/lib/llm-docs.ts                     | 22 +++++++++++--------
 6 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/docs-site/content/docs/ai-resources/agent-instructions.mdx b/docs-site/content/docs/ai-resources/agent-instructions.mdx
index 56a10c21..67efa21c 100644
--- a/docs-site/content/docs/ai-resources/agent-instructions.mdx
+++ b/docs-site/content/docs/ai-resources/agent-instructions.mdx
@@ -8,10 +8,10 @@ Use these instructions when a coding assistant needs to answer questions from th
 ```text
 When answering KTX docs questions:
 
-1. Start with https://ktx.dev/llms.txt.
+1. Start with https://docs.kaelio.com/ktx/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.
+4. Use https://docs.kaelio.com/ktx/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.
 ```
@@ -30,7 +30,7 @@ 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.
+You are helping with KTX. Read https://docs.kaelio.com/ktx/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
diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx
index 81bc3060..40983224 100644
--- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx
+++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx
@@ -37,8 +37,8 @@ Use this workflow when the user asks an assistant to answer a KTX docs question:
 ## Docs lookup from a shell
 
 ```bash
-curl https://ktx.dev/llms.txt
-curl https://ktx.dev/docs/getting-started/quickstart.md
+curl https://docs.kaelio.com/ktx/llms.txt
+curl https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md
 ```
 
 ## Guardrails
diff --git a/docs-site/content/docs/ai-resources/markdown-access.mdx b/docs-site/content/docs/ai-resources/markdown-access.mdx
index cb83c70f..c363a215 100644
--- a/docs-site/content/docs/ai-resources/markdown-access.mdx
+++ b/docs-site/content/docs/ai-resources/markdown-access.mdx
@@ -10,7 +10,7 @@ KTX docs are available as plain Markdown so assistants do not need to parse the
 Fetch the curated index:
 
 ```text
-https://ktx.dev/llms.txt
+https://docs.kaelio.com/ktx/llms.txt
 ```
 
 Use this file to discover high-value pages, task-specific entry points, and Markdown URLs.
@@ -20,7 +20,7 @@ Use this file to discover high-value pages, task-specific entry points, and Mark
 Fetch the complete docs corpus:
 
 ```text
-https://ktx.dev/llms-full.txt
+https://docs.kaelio.com/ktx/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.
@@ -30,15 +30,15 @@ Use this when an assistant needs broad context across setup, concepts, CLI refer
 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/building-context.md
+https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md
+https://docs.kaelio.com/ktx/docs/cli-reference/ktx-agent.md
+https://docs.kaelio.com/ktx/docs/guides/building-context.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
+curl -H "Accept: text/markdown" https://docs.kaelio.com/ktx/docs/getting-started/quickstart
 ```
 
 ## Recommended retrieval order
diff --git a/docs-site/content/docs/ai-resources/prompt-recipes.mdx b/docs-site/content/docs/ai-resources/prompt-recipes.mdx
index c25da2b4..35f8a4ae 100644
--- a/docs-site/content/docs/ai-resources/prompt-recipes.mdx
+++ b/docs-site/content/docs/ai-resources/prompt-recipes.mdx
@@ -8,7 +8,7 @@ Use these prompts when asking a coding assistant to work with KTX. Replace proje
 ## 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.
+Read https://docs.kaelio.com/ktx/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
diff --git a/docs-site/content/docs/meta.json b/docs-site/content/docs/meta.json
index 4b683d67..93dc227f 100644
--- a/docs-site/content/docs/meta.json
+++ b/docs-site/content/docs/meta.json
@@ -3,12 +3,12 @@
   "title": "KTX",
   "pages": [
     "getting-started",
-    "ai-resources",
     "concepts",
     "guides",
     "integrations",
     "benchmarks",
     "cli-reference",
+    "ai-resources",
     "community"
   ]
 }
diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts
index 8bc39008..9d9b5c74 100644
--- a/docs-site/lib/llm-docs.ts
+++ b/docs-site/lib/llm-docs.ts
@@ -1,6 +1,6 @@
 import { source } from "@/lib/source";
 
-const siteOrigin = "https://ktx.dev";
+const siteOrigin = "https://docs.kaelio.com/ktx";
 
 export type LlmDocsPage = {
   title: string;
@@ -26,8 +26,8 @@ export async function getPageMarkdown(page: LlmDocsPage) {
 
   return normalizeMarkdown(`# ${page.title}${description}
 
-Canonical URL: ${page.url}
-Markdown URL: ${page.markdownUrl}
+Canonical URL: ${absoluteUrl(page.url)}
+Markdown URL: ${absoluteUrl(page.markdownUrl)}
 
 ${body}
 `);
@@ -40,7 +40,7 @@ export function buildLlmsTxt() {
     const page = byUrl.get(url);
     const description = page?.description ?? fallbackDescription;
     const markdownUrl = page?.markdownUrl ?? `${url}.md`;
-    return `- [${label}](${markdownUrl}): ${description}`;
+    return `- [${label}](${absoluteUrl(markdownUrl)}): ${description}`;
   };
 
   return `# KTX
@@ -64,10 +64,10 @@ ${link("/docs/guides/writing-context", "Writing Context", "Write semantic source
 
 ## Machine-Readable Documentation
 
-- [Full documentation](/llms-full.txt): All docs pages in one plain-text markdown response
-- [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
+- [Full documentation](${absoluteUrl("/llms-full.txt")}): All docs pages in one plain-text markdown response
+- [Markdown access guide](${absoluteUrl("/docs/ai-resources/markdown-access.md")}): How to fetch llms.txt, llms-full.txt, and per-page Markdown
+- [Quickstart markdown](${absoluteUrl("/docs/getting-started/quickstart.md")}): Human setup walkthrough
+- [Agent CLI markdown](${absoluteUrl("/docs/cli-reference/ktx-agent.md")}): Machine-readable agent commands
 
 ## CLI Reference
 
@@ -127,7 +127,7 @@ function buildPageIndex(pages: LlmDocsPage[]) {
       const links = categoryPages
         .map((page) => {
           const description = page.description ? `: ${page.description}` : "";
-          return `- [${page.title}](${page.markdownUrl})${description}`;
+          return `- [${page.title}](${absoluteUrl(page.markdownUrl)})${description}`;
         })
         .join("\n");
 
@@ -138,6 +138,10 @@ ${links}`;
     .join("\n\n");
 }
 
+function absoluteUrl(path: string) {
+  return `${siteOrigin}${path}`;
+}
+
 function formatCategoryName(category: string) {
   const labels: Record = {
     "ai-resources": "AI Resources",

From b4a302edfaa035ed60664e849e8a7d8488e7a659 Mon Sep 17 00:00:00 2001
From: Luca Martial 
Date: Mon, 11 May 2026 20:37:28 -0700
Subject: [PATCH 12/12] fix(docs-site): add docs index redirect, test, and trim
 Accept media type

Redirect bare /docs to the introduction page with proper metadata
resolution. Add a test for the redirect. Trim the media type in the
Accept header parser so whitespace around semicolons does not break
markdown content negotiation. Add a test script to package.json.

Co-Authored-By: Claude Opus 4.6 (1M context) 
---
 docs-site/app/docs/[[...slug]]/page.tsx   | 19 ++++++++++++++++---
 docs-site/middleware.ts                   |  2 +-
 docs-site/package.json                    |  3 ++-
 docs-site/tests/docs-index-route.test.mjs | 14 ++++++++++++++
 4 files changed, 33 insertions(+), 5 deletions(-)
 create mode 100644 docs-site/tests/docs-index-route.test.mjs

diff --git a/docs-site/app/docs/[[...slug]]/page.tsx b/docs-site/app/docs/[[...slug]]/page.tsx
index 0b59743d..869454ec 100644
--- a/docs-site/app/docs/[[...slug]]/page.tsx
+++ b/docs-site/app/docs/[[...slug]]/page.tsx
@@ -5,15 +5,26 @@ import {
   DocsTitle,
   DocsDescription,
 } from "fumadocs-ui/page";
-import { notFound } from "next/navigation";
+import { notFound, redirect } from "next/navigation";
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import { CodeBlock } from "@/components/code-block";
 import { DocsPageActions } from "@/components/docs-page-actions";
 
+const docsIndexPath = "/docs/getting-started/introduction";
+const docsIndexSlug = ["getting-started", "introduction"] as const;
+
+function isDocsIndex(slug: string[] | undefined) {
+  return slug === undefined || slug.length === 0 || slug.join("/") === "";
+}
+
 export default async function Page(props: {
   params: Promise<{ slug?: string[] }>;
 }) {
   const params = await props.params;
+  if (isDocsIndex(params.slug)) {
+    redirect(docsIndexPath);
+  }
+
   const page = source.getPage(params.slug);
   if (!page) notFound();
 
@@ -35,14 +46,16 @@ export default async function Page(props: {
 }
 
 export function generateStaticParams() {
-  return source.generateParams();
+  return [{ slug: [""] }, ...source.generateParams()];
 }
 
 export async function generateMetadata(props: {
   params: Promise<{ slug?: string[] }>;
 }) {
   const params = await props.params;
-  const page = source.getPage(params.slug);
+  const page = source.getPage(
+    isDocsIndex(params.slug) ? [...docsIndexSlug] : params.slug,
+  );
   if (!page) notFound();
 
   return {
diff --git a/docs-site/middleware.ts b/docs-site/middleware.ts
index 4e06ea8b..670ebd33 100644
--- a/docs-site/middleware.ts
+++ b/docs-site/middleware.ts
@@ -38,7 +38,7 @@ function isMarkdownPreferred(acceptHeader: string | null) {
         .find((parameter) => parameter.startsWith("q="));
 
       return {
-        type: type.toLowerCase(),
+        type: type.trim().toLowerCase(),
         quality: quality ? Number.parseFloat(quality.slice(2)) : 1,
         index,
       };
diff --git a/docs-site/package.json b/docs-site/package.json
index 8ab53b93..d4a88999 100644
--- a/docs-site/package.json
+++ b/docs-site/package.json
@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
     "fumadocs-core": "15.7.13",
diff --git a/docs-site/tests/docs-index-route.test.mjs b/docs-site/tests/docs-index-route.test.mjs
new file mode 100644
index 00000000..859ae54e
--- /dev/null
+++ b/docs-site/tests/docs-index-route.test.mjs
@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const docsSiteUrl = process.env.DOCS_SITE_URL ?? "http://localhost:3000";
+
+test("/docs redirects to the docs introduction", async () => {
+  const response = await fetch(`${docsSiteUrl}/docs`, { redirect: "manual" });
+
+  assert.equal(response.status, 307);
+  assert.equal(
+    response.headers.get("location"),
+    "/docs/getting-started/introduction",
+  );
+});