From d60d83e59577889545bbd226a8024cf1607a5dab Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Mon, 18 May 2026 09:49:43 -0400 Subject: [PATCH 1/4] docs: remove section overview pages (#130) --- README.md | 2 +- .../docs/ai-resources/agent-quickstart.mdx | 4 ++ docs-site/content/docs/ai-resources/index.mdx | 64 ----------------- docs-site/content/docs/ai-resources/meta.json | 1 - .../docs/cli-reference/{index.mdx => ktx.mdx} | 28 ++++++-- .../content/docs/cli-reference/meta.json | 2 +- .../docs/getting-started/introduction.mdx | 4 +- docs-site/content/docs/integrations/index.mdx | 71 ------------------- docs-site/content/docs/integrations/meta.json | 2 +- .../docs/integrations/primary-sources.mdx | 5 ++ docs-site/lib/llm-docs.ts | 2 +- 11 files changed, 37 insertions(+), 148 deletions(-) delete mode 100644 docs-site/content/docs/ai-resources/index.mdx rename docs-site/content/docs/cli-reference/{index.mdx => ktx.mdx} (78%) delete mode 100644 docs-site/content/docs/integrations/index.mdx diff --git a/README.md b/README.md index e058b828..be4027e6 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,7 @@ uv run pytest -q ## Docs - [Quickstart](docs-site/content/docs/getting-started/quickstart.mdx) -- [CLI Reference](docs-site/content/docs/cli-reference/index.mdx) +- [CLI Reference](docs-site/content/docs/cli-reference/ktx.mdx) - [Building Context](docs-site/content/docs/guides/building-context.mdx) - [Contributing](docs-site/content/docs/community/contributing.mdx) diff --git a/docs-site/content/docs/ai-resources/agent-quickstart.mdx b/docs-site/content/docs/ai-resources/agent-quickstart.mdx index 6fd6e5ac..0d49ab00 100644 --- a/docs-site/content/docs/ai-resources/agent-quickstart.mdx +++ b/docs-site/content/docs/ai-resources/agent-quickstart.mdx @@ -5,6 +5,10 @@ description: A task-first route for coding agents that need to understand KTX do 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: diff --git a/docs-site/content/docs/ai-resources/index.mdx b/docs-site/content/docs/ai-resources/index.mdx deleted file mode 100644 index 37bae650..00000000 --- a/docs-site/content/docs/ai-resources/index.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: AI Resources -description: Machine-readable docs, retrieval paths, and prompt recipes for coding assistants using KTX documentation. ---- - -Use this section when a coding assistant, IDE agent, or automation system needs -to read, cite, or update KTX documentation. These resources are optimized for -retrieval: agents can fetch small Markdown pages, use the full corpus only when -needed, and copy prompts that point them at current setup and CLI behavior. - -> **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. - -## What agents can do - -| Need | Recommended path | -|------|------------------| -| Find the right setup or CLI page | Fetch [`/llms.txt`](/llms.txt), then read the smallest matching `.md` page | -| Answer a setup question | Read [Agent Quickstart](/docs/ai-resources/agent-quickstart), then [Quickstart](/docs/getting-started/quickstart) or [ktx setup](/docs/cli-reference/ktx-setup) | -| Quote a command or flag | Read the matching [CLI Reference](/docs/cli-reference) page as Markdown | -| Update docs in this repo | Use [Agent Instructions](/docs/ai-resources/agent-instructions) and verify generated Markdown routes after editing | -| Reuse a prompt | Copy from [Prompt Recipes](/docs/ai-resources/prompt-recipes) | - -## Section map - -| Goal | Use this page | -|------|---------------| -| Give an assistant a task-first route through the docs | [Agent Quickstart](/docs/ai-resources/agent-quickstart) | -| Fetch docs as Markdown instead of rendered HTML | [Markdown Access](/docs/ai-resources/markdown-access) | -| Add lightweight KTX docs guidance to a system prompt | [Agent Instructions](/docs/ai-resources/agent-instructions) | -| Copy prompts for setup, command lookup, and docs editing | [Prompt Recipes](/docs/ai-resources/prompt-recipes) | - -## 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 | -| Page-level actions | Copy Markdown, view Markdown, or copy MDX from rendered docs pages | -| Prompt recipes | Reusable prompts for docs lookup, setup help, command discovery, and docs editing | - -## Agent usage notes - -When an assistant is unsure where to begin, use this retrieval order: - -1. Read [`/llms.txt`](/llms.txt). -2. Fetch one or two specific Markdown pages for the task. -3. Use [Agent Quickstart](/docs/ai-resources/agent-quickstart) to choose the - next command, guide, or CLI reference page. -4. Use [`/llms-full.txt`](/llms-full.txt) only when the answer requires broad - context across setup, integrations, concepts, and CLI reference. -5. Use page-level copy actions when the user wants exact generated Markdown or - source MDX. - -## Boundaries - -AI Resources explain how agents consume the docs. To install KTX into an -agent client, use [Agent Clients](/docs/integrations/agent-clients). To set up a -project, use [Quickstart](/docs/getting-started/quickstart) or -[`ktx setup`](/docs/cli-reference/ktx-setup). diff --git a/docs-site/content/docs/ai-resources/meta.json b/docs-site/content/docs/ai-resources/meta.json index ff555283..a925bf37 100644 --- a/docs-site/content/docs/ai-resources/meta.json +++ b/docs-site/content/docs/ai-resources/meta.json @@ -2,7 +2,6 @@ "title": "AI Resources", "defaultOpen": true, "pages": [ - "index", "agent-quickstart", "markdown-access", "agent-instructions", diff --git a/docs-site/content/docs/cli-reference/index.mdx b/docs-site/content/docs/cli-reference/ktx.mdx similarity index 78% rename from docs-site/content/docs/cli-reference/index.mdx rename to docs-site/content/docs/cli-reference/ktx.mdx index 2b681cba..937d2529 100644 --- a/docs-site/content/docs/cli-reference/index.mdx +++ b/docs-site/content/docs/cli-reference/ktx.mdx @@ -1,13 +1,29 @@ --- -title: "Overview" -description: "Command map and shared options for the KTX CLI." +title: "ktx" +description: "Root command map, global options, and project resolution for the KTX CLI." --- The `ktx` CLI sets up local projects, builds agent-ready context, checks connections, queries semantic-layer sources, searches wiki pages, runs the MCP server, and manages the bundled Python runtime. -## Command Map +## Command signature + +```bash +ktx [global-options] +``` + +When you run bare `ktx` in an interactive terminal outside any KTX project, the +CLI starts the same guided setup flow as `ktx setup`. Inside an existing +project, use command-specific help: + +```bash +ktx --help +ktx setup --help +ktx ingest --help +``` + +## Command map ```text ktx @@ -45,7 +61,7 @@ ktx The public context-build entrypoint is `ktx ingest [connectionId]` or `ktx ingest --all`. -## Global Options +## Global options | Flag | Description | |------|-------------| @@ -54,14 +70,14 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or | `-v`, `--version` | Show the CLI package name and version. | | `-h`, `--help` | Show help for the current command. | -## Project Resolution +## Project resolution Most commands are project-aware. Pass `--project-dir ` when scripting or when you are outside the project directory. If you omit it, KTX checks `KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back to the current directory. -## Common Workflows +## Common workflows ```bash # Start or resume setup diff --git a/docs-site/content/docs/cli-reference/meta.json b/docs-site/content/docs/cli-reference/meta.json index 6757e5bc..6385c7d4 100644 --- a/docs-site/content/docs/cli-reference/meta.json +++ b/docs-site/content/docs/cli-reference/meta.json @@ -2,7 +2,7 @@ "title": "CLI Reference", "defaultOpen": true, "pages": [ - "index", + "ktx", "ktx-setup", "ktx-connection", "ktx-ingest", diff --git a/docs-site/content/docs/getting-started/introduction.mdx b/docs-site/content/docs/getting-started/introduction.mdx index 72891d99..499d25a0 100644 --- a/docs-site/content/docs/getting-started/introduction.mdx +++ b/docs-site/content/docs/getting-started/introduction.mdx @@ -67,10 +67,10 @@ Server. Edit semantic-layer YAML and wiki Markdown safely. - + Complete flag and subcommand reference for every KTX command. - + Machine-readable docs and agent-facing setup notes. diff --git a/docs-site/content/docs/integrations/index.mdx b/docs-site/content/docs/integrations/index.mdx deleted file mode 100644 index 92a677aa..00000000 --- a/docs-site/content/docs/integrations/index.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Integrations -description: Connect KTX to warehouses, analytics tools, and coding agents. ---- - -KTX integrations bring trusted context into an analytics project and make that -context available to coding agents through the CLI. Start with `ktx setup` when -you want the guided flow, then use the integration reference pages for exact -configuration fields, generated files, and manual setup. - -## Integration types - -| Type | What it connects | Start here | -|------|------------------|------------| -| Primary sources | Warehouses and databases that KTX scans for schemas, constraints, row counts, and optional query history | [Primary Sources](/docs/integrations/primary-sources) | -| Context sources | Existing analytics and knowledge tools such as dbt, MetricFlow, LookML, Metabase, Looker, and Notion | [Context Sources](/docs/integrations/context-sources) | -| Agent clients | Claude Code, Codex, Cursor, OpenCode, and universal `.agents` consumers | [Agent Clients](/docs/integrations/agent-clients) | - -## Recommended setup flow - -Use this order for a new project: - -1. Run `ktx setup` from the analytics project directory. -2. Configure an LLM backend and embeddings so KTX can enrich and search context. -3. Add at least one primary source connection. -4. Add optional context sources that describe the same warehouse or business domain. -5. Build context during setup, or run `ktx ingest ` later. -6. Install agent integration with `ktx setup --agents` when the context is ready. - -For repeatable setup, pass `--project-dir`, `--no-input`, and the relevant -automation flags documented in [`ktx setup`](/docs/cli-reference/ktx-setup). - -## What setup writes - -| Path | Purpose | -|------|---------| -| `ktx.yaml` | Main project configuration for providers, embeddings, connections, source mappings, and query history | -| `.ktx/secrets/*` | Local file-backed secrets when you choose file references during setup | -| `.ktx/setup/*` | Local setup progress and context-build state | -| `semantic-layer//` | YAML semantic sources generated by database and source ingestion | -| `wiki/` | Markdown business context, definitions, and ingested knowledge | -| `.ktx/agents/install-manifest.json` | Manifest of agent integration files installed by `ktx setup --agents` | -| Agent client files | Skills, rules, or commands that teach agents when and how to call KTX | - -## Common commands - -```bash -# Start or resume the guided flow -ktx setup - -# Add or refresh every configured integration -ktx ingest --all - -# Refresh one configured warehouse, source, or knowledge integration -ktx ingest warehouse - -# Install one project-scoped agent target -ktx setup --agents --target codex - -# Check whether integrations are ready -ktx status -``` - -## Choosing docs - -Read [Primary Sources](/docs/integrations/primary-sources) when you need -database driver fields, authentication formats, query history support, or -warehouse-specific notes. Read [Context Sources](/docs/integrations/context-sources) -when you need source adapter fields, repository authentication, BI tool mapping, -or Notion crawl options. Read [Agent Clients](/docs/integrations/agent-clients) -when you need generated file locations or manual agent configuration. diff --git a/docs-site/content/docs/integrations/meta.json b/docs-site/content/docs/integrations/meta.json index 20dc642f..70fe26ec 100644 --- a/docs-site/content/docs/integrations/meta.json +++ b/docs-site/content/docs/integrations/meta.json @@ -1,5 +1,5 @@ { "title": "Integrations", "defaultOpen": true, - "pages": ["index", "primary-sources", "context-sources", "agent-clients"] + "pages": ["primary-sources", "context-sources", "agent-clients"] } diff --git a/docs-site/content/docs/integrations/primary-sources.mdx b/docs-site/content/docs/integrations/primary-sources.mdx index 00cc39aa..4b09c3a6 100644 --- a/docs-site/content/docs/integrations/primary-sources.mdx +++ b/docs-site/content/docs/integrations/primary-sources.mdx @@ -7,6 +7,11 @@ KTX connects to your data warehouse or database to build schema context, discover relationships, and execute semantic layer queries. Each connection is defined in `ktx.yaml` under the `connections` key. +For analytics tools and knowledge systems such as dbt, MetricFlow, LookML, +Metabase, Looker, and Notion, use [Context Sources](/docs/integrations/context-sources). +For Claude Code, Codex, Cursor, OpenCode, and other agent clients, use +[Agent Clients](/docs/integrations/agent-clients). + All connectors share these conventions: - Sensitive values support `env:VAR_NAME` (read from environment) and diff --git a/docs-site/lib/llm-docs.ts b/docs-site/lib/llm-docs.ts index 561f73e0..9ef474a3 100644 --- a/docs-site/lib/llm-docs.ts +++ b/docs-site/lib/llm-docs.ts @@ -52,7 +52,6 @@ KTX provides semantic-layer files, warehouse scans, wiki pages, provenance, and ## 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/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")} @@ -73,6 +72,7 @@ ${link("/docs/guides/writing-context", "Writing Context", "Write semantic source ## CLI Reference +${link("/docs/cli-reference/ktx", "ktx", "Root command map and global options")} ${link("/docs/cli-reference/ktx-setup", "ktx setup", "Interactive project setup")} ${link("/docs/cli-reference/ktx-sl", "ktx sl", "Semantic-layer commands")} ${link("/docs/cli-reference/ktx-wiki", "ktx wiki", "Wiki page commands")} From c539433d6631839bef3e31754345d9447e8b1b79 Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Mon, 18 May 2026 09:57:27 -0400 Subject: [PATCH 2/4] docs: tighten guide copy (#131) --- .../content/docs/guides/building-context.mdx | 69 +++++++------------ .../content/docs/guides/llm-configuration.mdx | 30 +++----- .../content/docs/guides/serving-agents.mdx | 39 +++++------ .../content/docs/guides/writing-context.mdx | 44 +++++------- 4 files changed, 67 insertions(+), 115 deletions(-) diff --git a/docs-site/content/docs/guides/building-context.mdx b/docs-site/content/docs/guides/building-context.mdx index 584e9003..39edaa85 100644 --- a/docs-site/content/docs/guides/building-context.mdx +++ b/docs-site/content/docs/guides/building-context.mdx @@ -3,12 +3,9 @@ title: Building Context description: Build and refresh KTX context from databases, source tools, query history, and text. --- -Building context turns configured connections into local semantic-layer sources -and wiki pages. Agents use those files to understand your schema, business -definitions, metric logic, joins, and known caveats before they write SQL. - -Use this guide after `ktx setup` has created `ktx.yaml` and at least one -database or context-source connection. +Build context after `ktx setup` creates `ktx.yaml` and at least one database or +context-source connection. KTX writes local semantic-layer sources and wiki +pages for agents to use before writing SQL. ## The build loop @@ -22,15 +19,12 @@ Most projects use this loop: 5. Validate and query representative sources before handing the context to an agent. -`ktx ingest --all` runs database connections first, then context-source -connections. That order lets dbt, BI, Notion, and text ingest attach context to -known warehouse tables. +`ktx ingest --all` runs databases first, then context-source connections, so +external metadata can attach to known warehouse tables. ## Database ingest -Database ingest connects to a configured warehouse and records local schema -context. It gives agents table, column, type, constraint, and row-count -grounding without requiring them to inspect the database directly. +Database ingest records table, column, type, constraint, and row-count context. ```bash # Build one configured database connection @@ -55,20 +49,16 @@ ktx ingest warehouse --deep ktx ingest --all --deep ``` -Deep ingest needs LLM and embedding readiness. If those providers are not -configured, run `ktx setup` or use `--fast`. +Deep ingest needs LLM and embedding readiness. Otherwise run `ktx setup` or use +`--fast`. -When you use `claude-code`, KTX still controls the tool surface for ingest and -memory capture. Claude Code built-in tools, discovered MCP servers, plugins, -skills, agents, and slash commands are not invokable by KTX agent loops unless -they are exact KTX MCP tools for the current run. +With `claude-code`, KTX agent loops can invoke only the KTX MCP tools for the +current run. ## Query history -PostgreSQL, BigQuery, and Snowflake can add query-history context. This helps -KTX learn common joins, filters, service-account patterns, redaction rules, and -usage-heavy query templates. BigQuery and Snowflake support a lookback window; -Postgres reads the current `pg_stat_statements` aggregate data instead. +PostgreSQL, BigQuery, and Snowflake can add query-history context: common joins, +filters, service-account patterns, redaction rules, and high-usage templates. Enable it during setup, store it under `connections..context.queryHistory`, or request it for one run: @@ -84,19 +74,13 @@ for one run. ## Relationship evidence -Many databases do not declare all foreign keys. KTX can score relationship -candidates using signals such as name similarity, type compatibility, value -overlap, embedding similarity, uniqueness, null rate, and structural priors. - -The public CLI does not expose separate relationship review subcommands. -Relationship evidence is built as part of deep database ingest when the -connector and readiness checks support it. +KTX scores relationship candidates during supported deep database ingest. The +public CLI does not expose separate relationship review subcommands. ## Context-source ingest -Context-source connections pull business metadata from tools your team already -uses. The current public `ktx ingest` command is connection-centric: pass one -configured connection id, or pass `--all`. +Context-source connections pull metadata from dbt, BI tools, Notion, and other +configured systems. Pass one connection id or `--all`. ```bash # Build one source connection @@ -117,14 +101,13 @@ Supported source types: | `metabase` | Metabase API | Questions, dashboards, table metadata, and mappings | | `notion` | Notion API | Wiki pages and business knowledge | -Source ingest extracts metadata, reconciles it with existing local context, and -writes semantic-layer YAML plus wiki Markdown. It merges rather than blindly -overwriting local edits. +Source ingest writes semantic-layer YAML and wiki Markdown, merging with local +edits. ## Text ingest -Use `ktx ingest text` for notes, Markdown files, runbooks, Slack exports, or -other free-form knowledge that should become searchable KTX memory. +Use `ktx ingest text` for notes, Markdown, runbooks, Slack exports, or other +searchable memory. ```bash # Capture a Markdown file @@ -146,14 +129,12 @@ Useful flags: | `--json` | Print structured output | | `--fail-fast` | Stop after the first failed text item | -Text ingest is a good fit for small, high-signal documents. For system-specific -connectors such as Notion, dbt, or Metabase, prefer configured source ingest so -KTX can preserve source metadata. +Use text ingest for small, high-signal documents. Prefer configured source +ingest for Notion, dbt, Metabase, and similar systems. ## Output and artifacts -Every ingest run prints a summary. Use `--json` when an agent or script needs a -structured plan and per-target results. +Every ingest run prints a summary. Use `--json` for scripts and agents. ```bash ktx ingest --all --json @@ -168,9 +149,7 @@ Typical generated files: | `wiki/user//*.md` | Text and memory ingest | User-scoped context | | `.ktx/setup/context-build.json` | Setup context build | Resume and readiness state for setup | -Ingest sessions also record transcripts with tool calls, LLM responses, and -write decisions. Inspect them when you need to debug why a source or wiki page -was written a certain way. +Ingest transcripts include tool calls, LLM responses, and write decisions. ## Example: first full refresh diff --git a/docs-site/content/docs/guides/llm-configuration.mdx b/docs-site/content/docs/guides/llm-configuration.mdx index 054d0b58..7e86cf96 100644 --- a/docs-site/content/docs/guides/llm-configuration.mdx +++ b/docs-site/content/docs/guides/llm-configuration.mdx @@ -3,8 +3,8 @@ title: LLM configuration description: Configure KTX LLM providers, model roles, and prompt caching. --- -KTX uses the top-level `llm` block in `ktx.yaml` for text generation, -structured extraction, and ingest or memory agent loops. +Configure text generation, structured extraction, and ingest or memory loops in +the top-level `llm` block. ## Backends @@ -15,9 +15,7 @@ Set `llm.provider.backend` to one of these values: - `vertex`: Use Vertex AI Anthropic models through Google Cloud credentials. - `gateway`: Use AI Gateway-compatible Anthropic model ids. - `claude-code`: Use your local Claude Code session through the Claude Agent - SDK. KTX removes provider-routing environment variables from Claude Code - child processes, so this backend doesn't silently fall back to - `ANTHROPIC_API_KEY`, Vertex, Gateway, or Bedrock credentials. + SDK. KTX strips provider-routing environment variables from child processes. ## Claude Code @@ -36,26 +34,20 @@ llm: repair: sonnet ``` -During setup, choose the Claude Code backend interactively or pass the model in -automation: +During setup, choose the backend interactively or pass the model in automation: ```bash ktx setup --llm-backend claude-code --llm-model opus --no-input ``` -For Claude Code, `sonnet`, `opus`, and `haiku` map to the current KTX defaults. -You can also pass a full Claude model ID, such as `claude-opus-4-7`. +For Claude Code, `sonnet`, `opus`, and `haiku` map to KTX defaults. Full Claude +model IDs are also accepted. -`claude-code` keeps KTX tool boundaries intact. KTX exposes only the MCP tools -needed for the current KTX agent loop, disables Claude Code built-in tools, -keeps plugins empty, and denies every non-KTX tool request through -`canUseTool`. The Claude Agent SDK may still report host-discovered slash -commands, skills, and subagent names in init metadata; that metadata is not an -execution grant for KTX agent loops. +`claude-code` exposes only KTX MCP tools for the current agent loop. SDK init +metadata may still list host slash commands, skills, and subagents; KTX does not +grant execution access to them. ## Prompt caching -`llm.promptCaching` has partial parity on `claude-code`. KTX doesn't pass -Anthropic cache-control markers to the Claude Agent SDK. Status and doctor warn -when you configure prompt-cache TTL, tool, or history fields that the Claude -Agent SDK backend ignores. +`llm.promptCaching` has partial parity on `claude-code`. Status and doctor warn +when the Claude Agent SDK backend ignores configured cache fields. diff --git a/docs-site/content/docs/guides/serving-agents.mdx b/docs-site/content/docs/guides/serving-agents.mdx index 192b1c7f..8710d3ba 100644 --- a/docs-site/content/docs/guides/serving-agents.mdx +++ b/docs-site/content/docs/guides/serving-agents.mdx @@ -3,9 +3,8 @@ title: Serving Agents description: Expose KTX context to Claude Code, Codex, Cursor, OpenCode, and custom agents. --- -KTX serves agents through the public CLI and project-local instruction files. -Agents do not need a separate server. They read the generated rules, call KTX -commands, inspect local context files, and use JSON output when they need +KTX serves agents through the CLI and project-local instruction files. Agents +read generated rules, call KTX commands, inspect context files, and use JSON for structured results. ## Recommended setup @@ -39,14 +38,13 @@ ktx setup --agents --target claude-code --global ktx setup --agents --target codex --global ``` -KTX records installed files in `.ktx/agents/install-manifest.json`. Rerun -`ktx setup --agents` after moving a checkout or reinstalling the CLI so the -generated instructions point at the current CLI path. +Installed files are recorded in `.ktx/agents/install-manifest.json`. Rerun +`ktx setup --agents` after moving a checkout or reinstalling the CLI. ## Agent command set -All supported agent clients use the same command surface. Use `--project-dir` -when the agent is running outside the KTX project directory. +All supported clients use the same command surface. Use `--project-dir` outside +the KTX project directory. ### Readiness @@ -54,9 +52,8 @@ when the agent is running outside the KTX project directory. ktx status --json ``` -Agents should run this before relying on context. It reports project, LLM, -embedding, database, context-source, context-build, and agent-integration -readiness. +Run this before relying on context. It reports project, provider, connection, +context-build, and agent-integration readiness. ### Semantic layer discovery @@ -66,8 +63,8 @@ ktx sl list --connection-id warehouse --json ktx sl search "revenue" --json --limit 10 ``` -Agents use these commands to discover source names, connection ids, measures, -dimensions, and likely files to inspect. +Use these commands to find source names, connection ids, measures, dimensions, +and files to inspect. ### Semantic-layer validation and queries @@ -106,9 +103,8 @@ ktx wiki list --json ktx wiki search "revenue recognition" --json --limit 10 ``` -Agents should search wiki context when a question depends on business -definitions, metric caveats, process rules, or terms that are not obvious from -schema names. +Search wiki context for business definitions, metric caveats, process rules, and +non-obvious terms. ### Context refresh @@ -120,8 +116,7 @@ ktx ingest --all ktx ingest text docs/revenue-notes.md --connection-id warehouse ``` -Use `--deep` only when LLM and embedding setup is ready and the user expects an -AI-enriched refresh. +Use `--deep` only when LLM and embedding setup is ready. ## Good agent behavior @@ -135,14 +130,12 @@ Agents should: - Validate edited semantic sources with `ktx sl validate`. - Keep generated context changes reviewable in git. -Agents should not assume a background server, ORPC route, frontend app, or -external migration system exists. KTX is a local context layer with a CLI and -plain project files. +KTX is a local context layer with a CLI and plain project files. Do not assume a +background server, ORPC route, frontend app, or external migration system. ## Manual setup -Manual setup is useful for custom agents that can read project-local -instructions but are not yet a named target. +Use manual setup for custom agents that can read project-local instructions. 1. Install the universal target: diff --git a/docs-site/content/docs/guides/writing-context.mdx b/docs-site/content/docs/guides/writing-context.mdx index b68960bf..2b9824c8 100644 --- a/docs-site/content/docs/guides/writing-context.mdx +++ b/docs-site/content/docs/guides/writing-context.mdx @@ -3,12 +3,8 @@ title: Writing Context description: Edit semantic sources and wiki pages so agents use your business logic. --- -KTX context is meant to be edited. Ingest gives you a grounded first draft, then -you refine source YAML and wiki Markdown until agents can answer data questions -with the same definitions your team uses. - -Use this guide when you are adding measures, fixing joins, documenting business -rules, or reviewing context changes made by an agent. +Ingest creates the first draft. Edit source YAML and wiki Markdown when you need +sharper metrics, joins, or business rules. ## Editing workflow @@ -45,10 +41,8 @@ Use this order for most context changes: ## Semantic sources -Semantic sources are YAML files that describe queryable entities. A source is -usually a table, but it can also point at a custom SQL expression. Sources -define the vocabulary agents use for measures, dimensions, segments, joins, and -grain-aware query planning. +Semantic sources are YAML files for queryable tables or custom SQL. They define +agent-facing measures, dimensions, segments, joins, and grain. Source files live at: @@ -198,8 +192,8 @@ joins: ## Measures -Good measures have precise names, SQL expressions at the correct grain, and -descriptions that say what is included and excluded. +Good measures have precise names, correct-grain SQL, and descriptions that name +key inclusions and exclusions. ```yaml measures: @@ -209,14 +203,13 @@ measures: description: Completed order revenue after refunds, excluding cancelled orders. ``` -Prefer one canonical measure plus wiki synonyms over several nearly identical -measures. If your team uses multiple definitions, document the distinction in a -wiki page and link it with `sl_refs`. +Prefer one canonical measure plus wiki synonyms. Put competing definitions in a +linked wiki page. ## Joins and grain -`grain` and `relationship` prevent agents from producing double-counted SQL. -State the row grain even when it seems obvious. +`grain` and `relationship` prevent double-counted SQL. State the row grain even +when it seems obvious. ```yaml grain: @@ -228,8 +221,7 @@ joins: ``` Use `many_to_one` for dimensions such as customer, account, product, or plan. -Use `one_to_many` only when the target can fan out the source rows, such as -orders to order items. +Use `one_to_many` only when the target can fan out rows. ## Validate and query @@ -239,8 +231,7 @@ Validation checks source YAML against the live database schema: ktx sl validate orders --connection-id warehouse ``` -It catches missing columns, invalid join targets, and table-reference problems -before an agent relies on the source. +It catches missing columns, invalid joins, and table-reference problems. Compile a query to inspect generated SQL: @@ -268,9 +259,8 @@ ktx sl query \ ## Wiki pages -Wiki pages capture business context that does not belong in a single source -file: metric policies, dashboard caveats, company vocabulary, data freshness, -known issues, and source-of-truth notes. +Wiki pages hold context that does not belong in one source file: policies, +caveats, vocabulary, freshness, known issues, and source-of-truth notes. Wiki files live under: @@ -280,8 +270,7 @@ wiki/ user// ``` -Use global pages for shared business rules. Use user-scoped pages for local -notes, personal conventions, or context that should not be shared broadly. +Use global pages for shared rules and user-scoped pages for local notes. ### Wiki page example @@ -338,8 +327,7 @@ ktx sl search "revenue" --json ktx wiki search "revenue recognition" --json --limit 10 ``` -Check that definitions are specific, hidden columns stay hidden, joins have -explicit relationships, and measures compile into the expected SQL. +Check definitions, hidden columns, join relationships, and generated SQL. ## Common errors From 6a60977eb5a004145036c4fef8eae0698852fa95 Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Mon, 18 May 2026 09:59:01 -0400 Subject: [PATCH 3/4] fix(docs): replace broken page copy buttons with working single button (#132) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three page-level buttons (Copy MD, View MD, Copy MDX) were broken because the fetch URL missed the /ktx basePath. Replace with a single "Copy as Markdown" button that strips frontmatter from the MDX source already available client-side — no fetch needed. Drop the .md link since agents discover markdown URLs through llms.txt and content negotiation. Co-authored-by: Claude Opus 4.6 (1M context) --- docs-site/app/docs/[[...slug]]/page.tsx | 5 +- docs-site/components/docs-page-actions.tsx | 120 +++++---------------- 2 files changed, 25 insertions(+), 100 deletions(-) diff --git a/docs-site/app/docs/[[...slug]]/page.tsx b/docs-site/app/docs/[[...slug]]/page.tsx index dd5d944c..e0677c9e 100644 --- a/docs-site/app/docs/[[...slug]]/page.tsx +++ b/docs-site/app/docs/[[...slug]]/page.tsx @@ -51,10 +51,7 @@ 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 index 95bf93a4..96d3980b 100644 --- a/docs-site/components/docs-page-actions.tsx +++ b/docs-site/components/docs-page-actions.tsx @@ -2,109 +2,37 @@ import { useState } from "react"; -type CopyState = "idle" | "copied" | "error"; - type Props = { - markdownUrl: string; mdxSource: string; }; -export function DocsPageActions({ markdownUrl, mdxSource }: Props) { +function stripFrontmatter(source: string) { + return source.trim().replace(/^---\n[\s\S]*?\n---\n?/, "").trim(); +} + +export function DocsPageActions({ mdxSource }: Props) { + const [copied, setCopied] = useState(false); + + const onCopy = async () => { + try { + await navigator.clipboard.writeText(stripFrontmatter(mdxSource)); + setCopied(true); + setTimeout(() => setCopied(false), 1500); + } catch { + // Clipboard denied — fail silently + } + }; + return (
- - - View MD - - + {copied ? "Copied" : "Copy as Markdown"} +
); } - -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); -} From 611f830fe0fdb0cd1e9c660898a19321e47e4c80 Mon Sep 17 00:00:00 2001 From: Luca Martial <48870843+luca-martial@users.noreply.github.com> Date: Mon, 18 May 2026 10:50:34 -0400 Subject: [PATCH 4/4] fix(docs): restore search overlay behavior (#134) --- docs-site/app/api/search/route.ts | 4 ++ docs-site/app/global.css | 10 ++-- docs-site/app/layout.tsx | 4 +- docs-site/tests/docs-index-route.test.mjs | 18 +++++++ docs-site/tests/docs-search-behavior.test.mjs | 53 +++++++++++++++++++ 5 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 docs-site/app/api/search/route.ts create mode 100644 docs-site/tests/docs-search-behavior.test.mjs diff --git a/docs-site/app/api/search/route.ts b/docs-site/app/api/search/route.ts new file mode 100644 index 00000000..d86bfc5b --- /dev/null +++ b/docs-site/app/api/search/route.ts @@ -0,0 +1,4 @@ +import { source } from "@/lib/source"; +import { createFromSource } from "fumadocs-core/search/server"; + +export const { GET } = createFromSource(source); diff --git a/docs-site/app/global.css b/docs-site/app/global.css index bc4ed8a4..08bd9b83 100644 --- a/docs-site/app/global.css +++ b/docs-site/app/global.css @@ -69,7 +69,11 @@ --color-fd-muted-foreground: #7a8d96; } -html, body { +/* Keep html overflow at the default `visible` so body's overflow + propagates to the viewport (per CSS Overflow spec). That lets + `react-remove-scroll-bar` lock viewport scroll via body alone while + leaving the sticky sidebar placeholder anchored to the viewport. */ +body { overflow-x: clip; } @@ -778,8 +782,8 @@ body::after { mix-blend-mode: overlay; } -/* Make sure content stays above background */ -body > * { +/* Make sure page content stays above the decorative background. */ +.ktx-site-shell { position: relative; z-index: 2; } diff --git a/docs-site/app/layout.tsx b/docs-site/app/layout.tsx index 48e12a3f..7c808130 100644 --- a/docs-site/app/layout.tsx +++ b/docs-site/app/layout.tsx @@ -41,7 +41,9 @@ export default function RootLayout({ children }: { children: ReactNode }) { suppressHydrationWarning > - {children} + +
{children}
+ ); diff --git a/docs-site/tests/docs-index-route.test.mjs b/docs-site/tests/docs-index-route.test.mjs index 7d1c62c0..721813ec 100644 --- a/docs-site/tests/docs-index-route.test.mjs +++ b/docs-site/tests/docs-index-route.test.mjs @@ -111,3 +111,21 @@ test("/ktx/docs redirects to the docs introduction", async () => { `${docsBasePath}/docs/getting-started/introduction`, ); }); + +test("/ktx/api/search returns docs search results", async () => { + const response = await fetch( + `${docsSiteUrl}${docsBasePath}/api/search?query=setup`, + ); + + assert.equal(response.status, 200); + + const results = await response.json(); + assert.ok(Array.isArray(results), "search response should be an array"); + assert.ok( + results.some( + (result) => + typeof result.url === "string" && result.url.startsWith("/docs/"), + ), + "search should return at least one docs result", + ); +}); diff --git a/docs-site/tests/docs-search-behavior.test.mjs b/docs-site/tests/docs-search-behavior.test.mjs new file mode 100644 index 00000000..0a96482b --- /dev/null +++ b/docs-site/tests/docs-search-behavior.test.mjs @@ -0,0 +1,53 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { dirname, join } from "node:path"; +import { test } from "node:test"; +import { fileURLToPath } from "node:url"; + +const docsSiteDir = join(dirname(fileURLToPath(import.meta.url)), ".."); + +async function readDocsFile(path) { + return readFile(join(docsSiteDir, path), "utf8"); +} + +test("root provider uses the base-path-aware search API", async () => { + const layout = await readDocsFile("app/layout.tsx"); + + assert.match(layout, /search=\{\{/); + assert.match(layout, /api:\s*"\/ktx\/api\/search"/); +}); + +test("site background stacking does not target every body child", async () => { + const css = await readDocsFile("app/global.css"); + + assert.doesNotMatch(css, /body\s*>\s*\*\s*\{[^}]*z-index/s); + assert.match(css, /\.ktx-site-shell\s*\{[^}]*z-index:\s*2/s); +}); + +test("search lock relies on body overflow propagation, not html or sidebar overrides", async () => { + const css = await readDocsFile("app/global.css"); + + // Body still clips horizontal overflow defensively. + assert.match(css, /(^|\s)body\s*\{[^}]*overflow-x:\s*clip/s); + + // html must keep its default `visible` overflow so body's lock + // (`overflow: hidden` from react-remove-scroll-bar) propagates to the + // viewport. Locking html directly breaks `position: sticky` on the + // sidebar placeholder. + assert.doesNotMatch(css, /(^|\s)html\s*,?\s*\{[^}]*overflow(-y|\s*:)\s*(hidden|clip)/s); + assert.doesNotMatch( + css, + /html:has\(body\[data-scroll-locked\]\)[^{]*\{[^}]*overflow:\s*(hidden|clip)/s, + ); + + // No site-specific overrides to body's data-scroll-locked overflow or + // to the sidebar placeholder when locked. + assert.doesNotMatch( + css, + /html\s+body\[data-scroll-locked\][^{]*\{[^}]*overflow:/s, + ); + assert.doesNotMatch( + css, + /body\[data-scroll-locked\]\s+\[data-sidebar-placeholder\][^{]*\{[^}]*position:\s*fixed/s, + ); +});