mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
docs: revamp quickstart and tighten code-block styling (#135)
* docs: streamline quickstart * feat(docs): simplify quickstart code-block styling Remove the fake terminal chrome (traffic lights + zsh header) and language pill from bash blocks, and the teal left-accent from output blocks. Bash fences now render as minimal cards; text fences route to a muted "output" preview. Make detectLanguage recursive and enable addLanguageClass in source.config.ts so Shiki tokens carry through to the renderer. Switch Shiki themes to min-light / github-dark and disable monospace ligatures so flag pairs like --agents keep a visible space. * fix(docs): restore quickstart CI snippets
This commit is contained in:
Andrey Avtomonov
GitHub
parent
7d156d9a06
commit
b507ff171d
9 changed files with 191 additions and 345 deletions
|
|
@ -165,6 +165,17 @@ pre {
|
|||
line-height: 1.7 !important;
|
||||
}
|
||||
|
||||
/* Disable monospace ligatures so `--flag` keeps a visible space and double
|
||||
dashes don't fuse into an em-dash glyph. */
|
||||
code,
|
||||
pre,
|
||||
pre code,
|
||||
.ktx-code,
|
||||
.ktx-code code {
|
||||
font-variant-ligatures: none !important;
|
||||
font-feature-settings: "liga" 0, "calt" 0 !important;
|
||||
}
|
||||
|
||||
.dark pre {
|
||||
background: transparent !important;
|
||||
}
|
||||
|
|
@ -220,57 +231,10 @@ figure[data-rehype-pretty-code-figure]:has(.ktx-code) {
|
|||
margin: 0;
|
||||
}
|
||||
|
||||
/* ── Mode A: Terminal ─────────────────────── */
|
||||
.ktx-code-terminal {
|
||||
background: #0c1417;
|
||||
border: 1px solid rgba(255, 255, 255, 0.08);
|
||||
color: #c8c3bc;
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.1),
|
||||
0 12px 32px -16px rgba(0, 0, 0, 0.3);
|
||||
}
|
||||
|
||||
.ktx-code-terminal:hover {
|
||||
border-color: rgba(34, 211, 238, 0.2);
|
||||
box-shadow:
|
||||
0 1px 2px rgba(0, 0, 0, 0.1),
|
||||
0 14px 32px -12px rgba(34, 211, 238, 0.18);
|
||||
}
|
||||
|
||||
.ktx-code-terminal-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
padding: 10px 12px;
|
||||
border-bottom: 1px solid rgba(255, 255, 255, 0.06);
|
||||
background: linear-gradient(180deg, rgba(255, 255, 255, 0.03), transparent);
|
||||
}
|
||||
|
||||
.ktx-tl-dot {
|
||||
width: 11px;
|
||||
height: 11px;
|
||||
border-radius: 999px;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.ktx-code-terminal-label {
|
||||
margin-left: 8px;
|
||||
font-size: 11px;
|
||||
font-weight: 500;
|
||||
letter-spacing: 0.02em;
|
||||
color: rgba(255, 255, 255, 0.4);
|
||||
}
|
||||
|
||||
.ktx-code-body-terminal {
|
||||
background: transparent !important;
|
||||
color: #c8c3bc !important;
|
||||
}
|
||||
|
||||
/* ── Mode D: Output preview (wizard prompts, status output) ── */
|
||||
.ktx-code-output {
|
||||
background: var(--color-fd-muted);
|
||||
border: 1px solid var(--color-fd-border);
|
||||
border-left: 3px solid color-mix(in oklch, var(--color-fd-primary) 50%, var(--color-fd-border));
|
||||
position: relative;
|
||||
box-shadow: 0 1px 2px rgba(27, 27, 24, 0.02);
|
||||
}
|
||||
|
|
@ -278,17 +242,14 @@ figure[data-rehype-pretty-code-figure]:has(.ktx-code) {
|
|||
.dark .ktx-code-output {
|
||||
background: #111a1e;
|
||||
border-color: rgba(255, 255, 255, 0.05);
|
||||
border-left-color: rgba(34, 211, 238, 0.25);
|
||||
}
|
||||
|
||||
.ktx-code-output:hover {
|
||||
border-color: color-mix(in oklch, var(--color-fd-primary) 25%, var(--color-fd-border));
|
||||
border-left-color: var(--color-fd-primary);
|
||||
}
|
||||
|
||||
.dark .ktx-code-output:hover {
|
||||
border-color: rgba(255, 255, 255, 0.08);
|
||||
border-left-color: rgba(34, 211, 238, 0.45);
|
||||
}
|
||||
|
||||
.ktx-code-output-label {
|
||||
|
|
@ -308,8 +269,8 @@ figure[data-rehype-pretty-code-figure]:has(.ktx-code) {
|
|||
|
||||
.ktx-code-output-copy {
|
||||
position: absolute !important;
|
||||
top: 6px !important;
|
||||
right: 6px !important;
|
||||
top: 7px !important;
|
||||
right: 8px !important;
|
||||
opacity: 0;
|
||||
transform: translateY(-4px);
|
||||
transition: opacity 0.2s var(--ktx-ease), transform 0.2s var(--ktx-ease);
|
||||
|
|
@ -449,30 +410,10 @@ figure[data-rehype-pretty-code-figure]:has(.ktx-code) {
|
|||
border-color: rgba(34, 211, 238, 0.2);
|
||||
}
|
||||
|
||||
.ktx-code-minimal-lang {
|
||||
position: absolute;
|
||||
top: 8px;
|
||||
left: 14px;
|
||||
font-size: 10px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.05em;
|
||||
color: var(--color-fd-muted-foreground);
|
||||
font-family: var(--font-display), var(--font-sans), sans-serif;
|
||||
opacity: 0;
|
||||
transition: opacity 0.2s var(--ktx-ease);
|
||||
pointer-events: none;
|
||||
z-index: 1;
|
||||
}
|
||||
|
||||
.ktx-code-minimal:hover .ktx-code-minimal-lang {
|
||||
opacity: 0.5;
|
||||
}
|
||||
|
||||
.ktx-code-minimal-copy {
|
||||
position: absolute !important;
|
||||
top: 6px !important;
|
||||
right: 6px !important;
|
||||
top: 7px !important;
|
||||
right: 8px !important;
|
||||
opacity: 0;
|
||||
transform: translateY(-4px);
|
||||
transition: opacity 0.2s var(--ktx-ease), transform 0.2s var(--ktx-ease);
|
||||
|
|
@ -1062,8 +1003,7 @@ body::after {
|
|||
.pill-badge .pill-dot { animation: none; }
|
||||
.card-lift { transition: none; }
|
||||
.ktx-code,
|
||||
.ktx-code-minimal-copy,
|
||||
.ktx-code-minimal-lang {
|
||||
.ktx-code-minimal-copy {
|
||||
transition: none;
|
||||
}
|
||||
#nd-sidebar div[data-state]:not([class]) > button[data-state] svg {
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ type Props = ComponentPropsWithoutRef<"pre"> & {
|
|||
"data-language"?: string;
|
||||
};
|
||||
|
||||
const TERMINAL_LANGS = new Set(["bash", "sh", "shell", "zsh"]);
|
||||
const OUTPUT_LANGS = new Set(["text", "plain", "plaintext", "console", "output"]);
|
||||
const WIZARD_GLYPHS = /^\s*[◆◇◯◐○●]/;
|
||||
|
||||
function extractText(node: ReactNode): string {
|
||||
|
|
@ -27,6 +27,33 @@ function extractText(node: ReactNode): string {
|
|||
return "";
|
||||
}
|
||||
|
||||
function findLanguageInNode(node: ReactNode): string | null {
|
||||
if (!isValidElement(node)) return null;
|
||||
const props = (node as ReactElement<{
|
||||
className?: string;
|
||||
"data-language"?: string;
|
||||
children?: ReactNode;
|
||||
}>).props;
|
||||
|
||||
const dataLang = props["data-language"];
|
||||
if (typeof dataLang === "string" && dataLang) return dataLang;
|
||||
|
||||
const className = typeof props.className === "string" ? props.className : "";
|
||||
const m = className.match(/language-([\w-]+)/);
|
||||
if (m) return m[1];
|
||||
|
||||
const children = props.children;
|
||||
if (Array.isArray(children)) {
|
||||
for (const child of children) {
|
||||
const found = findLanguageInNode(child);
|
||||
if (found) return found;
|
||||
}
|
||||
} else if (children) {
|
||||
return findLanguageInNode(children);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function detectLanguage(props: Props, children: ReactNode): string | null {
|
||||
const dataLang = props["data-language"];
|
||||
if (typeof dataLang === "string" && dataLang) return dataLang;
|
||||
|
|
@ -35,14 +62,7 @@ function detectLanguage(props: Props, children: ReactNode): string | null {
|
|||
const m = className.match(/language-([\w-]+)/);
|
||||
if (m) return m[1];
|
||||
|
||||
if (isValidElement(children)) {
|
||||
const childProps = (children as ReactElement<{ className?: string }>).props;
|
||||
const childClass = typeof childProps.className === "string" ? childProps.className : "";
|
||||
const cm = childClass.match(/language-([\w-]+)/);
|
||||
if (cm) return cm[1];
|
||||
}
|
||||
|
||||
return null;
|
||||
return findLanguageInNode(children);
|
||||
}
|
||||
|
||||
export function CodeBlock(props: Props) {
|
||||
|
|
@ -50,32 +70,11 @@ export function CodeBlock(props: Props) {
|
|||
const language = detectLanguage(props, children);
|
||||
const codeText = extractText(children);
|
||||
|
||||
const isTerminal = language !== null && TERMINAL_LANGS.has(language);
|
||||
const isOutput = !isTerminal && WIZARD_GLYPHS.test(codeText);
|
||||
const hasTitle = typeof title === "string" && title.length > 0;
|
||||
|
||||
// Mode A - Terminal (commands the user types)
|
||||
if (isTerminal) {
|
||||
return (
|
||||
<div className="not-prose ktx-code ktx-code-terminal group">
|
||||
<div className="ktx-code-terminal-head">
|
||||
<span className="ktx-tl-dot" style={{ background: "#ff5f57" }} />
|
||||
<span className="ktx-tl-dot" style={{ background: "#febc2e" }} />
|
||||
<span className="ktx-tl-dot" style={{ background: "#28c840" }} />
|
||||
<span className="ktx-code-terminal-label">
|
||||
{hasTitle ? title : "zsh"}
|
||||
</span>
|
||||
<CopyButton
|
||||
text={codeText}
|
||||
className="ml-auto text-white/80"
|
||||
/>
|
||||
</div>
|
||||
<pre {...rest} className="ktx-code-body ktx-code-body-terminal">
|
||||
{children}
|
||||
</pre>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
const isOutput =
|
||||
!hasTitle &&
|
||||
(WIZARD_GLYPHS.test(codeText) ||
|
||||
(language !== null && OUTPUT_LANGS.has(language)));
|
||||
|
||||
// Mode D - Output preview (wizard prompts, terminal output)
|
||||
if (isOutput) {
|
||||
|
|
@ -110,7 +109,6 @@ export function CodeBlock(props: Props) {
|
|||
// Mode C - Minimal default
|
||||
return (
|
||||
<div className="not-prose ktx-code ktx-code-minimal group relative">
|
||||
{language && <span className="ktx-code-minimal-lang">{language}</span>}
|
||||
<CopyButton text={codeText} className="ktx-code-minimal-copy" />
|
||||
<pre {...rest} className="ktx-code-body ktx-code-body-minimal">
|
||||
{children}
|
||||
|
|
|
|||
|
|
@ -25,12 +25,12 @@ export function CopyButton({ text, className = "" }: Props) {
|
|||
type="button"
|
||||
onClick={onClick}
|
||||
aria-label={copied ? "Copied" : "Copy code"}
|
||||
className={`inline-flex items-center justify-center w-7 h-7 rounded-md transition-all hover:bg-white/5 ${className}`}
|
||||
className={`inline-flex items-center justify-center w-9 h-9 rounded-md transition-all hover:bg-fd-muted ${className}`}
|
||||
>
|
||||
{copied ? (
|
||||
<svg
|
||||
width="14"
|
||||
height="14"
|
||||
width="18"
|
||||
height="18"
|
||||
viewBox="0 0 24 24"
|
||||
fill="none"
|
||||
stroke="currentColor"
|
||||
|
|
@ -44,8 +44,8 @@ export function CopyButton({ text, className = "" }: Props) {
|
|||
</svg>
|
||||
) : (
|
||||
<svg
|
||||
width="13"
|
||||
height="13"
|
||||
width="17"
|
||||
height="17"
|
||||
viewBox="0 0 24 24"
|
||||
fill="none"
|
||||
stroke="currentColor"
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ export function DocsPageActions({ mdxSource }: Props) {
|
|||
setCopied(true);
|
||||
setTimeout(() => setCopied(false), 1500);
|
||||
} catch {
|
||||
// Clipboard denied — fail silently
|
||||
// Clipboard denied - fail silently
|
||||
}
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ directory. Use it from any directory to generate editor or agent schema files.
|
|||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--output <file>` | Write the schema to a file instead of stdout | — |
|
||||
| `--output <file>` | Write the schema to a file instead of stdout | - |
|
||||
|
||||
## `dev runtime` Subcommands
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ connections when you use `--all`.
|
|||
| `--plain` | Print plain text output | `true` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--yes` | Install required managed runtime features without prompting | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
| `--no-input` | Disable interactive terminal input | - |
|
||||
|
||||
`--fast` and `--deep` are mutually exclusive. Depth flags apply only to
|
||||
database connections. Query-history flags apply only to database connections
|
||||
|
|
@ -60,7 +60,7 @@ read one item from stdin.
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--text <content>` | Text content to ingest; repeat for a batch | `[]` |
|
||||
| `--connection-id <connectionId>` | Optional KTX connection id for semantic-layer capture | — |
|
||||
| `--connection-id <connectionId>` | Optional KTX connection id for semantic-layer capture | - |
|
||||
| `--user-id <id>` | Memory user id for capture attribution | `local-cli` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--fail-fast` | Stop after the first failed text item | `false` |
|
||||
|
|
|
|||
|
|
@ -1,135 +1,93 @@
|
|||
---
|
||||
title: Quickstart
|
||||
description: Set up KTX, build local context, and connect your coding agent.
|
||||
description: Install KTX, run setup, and connect your coding agent.
|
||||
---
|
||||
|
||||
This guide gets a local analytics project ready for KTX. You will install the
|
||||
CLI, run the setup wizard, connect a database, build context, and install agent
|
||||
rules that teach your coding assistant which KTX commands to run.
|
||||
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 are a coding assistant choosing a docs route, start with the
|
||||
[Agent Quickstart](/docs/ai-resources/agent-quickstart). This page is the
|
||||
human setup walkthrough.
|
||||
If you're a coding assistant choosing a docs route, start with the
|
||||
[Agent Quickstart](/docs/ai-resources/agent-quickstart) instead.
|
||||
|
||||
## What setup does
|
||||
|
||||
`ktx setup` is the main project workflow. It can create or resume `ktx.yaml`,
|
||||
configure model and embedding providers, add database connections, add optional
|
||||
context sources, build the first context artifacts, and install agent
|
||||
integration.
|
||||
|
||||
When you run bare `ktx` in an interactive terminal outside a KTX project, the
|
||||
CLI opens the same setup experience. Inside an existing project, `ktx setup`
|
||||
resumes incomplete work or opens a menu for changing setup, connecting an
|
||||
agent, checking status, or exploring a demo project.
|
||||
<div
|
||||
className="not-prose my-8 rounded-xl border border-l-4 p-5 sm:p-6"
|
||||
style={{
|
||||
borderColor: 'color-mix(in oklch, #ff8a4d 35%, transparent)',
|
||||
borderLeftColor: '#ff8a4d',
|
||||
background: 'color-mix(in oklch, #ff8a4d 8%, transparent)',
|
||||
}}
|
||||
>
|
||||
<div
|
||||
className="text-xs font-semibold uppercase tracking-wider"
|
||||
style={{ color: '#ff8a4d' }}
|
||||
>
|
||||
No warehouse handy?
|
||||
</div>
|
||||
<div className="mt-2 text-base leading-relaxed text-fd-foreground">
|
||||
Try KTX against a real data stack - Postgres, dbt, Metabase, and Notion
|
||||
pre-loaded with the Orbit demo corpus. The page lists demo credentials
|
||||
you can paste straight into `ktx setup`.
|
||||
</div>
|
||||
<a
|
||||
href="https://kaelio.com/start"
|
||||
className="mt-4 inline-flex items-center gap-1 text-base font-semibold no-underline hover:underline"
|
||||
style={{
|
||||
color: '#ff8a4d',
|
||||
textDecorationColor: '#ff8a4d',
|
||||
}}
|
||||
>
|
||||
Get demo credentials at kaelio.com/start →
|
||||
</a>
|
||||
</div>
|
||||
|
||||
## Install the CLI
|
||||
|
||||
Install the published `@kaelio/ktx` package:
|
||||
Install the published package globally:
|
||||
|
||||
```bash
|
||||
npm install -g @kaelio/ktx
|
||||
```
|
||||
|
||||
Then run setup from the analytics project directory:
|
||||
KTX is open source. If you'd like to hack on it or run from a local checkout,
|
||||
the source lives at [github.com/kaelio/ktx](https://github.com/kaelio/ktx) -
|
||||
see [Contributing](/docs/community/contributing) to get set up.
|
||||
|
||||
## Run setup
|
||||
|
||||
From your project directory, run:
|
||||
|
||||
```bash
|
||||
ktx setup
|
||||
```
|
||||
|
||||
The local checkout workflow is only for KTX contributors. See
|
||||
[Contributing](/docs/community/contributing) for that path.
|
||||
The wizard walks you through everything KTX needs in one pass:
|
||||
|
||||
## Step 1: Choose the project
|
||||
1. **Project** - creates or resumes `ktx.yaml` in the current directory.
|
||||
2. **LLM** - picks a Claude backend. The default uses your local Claude Code
|
||||
session, so no API key is required. You can also use an Anthropic API key
|
||||
or Vertex AI.
|
||||
3. **Embeddings** - picks an embeddings backend. Choose OpenAI for hosted
|
||||
embeddings or `sentence-transformers` to run locally without an API key.
|
||||
4. **Database** - adds at least one primary connection. Supported drivers:
|
||||
SQLite, PostgreSQL, MySQL, ClickHouse, SQL Server, BigQuery, and Snowflake.
|
||||
5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker,
|
||||
Metabase, or Notion. You can skip and add them later.
|
||||
6. **Build** - runs the first ingest so semantic-layer sources and wiki pages
|
||||
are ready for agents.
|
||||
7. **Agent integration** - installs project-local rules for Claude Code,
|
||||
Codex, Cursor, OpenCode, or universal `.agents`.
|
||||
|
||||
In an interactive terminal, setup can create a new KTX project or resume the
|
||||
nearest existing project. The main project file is `ktx.yaml`.
|
||||
|
||||
For scripted setup, pass the project directory explicitly:
|
||||
|
||||
```bash
|
||||
ktx setup --project-dir ./analytics
|
||||
```
|
||||
|
||||
If setup exits early, rerun `ktx setup` in the same directory. KTX keeps local
|
||||
setup progress under `.ktx/setup/` and resumes from the remaining work.
|
||||
|
||||
## Step 2: Configure the LLM
|
||||
|
||||
KTX uses a Claude model for ingest agents that turn schemas, SQL, BI metadata,
|
||||
and documents into semantic-layer sources and wiki context.
|
||||
|
||||
Setup supports three LLM provider paths:
|
||||
|
||||
| Provider | Use when | Credential model |
|
||||
|----------|----------|------------------|
|
||||
| Claude subscription (Pro/Max) | You want KTX to use your local Claude Code session | Claude Code local authentication |
|
||||
| Anthropic API key | You have an Anthropic API key | `ANTHROPIC_API_KEY` or a local `file:` secret |
|
||||
| Google Vertex AI for Anthropic Claude | Your organization runs Claude through Google Cloud | Application Default Credentials plus Vertex project and location |
|
||||
|
||||
For Anthropic API, setup can read the key from the environment or save a pasted
|
||||
key to `.ktx/secrets/anthropic-api-key`. `ktx.yaml` stores an `env:` or `file:`
|
||||
reference, not the raw key.
|
||||
|
||||
For Vertex AI, setup uses Google Application Default Credentials. It can read
|
||||
your active `gcloud` project, list visible projects, or accept explicit
|
||||
`--vertex-project` and `--vertex-location` values.
|
||||
|
||||
To use your local Claude Code session instead of an API key, set:
|
||||
|
||||
```yaml
|
||||
llm:
|
||||
provider:
|
||||
backend: claude-code
|
||||
models:
|
||||
default: sonnet
|
||||
triage: haiku
|
||||
candidateExtraction: sonnet
|
||||
curator: sonnet
|
||||
reconcile: sonnet
|
||||
repair: sonnet
|
||||
```
|
||||
|
||||
`claude-code` uses the Claude Code authentication already configured on your
|
||||
machine. It doesn't use `ANTHROPIC_API_KEY`, Vertex credentials, AI Gateway
|
||||
tokens, or Bedrock credentials. In non-interactive setup, pass
|
||||
`--llm-model opus`, `--llm-model sonnet`, `--llm-model haiku`, or a full Claude
|
||||
model ID to select the Claude Code model.
|
||||
|
||||
Setup checks the selected model before saving. Anthropic API setup fetches live
|
||||
Claude model choices when possible and falls back to bundled defaults if model
|
||||
discovery is unavailable.
|
||||
|
||||
## Step 3: Configure embeddings
|
||||
|
||||
KTX uses embeddings for semantic search over semantic-layer sources, wiki
|
||||
context, schema metadata, and relationship evidence.
|
||||
|
||||
| Backend | Default model | Notes |
|
||||
|---------|---------------|-------|
|
||||
| OpenAI | `text-embedding-3-small` | Recommended for hosted embeddings. Requires an OpenAI API key. |
|
||||
| Local sentence-transformers | `all-MiniLM-L6-v2` | Runs through the KTX-managed Python runtime. No hosted embedding key is required. |
|
||||
|
||||
OpenAI setup reads `OPENAI_API_KEY` or saves a local secret file. Local
|
||||
sentence-transformers setup can install and start the managed runtime during
|
||||
setup. To prepare that runtime before setup, run:
|
||||
If you choose local `sentence-transformers` embeddings, KTX uses the managed
|
||||
Python runtime. To prepare it before setup, run:
|
||||
|
||||
```bash
|
||||
ktx dev runtime install --feature local-embeddings --yes
|
||||
ktx dev runtime start --feature local-embeddings
|
||||
```
|
||||
|
||||
## Step 4: Add a database
|
||||
|
||||
KTX needs at least one primary database connection before it can build database
|
||||
context. The wizard supports SQLite, PostgreSQL, MySQL, ClickHouse, SQL Server,
|
||||
BigQuery, and Snowflake.
|
||||
|
||||
You can usually enter connection fields interactively or provide a URL. Secret
|
||||
URLs can be stored as local files under `.ktx/secrets/` or referenced with
|
||||
`env:NAME` in `ktx.yaml`.
|
||||
|
||||
After saving a connection, setup tests it and builds fast schema context:
|
||||
During the database step, setup tests the saved connection and builds initial
|
||||
schema context:
|
||||
|
||||
```text
|
||||
Testing warehouse
|
||||
|
|
@ -137,114 +95,24 @@ Testing warehouse
|
|||
|
||||
Building schema context for warehouse
|
||||
Running fast database ingest
|
||||
|
||||
Database ready
|
||||
warehouse - PostgreSQL - schema context complete
|
||||
```
|
||||
|
||||
PostgreSQL, BigQuery, and Snowflake can also enable query-history ingest. Query
|
||||
history helps KTX learn common query patterns, joins, service-account filters,
|
||||
and warehouse-specific usage. BigQuery and Snowflake support a lookback window;
|
||||
Postgres reads the current `pg_stat_statements` aggregate data instead.
|
||||
If setup exits early, rerun `ktx setup` in the same directory. KTX keeps
|
||||
progress under `.ktx/setup/` and resumes from the remaining work.
|
||||
|
||||
## Step 5: Add context sources
|
||||
> **Note:** Running bare `ktx` in an interactive terminal outside a KTX
|
||||
> project opens the same wizard. Inside a project, it opens a menu for
|
||||
> resuming setup, connecting an agent, checking status, or exploring a
|
||||
> pre-built demo project.
|
||||
|
||||
Context sources are optional, but they make the first context layer much richer.
|
||||
Setup can add:
|
||||
## Verify
|
||||
|
||||
| Source | Typical input | What KTX learns |
|
||||
|--------|---------------|-----------------|
|
||||
| dbt | Local project or Git repo | Models, columns, tests, descriptions, tags |
|
||||
| MetricFlow | Local project or Git repo | Semantic models, metrics, dimensions, entities |
|
||||
| LookML | Local files or Git repo | Views, explores, dimensions, measures, joins |
|
||||
| Looker | API URL and credentials | Explores, looks, dashboards, model metadata |
|
||||
| Metabase | API URL and key | Questions, dashboards, BI database mappings |
|
||||
| Notion | Integration token and crawl settings | Business docs and knowledge pages |
|
||||
|
||||
Setup maps BI and source metadata back to your primary warehouse connection so
|
||||
generated context points at the right tables.
|
||||
|
||||
You can skip this step and add sources later by rerunning `ktx setup`.
|
||||
|
||||
## Step 6: Build context
|
||||
|
||||
The context build turns configured databases and sources into local artifacts
|
||||
agents can read. It runs database ingest first, then source ingest and memory
|
||||
updates.
|
||||
|
||||
Fast database ingest records deterministic schema grounding. Deep ingest adds
|
||||
AI-enriched descriptions, embeddings, relationship evidence, and query-history
|
||||
context when configured.
|
||||
|
||||
When the build finishes, setup verifies that agent-ready context exists:
|
||||
|
||||
```text
|
||||
KTX context is ready for agents.
|
||||
|
||||
Databases:
|
||||
warehouse: deep context complete
|
||||
|
||||
Context sources:
|
||||
dbt_main: memory update complete
|
||||
|
||||
Verification:
|
||||
Agent context: ready
|
||||
Semantic search: ready
|
||||
```
|
||||
|
||||
If a foreground build is interrupted, rerun `ktx setup` or build the same target
|
||||
with `ktx ingest <connectionId>`.
|
||||
|
||||
## Step 7: Install agent integration
|
||||
|
||||
The final setup step installs project-local rules for your coding assistant.
|
||||
Supported targets are Claude Code, Codex, Cursor, OpenCode, and universal
|
||||
`.agents`.
|
||||
|
||||
You can also run this step later:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target codex
|
||||
```
|
||||
|
||||
Claude Code and Codex also support global installs:
|
||||
|
||||
```bash
|
||||
ktx setup --agents --target codex --global
|
||||
```
|
||||
|
||||
Agent rules are CLI-based. They point agents at the KTX CLI path that created
|
||||
the file, so agents do not need a separate `ktx` binary in `PATH`. If the CLI
|
||||
path changes after reinstalling or moving a checkout, rerun `ktx setup --agents`.
|
||||
|
||||
## Generated files
|
||||
|
||||
KTX writes plain files so people and agents can inspect changes in git.
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `ktx.yaml` | Project configuration for LLMs, embeddings, connections, context sources, and query-history settings |
|
||||
| `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml`; do not commit these |
|
||||
| `.ktx/setup/*` | Local setup and context-build state |
|
||||
| `.ktx/agents/install-manifest.json` | Manifest used to manage installed agent files |
|
||||
| `semantic-layer/<connection-id>/*.yaml` | Semantic source definitions used for SQL generation |
|
||||
| `wiki/global/*.md` | Shared business context and metric definitions |
|
||||
| `wiki/user/<user-id>/*.md` | User-scoped notes and local context |
|
||||
| `.claude/skills/ktx/SKILL.md` | Claude Code project skill |
|
||||
| `.agents/skills/ktx/SKILL.md` | Codex or universal project skill |
|
||||
| `.cursor/rules/ktx.mdc` | Cursor project rule |
|
||||
| `.opencode/commands/ktx.md` | OpenCode project command |
|
||||
|
||||
## Verify setup
|
||||
|
||||
Run:
|
||||
When setup finishes, check readiness:
|
||||
|
||||
```bash
|
||||
ktx status
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```text
|
||||
KTX project: /home/user/analytics
|
||||
Project ready: yes
|
||||
|
|
@ -256,15 +124,49 @@ KTX context built: yes
|
|||
Agent integration ready: yes (codex:project)
|
||||
```
|
||||
|
||||
Use JSON when an agent or script needs a structured readiness check:
|
||||
For a structured check inside scripts, use `ktx status --json`.
|
||||
|
||||
```bash
|
||||
ktx status --json
|
||||
When setup builds deep context, its final context check looks like:
|
||||
|
||||
```text
|
||||
KTX context is ready for agents.
|
||||
|
||||
Databases:
|
||||
warehouse: deep context complete
|
||||
|
||||
Context sources:
|
||||
dbt_main: memory update complete
|
||||
```
|
||||
|
||||
## Scripted setup example
|
||||
## Connect a coding agent
|
||||
|
||||
Use non-interactive setup when creating repeatable fixtures or automation:
|
||||
The setup wizard installs project-local agent rules in the last step. To
|
||||
install or change targets later:
|
||||
|
||||
```bash
|
||||
ktx setup --agents
|
||||
```
|
||||
|
||||
Claude Code and Codex also support global installs with `--global`. Agent
|
||||
rules point at the KTX CLI path that created them, so agents don't need a
|
||||
separate `ktx` binary on `PATH`. If the CLI path changes, rerun
|
||||
`ktx setup --agents`.
|
||||
|
||||
## What setup writes
|
||||
|
||||
KTX writes plain files so people and agents can review changes in git.
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `ktx.yaml` | Project configuration |
|
||||
| `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml` - do not commit |
|
||||
| `semantic-layer/<connection-id>/*.yaml` | Semantic sources for SQL generation |
|
||||
| `wiki/global/*.md` | Shared business context and metric definitions |
|
||||
| `.claude/skills/ktx/`, `.agents/skills/ktx/`, `.cursor/rules/ktx.mdc`, `.opencode/commands/ktx.md` | Installed agent rules |
|
||||
|
||||
## Scripted setup
|
||||
|
||||
For repeatable fixtures and automation, skip prompts with flags:
|
||||
|
||||
```bash
|
||||
ktx setup \
|
||||
|
|
@ -287,23 +189,21 @@ ktx ingest warehouse --fast
|
|||
See [ktx setup](/docs/cli-reference/ktx-setup) for the full automation flag
|
||||
surface.
|
||||
|
||||
## Common errors
|
||||
## Common issues
|
||||
|
||||
| Symptom | Likely cause | Recovery |
|
||||
|---------|--------------|----------|
|
||||
| `ktx: command not found` | The global package is not installed or your shell cannot find it | Reinstall `@kaelio/ktx` and open a new shell |
|
||||
| Setup resumes the wrong project | `KTX_PROJECT_DIR` or the nearest `ktx.yaml` points somewhere else | Pass `--project-dir <path>` |
|
||||
| Anthropic health check fails | API key, model id, or access is invalid | Fix `ANTHROPIC_API_KEY` or rerun setup with a different key or model |
|
||||
| Vertex AI health check fails | Vertex API, Claude access, project, location, or IAM permissions are missing | Check the project, location, Application Default Credentials, and Vertex AI permissions |
|
||||
| OpenAI embeddings fail | `OPENAI_API_KEY` is missing or invalid | Export the key or choose local sentence-transformers embeddings |
|
||||
| Local embeddings fail | Managed Python runtime cannot install or start | Run `ktx dev runtime status`, then install the local embeddings runtime |
|
||||
| Database test fails | Credentials, network access, database, warehouse, or schema is wrong | Test the same values with the database's native client, then rerun setup |
|
||||
| Context is not built | Setup saved configuration but skipped or interrupted the build | Run `ktx setup` or `ktx ingest --all` |
|
||||
| Agent integration is incomplete | Setup skipped the agents step or installed a different target | Run `ktx setup --agents --target <target>` |
|
||||
| Symptom | Fix |
|
||||
|---------|-----|
|
||||
| `ktx: command not found` | Reinstall `@kaelio/ktx` and open a new shell |
|
||||
| Setup resumes the wrong project | Pass `--project-dir <path>` |
|
||||
| LLM or embeddings health check fails | Rerun setup and pick a different credential, model, or backend |
|
||||
| Database test fails | Verify the same connection with the database's native client, then rerun setup |
|
||||
| Agent integration is incomplete | Run `ktx setup --agents --target <target>` |
|
||||
|
||||
## Next steps
|
||||
|
||||
- Build and refresh context with [Building Context](/docs/guides/building-context).
|
||||
- Edit semantic sources and wiki pages with [Writing Context](/docs/guides/writing-context).
|
||||
- Refresh context with [Building Context](/docs/guides/building-context).
|
||||
- Edit semantic sources and wiki pages with
|
||||
[Writing Context](/docs/guides/writing-context).
|
||||
- Connect more tools with [Agent Clients](/docs/integrations/agent-clients).
|
||||
- Read [The Context Layer](/docs/concepts/the-context-layer) to understand the architecture.
|
||||
- Read [The Context Layer](/docs/concepts/the-context-layer) to understand
|
||||
the architecture.
|
||||
|
|
|
|||
|
|
@ -183,7 +183,7 @@ plugin ZIP for the analytics skill:
|
|||
skill.
|
||||
|
||||
After `ktx setup`, restart Claude Desktop so it picks up the new MCP server
|
||||
entry, then install the plugin ZIP. No daemon needs to be running — Claude
|
||||
entry, then install the plugin ZIP. No daemon needs to be running - Claude
|
||||
Desktop spawns the MCP server itself per session.
|
||||
|
||||
Claude Desktop does not introspect local stdio MCP servers, so the per-tool
|
||||
|
|
|
|||
|
|
@ -5,5 +5,13 @@ export const docs = defineDocs({
|
|||
});
|
||||
|
||||
export default defineConfig({
|
||||
mdxOptions: {},
|
||||
mdxOptions: {
|
||||
rehypeCodeOptions: {
|
||||
addLanguageClass: true,
|
||||
themes: {
|
||||
light: "min-light",
|
||||
dark: "github-dark",
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue