docs: refresh KTX demo readiness guidance

README.md

@@ -43,6 +43,7 @@ SQLite.
 Install the CLI and run the setup wizard:
 
 ```bash
+npm install @kaelio/ktx
 npm install -g @kaelio/ktx
 ktx setup
 ```
@@ -70,6 +71,40 @@ KTX context built: yes
 Agent integration ready: yes (claude-code:project)
 ```
 
+Run the packaged demo without installing globally:
+
+```bash
+npx @kaelio/ktx setup demo --no-input
+npx @kaelio/ktx setup demo inspect
+```
+
+The default demo uses packaged sample data and prebuilt context. It does not
+require API keys, network access, or an LLM provider.
+
+Generate SQL from a semantic-layer source:
+
+```bash
+npx @kaelio/ktx sl query --project-dir "$PROJECT_DIR" \
+  --connection-id warehouse \
+  --measure accounts.account_count \
+  --dimension accounts.segment \
+  --format sql
+```
+
+List and test a configured warehouse connection:
+
+```bash
+ktx connection list --project-dir "$PROJECT_DIR"
+ktx connection test warehouse --project-dir "$PROJECT_DIR"
+```
+
+The connection test prints the configured driver and discovered table count:
+
+```text
+Driver: sqlite
+Tables: 1
+```
+
 ## What's in a project
 
 ```
@@ -97,6 +132,47 @@ Semantic sources and knowledge pages are committed to git. The `.ktx/` directory
 holds ephemeral state and is git-ignored — delete it and KTX rebuilds on the
 next run.
 
+### Scan the demo warehouse
+
+Scan artifacts are written under
+`raw-sources/warehouse/live-database/<syncId>/` in the project directory.
+
+```bash
+SCAN_OUTPUT="$(ktx scan warehouse --project-dir "$PROJECT_DIR")"
+printf '%s\n' "$SCAN_OUTPUT"
+SCAN_RUN_ID="$(printf '%s\n' "$SCAN_OUTPUT" | awk '/^Run: / { print $2 }')"
+ktx scan status --project-dir "$PROJECT_DIR" "$SCAN_RUN_ID"
+ktx scan report --project-dir "$PROJECT_DIR" "$SCAN_RUN_ID"
+```
+
+For non-SQLite drivers, prefer credential references such as `--url env:NAME`
+or `--url file:PATH` over literal credential URLs.
+
+## Managed Python runtime
+
+KTX installs its Python runtime only when a Python-backed command needs it.
+The runtime lives outside the npm cache, is versioned by the installed CLI
+version, and is managed by `ktx runtime` commands.
+
+KTX requires `uv` on `PATH` to create the managed runtime. Install `uv` with
+your system package manager or the official installer before running Python-
+backed KTX commands. KTX doesn't download `uv` automatically; run
+`ktx runtime doctor` if runtime installation fails:
+
+```bash
+ktx runtime install --yes
+ktx runtime status
+ktx runtime doctor
+ktx runtime start
+ktx runtime stop
+ktx runtime prune --dry-run
+ktx runtime prune --yes
+```
+
+The release artifact manifest contains the public npm tarball and the bundled `kaelio-ktx`
+runtime wheel. The `python/ktx-sl` and `python/ktx-daemon` directories remain
+source packages for development, not public release artifacts.
+
 ## Serve agents
 
 KTX integrates with coding agents through CLI skills, an MCP server, or both.
@@ -126,6 +202,11 @@ This exposes tools for connections, knowledge search, semantic-layer sources,
 validation, queries, ingestion, and replay. The `--semantic-compute` flag starts
 the managed Python runtime for query planning automatically.
 
+The standalone MCP server exposes `connection_list`, `knowledge_search`,
+`knowledge_read`, `knowledge_write`, `sl_list_sources`, `sl_read_source`,
+`sl_write_source`, `sl_validate`, `sl_query`, `ingest_trigger`,
+`ingest_status`, `ingest_report`, and `ingest_replay`.
+
 Supported agents: Claude Code, Codex, Cursor, OpenCode, and any agent that
 reads `.agents/` skills or MCP configuration.
 
@@ -136,7 +217,13 @@ reads `.agents/` skills or MCP configuration.
 | `packages/cli` | CLI entry point |
 | `packages/context` | Core context engine |
 | `packages/llm` | LLM and embedding providers |
-| `packages/connector-*` | Database connectors (Postgres, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite) |
+| `packages/connector-bigquery` | BigQuery scan connector |
+| `packages/connector-clickhouse` | ClickHouse scan connector |
+| `packages/connector-mysql` | MySQL scan connector |
+| `packages/connector-postgres` | Postgres scan connector |
+| `packages/connector-snowflake` | Snowflake scan connector |
+| `packages/connector-sqlite` | SQLite scan connector |
+| `packages/connector-sqlserver` | SQL Server scan connector |
 | `python/ktx-sl` | Semantic-layer query planning |
 | `python/ktx-daemon` | Portable compute service |
 

packages/cli/src/demo.test.ts

@@ -11,6 +11,9 @@ import type { renderMemoryFlowTui } from './memory-flow-tui.js';
 import { KTX_NEXT_STEP_COMMANDS } from './next-steps.js';
 import { resetVizFallbackWarningsForTest } from './viz-fallback.js';
 
