apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-13 08:15:14 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: standardize ktx naming

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-20 17:32:15 +02:00
parent 27afd6a3b0
commit 1f8c1089f6
41 changed files with 331 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs-site/content/docs/cli-reference/ktx-admin.mdx
View file

@ -19,9 +19,9 @@ ktx admin <subcommand> [options]
| Subcommand | Description |
|-----------|-------------|
| `init [directory]` | Initialize a Git-backed KTX project directory for maintenance scripts |
| `init [directory]` | Initialize a Git-backed **ktx** project directory for maintenance scripts |
| `schema` | Print a JSON Schema describing `ktx.yaml` |
| `runtime` | Install, start, stop, and inspect the KTX-managed Python runtime |
| `runtime` | Install, start, stop, and inspect the **ktx**-managed Python runtime |
| `reindex` | Sync local wiki and semantic-layer search indexes from disk |
## `admin init`
@ -44,8 +44,8 @@ directory. Use it from any directory to generate editor or agent schema files.
| Subcommand | Description |
|-----------|-------------|
| `install` | Install the bundled Python runtime wheel into the managed runtime |
| `start` | Start the KTX daemon |
| `stop` | Stop the KTX daemon |
| `start` | Start the **ktx** daemon |
| `stop` | Stop the **ktx** daemon |
| `status` | Show managed Python runtime status and readiness checks |
## `admin runtime` Options
@ -56,7 +56,7 @@ directory. Use it from any directory to generate editor or agent schema files.
| `--json` | Print JSON output for `status` | `false` |
| `--yes` | Accepted by `install` for scripted install commands | `false` |
| `--force` | Reinstall for `install`, or restart for `start` | `false` |
| `--all` | Stop all recorded or discoverable KTX daemon processes with `stop` | `false` |
| `--all` | Stop all recorded or discoverable **ktx** daemon processes with `stop` | `false` |
## Examples
@ -102,15 +102,15 @@ ktx admin reindex --output plain
ktx admin reindex --json
```
By default, KTX compares stored search text with the files on disk. It only
By default, **ktx** compares stored search text with the files on disk. It only
re-embeds changed rows and removes rows for files that no longer exist. With
`--force`, KTX clears each discovered scope first and then rebuilds it.
`--force`, **ktx** clears each discovered scope first and then rebuilds it.
When embeddings are not configured, KTX still writes lexical FTS rows and
prints an embeddings warning. If a scope fails, KTX keeps processing the
When embeddings are not configured, **ktx** still writes lexical FTS rows and
prints an embeddings warning. If a scope fails, **ktx** keeps processing the
remaining scopes and exits with code `1` after output is written. If the local
state database cannot open or the configured managed embedding runtime is
missing, KTX prints the error and exits with code `1`.
missing, **ktx** prints the error and exits with code `1`.
## Common errors

2
docs-site/content/docs/cli-reference/ktx-connection.mdx
View file

@ -3,7 +3,7 @@ title: "ktx connection"
description: "List and test configured database and context-source connections."
---
Inspect configured connections in your KTX project. Connections define how KTX
Inspect configured connections in your **ktx** project. Connections define how **ktx**
reaches primary sources (databases and warehouses) and context sources (BI
tools, modeling projects, and knowledge systems). Use `ktx setup` to add,
remove, or reconfigure them.

18
docs-site/content/docs/cli-reference/ktx-ingest.mdx
View file

@ -1,10 +1,10 @@
---
title: "ktx ingest"
description: "Build or refresh KTX context, or capture text into KTX memory."
description: "Build or refresh ktx context, or capture text into ktx memory."
---
`ktx ingest` builds or refreshes KTX context from configured connections, and
can also capture free-form text into KTX memory. Database connections build
`ktx ingest` builds or refreshes **ktx** context from configured connections, and
can also capture free-form text into **ktx** memory. Database connections build
schema context. Context-source connections ingest metadata from tools such as
dbt, Looker, Metabase, MetricFlow, LookML, and Notion. Pass `--text` or
`--file` to capture inline text or text files into memory instead.
@ -18,7 +18,7 @@ ktx ingest [options] [connectionId]
- Bare `ktx ingest` (no positional, no `--all`) ingests every configured
connection.
- `ktx ingest <connectionId>` ingests one configured connection.
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into KTX
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into **ktx**
memory instead of ingesting a connection.
Database connections run before context-source connections when more than one
@ -34,9 +34,9 @@ connection is selected.
| `--query-history` | Include database query-history usage patterns | Stored connection default |
| `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default |
| `--query-history-window-days <days>` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
| `--text <content>` | Capture inline text into KTX memory; repeatable | `[]` |
| `--file <path>` | Capture a text file into KTX memory; use `-` for stdin; repeatable | `[]` |
| `--connection-id <connectionId>` | KTX connection id to tag captured text/file notes | - |
| `--text <content>` | Capture inline text into **ktx** memory; repeatable | `[]` |
| `--file <path>` | Capture a text file into **ktx** memory; use `-` for stdin; repeatable | `[]` |
| `--connection-id <connectionId>` | **ktx** connection id to tag captured text/file notes | - |
| `--user-id <id>` | Memory user id for text/file capture attribution | `local-cli` |
| `--fail-fast` | Stop after the first failed text/file item | `false` |
| `--plain` | Print plain text output | `true` |
@ -54,7 +54,7 @@ requires deep ingest readiness.
When more than one connection is selected, database ingest runs first, then
context-source ingest and memory updates run for context-source connections.
Some ingest paths use the managed KTX Python runtime. Query-history ingest uses
Some ingest paths use the managed **ktx** Python runtime. Query-history ingest uses
it for SQL analysis, and Looker context-source ingest uses it for Looker identifier
parsing. In an interactive terminal, `ktx ingest` prompts before installing the
required runtime features. Use `--yes` to install them without prompting, or
@ -141,7 +141,7 @@ jq -c '. | {at, level, phase, event, durationMs, data, error}' \
.ktx/ingest-traces/<jobId>/trace.jsonl
```
KTX writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
**ktx** writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
`error`, `info`, `debug`, or `trace` before running ingest to change the trace
verbosity:

10
docs-site/content/docs/cli-reference/ktx-mcp.mdx
View file

@ -1,9 +1,9 @@
---
title: "ktx mcp"
description: "Run the KTX MCP HTTP server for agent clients."
description: "Run the ktx MCP HTTP server for agent clients."
---
`ktx mcp` starts, stops, inspects, and tails the local KTX MCP server for a KTX
`ktx mcp` starts, stops, inspects, and tails the local **ktx** MCP server for a **ktx**
project. Use it when an agent client connects through MCP instead of generated
CLI instructions.
@ -17,8 +17,8 @@ ktx mcp <subcommand> [options]
| Subcommand | Description |
|-----------|-------------|
| `start` | Start the KTX MCP HTTP server |
| `stop` | Stop the KTX MCP daemon |
| `start` | Start the **ktx** MCP HTTP server |
| `stop` | Stop the **ktx** MCP daemon |
| `status` | Show daemon status, URL, PID, token mode, and project path |
| `logs` | Print the daemon log |
@ -65,6 +65,6 @@ hosts and origins for browser clients.
| Error | Cause | Recovery |
|-------|-------|----------|
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or pass `--project-dir <path>` |
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a **ktx** project or pass `--project-dir <path>` |
| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |

22
docs-site/content/docs/cli-reference/ktx-setup.mdx
View file

@ -1,14 +1,14 @@
---
title: "ktx setup"
description: "Set up or resume a local KTX project."
description: "Set up or resume a local ktx project."
---
`ktx setup` is the guided configuration flow for a local KTX project. It can
`ktx setup` is the guided configuration flow for a local **ktx** project. It can
create or resume `ktx.yaml`, configure LLM and embedding providers, add
database and context-source connections, prepare required runtime features,
build initial context, and install agent integrations.
When you run bare `ktx` in an interactive terminal outside any KTX project, the
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
CLI starts this same setup flow. Inside an existing project, `ktx setup`
resumes from incomplete setup state or opens the setup menu.
@ -52,7 +52,7 @@ prompts.
| Flag | Description |
|------|-------------|
| `--llm-backend <backend>` | LLM backend: `anthropic`, `vertex`, or `claude-code` |
| `--llm-backend claude-code` | Use the local Claude Code session for KTX LLM calls |
| `--llm-backend claude-code` | Use the local Claude Code session for **ktx** LLM calls |
| `--llm-model <model>` | LLM model ID or backend model alias to validate and save |
| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
| `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
@ -75,7 +75,7 @@ of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts
| `--embedding-api-key-file <path>` | File containing the embedding provider API key |
| `--skip-embeddings` | Leave embedding setup incomplete |
`sentence-transformers` uses the KTX-managed Python runtime. Choose only one
`sentence-transformers` uses the **ktx**-managed Python runtime. Choose only one
embedding credential source.
### Runtime
@ -84,9 +84,9 @@ Setup prepares the managed Python runtime when your selected configuration
needs it. In the full setup flow, the runtime step runs after database and
context-source setup and before the initial context build.
KTX prepares the `core` runtime feature when query-history ingest, Looker
**ktx** prepares the `core` runtime feature when query-history ingest, Looker
context-source ingest, database introspection fallback, or daemon-backed
context build paths need it. KTX prepares the `local-embeddings` runtime feature when you
context build paths need it. **ktx** prepares the `local-embeddings` runtime feature when you
choose managed local `sentence-transformers` embeddings. Existing external
daemon URLs, such as `KTX_DAEMON_URL` or `KTX_SQL_ANALYSIS_URL`, satisfy the
matching dependency and skip managed runtime installation for that dependency.
@ -109,7 +109,7 @@ runtime features are missing.
| `--database-schema <schema>` | Database schema or dataset to include; repeatable |
| `--skip-databases` | Leave database setup incomplete |
KTX needs at least one database connection before it can build database
**ktx** needs at least one database connection before it can build database
context. Use `--skip-databases` only when intentionally leaving the project
incomplete.
@ -165,7 +165,7 @@ ktx setup
# Run setup for a specific project directory
ktx setup --project-dir ./analytics
# Use Claude Code with Opus for KTX LLM calls
# Use Claude Code with Opus for ktx LLM calls
ktx setup \
--project-dir ./analytics \
--llm-backend claude-code \
@ -211,14 +211,14 @@ Interactive setup renders prompts and progress messages. Use `ktx status` to
check setup and context readiness after setup exits.
```text
KTX project: /home/user/analytics
ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (postgres-warehouse)
Context sources configured: yes (dbt-main)
Runtime ready: yes (core)
KTX context built: yes
ktx context built: yes
Agent integration ready: yes (codex:project)
```

