From b507ff171de5d56bcef2002c81233893311d8598 Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Mon, 18 May 2026 19:22:19 +0200 Subject: [PATCH] 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 --- docs-site/app/global.css | 92 +---- docs-site/components/code-block.tsx | 68 ++-- docs-site/components/copy-button.tsx | 10 +- docs-site/components/docs-page-actions.tsx | 2 +- .../content/docs/cli-reference/ktx-dev.mdx | 2 +- .../content/docs/cli-reference/ktx-ingest.mdx | 4 +- .../docs/getting-started/quickstart.mdx | 346 +++++++----------- .../docs/integrations/agent-clients.mdx | 2 +- docs-site/source.config.ts | 10 +- 9 files changed, 191 insertions(+), 345 deletions(-) diff --git a/docs-site/app/global.css b/docs-site/app/global.css index 08bd9b83..e7e2c5b2 100644 --- a/docs-site/app/global.css +++ b/docs-site/app/global.css @@ -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 { diff --git a/docs-site/components/code-block.tsx b/docs-site/components/code-block.tsx index 7d6a22af..9c9d71ec 100644 --- a/docs-site/components/code-block.tsx +++ b/docs-site/components/code-block.tsx @@ -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 ( -
-
- - - - - {hasTitle ? title : "zsh"} - - -
- 
-          {children}
-
-
- ); - } + 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 (
- {language && {language}} 
         {children}
diff --git a/docs-site/components/copy-button.tsx b/docs-site/components/copy-button.tsx
index 876f5de0..c0dd1f31 100644
--- a/docs-site/components/copy-button.tsx
+++ b/docs-site/components/copy-button.tsx
@@ -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 ? (
         
       ) : (
          setCopied(false), 1500);
     } catch {
-      // Clipboard denied — fail silently
+      // Clipboard denied - fail silently
     }
   };
 
diff --git a/docs-site/content/docs/cli-reference/ktx-dev.mdx b/docs-site/content/docs/cli-reference/ktx-dev.mdx
index 50d4ea77..efa3d74b 100644
--- a/docs-site/content/docs/cli-reference/ktx-dev.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-dev.mdx
@@ -36,7 +36,7 @@ directory. Use it from any directory to generate editor or agent schema files.
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--output ` | Write the schema to a file instead of stdout | — |
+| `--output ` | Write the schema to a file instead of stdout | - |
 
 ## `dev runtime` Subcommands
 
diff --git a/docs-site/content/docs/cli-reference/ktx-ingest.mdx b/docs-site/content/docs/cli-reference/ktx-ingest.mdx
index 9d94cd88..49485d10 100644
--- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx
@@ -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 ` | Text content to ingest; repeat for a batch | `[]` |
-| `--connection-id ` | Optional KTX connection id for semantic-layer capture | — |
+| `--connection-id ` | Optional KTX connection id for semantic-layer capture | - |
 | `--user-id ` | Memory user id for capture attribution | `local-cli` |
 | `--json` | Print JSON output | `false` |
 | `--fail-fast` | Stop after the first failed text item | `false` |
diff --git a/docs-site/content/docs/getting-started/quickstart.mdx b/docs-site/content/docs/getting-started/quickstart.mdx
index 0118522c..23c77827 100644
--- a/docs-site/content/docs/getting-started/quickstart.mdx
+++ b/docs-site/content/docs/getting-started/quickstart.mdx
@@ -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.
+

+  

+    No warehouse handy?
+  

+  

+    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`.
+  

+  
+    Get demo credentials at kaelio.com/start →
+  
+

 
 ## 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 `.
-
-## 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//*.yaml` | Semantic source definitions used for SQL generation |
-| `wiki/global/*.md` | Shared business context and metric definitions |
-| `wiki/user//*.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//*.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 ` |
-| 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 ` |
+| Symptom | Fix |
+|---------|-----|
+| `ktx: command not found` | Reinstall `@kaelio/ktx` and open a new shell |
+| Setup resumes the wrong project | Pass `--project-dir ` |
+| 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 ` |
 
 ## 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.
diff --git a/docs-site/content/docs/integrations/agent-clients.mdx b/docs-site/content/docs/integrations/agent-clients.mdx
index 1934c978..82c25220 100644
--- a/docs-site/content/docs/integrations/agent-clients.mdx
+++ b/docs-site/content/docs/integrations/agent-clients.mdx
@@ -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
diff --git a/docs-site/source.config.ts b/docs-site/source.config.ts
index 71c0f614..5af0fa2b 100644
--- a/docs-site/source.config.ts
+++ b/docs-site/source.config.ts
@@ -5,5 +5,13 @@ export const docs = defineDocs({
 });
 
 export default defineConfig({
-  mdxOptions: {},
+  mdxOptions: {
+    rehypeCodeOptions: {
+      addLanguageClass: true,
+      themes: {
+        light: "min-light",
+        dark: "github-dark",
+      },
+    },
+  },
 });