mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
2c9a58bb56
Bare invocations now do the obvious thing instead of erroring out, and mode-as-subcommand patterns collapse into flags on the parent. No new top-level commands. - `ktx ingest` (bare) ingests every configured connection. The `text` subcommand is gone; capture inline notes with `ktx ingest --text "..."` and files with `ktx ingest --file path` (use `-` for stdin). `--text`/`--file` reject a positional connection id; pass `--connection-id` to tag captured notes. - `ktx connection` (bare) lists; `ktx connection test` (bare) tests every configured connection. - `ktx wiki` and `ktx sl` flatten `list`/`search`: bare lists, with a `[query...]` positional searches (multi-word joined with spaces). `sl validate` and `sl query` stay as distinct verbs and now read `--connection-id` from the parent. - `ktx mcp` (bare) prints daemon status. Adds a shared `resolveConnectionSelection` helper consumed by ingest and connection test. Updates README, docs-site cli-reference and guides, next-steps strings, agent SKILL templates, and all affected tests. Per-package type-check, unit tests (605), smoke tests, and dead-code checks all pass.
124 lines
4.1 KiB
Text
124 lines
4.1 KiB
Text
---
|
|
title: "ktx wiki"
|
|
description: "List or search wiki pages."
|
|
---
|
|
|
|
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.
|
|
|
|
## Command signature
|
|
|
|
```bash
|
|
ktx wiki [options] [query...]
|
|
```
|
|
|
|
- Bare `ktx wiki` lists local wiki pages.
|
|
- `ktx wiki <query...>` searches local wiki pages (multi-word queries are
|
|
joined with a space).
|
|
|
|
Edit the Markdown files under `wiki/` directly, or ingest source content with
|
|
`ktx ingest`, when you need to add or update wiki knowledge.
|
|
|
|
## Options
|
|
|
|
| Flag | Description | Default |
|
|
|------|-------------|---------|
|
|
| `--user-id <id>` | Local user id | `local` |
|
|
| `--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` |
|
|
|
|
`ktx wiki <query>` uses hybrid search when `storage.search` is `sqlite-fts5`.
|
|
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
|
|
and keeps lexical and token results.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# List all wiki pages
|
|
ktx wiki
|
|
|
|
# List all wiki pages as JSON
|
|
ktx wiki --json
|
|
|
|
# Search wiki pages
|
|
ktx wiki "monthly recurring revenue"
|
|
|
|
# Search wiki pages as JSON
|
|
ktx wiki "monthly recurring revenue" --json --limit 10
|
|
|
|
# Print search results as TSV
|
|
ktx wiki "monthly recurring revenue" --output plain
|
|
|
|
# Inspect which search lanes were used
|
|
ktx --debug wiki "monthly recurring revenue" --json
|
|
```
|
|
|
|
## Output
|
|
|
|
Wiki commands print clack-style pretty output in a TTY and TSV-style plain
|
|
output when requested. JSON output wraps the items with a command metadata
|
|
envelope. Search results include `matchReasons` and `lanes` metadata so you can
|
|
see whether lexical, token, or semantic search contributed to the ranking. Open
|
|
the matching Markdown files directly when you need the full page contents.
|
|
Pretty search output shows `#1`, `#2`, and later rank badges for the displayed
|
|
results. Plain and JSON output keep the raw `score` value, which is a ranking
|
|
score rather than a percentage.
|
|
|
|
```json
|
|
{
|
|
"kind": "list",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"key": "revenue-definitions",
|
|
"summary": "Canonical revenue metric definitions",
|
|
"score": 0.92,
|
|
"matchReasons": ["lexical", "semantic"],
|
|
"lanes": [
|
|
{
|
|
"lane": "lexical",
|
|
"status": "available",
|
|
"requestedCandidatePoolLimit": 25,
|
|
"effectiveCandidatePoolLimit": 25,
|
|
"returnedCandidateCount": 3,
|
|
"weight": 1.5
|
|
},
|
|
{
|
|
"lane": "semantic",
|
|
"status": "available",
|
|
"requestedCandidatePoolLimit": 25,
|
|
"effectiveCandidatePoolLimit": 25,
|
|
"returnedCandidateCount": 8,
|
|
"weight": 3
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
"meta": {
|
|
"command": "wiki search"
|
|
}
|
|
}
|
|
```
|
|
|
|
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:
|
|
|
|
```text
|
|
[debug] wiki search mode=sqlite-fts5 embedding=configured results=2
|
|
[debug] wiki search lane=lexical status=available returned=1 weight=1.5
|
|
[debug] wiki search lane=token status=available returned=1 weight=0.75
|
|
[debug] wiki search lane=semantic status=available returned=2 weight=3
|
|
```
|
|
|
|
## Common errors
|
|
|
|
| Error | Cause | Recovery |
|
|
|-------|-------|----------|
|
|
| Search returns no results | The query terms do not match summaries, tags, or content, and the semantic lane is unavailable or has no positive matches | Run with `--debug`, check the semantic lane status, retry with business synonyms, then create a page if the knowledge is missing |
|
|
| A page is missing | No Markdown file exists for that business context | Add a file under `wiki/` or run `ktx ingest <connectionId>` |
|