6
docs-site/content/docs/cli-reference/ktx-sl.mdx
View file

@ -35,7 +35,7 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | Filter by KTX connection id | - |
| `--connection-id <id>` | Filter by **ktx** connection id | - |
| `--limit <number>` | Maximum search results (search mode only) | - |
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
@ -44,13 +44,13 @@ ktx sl query [options]
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | KTX connection id (required) | - |
| `--connection-id <id>` | **ktx** connection id (required) | - |
### `sl query`
| Flag | Description | Default |
|------|-------------|---------|
| `--connection-id <id>` | KTX connection id | - |
| `--connection-id <id>` | **ktx** connection id | - |
| `--query-file <path>` | JSON semantic query file | - |
| `--measure <measure>` | Measure to query; repeatable (at least one required) | - |
| `--dimension <dimension>` | Dimension to include; repeatable | - |

4
docs-site/content/docs/cli-reference/ktx-sql.mdx
View file

@ -3,7 +3,7 @@ title: "ktx sql"
description: "Execute parser-validated read-only SQL against a configured connection."
---
Run read-only SQL against a database connection in your KTX project. The command
Run read-only SQL against a database connection in your **ktx** project. The command
validates the statement before execution and only accepts a single `SELECT` or
`WITH` query.
@ -22,7 +22,7 @@ JSON.
| Flag | Description | Default |
|------|-------------|---------|
| `-c`, `--connection <id>` | KTX database connection id. Required. | - |
| `-c`, `--connection <id>` | **ktx** database connection id. Required. | - |
| `--max-rows <n>` | Maximum rows to return. Must be between `1` and `10000`. | `1000` |
| `--output <mode>` | Output mode: `pretty`, `plain` (TSV), or `json`. | `pretty` |
| `--json` | Shortcut for `--output=json` (overrides `--output`). | `false` |

