chore: move docs site workspace

2026-06-10 08:05:14 +02:00 · 2026-05-11 16:53:42 +02:00 · 2026-05-11 16:53:42 +02:00 · a46563bb01
commit a46563bb01
parent 0ae9b6effd
52 changed files with 3 additions and 3 deletions
--- a/docs-site/content/docs/cli-reference/ktx-agent.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-agent.mdx
@ -0,0 +1,126 @@
+---
+title: "ktx agent"
+description: "Machine-readable commands for coding agents."
+---
+
+Hidden commands that provide machine-readable JSON output for coding agents. These are the commands that agent integrations (Claude Code, Cursor, Codex, OpenCode) call under the hood — you typically won't use them directly.
+
+All `ktx agent` subcommands require `--json` and produce structured JSON output on stdout.
+
+## Usage
+
+```bash
+ktx agent <subcommand> --json [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `tools` | Print available agent-facing KTX tools |
+| `context` | Print project context for agent planning |
+| `sl list` | List semantic-layer sources |
+| `sl read <sourceName>` | Read one semantic-layer source |
+| `sl query` | Run a semantic-layer query from a JSON file |
+| `wiki search <query>` | Search KTX wiki pages |
+| `wiki read <pageId>` | Read one KTX wiki page |
+| `sql execute` | Execute read-only SQL with a row limit |
+
+## Options
+
+### `agent tools`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+
+### `agent context`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+
+### `agent sl list`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+| `--connection-id <id>` | Filter by connection id | — |
+| `--query <text>` | Search source names and descriptions | — |
+
+### `agent sl read`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+| `--connection-id <id>` | Connection id containing the source | — |
+
+### `agent sl query`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+| `--connection-id <id>` | Connection id for execution (required) | — |
+| `--query-file <path>` | JSON semantic-layer query file (required) | — |
+| `--execute` | Execute the compiled query against the connection | `false` |
+| `--max-rows <number>` | Maximum rows to return when executing (1-1000) | — |
+
+### `agent wiki search`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+| `--limit <number>` | Maximum search results | `10` |
+
+### `agent wiki read`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+
+### `agent sql execute`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output (required) | — |
+| `--connection-id <id>` | Connection id for execution (required) | — |
+| `--sql-file <path>` | SQL file to execute (required) | — |
+| `--max-rows <number>` | Maximum rows to return, 1-1000 (required) | — |
+
+## Examples
+
+```bash
+# List available tools
+ktx agent tools --json
+
+# Get project context for planning
+ktx agent context --json
+
+# List semantic sources
+ktx agent sl list --json
+
+# Search semantic sources by name
+ktx agent sl list --json --query "revenue"
+
+# Read a semantic source
+ktx agent sl read orders --json --connection-id my-warehouse
+
+# Run a semantic-layer query from a file
+ktx agent sl query --json \
+  --connection-id my-warehouse \
+  --query-file /tmp/query.json \
+  --execute \
+  --max-rows 100
+
+# Search wiki pages
+ktx agent wiki search "churn definition" --json
+
+# Read a specific wiki page
+ktx agent wiki read page-abc123 --json
+
+# Execute read-only SQL
+ktx agent sql execute --json \
+  --connection-id my-warehouse \
+  --sql-file /tmp/query.sql \
+  --max-rows 500
+```
--- a/docs-site/content/docs/cli-reference/ktx-connection.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-connection.mdx
@ -0,0 +1,149 @@
+---
+title: "ktx connection"
+description: "Add, list, test, and map data sources."
+---
+
+Manage database and source connections in your KTX project. Connections define how KTX reaches your data warehouse, BI tools, and context sources.
+
+## Usage
+
+```bash
+ktx connection <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `list` | List configured connections |
+| `test <connectionId>` | Test a configured connection |
+| `add <driver> <connectionId>` | Add or replace a configured connection |
+| `remove <connectionId>` | Remove a configured connection from `ktx.yaml` |
+| `map <sourceConnectionId>` | Refresh and validate BI-to-warehouse mappings |
+| `mapping list <connectionId>` | List Metabase database mappings |
+| `mapping set <connectionId> <field> <assignment>` | Set a Metabase or Looker warehouse mapping |
+| `mapping apply-bulk <connectionId>` | Apply mappings from JSON |
+| `mapping set-sync-enabled <connectionId> <dbId>` | Enable or disable sync for one Metabase database |
+| `mapping sync-state get <connectionId>` | Read sync-state selection |
+| `mapping sync-state set <connectionId>` | Write sync-state selection |
+| `mapping refresh <connectionId>` | Refresh Metabase database mappings |
+| `mapping validate <connectionId>` | Validate Metabase database mappings |
+| `mapping clear <connectionId> [dbId]` | Clear Metabase database mappings |
+| `metabase setup` | Guided setup for a Metabase connection |
+| `notion pick <connectionId>` | Pick Notion root pages for a configured Notion connection |
+
+## Options
+
+### `connection add`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--url <url>` | Connection URL, `env:NAME`, or `file:/path` reference | — |
+| `--schema <schema>` | Schema to include; repeatable | — |
+| `--readonly` | Mark the connection as read-only | `false` |
+| `--force` | Replace an existing connection | `false` |
+| `--allow-literal-credentials` | Allow writing a literal credential URL to `ktx.yaml` | `false` |
+
+#### Notion-specific options for `connection add`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--token-env <name>` | Environment variable containing Notion auth token | — |
+| `--token-file <path>` | File containing Notion auth token | — |
+| `--crawl-mode <mode>` | Notion crawl mode (`all_accessible` or `selected_roots`) | `selected_roots` |
+| `--root-page-id <id>` | Root page to crawl; repeatable | — |
+| `--root-database-id <id>` | Root database to crawl; repeatable | — |
+| `--root-data-source-id <id>` | Root data source to crawl; repeatable | — |
+| `--max-pages <n>` | Maximum pages per run | — |
+| `--max-knowledge-creates <n>` | Maximum knowledge creates per run | — |
+| `--max-knowledge-updates <n>` | Maximum knowledge updates per run | — |
+
+### `connection remove`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--force` | Remove without prompting | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `connection map`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output | `false` |
+
+### `connection mapping` subcommands
+
+| Flag | Subcommand | Description | Default |
+|------|-----------|-------------|---------|
+| `--json` | `list`, `sync-state get` | Print JSON output | `false` |
+| `--file <path>` | `apply-bulk` | JSON mapping file (required) | — |
+| `--enabled <value>` | `set-sync-enabled` | `true` or `false` (required) | — |
+| `--mode <mode>` | `sync-state set` | `ALL`, `ONLY`, or `EXCEPT` (required) | — |
+| `--collections <ids>` | `sync-state set` | Comma-separated collection ids | — |
+| `--items <ids>` | `sync-state set` | Comma-separated item ids | — |
+| `--tag-names <names>` | `sync-state set` | Comma-separated tag names | — |
+| `--auto-accept` | `refresh` | Accept refresh changes without prompting | `false` |
+
+### `connection metabase setup`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--id <connectionId>` | KTX connection id to write | — |
+| `--url <url>` | Metabase API URL | — |
+| `--api-key <key>` | Metabase API key | — |
+| `--mint-api-key` | Mint a Metabase API key with credentials | `false` |
+| `--username <email>` | Metabase admin username for API-key minting | — |
+| `--password <password>` | Metabase admin password for API-key minting | — |
+| `--map <id=target>` | Assign a Metabase database id to a warehouse connection; repeatable | — |
+| `--sync <metabaseDatabaseId>` | Enable sync for a discovered database; repeatable | — |
+| `--sync-mode <mode>` | Metabase sync selection mode (`ALL`, `ONLY`, or `EXCEPT`) | `ALL` |
+| `--run-ingest` | Run ingest after setup | `false` |
+| `--yes` | Confirm and apply setup changes without prompting | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `connection notion pick`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--no-input` | Disable interactive terminal input | — |
+| `--root-page-id <id>` | Root page UUID to crawl; repeatable (required with `--no-input`) | — |
+
+## Examples
+
+```bash
+# List all configured connections
+ktx connection list
+
+# Add a Postgres connection using an environment variable
+ktx connection add postgres my-warehouse --url "env:DATABASE_URL"
+
+# Add a Postgres connection with specific schemas
+ktx connection add postgres analytics --url "env:PG_URL" --schema public --schema analytics
+
+# Add a read-only Snowflake connection
+ktx connection add snowflake sf-prod --url "env:SNOWFLAKE_URL" --readonly
+
+# Test a connection
+ktx connection test my-warehouse
+
+# Remove a connection
+ktx connection remove old-warehouse
+
+# Add a Notion source connection
+ktx connection add notion my-notion \
+  --token-env NOTION_TOKEN \
+  --crawl-mode selected_roots \
+  --root-page-id abc123def456...
+
+# Run guided Metabase setup
+ktx connection metabase setup --url https://metabase.example.com
+
+# Map a BI database to a warehouse connection
+ktx connection mapping set metabase-prod databaseMappings 1=my-warehouse
+
+# Refresh Metabase mappings
+ktx connection mapping refresh metabase-prod --auto-accept
+
+# Pick Notion root pages interactively
+ktx connection notion pick my-notion
+```
--- a/docs-site/content/docs/cli-reference/ktx-dev.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-dev.mdx
@ -0,0 +1,147 @@
+---
+title: "ktx dev"
+description: "Low-level diagnostics, scans, adapter commands, and mapping tools."
+---
+
+Hidden commands for low-level project management, diagnostics, direct adapter control, and shell completion. Most users interact with these through higher-level commands like [`ktx ingest`](/docs/cli-reference/ktx-ingest) and [`ktx setup`](/docs/cli-reference/ktx-setup), but `ktx dev` provides direct access when you need fine-grained control.
+
+## Usage
+
+```bash
+ktx dev <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `init [directory]` | Initialize a Git-backed KTX project directory |
+| `doctor` | Check KTX setup, project, and demo readiness |
+| `doctor setup` | Check KTX install, build, and local runtime readiness |
+| `scan` | Run or inspect standalone connection scans |
+| `ingest run` | Run local ingest for one configured connection and source adapter |
+| `ingest status [runId]` | Print status for a stored local ingest run |
+| `ingest watch [runId]` | Open a stored ingest visual report |
+| `ingest replay <runId>` | Replay a stored ingest run through memory-flow output |
+| `mapping` | Manage Metabase warehouse mappings (same as `ktx connection mapping`) |
+| `completion zsh` | Generate zsh completion script |
+
+## Options
+
+### `dev init`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--name <name>` | Project name written to `ktx.yaml` | — |
+| `--force` | Rewrite `ktx.yaml` and scaffold files in an existing project | `false` |
+
+### `dev doctor`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `dev doctor setup`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `dev scan`
+
+See [`ktx scan`](/docs/cli-reference/ktx-scan) for the full scan command reference.
+
+### `dev ingest run`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <connectionId>` | KTX connection id (required) | — |
+| `--adapter <adapter>` | Ingest source adapter name (required) | — |
+| `--source-dir <path>` | Directory containing source files | — |
+| `--database-introspection-url <url>` | Daemon URL for live-database introspection | — |
+| `--debug-llm-request-file <path>` | Write sanitized LLM request structure to a JSONL file | — |
+| `--plain` | Print plain text output | `false` |
+| `--json` | Print JSON output | `false` |
+| `--viz` | Render memory-flow TUI output | `false` |
+| `--no-input` | Disable interactive terminal input for visualization | — |
+
+### `dev ingest status`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--report-file <path>` | Bundle ingest report JSON file to render | — |
+| `--plain` | Print plain text output | `false` |
+| `--json` | Print JSON output | `false` |
+| `--viz` | Render memory-flow TUI output | `false` |
+| `--no-input` | Disable interactive terminal input for visualization | — |
+
+### `dev ingest watch`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--report-file <path>` | Bundle ingest report JSON file to render | — |
+| `--plain` | Print plain text output | `false` |
+| `--json` | Print JSON output | `false` |
+| `--viz` | Render memory-flow TUI output (the default unless `--plain` or `--json` is set) | `true` |
+| `--no-input` | Disable interactive terminal input for visualization | — |
+
+### `dev ingest replay`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--report-file <path>` | Bundle ingest report JSON file to render | — |
+| `--plain` | Print plain text output | `false` |
+| `--json` | Print JSON output | `false` |
+| `--viz` | Render memory-flow TUI output | `false` |
+| `--no-input` | Disable interactive terminal input for visualization | — |
+
+### `dev completion zsh`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--install` | Install zsh completion into `~/.zfunc` and update `~/.zshrc` | `false` |
+
+## Examples
+
+```bash
+# Initialize a new KTX project
+ktx dev init
+
+# Initialize in a specific directory with a project name
+ktx dev init ./my-project --name "Analytics Context"
+
+# Re-initialize an existing project
+ktx dev init --force
+
+# Check project readiness
+ktx dev doctor
+
+# Check CLI install readiness
+ktx dev doctor setup
+
+# Run a low-level ingest with a specific adapter
+ktx dev ingest run --connection-id my-dbt --adapter dbt
+
+# Run ingest from a specific source directory
+ktx dev ingest run \
+  --connection-id my-dbt \
+  --adapter dbt \
+  --source-dir ./dbt-project
+
+# View ingest status with the visual TUI
+ktx dev ingest watch run-abc123
+
+# Replay a stored ingest session
+ktx dev ingest replay run-abc123
+
+# View ingest status from a report file
+ktx dev ingest status --report-file /tmp/ingest-report.json
+
+# Generate zsh completions
+ktx dev completion zsh
+
+# Install zsh completions
+ktx dev completion zsh --install
+```
--- a/docs-site/content/docs/cli-reference/ktx-ingest.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-ingest.mdx
@ -0,0 +1,70 @@
+---
+title: "ktx ingest"
+description: "Build and refresh context from configured sources."
+---
+
+Ingest context from your configured sources — dbt, Looker, Metabase, MetricFlow, LookML, or Notion. The ingest process extracts metadata from your tools, then uses an LLM agent to reconcile it with existing context, writing semantic sources and knowledge pages to your project.
+
+## Usage
+
+```bash
+ktx ingest [connectionId] [options]
+ktx ingest <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `status [runId]` | Print status for the latest or selected public ingest run |
+| `watch [runId]` | Open the latest or selected public ingest visual report |
+
+## Options
+
+### `ingest` (run)
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--all` | Ingest every eligible configured source | `false` |
+| `--json` | Print JSON output | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `ingest status`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### `ingest watch`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output instead of the visual report | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+## Examples
+
+```bash
+# Ingest from a specific connection
+ktx ingest my-dbt-source
+
+# Ingest from all eligible sources
+ktx ingest --all
+
+# Check the status of the latest ingest
+ktx ingest status
+
+# Check the status of a specific ingest run
+ktx ingest status run-abc123
+
+# Watch the latest ingest report
+ktx ingest watch
+
+# Get ingest status as JSON
+ktx ingest status --json
+```
+
+## Low-level ingest commands
+
+For adapter-level control, use `ktx dev ingest`. See [`ktx dev`](/docs/cli-reference/ktx-dev) for the full low-level ingest surface including `run`, `status`, `watch`, and `replay` with output mode options (`--plain`, `--json`, `--viz`).
--- a/docs-site/content/docs/cli-reference/ktx-scan.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-scan.mdx
@ -0,0 +1,145 @@
+---
+title: "ktx scan"
+description: "Run or inspect database scans."
+---
+
+Discover your database schema — tables, columns, types, constraints, and relationships. Scanning is the first step in building context: KTX needs to understand your warehouse structure before it can build semantic sources.
+
+Scan commands live under `ktx dev scan`. See also the [Building Context](/docs/guides/building-context) guide for a walkthrough.
+
+## Usage
+
+```bash
+ktx dev scan <connectionId> [options]
+ktx dev scan <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `status <runId>` | Print status for a local scan run |
+| `report <runId>` | Print a local scan report |
+| `relationships <runId>` | Print relationship artifacts for a local scan run |
+| `relationship-apply <runId>` | Apply accepted relationship review decisions as manual manifest joins |
+| `relationship-feedback` | Export persisted relationship review decisions as calibration labels |
+| `relationship-calibration` | Summarize relationship feedback labels against current score thresholds |
+| `relationship-thresholds` | Evaluate relationship feedback labels for offline threshold advice |
+
+## Options
+
+### `scan` (run)
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mode <mode>` | Scan mode: `structural`, `enriched`, or `relationships` | `structural` |
+| `--dry-run` | Run without writing scan results | `false` |
+| `--database-introspection-url <url>` | Daemon URL for live-database introspection | — |
+
+### `scan report`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print the raw scan report JSON | `false` |
+
+### `scan relationships`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--status <status>` | Filter by status: `accepted`, `review`, `rejected`, `skipped`, or `all` | `review` |
+| `--limit <count>` | Maximum relationships to print per status | `25` |
+| `--accept <candidateId>` | Record an accepted decision for a relationship candidate | — |
+| `--reject <candidateId>` | Record a rejected decision for a relationship candidate | — |
+| `--note <text>` | Attach a note when recording a relationship review decision | — |
+| `--reviewer <name>` | Reviewer name for a relationship review decision | — |
+| `--json` | Print relationship artifacts as JSON | `false` |
+
+### `scan relationship-apply`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--all-accepted` | Apply all accepted relationship review decisions for the scan run | `false` |
+| `--candidate <candidateId>` | Apply one accepted relationship review decision; repeatable | — |
+| `--dry-run` | Preview relationships that would be written without rewriting manifest shards | `false` |
+| `--json` | Print the apply result as JSON | `false` |
+
+### `scan relationship-feedback`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection <connectionId>` | Only export labels for one KTX connection | — |
+| `--decision <decision>` | Filter: `accepted`, `rejected`, or `all` | `all` |
+| `--json` | Print the export as JSON | `false` |
+| `--jsonl` | Print labels as newline-delimited JSON | `false` |
+
+### `scan relationship-calibration`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection <connectionId>` | Only calibrate labels for one KTX connection | — |
+| `--decision <decision>` | Filter: `accepted`, `rejected`, or `all` | `all` |
+| `--accept-threshold <value>` | Score threshold treated as predicted accepted (0–1) | `0.85` |
+| `--review-threshold <value>` | Score threshold treated as predicted review (0–1) | `0.55` |
+| `--json` | Print the calibration report as JSON | `false` |
+
+### `scan relationship-thresholds`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection <connectionId>` | Only evaluate labels for one KTX connection | — |
+| `--min-total-labels <count>` | Minimum scored labels before advice can be ready | `20` |
+| `--min-accepted-labels <count>` | Minimum accepted labels before advice can be ready | `5` |
+| `--min-rejected-labels <count>` | Minimum rejected labels before advice can be ready | `5` |
+| `--json` | Print the threshold advice report as JSON | `false` |
+
+## Examples
+
+```bash
+# Run a structural scan of a connection
+ktx dev scan my-warehouse
+
+# Run a scan with LLM enrichment
+ktx dev scan my-warehouse --mode enriched
+
+# Run a scan with relationship detection
+ktx dev scan my-warehouse --mode relationships
+
+# Dry-run a scan (don't write results)
+ktx dev scan my-warehouse --dry-run
+
+# Check the status of a scan run
+ktx dev scan status run-abc123
+
+# View the scan report
+ktx dev scan report run-abc123
+
+# View scan report as JSON
+ktx dev scan report run-abc123 --json
+
+# List relationship candidates pending review
+ktx dev scan relationships run-abc123
+
+# List all relationships regardless of status
+ktx dev scan relationships run-abc123 --status all
+
+# Accept a relationship candidate
+ktx dev scan relationships run-abc123 --accept candidate-xyz
+
+# Reject a relationship candidate with a note
+ktx dev scan relationships run-abc123 --reject candidate-xyz --note "false positive"
+
+# Apply all accepted relationships to the manifest
+ktx dev scan relationship-apply run-abc123 --all-accepted
+
+# Preview what would be applied
+ktx dev scan relationship-apply run-abc123 --all-accepted --dry-run
+
+# Export relationship feedback as calibration labels
+ktx dev scan relationship-feedback --json
+
+# Calibrate relationship detection thresholds
+ktx dev scan relationship-calibration --accept-threshold 0.9 --review-threshold 0.6
+
+# Get threshold advice based on review decisions
+ktx dev scan relationship-thresholds
+```
--- a/docs-site/content/docs/cli-reference/ktx-serve.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-serve.mdx
@ -0,0 +1,51 @@
+---
+title: "ktx serve"
+description: "Run the MCP stdio server."
+---
+
+Start a Model Context Protocol (MCP) server that exposes your KTX project's context to coding agents. The server runs over stdio and provides tools for querying semantic sources, searching knowledge, managing connections, and running ingests.
+
+## Usage
+
+```bash
+ktx serve --mcp stdio [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mcp <mode>` | MCP transport mode (required; only `stdio` is supported) | — |
+| `--user-id <id>` | Local user id | `local` |
+| `--semantic-compute` | Enable semantic-layer compute | `false` |
+| `--semantic-compute-url <url>` | HTTP semantic-layer compute URL | — |
+| `--database-introspection-url <url>` | Daemon URL for live-database introspection | — |
+| `--execute-queries` | Allow semantic-layer query execution (requires `--semantic-compute`) | `false` |
+| `--memory-capture` | Enable memory capture | `false` |
+| `--memory-model <model>` | Memory capture model | — |
+
+## Examples
+
+```bash
+# Start the MCP server over stdio
+ktx serve --mcp stdio
+
+# Start with semantic-layer compute enabled
+ktx serve --mcp stdio --semantic-compute
+
+# Start with query execution enabled
+ktx serve --mcp stdio --semantic-compute --execute-queries
+
+# Start with a remote semantic compute backend
+ktx serve --mcp stdio --semantic-compute-url http://localhost:8080
+
+# Start with memory capture
+ktx serve --mcp stdio --memory-capture
+
+# Use a specific project directory
+ktx serve --mcp stdio --project-dir /path/to/my-project
+```
+
+## Agent integration
+
+The MCP server is typically configured through `ktx setup --agents` rather than started manually. See the [Serving Agents](/docs/guides/serving-agents) guide and [Agent Clients](/docs/integrations/agent-clients) integration page for per-tool configuration.
--- a/docs-site/content/docs/cli-reference/ktx-setup.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx
@ -0,0 +1,174 @@
+---
+title: "ktx setup"
+description: "Set up or resume a local KTX project."
+---
+
+Interactive wizard that walks you through configuring LLM credentials, embeddings, database connections, context sources, and agent integrations. When run without flags in a directory that has no `ktx.yaml`, it launches the full guided flow. When run in an existing project, it resumes from the first incomplete step.
+
+## Usage
+
+```bash
+ktx setup [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `setup demo` | Run the packaged KTX demo from setup |
+| `setup demo init` | Initialize the packaged demo project |
+| `setup demo reset` | Reset the packaged demo project |
+| `setup demo replay` | Replay the packaged demo memory-flow |
+| `setup demo scan` | Run the packaged demo scan |
+| `setup demo inspect` | Inspect packaged demo outputs |
+| `setup demo doctor` | Check packaged demo readiness |
+| `setup demo ingest` | Run packaged demo ingest |
+| `setup context build` | Build agent-ready KTX context for setup |
+| `setup context watch [runId]` | Watch a setup-managed context build |
+| `setup context status [runId]` | Print setup-managed context build status |
+| `setup context stop [runId]` | Request a pause for a setup-managed context build |
+| `setup remove` | Remove setup-managed local integrations |
+| `setup status` | Show setup readiness for the resolved KTX project |
+
+## Options
+
+### General
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--project-dir <path>` | KTX project directory | `KTX_PROJECT_DIR`, nearest `ktx.yaml`, or cwd |
+| `--new` | Create a new KTX project before setup | `false` |
+| `--existing` | Use an existing KTX project | `false` |
+| `--yes` | Accept safe defaults in non-interactive setup | `false` |
+| `--no-input` | Disable interactive terminal input | — |
+
+### Agent Integration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--agents` | Install agent integration only | `false` |
+| `--target <target>` | Agent target (`claude-code`, `codex`, `cursor`, `opencode`, `universal`) | — |
+| `--agent-scope <scope>` | Agent install scope (`project` or `global`) | `project` |
+| `--agent-install-mode <mode>` | Agent install mode (`cli`, `mcp`, or `both`) | `cli` |
+| `--project` | Install agent integration into the project scope | `false` |
+| `--global` | Install agent integration into the global target scope (Claude Code and Codex only) | `false` |
+| `--skip-agents` | Leave agent integration incomplete for now | `false` |
+
+### LLM Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key | — |
+| `--anthropic-api-key-file <path>` | File containing the Anthropic API key | — |
+| `--anthropic-model <model>` | Anthropic model ID to validate and save | — |
+| `--skip-llm` | Leave LLM setup incomplete for now | `false` |
+
+### Embedding Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--embedding-backend <backend>` | Embedding backend (`openai` or `sentence-transformers`) | — |
+| `--embedding-api-key-env <name>` | Environment variable containing the embedding provider API key | — |
+| `--embedding-api-key-file <path>` | File containing the embedding provider API key | — |
+| `--skip-embeddings` | Leave embedding setup incomplete for now | `false` |
+
+### Database Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--database <driver>` | Database driver to configure; repeatable (`sqlite`, `postgres`, `mysql`, `clickhouse`, `sqlserver`, `bigquery`, `snowflake`) | — |
+| `--database-connection-id <id>` | Existing or new connection id; repeatable | — |
+| `--new-database-connection-id <id>` | Connection id for one new database connection | — |
+| `--database-url <url>` | URL, `env:NAME`, or `file:/path` for one new URL-style database connection | — |
+| `--database-schema <schema>` | Database schema to include; repeatable | — |
+| `--skip-databases` | Leave database setup incomplete | `false` |
+
+### Historic SQL
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--enable-historic-sql` | Enable Historic SQL when the selected database supports it | `false` |
+| `--disable-historic-sql` | Disable Historic SQL for the selected database | `false` |
+| `--historic-sql-window-days <number>` | Historic SQL query-history window in days | — |
+| `--historic-sql-min-calls <number>` | Postgres `pg_stat_statements` minimum calls floor | — |
+| `--historic-sql-service-account-pattern <pattern>` | Historic SQL service-account regex; repeatable | — |
+| `--historic-sql-redaction-pattern <pattern>` | Historic SQL SQL-literal redaction regex; repeatable | — |
+
+### Context Source Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--source <type>` | Source connector type (`dbt`, `metricflow`, `metabase`, `looker`, `lookml`, `notion`) | — |
+| `--source-connection-id <id>` | Connection id for source setup | — |
+| `--source-path <path>` | Local source path for dbt, MetricFlow, or LookML | — |
+| `--source-git-url <url>` | Git URL for dbt, MetricFlow, or LookML | — |
+| `--source-branch <branch>` | Git branch for source setup | — |
+| `--source-subpath <path>` | Repo subpath for source setup | — |
+| `--source-auth-token-ref <ref>` | `env:` or `file:` credential ref for source repo auth | — |
+| `--source-url <url>` | Source service URL for Metabase or Looker | — |
+| `--source-api-key-ref <ref>` | `env:` or `file:` API key ref for Metabase or Notion | — |
+| `--source-client-id <id>` | Looker client id | — |
+| `--source-client-secret-ref <ref>` | `env:` or `file:` Looker client secret ref | — |
+| `--source-warehouse-connection-id <id>` | Mapped warehouse connection id | — |
+| `--source-project-name <name>` | dbt project name override | — |
+| `--source-profiles-path <path>` | dbt profiles path | — |
+| `--source-target <target>` | dbt target or source-specific mapping target | — |
+| `--metabase-database-id <id>` | Metabase database id to map | — |
+| `--notion-crawl-mode <mode>` | Notion crawl mode (`all_accessible` or `selected_roots`) | — |
+| `--notion-root-page-id <id>` | Notion root page id; repeatable | — |
+| `--skip-initial-source-ingest` | Validate source setup without building source context during setup | `false` |
+| `--skip-sources` | Mark optional source setup complete with no sources | `false` |
+
+### Subcommand Options
+
+| Flag | Subcommand | Description | Default |
+|------|-----------|-------------|---------|
+| `--json` | `status`, `context status` | Print JSON output | `false` |
+| `--no-input` | `context build`, `context watch` | Disable interactive terminal input | — |
+| `--force` | `context stop` | Request the pause without interactive confirmation | `false` |
+| `--agents` | `remove` | Remove setup-managed agent integration files | `false` |
+| `--mode <mode>` | `demo` | Demo mode: `seeded`, `replay`, or `full` | `seeded` |
+| `--plain` | `demo` | Print plain text output | `false` |
+
+## Examples
+
+```bash
+# Run the interactive setup wizard
+ktx setup
+
+# Create a new project and run setup
+ktx setup --new
+
+# Resume setup in an existing project
+ktx setup --existing
+
+# Non-interactive setup with Anthropic key from environment
+ktx setup --yes --anthropic-api-key-env ANTHROPIC_API_KEY
+
+# Set up a Postgres connection
+ktx setup --database postgres --database-url "env:DATABASE_URL"
+
+# Install agent integration for Claude Code only
+ktx setup --agents --target claude-code
+
+# Install agent integration globally for Codex
+ktx setup --agents --target codex --global
+
+# Add a dbt source from a local path
+ktx setup --source dbt --source-path ./my-dbt-project
+
+# Skip optional steps for a minimal setup
+ktx setup --skip-sources --skip-agents
+
+# Check setup readiness
+ktx setup status
+
+# Build context after setup
+ktx setup context build
+
+# Watch a running context build
+ktx setup context watch
+
+# Run the packaged demo
+ktx setup demo
+```
--- a/docs-site/content/docs/cli-reference/ktx-sl.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-sl.mdx
@ -0,0 +1,122 @@
+---
+title: "ktx sl"
+description: "List, read, validate, query, or write semantic-layer sources."
+---
+
+Interact with your project's semantic layer. Semantic sources are YAML definitions that describe your tables, columns, measures, joins, and grain — the vocabulary agents use to generate correct SQL.
+
+## Usage
+
+```bash
+ktx sl <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `list` | List semantic-layer sources |
+| `read <sourceName>` | Read a semantic-layer source |
+| `validate <sourceName>` | Validate a semantic-layer source against the database schema |
+| `write <sourceName>` | Write a semantic-layer source |
+| `query` | Compile or execute a semantic-layer query |
+
+## Options
+
+### `sl list`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <id>` | Filter by KTX connection id | — |
+| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
+| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
+
+### `sl read`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <id>` | KTX connection id (required) | — |
+
+### `sl validate`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <id>` | KTX connection id (required) | — |
+
+### `sl write`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <id>` | KTX connection id (required) | — |
+| `--yaml <yaml>` | Semantic-layer source YAML content (required) | — |
+
+### `sl query`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--connection-id <id>` | KTX connection id | — |
+| `--measure <measure>` | Measure to query; repeatable (at least one required) | — |
+| `--dimension <dimension>` | Dimension to include; repeatable | — |
+| `--filter <filter>` | Filter expression; repeatable | — |
+| `--segment <segment>` | Segment to include; repeatable | — |
+| `--order-by <field[:direction]>` | Order field, optionally suffixed with `:asc` or `:desc`; repeatable | — |
+| `--limit <n>` | Query limit | — |
+| `--include-empty` | Include empty rows | `false` |
+| `--format <format>` | Output format: `json` or `sql` | `json` |
+| `--execute` | Execute the compiled query against the database | `false` |
+| `--max-rows <n>` | Maximum rows to return when executing | — |
+
+## Examples
+
+```bash
+# List all semantic sources
+ktx sl list
+
+# List sources for a specific connection
+ktx sl list --connection-id my-warehouse
+
+# List sources as JSON
+ktx sl list --json
+
+# Read a source definition
+ktx sl read orders --connection-id my-warehouse
+
+# Validate a source against the live schema
+ktx sl validate orders --connection-id my-warehouse
+
+# Write a new source from YAML
+ktx sl write customers --connection-id my-warehouse --yaml "$(cat sources/customers.yaml)"
+
+# Compile a query and view the generated SQL
+ktx sl query \
+  --connection-id my-warehouse \
+  --measure orders.total_revenue \
+  --dimension orders.created_date \
+  --format sql
+
+# Execute a query with filters
+ktx sl query \
+  --connection-id my-warehouse \
+  --measure orders.total_revenue \
+  --dimension orders.status \
+  --filter "orders.created_date >= '2024-01-01'" \
+  --execute \
+  --max-rows 100
+
+# Query with ordering and limit
+ktx sl query \
+  --connection-id my-warehouse \
+  --measure orders.total_revenue \
+  --dimension customers.country \
+  --order-by total_revenue:desc \
+  --limit 10 \
+  --execute
+
+# Execute and cap the result set
+ktx sl query \
+  --connection-id my-warehouse \
+  --measure orders.count \
+  --dimension orders.created_date \
+  --execute \
+  --max-rows 1000
+```
--- a/docs-site/content/docs/cli-reference/ktx-status.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-status.mdx
@ -0,0 +1,28 @@
+---
+title: "ktx status"
+description: "Show current project status."
+---
+
+Print the current setup status of your KTX project — which steps are complete, which need attention, and whether the project is ready for agents.
+
+## Usage
+
+```bash
+ktx status [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Print JSON output | `false` |
+
+## Examples
+
+```bash
+# Show project status
+ktx status
+
+# Get status as JSON (useful for scripting)
+ktx status --json
+```
--- a/docs-site/content/docs/cli-reference/ktx-wiki.mdx
+++ b/docs-site/content/docs/cli-reference/ktx-wiki.mdx
@ -0,0 +1,92 @@
+---
+title: "ktx wiki"
+description: "List, read, search, or write knowledge pages."
+---
+
+Manage knowledge pages in your KTX project. Knowledge pages are Markdown documents that capture business definitions, rules, and gotchas. Agents search them for context when answering questions about your data.
+
+## Usage
+
+```bash
+ktx wiki <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `list` | List local wiki pages |
+| `read <key>` | Read one local wiki page |
+| `search <query>` | Search local wiki pages |
+| `write <key>` | Write one local wiki page |
+
+## Options
+
+### `wiki list`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-id <id>` | Local user id | `local` |
+
+### `wiki read`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-id <id>` | Local user id | `local` |
+
+### `wiki search`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-id <id>` | Local user id | `local` |
+
+### `wiki write`
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-id <id>` | Local user id | `local` |
+| `--scope <scope>` | Scope: `global` or `user` | `global` |
+| `--summary <summary>` | Wiki page summary (required) | — |
+| `--content <content>` | Wiki page content (required) | — |
+| `--tag <tag>` | Wiki tag; repeatable | — |
+| `--ref <ref>` | Wiki ref; repeatable | — |
+| `--sl-ref <ref>` | Semantic-layer ref; repeatable | — |
+
+## Examples
+
+```bash
+# List all wiki pages
+ktx wiki list
+
+# Read a specific wiki page
+ktx wiki read revenue-definitions
+
+# Search wiki pages
+ktx wiki search "monthly recurring revenue"
+
+# Write a global knowledge page
+ktx wiki write revenue-definitions \
+  --summary "Canonical revenue metric definitions" \
+  --content "## MRR\nMonthly Recurring Revenue is calculated as..."
+
+# Write a user-scoped knowledge page
+ktx wiki write my-notes \
+  --scope user \
+  --summary "Personal analysis notes" \
+  --content "Things to check when revenue numbers look off..."
+
+# Write a page with tags and references
+ktx wiki write churn-rules \
+  --summary "Churn calculation business rules" \
+  --content "A customer is considered churned when..." \
+  --tag finance \
+  --tag retention \
+  --sl-ref customers \
+  --sl-ref subscriptions
+
+# Write a page with external references
+ktx wiki write data-freshness \
+  --summary "Data pipeline SLAs and freshness guarantees" \
+  --content "The orders table refreshes every 15 minutes..." \
+  --ref "https://wiki.example.com/data-pipelines"
+```
--- a/docs-site/content/docs/cli-reference/meta.json
+++ b/docs-site/content/docs/cli-reference/meta.json
@ -0,0 +1,16 @@
+{
+  "title": "CLI Reference",
+  "defaultOpen": true,
+  "pages": [
+    "ktx-setup",
+    "ktx-connection",
+    "ktx-scan",
+    "ktx-ingest",
+    "ktx-sl",
+    "ktx-wiki",
+    "ktx-serve",
+    "ktx-status",
+    "ktx-agent",
+    "ktx-dev"
+  ]
+}