+const SEEDED_DEMO_SEMANTIC_SOURCE_COUNT = 46;
+const SEEDED_DEMO_KNOWLEDGE_PAGE_COUNT = 28;
+
 function makeIo(options: { isTTY?: boolean; columns?: number; rawMode?: boolean } = {}) {
   let stdout = '';
   let stderr = '';
@@ -336,8 +339,14 @@ describe('runKtxDemo', () => {
         notion: { pageCount: 8 },
       },
       generatedOutputs: {
-        semanticLayer: { manifestSourceCount: 6, fileCount: 6 },
-        knowledge: { manifestPageCount: 10, fileCount: 10 },
+        semanticLayer: {
+          manifestSourceCount: SEEDED_DEMO_SEMANTIC_SOURCE_COUNT,
+          fileCount: SEEDED_DEMO_SEMANTIC_SOURCE_COUNT,
+        },
+        knowledge: {
+          manifestPageCount: SEEDED_DEMO_KNOWLEDGE_PAGE_COUNT,
+          fileCount: SEEDED_DEMO_KNOWLEDGE_PAGE_COUNT,
+        },
         links: { manifestLinkCount: 23, linkCount: 23 },
         reports: { primaryPath: 'reports/seeded-demo-report.json', fileCount: 1 },
       },
@@ -636,10 +645,16 @@ describe('runKtxDemo', () => {
     ).resolves.toBe(0);
 
     expect(seededIo.stdout()).toContain('Status: ready');
-    expect(seededIo.stdout()).toContain('Semantic-layer sources: 6 manifest, 6 files');
-    expect(seededIo.stdout()).toContain('Knowledge pages: 10 manifest, 10 files');
+    expect(seededIo.stdout()).toContain(
+      `Semantic-layer sources: ${SEEDED_DEMO_SEMANTIC_SOURCE_COUNT} manifest, ${SEEDED_DEMO_SEMANTIC_SOURCE_COUNT} files`,
+    );
+    expect(seededIo.stdout()).toContain(
+      `Knowledge pages: ${SEEDED_DEMO_KNOWLEDGE_PAGE_COUNT} manifest, ${SEEDED_DEMO_KNOWLEDGE_PAGE_COUNT} files`,
+    );
     expect(seededIo.stdout()).not.toContain('Status: corrupt');
-    expect(seededIo.stdout()).not.toContain('Semantic-layer sources: 6 manifest, 0 files');
+    expect(seededIo.stdout()).not.toContain(
+      `Semantic-layer sources: ${SEEDED_DEMO_SEMANTIC_SOURCE_COUNT} manifest, 0 files`,
+    );
   });
 
   it('fails corrupted demo projects in no-input mode with reset guidance', async () => {

packages/cli/src/standalone-smoke.test.ts

@@ -368,9 +368,9 @@ describe('standalone built ktx CLI smoke', () => {
       const knowledgeSearch = structuredContent<{
         results: Array<{ key: string; summary: string; score: number }>;
         totalFound: number;
-      }>(await client.callTool({ name: 'knowledge_search', arguments: { query: 'ARR contract', limit: 5 } }));
+      }>(await client.callTool({ name: 'knowledge_search', arguments: { query: 'ARR contract-first definition', limit: 10 } }));
       expect(knowledgeSearch.totalFound).toBeGreaterThan(0);
-      expect(knowledgeSearch.results.map((result) => result.key)).toContain('arr-contract-first');
+      expect(knowledgeSearch.results.map((result) => result.key)).toContain('orbit-arr-contract-first-definition');
 
       const knowledgeRead = structuredContent<{
         key: string;
@@ -378,26 +378,26 @@ describe('standalone built ktx CLI smoke', () => {
         content: string;
         tags: string[];
         slRefs: string[];
-      }>(await client.callTool({ name: 'knowledge_read', arguments: { key: 'arr-contract-first' } }));
-      expect(knowledgeRead.key).toBe('arr-contract-first');
+      }>(await client.callTool({ name: 'knowledge_read', arguments: { key: 'orbit-arr-contract-first-definition' } }));
+      expect(knowledgeRead.key).toBe('orbit-arr-contract-first-definition');
       expect(knowledgeRead.summary).toContain('ARR');
       expect(knowledgeRead.content).toContain('contract');
-      expect(knowledgeRead.slRefs).toContain('orbit_demo.contracts');
+      expect(knowledgeRead.slRefs).toContain('mart_arr_daily');
 
       const slRead = structuredContent<{ sourceName: string; yaml: string }>(
         await client.callTool({
           name: 'sl_read_source',
-          arguments: { connectionId: 'orbit_demo', sourceName: 'accounts' },
+          arguments: { connectionId: 'dbt-main', sourceName: 'mart_arr_daily' },
         }),
       );
-      expect(slRead.sourceName).toBe('accounts');
-      expect(slRead.yaml).toContain('name: accounts');
+      expect(slRead.sourceName).toBe('mart_arr_daily');
+      expect(slRead.yaml).toContain('name: mart_arr_daily');
       expect(slRead.yaml).toContain('measures:');
 
       const slValidate = structuredContent<{ success: boolean; errors: string[]; warnings: string[] }>(
         await client.callTool({
           name: 'sl_validate',
-          arguments: { connectionId: 'orbit_demo', names: ['accounts', 'contracts'] },
+          arguments: { connectionId: 'dbt-main', names: ['mart_arr_daily', 'stg_contracts'] },
         }),
       );
       expect(slValidate.success).toBe(true);