8
docs-site/content/docs/cli-reference/ktx-status.mdx
View file

@ -1,9 +1,9 @@
---
title: "ktx status"
description: "Check KTX setup and project readiness."
description: "Check ktx setup and project readiness."
---
Run the KTX readiness doctor. Inside a KTX project, this checks setup,
Run the **ktx** readiness doctor. Inside a **ktx** project, this checks setup,
project configuration, semantic search, query history, connections, and related
diagnostics. Outside a project, it checks local CLI setup readiness so you know
whether `ktx setup` can run.
@ -53,7 +53,7 @@ flow, then rerun `ktx status`.
```json
{
"title": "KTX project doctor",
"title": "ktx project doctor",
"checks": [
{
"id": "project-config",
@ -69,7 +69,7 @@ flow, then rerun `ktx status`.
| Error | Cause | Recovery |
|-------|-------|----------|
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a KTX project or set `KTX_PROJECT_DIR` for project checks |
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a **ktx** project or set `KTX_PROJECT_DIR` for project checks |
| Project config check fails | The project directory is missing or has an invalid `ktx.yaml` | Run `ktx setup` to resume setup |
| Schema validation fails | `ktx.yaml` does not match the current config schema | Run `ktx status --validate --json` for structured issue details, then edit `ktx.yaml` or rerun `ktx setup` |
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run `ktx setup` or inspect the check's `fix` field in JSON output |

8
docs-site/content/docs/cli-reference/ktx-wiki.mdx
View file

@ -3,7 +3,7 @@ title: "ktx wiki"
description: "List or search wiki pages."
---
List and search wiki pages in your KTX project. Wiki pages are Markdown
List and search wiki pages in your **ktx** project. Wiki pages are Markdown
documents that capture business definitions, rules, and gotchas. Agents search
them for context when answering questions about your data.
@ -30,9 +30,9 @@ Edit the Markdown files under `wiki/` directly, or ingest source content with
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
`ktx wiki <query>` uses hybrid search when `storage.search` is `sqlite-fts5`.
KTX combines lexical SQLite FTS5 matches, token matches, and semantic matches
**ktx** combines lexical SQLite FTS5 matches, token matches, and semantic matches
from wiki page embeddings stored in `.ktx/db.sqlite`. If embeddings are not
configured or the embedding backend is unavailable, KTX skips the semantic lane
configured or the embedding backend is unavailable, **ktx** skips the semantic lane
and keeps lexical and token results.
## Examples
@ -105,7 +105,7 @@ score rather than a percentage.
}
```
When you pass the global `--debug` flag, KTX writes search diagnostics to
When you pass the global `--debug` flag, **ktx** writes search diagnostics to
stderr and leaves stdout unchanged. This is useful with `--json` because stdout
stays machine-readable:

8
docs-site/content/docs/cli-reference/ktx.mdx
View file

@ -1,6 +1,6 @@
---
title: "ktx"
description: "Root command map, global options, and project resolution for the KTX CLI."
description: "Root command map, global options, and project resolution for the ktx CLI."
---
The `ktx` CLI sets up local projects, builds agent-ready context, checks
@ -13,7 +13,7 @@ server, and manages the bundled Python runtime.
ktx [global-options] <command>
```
When you run bare `ktx` in an interactive terminal outside any KTX project, the
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
CLI starts the same guided setup flow as `ktx setup`. Inside an existing
project, use command-specific help:
@ -66,7 +66,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
| Flag | Description |
|------|-------------|
| `--project-dir <path>` | KTX project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
| `--project-dir <path>` | **ktx** project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
| `--debug` | Print diagnostic dispatch and project-resolution details to stderr. |
| `-v`, `--version` | Show the CLI package name and version. |
| `-h`, `--help` | Show help for the current command. |
@ -74,7 +74,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
## Project resolution
Most commands are project-aware. Pass `--project-dir <path>` when scripting or
when you are outside the project directory. If you omit it, KTX checks
when you are outside the project directory. If you omit it, **ktx** checks
`KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back
to the current directory.