chore: move docs site workspace

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