From 8050b59f6ebfc5d0ff1347ed1bfdc3bdb45a7e15 Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Mon, 8 Jun 2026 21:28:56 -0700 Subject: [PATCH] docs: consolidate AI Resources into a single page (#274) * docs: consolidate AI Resources into a single page The AI Resources section was four pages (agent-quickstart, markdown-access, agent-instructions, prompt-recipes) that repeated the same docs-consumption guidance. Collapse them into one page at /docs/ai-resources covering markdown endpoints, retrieval order, the task router, agent instructions, prompts, and guardrails. Also fix a stale claim: the page actions are a single "Copy as Markdown" button, not the documented "Copy MD / View MD / Copy MDX" trio. Update the cross-references in README, the introduction cards, the quickstart, and the llms.txt entry points to the consolidated page. Co-Authored-By: Claude Opus 4.8 * fix(docs-site): redirect retired AI Resources slugs, preserving .md route Redirect the retired per-page slugs (/docs/ai-resources/*) to the consolidated page. Because Next evaluates redirects before the .md rewrite, a single catch-all would 308 a cached per-page Markdown URL to the HTML page and break the agent Markdown contract. Match the .md variant first and keep its suffix so it lands on /docs/ai-resources.md. Extend the routing test to assert both the HTML and .md redirects, and that following the .md URL end to end serves text/markdown. Co-Authored-By: Claude Opus 4.8 * docs: move AI Resources under the Community & Resources section As a single page, AI Resources rendered as an orphaned, unbolded link wedged between the top-level multi-page sections instead of as a section of its own. Move it under Community (renamed "Community & Resources") so it renders as a normal child link, consistent with how the single-page Configuration section already works. Redirect the former top-level URL and the retired per-page slugs (HTML and .md, the .md variants first so cached Markdown URLs keep their suffix) to the new home, relabel the llms.txt group to match, and repoint the README, introduction, quickstart, and llms.txt cross-links. Co-Authored-By: Claude Opus 4.8 --------- Co-authored-by: Claude Opus 4.8 --- README.md | 4 +- .../docs/ai-resources/agent-instructions.mdx | 40 ------- .../docs/ai-resources/agent-quickstart.mdx | 54 --------- .../docs/ai-resources/markdown-access.mdx | 76 ------------ docs-site/content/docs/ai-resources/meta.json | 10 -- .../docs/ai-resources/prompt-recipes.mdx | 55 --------- .../content/docs/community/ai-resources.mdx | 111 ++++++++++++++++++ docs-site/content/docs/community/meta.json | 4 +- .../docs/getting-started/introduction.mdx | 4 +- .../docs/getting-started/quickstart.mdx | 4 +- docs-site/content/docs/meta.json | 1 - docs-site/lib/llm-docs.ts | 8 +- docs-site/next.config.mjs | 26 ++++ docs-site/tests/docs-index-route.test.mjs | 47 ++++++++ 14 files changed, 195 insertions(+), 249 deletions(-) delete mode 100644 docs-site/content/docs/ai-resources/agent-instructions.mdx delete mode 100644 docs-site/content/docs/ai-resources/agent-quickstart.mdx delete mode 100644 docs-site/content/docs/ai-resources/markdown-access.mdx delete mode 100644 docs-site/content/docs/ai-resources/meta.json delete mode 100644 docs-site/content/docs/ai-resources/prompt-recipes.mdx create mode 100644 docs-site/content/docs/community/ai-resources.mdx diff --git a/README.md b/README.md index 79b92161..3f704f04 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@

Quickstart · CLI Reference · - Agent Setup · + Agent Setup · Slack

@@ -209,7 +209,7 @@ then the current directory. Pass `--project-dir ` when scripting. - [The Context Layer](https://docs.kaelio.com/ktx/docs/concepts/the-context-layer) - [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context) - [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx) -- [Agent Quickstart](https://docs.kaelio.com/ktx/docs/ai-resources/agent-quickstart) +- [AI Resources](https://docs.kaelio.com/ktx/docs/community/ai-resources) - [Community & Support](https://docs.kaelio.com/ktx/docs/community/support) ## Community diff --git a/docs-site/content/docs/ai-resources/agent-instructions.mdx b/docs-site/content/docs/ai-resources/agent-instructions.mdx deleted file mode 100644 index 37ee6ba9..00000000 --- a/docs-site/content/docs/ai-resources/agent-instructions.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -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://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://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. -``` - -## 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://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 - -```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 deleted file mode 100644 index 6a47f56f..00000000 --- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Agent Quickstart -description: A task-first route for coding agents that need to understand ktx docs. ---- - -This page is for coding assistants reading or citing the **ktx** docs. It is intentionally limited to documentation lookup, docs navigation, and safe command discovery. - -For Markdown endpoints, use [Markdown Access](/docs/ai-resources/markdown-access). -For reusable task prompts, use [Prompt Recipes](/docs/ai-resources/prompt-recipes). -To install **ktx** into an agent client, use [Agent Clients](/docs/integrations/agent-clients). - -## First read - -Agents should start with the smallest source that answers the task: - -1. [`/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 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 sl](/docs/cli-reference/ktx-sl) | [ktx wiki](/docs/cli-reference/ktx-wiki) | - -## Operating workflow - -Use this workflow when the user asks an assistant to answer a **ktx** docs question: - -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. - -## Docs lookup from a shell - -```bash -curl https://docs.kaelio.com/ktx/llms.txt -curl https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md -``` - -## Guardrails - -- 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/markdown-access.mdx b/docs-site/content/docs/ai-resources/markdown-access.mdx deleted file mode 100644 index 99fb1295..00000000 --- a/docs-site/content/docs/ai-resources/markdown-access.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -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://docs.kaelio.com/ktx/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://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. - -## Per-page Markdown - -Every docs page has a Markdown route: - -```text -https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md -https://docs.kaelio.com/ktx/docs/cli-reference/ktx-sl.md -https://docs.kaelio.com/ktx/docs/cli-reference/ktx-wiki.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://docs.kaelio.com/ktx/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. - -## 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 | -|---------|-------------| -| 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 | -| Copying rendered text by hand | Use **Copy MD** or **Copy MDX** from the page actions | diff --git a/docs-site/content/docs/ai-resources/meta.json b/docs-site/content/docs/ai-resources/meta.json deleted file mode 100644 index a925bf37..00000000 --- a/docs-site/content/docs/ai-resources/meta.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "title": "AI Resources", - "defaultOpen": true, - "pages": [ - "agent-quickstart", - "markdown-access", - "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 deleted file mode 100644 index 9ba8e3b8..00000000 --- a/docs-site/content/docs/ai-resources/prompt-recipes.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -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://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 - -```text -Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install -and configure ktx in this project. -``` - -## Find a command - -```text -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. -``` - -## Explain setup - -```text -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. -``` - -## Compare concepts - -```text -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 - -```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. -``` - -## Copy exact docs source - -```text -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. 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/community/ai-resources.mdx b/docs-site/content/docs/community/ai-resources.mdx new file mode 100644 index 00000000..3bb9336d --- /dev/null +++ b/docs-site/content/docs/community/ai-resources.mdx @@ -0,0 +1,111 @@ +--- +title: AI Resources +description: How coding agents read, cite, and act on the ktx docs - Markdown endpoints, a task router, and copy-paste prompts. +--- + +This page is for coding assistants that read or cite the **ktx** docs. It covers +the machine-readable endpoints, a task router for common questions, and +copy-paste prompts. It is scoped to documentation lookup and safe command +discovery - to wire **ktx** into an agent client, see +[Agent Clients](/docs/integrations/agent-clients). + +## Markdown endpoints + +**ktx** docs are available as plain Markdown so assistants never have to parse +the rendered HTML site. + +- [`/llms.txt`](/llms.txt) - a curated index of high-value pages and agent entry + points. **Start here.** +- [`/llms-full.txt`](/llms-full.txt) - the entire docs corpus in one response. + Use only when a task needs broad context across many pages. +- **Per-page Markdown** - append `.md` to any docs URL: + +```text +https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md +https://docs.kaelio.com/ktx/docs/cli-reference/ktx-sl.md +https://docs.kaelio.com/ktx/docs/guides/building-context.md +``` + +A request for any docs URL with an `Accept: text/markdown` header returns the +same Markdown without the `.md` suffix: + +```bash +curl -H "Accept: text/markdown" https://docs.kaelio.com/ktx/docs/getting-started/quickstart +``` + +Each Markdown response leads with the page title, description, canonical URL, and +Markdown URL; frontmatter is stripped; code blocks and tables are preserved; and +missing pages return a plain-text `404` instead of falling back to HTML. Rendered +pages also expose a **Copy as Markdown** action near the title. + +### Retrieval order + +1. Fetch [`/llms.txt`](/llms.txt). +2. Pick one or two relevant per-page `.md` URLs. +3. Fetch [`/llms-full.txt`](/llms-full.txt) only when page-level docs are not + enough. + +```bash +curl https://docs.kaelio.com/ktx/llms.txt +curl https://docs.kaelio.com/ktx/docs/getting-started/quickstart.md +``` + +## Task router + +| 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 sl](/docs/cli-reference/ktx-sl) | [ktx wiki](/docs/cli-reference/ktx-wiki) | + +## Agent instructions + +Paste this into a project or system prompt when an assistant needs to answer +from the **ktx** docs: + +```text +When answering ktx docs questions: + +1. Start with https://docs.kaelio.com/ktx/llms.txt. +2. Fetch the smallest relevant Markdown page (append .md to its docs URL). +3. Prefer the .md route over rendered HTML. +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 CLI behavior disagree, say what differs and prefer local verified output. +``` + +## Prompts + +Replace project names, connection ids, and business terms with your own values. + +**Install and configure ktx in a project** + +```text +Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install and configure ktx +``` + +**Find the right command** + +```text +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. +``` + +**Review semantic changes** + +```text +Review the ktx semantic-layer and wiki changes in this branch. Check that measures have clear definitions, joins use valid keys, hidden or internal columns are not exposed to agents, and validation passes. List concrete file and line issues first. +``` + +## Guardrails + +- Do not invent CLI flags - fetch the relevant CLI reference page. +- Do not scrape rendered HTML when a `.md` route exists. +- Do not treat `/llms.txt` as complete documentation - use it as an index, then + fetch the linked pages. +- 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/community/meta.json b/docs-site/content/docs/community/meta.json index 199bc1b8..fec59882 100644 --- a/docs-site/content/docs/community/meta.json +++ b/docs-site/content/docs/community/meta.json @@ -1,5 +1,5 @@ { - "title": "Community", + "title": "Community & Resources", "defaultOpen": true, - "pages": ["support", "contributing", "telemetry"] + "pages": ["support", "contributing", "telemetry", "ai-resources"] } diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 50ffe20d..4bfbab6a 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -95,8 +95,8 @@ best first step for users; contributor setup lives in the community docs. Complete flag and subcommand reference for every **ktx** command. - - Machine-readable docs and agent-facing setup notes. + + Machine-readable docs, a task router, and copy-paste agent prompts. diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx index 5fe69113..50059cb6 100644 --- a/docs-site/content/docs/getting-started/quickstart.mdx +++ b/docs-site/content/docs/getting-started/quickstart.mdx @@ -9,8 +9,8 @@ This guide takes a local analytics project from empty to agent-ready. You'll install the CLI, run one guided setup command, and hand the context to a coding assistant. -If you're a coding assistant choosing a docs route, start with the -[Agent Quickstart](/docs/ai-resources/agent-quickstart) instead. +If you're a coding assistant choosing a docs route, start with +[AI Resources](/docs/community/ai-resources) instead.
= { - "ai-resources": "AI Resources", "cli-reference": "CLI Reference", + community: "Community & Resources", }; if (labels[category]) { diff --git a/docs-site/next.config.mjs b/docs-site/next.config.mjs index e47a0cc7..f800bcf5 100644 --- a/docs-site/next.config.mjs +++ b/docs-site/next.config.mjs @@ -72,6 +72,32 @@ const config = { permanent: false, basePath: false, }, + { + // AI Resources collapsed from four pages to one and now lives under the + // Community & Resources section. Redirect the old top-level URL and the + // retired per-page slugs to the new home. Redirects run before the .md + // rewrite, so the Markdown variants must be matched first and keep their + // .md suffix; otherwise a cached Markdown URL would 308 to the HTML page + // and break the agent Markdown contract. + source: "/docs/ai-resources.md", + destination: "/docs/community/ai-resources.md", + permanent: true, + }, + { + source: "/docs/ai-resources/:slug([^/]+\\.md)", + destination: "/docs/community/ai-resources.md", + permanent: true, + }, + { + source: "/docs/ai-resources", + destination: "/docs/community/ai-resources", + permanent: true, + }, + { + source: "/docs/ai-resources/:slug", + destination: "/docs/community/ai-resources", + permanent: true, + }, ]; }, }; diff --git a/docs-site/tests/docs-index-route.test.mjs b/docs-site/tests/docs-index-route.test.mjs index 6fac0e3c..e2ab24f0 100644 --- a/docs-site/tests/docs-index-route.test.mjs +++ b/docs-site/tests/docs-index-route.test.mjs @@ -145,6 +145,53 @@ test("/ktx/docs redirects to the docs introduction", async () => { ); }); +test("retired AI Resources URLs redirect to the page under Community", async () => { + // The former top-level URL. + const bare = await fetch( + `${docsSiteUrl}${docsBasePath}/docs/ai-resources`, + { redirect: "manual" }, + ); + + assert.equal(bare.status, 308); + assert.equal( + bare.headers.get("location"), + `${docsBasePath}/docs/community/ai-resources`, + ); + + // A retired per-page slug. + const slug = await fetch( + `${docsSiteUrl}${docsBasePath}/docs/ai-resources/agent-quickstart`, + { redirect: "manual" }, + ); + + assert.equal(slug.status, 308); + assert.equal( + slug.headers.get("location"), + `${docsBasePath}/docs/community/ai-resources`, + ); + + // A retired per-page Markdown URL must stay Markdown: it has to redirect to + // the new .md route, not fall through to the HTML page. + const markdown = await fetch( + `${docsSiteUrl}${docsBasePath}/docs/ai-resources/agent-quickstart.md`, + { redirect: "manual" }, + ); + + assert.equal(markdown.status, 308); + assert.equal( + markdown.headers.get("location"), + `${docsBasePath}/docs/community/ai-resources.md`, + ); + + // Following that redirect end to end must land on Markdown, not HTML. + const followed = await fetch( + `${docsSiteUrl}${docsBasePath}/docs/ai-resources/agent-quickstart.md`, + ); + + assert.equal(followed.status, 200); + assert.match(followed.headers.get("content-type") ?? "", /text\/markdown/); +}); + test("/ redirects into the /ktx docs site", async () => { const response = await fetch(`${docsSiteUrl}/`, { redirect: "manual",