docs: align managed runtime examples

README.md

@@ -20,13 +20,11 @@ artifacts. You can inspect them, commit them, and serve them to any MCP client.
 
 ## Quick start
 
-Run the pre-seeded demo from the repository root:
+Run the pre-seeded demo through the public npm package:
 
 ```bash
-pnpm install
-pnpm run setup:dev
-pnpm run ktx -- setup demo --no-input
-pnpm run ktx -- setup demo inspect
+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
@@ -35,7 +33,7 @@ require API keys, network access, or an LLM provider.
 To replay the packaged ingest run, use:
 
 ```bash
-pnpm run ktx -- setup demo --mode replay --no-input
+npx @kaelio/ktx setup demo --mode replay --no-input
 ```
 
 To run the full agentic demo with an LLM provider, set a provider key for the
@@ -43,22 +41,29 @@ current process:
 
 ```bash
 ANTHROPIC_API_KEY=$YOUR_ANTHROPIC_API_KEY \
-  pnpm run ktx -- setup demo --mode full --no-input
+  npx @kaelio/ktx setup demo --mode full --no-input
 ```
 
 Interactive full-demo setup can prompt for a provider key without writing the
 key to `ktx.yaml`.
 
-## Build a local project
-
-Create a project from the repository root:
+You can also install the CLI in a project or globally:
 
 ```bash
-uv sync --all-packages
-source .venv/bin/activate
+npm install @kaelio/ktx
+npx ktx --help
+npm install -g @kaelio/ktx
+ktx --help
+```
 
+## Build a local project
+
+Create a project from a local workspace:
+
+```bash
+npm install @kaelio/ktx
 PROJECT_DIR="$(mktemp -d)/ktx-demo"
-pnpm run ktx -- init "$PROJECT_DIR" --name ktx-demo
+npx ktx init "$PROJECT_DIR" --name ktx-demo
 ```
 
 Create a SQLite warehouse:
@@ -112,7 +117,7 @@ YAML
 Write and validate a semantic-layer source:
 
 ```bash
-pnpm run ktx -- sl write accounts --project-dir "$PROJECT_DIR" \
+npx ktx sl write accounts --project-dir "$PROJECT_DIR" \
   --connection-id warehouse --yaml 'name: accounts
 table: accounts
 description: CRM accounts with segmentation attributes.
@@ -133,14 +138,14 @@ measures:
 joins: []
 '
 
-pnpm run ktx -- sl validate accounts --project-dir "$PROJECT_DIR" \
+npx ktx sl validate accounts --project-dir "$PROJECT_DIR" \
   --connection-id warehouse
 ```
 
 Generate SQL and execute the query:
 
 ```bash
-pnpm run ktx -- sl query --project-dir "$PROJECT_DIR" \
+npx ktx sl query --project-dir "$PROJECT_DIR" \
   --connection-id warehouse \
   --measure accounts.account_count \
   --dimension accounts.segment \
@@ -148,7 +153,7 @@ pnpm run ktx -- sl query --project-dir "$PROJECT_DIR" \
   --limit 5 \
   --format sql
 
-pnpm run ktx -- sl query --project-dir "$PROJECT_DIR" \
+npx ktx sl query --project-dir "$PROJECT_DIR" \
   --connection-id warehouse \
   --measure accounts.account_count \
   --dimension accounts.segment \
@@ -161,8 +166,8 @@ pnpm run ktx -- sl query --project-dir "$PROJECT_DIR" \
 List and test the warehouse connection:
 
 ```bash
-pnpm run ktx -- connection list --project-dir "$PROJECT_DIR"
-pnpm run ktx -- connection test warehouse --project-dir "$PROJECT_DIR"
+npx ktx connection list --project-dir "$PROJECT_DIR"
+npx ktx connection test warehouse --project-dir "$PROJECT_DIR"
 ```
 
 The connection test prints the configured driver and discovered table count:
@@ -179,34 +184,55 @@ Scan artifacts are written under
 
 ```bash
 
-SCAN_OUTPUT="$(pnpm run ktx -- scan warehouse --project-dir "$PROJECT_DIR")"
+SCAN_OUTPUT="$(npx ktx scan warehouse --project-dir "$PROJECT_DIR")"
 printf '%s\n' "$SCAN_OUTPUT"
 SCAN_RUN_ID="$(printf '%s\n' "$SCAN_OUTPUT" | awk '/^Run: / { print $2 }')"
-pnpm run ktx -- scan status --project-dir "$PROJECT_DIR" "$SCAN_RUN_ID"
-pnpm run ktx -- scan report --project-dir "$PROJECT_DIR" "$SCAN_RUN_ID"
+npx ktx scan status --project-dir "$PROJECT_DIR" "$SCAN_RUN_ID"
+npx 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:
+
+```bash
+npx ktx runtime install --yes
+npx ktx runtime status
+npx ktx runtime doctor
+npx ktx runtime start
+npx ktx runtime stop
+```
+
+Commands such as `npx @kaelio/ktx sl query ... --yes` can install the core
+runtime lazily from the bundled wheel. Local embeddings remain lazy; prepare
+them only when you select local `sentence-transformers` embeddings:
+
+```bash
+npx ktx runtime install --feature local-embeddings --yes
+npx ktx runtime start --feature local-embeddings
+```
+
 ## Serve MCP
 
-Start the Python compute daemon in one terminal:
+Start the stdio MCP server from the project directory:
 
 ```bash
-source .venv/bin/activate
-uv run ktx-daemon serve-http --host 127.0.0.1 --port 8765
-```
-
-Start the stdio MCP server in another terminal:
-
-```bash
-pnpm run ktx -- serve --mcp stdio --project-dir "$PROJECT_DIR" \
+npx ktx serve --mcp stdio --project-dir "$PROJECT_DIR" \
   --user-id local \
-  --semantic-compute-url http://127.0.0.1:8765 \
-  --execute-queries
+  --semantic-compute \
+  --execute-queries \
+  --yes
 ```
 
+The `--semantic-compute` flag uses the managed Python runtime when no explicit
+semantic compute URL is provided. KTX starts or reuses the managed runtime as
+needed.
+
 The 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`,
@@ -252,10 +278,10 @@ packages.
 
 ## Release status
 
-This repository is prepared for source publication. Package publishing is still
-disabled by `release-policy.json`; registry names, public versions, package
-visibility, and provenance policy must be chosen before publishing artifacts to
-npm or Python package indexes.
+This repository builds a single public npm artifact named `@kaelio/ktx`.
+Package publishing is still disabled by `release-policy.json`; registry
+credentials, public versions, release tags, and provenance policy must be
+chosen before publishing artifacts to npm or Python package indexes.
 
 Build local package artifacts with: