mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
Merge origin/main into start-docs-locally
This commit is contained in:
Andrey Avtomonov
commit
78527fdf59
22 changed files with 216 additions and 369 deletions
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
4
docs-site/app/api/search/route.ts
Normal file
4
docs-site/app/api/search/route.ts
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
import { source } from "@/lib/source";
|
||||
import { createFromSource } from "fumadocs-core/search/server";
|
||||
|
||||
export const { GET } = createFromSource(source);
|
||||
|
|
@ -51,10 +51,7 @@ export default async function Page(props: {
|
|||
<>
|
||||
<div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between sm:gap-4">
|
||||
<DocsTitle>{page.data.title}</DocsTitle>
|
||||
<DocsPageActions
|
||||
markdownUrl={`${page.url}.md`}
|
||||
mdxSource={mdxSource}
|
||||
/>
|
||||
<DocsPageActions mdxSource={mdxSource} />
|
||||
</div>
|
||||
<DocsDescription className="wrap-anywhere">
|
||||
{page.data.description}
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -41,7 +41,9 @@ export default function RootLayout({ children }: { children: ReactNode }) {
|
|||
suppressHydrationWarning
|
||||
>
|
||||
<body>
|
||||
<RootProvider>{children}</RootProvider>
|
||||
<RootProvider search={{ options: { api: "/ktx/api/search" } }}>
|
||||
<div className="ktx-site-shell">{children}</div>
|
||||
</RootProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
|
|
|
|||
|
|
@ -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 (
|
||||
<div className="not-prose flex flex-wrap items-center gap-2 text-xs">
|
||||
<CopyMarkdownButton markdownUrl={markdownUrl} />
|
||||
<a
|
||||
href={markdownUrl}
|
||||
className="inline-flex h-8 items-center rounded-md border border-fd-border bg-fd-background px-3 font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground"
|
||||
<button
|
||||
type="button"
|
||||
onClick={onCopy}
|
||||
className="inline-flex h-8 items-center rounded-md border border-fd-border bg-fd-background px-3 font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground data-[state=copied]:border-emerald-500/40 data-[state=copied]:text-emerald-600"
|
||||
data-state={copied ? "copied" : "idle"}
|
||||
>
|
||||
View MD
|
||||
</a>
|
||||
<CopyTextButton label="Copy MDX" text={mdxSource} />
|
||||
{copied ? "Copied" : "Copy as Markdown"}
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function CopyMarkdownButton({ markdownUrl }: { markdownUrl: string }) {
|
||||
const [state, setState] = useState<CopyState>("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 (
|
||||
<ActionButton
|
||||
label={labelForState(state, "Copy MD")}
|
||||
onClick={onClick}
|
||||
state={state}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
function CopyTextButton({ label, text }: { label: string; text: string }) {
|
||||
const [state, setState] = useState<CopyState>("idle");
|
||||
|
||||
const onClick = async () => {
|
||||
try {
|
||||
await navigator.clipboard.writeText(text);
|
||||
flash(setState, "copied");
|
||||
} catch {
|
||||
flash(setState, "error");
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<ActionButton
|
||||
label={labelForState(state, label)}
|
||||
onClick={onClick}
|
||||
state={state}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
function ActionButton({
|
||||
label,
|
||||
onClick,
|
||||
state,
|
||||
}: {
|
||||
label: string;
|
||||
onClick: () => void;
|
||||
state: CopyState;
|
||||
}) {
|
||||
return (
|
||||
<button
|
||||
type="button"
|
||||
onClick={onClick}
|
||||
className="inline-flex h-8 items-center rounded-md border border-fd-border bg-fd-background px-3 font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground data-[state=copied]:border-emerald-500/40 data-[state=copied]:text-emerald-600 data-[state=error]:border-red-500/40 data-[state=error]:text-red-600"
|
||||
data-state={state}
|
||||
>
|
||||
{label}
|
||||
</button>
|
||||
);
|
||||
}
|
||||
|
||||
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<CopyState, "idle">,
|
||||
) {
|
||||
setState(state);
|
||||
window.setTimeout(() => setState("idle"), 1500);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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/<path>.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).
|
||||
|
|
@ -2,7 +2,6 @@
|
|||
"title": "AI Resources",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"agent-quickstart",
|
||||
"markdown-access",
|
||||
"agent-instructions",
|
||||
|
|
|
|||
|
|
@ -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] <command>
|
||||
```
|
||||
|
||||
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 <path>` 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
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
"title": "CLI Reference",
|
||||
"defaultOpen": true,
|
||||
"pages": [
|
||||
"index",
|
||||
"ktx",
|
||||
"ktx-setup",
|
||||
"ktx-connection",
|
||||
"ktx-ingest",
|
||||
|
|
|
|||
|
|
@ -88,10 +88,10 @@ best first step for users; contributor setup lives in the community docs.
|
|||
<Card title="Writing Context" href="/docs/guides/writing-context">
|
||||
Edit semantic-layer YAML and wiki Markdown safely.
|
||||
</Card>
|
||||
<Card title="Agent Clients" href="/docs/integrations/agent-clients">
|
||||
Serve KTX context to MCP-capable agent clients.
|
||||
<Card title="CLI Reference" href="/docs/cli-reference/ktx">
|
||||
Complete flag and subcommand reference for every KTX command.
|
||||
</Card>
|
||||
<Card title="Contributing" href="/docs/community/contributing">
|
||||
Set up a development checkout and contribute code, docs, or connectors.
|
||||
<Card title="Agent Quickstart" href="/docs/ai-resources/agent-quickstart">
|
||||
Machine-readable docs and agent-facing setup notes.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
|
|
|||
|
|
@ -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.<id>.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/<user-id>/*.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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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/<user-id>/
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <connectionId>` 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/<connection-id>/` | 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.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"title": "Integrations",
|
||||
"defaultOpen": true,
|
||||
"pages": ["index", "primary-sources", "context-sources", "agent-clients"]
|
||||
"pages": ["primary-sources", "context-sources", "agent-clients"]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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")}
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
);
|
||||
});
|
||||
|
|
|
|||
53
docs-site/tests/docs-search-behavior.test.mjs
Normal file
53
docs-site/tests/docs-search-behavior.test.mjs
Normal file
|
|
@ -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,
|
||||
);
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue