@kaelio/ktx 0.11.0 → 0.13.0

package/dist/skills/lookml_ingest/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: lookml_ingest
-description: Map a LookML view/model/explore into KTX semantic layer sources. Covers the LookML to KTX primitive table, provenance tagging, and three worked examples (overlay, standalone from derived_table, standalone with sql_always_where). Load when the turn contains `.lkml` content.
+description: Map a LookML view/model/explore into ktx semantic layer sources. Covers the LookML to ktx primitive table, provenance tagging, and three worked examples (overlay, standalone from derived_table, standalone with sql_always_where). Load when the turn contains `.lkml` content.
 callers: [memory_agent]
 ---
 
-# LookML to KTX Semantic Layer
+# LookML to ktx Semantic Layer
 
 LookML views map to SL sources, `measure:` to measures, `explore: { join: }` to the join graph. This skill lays out the mapping and the three capture shapes.
 
 ## Mapping table
 
-| LookML | KTX form | Notes |
+| LookML | ktx form | Notes |
 |---|---|---|
-| `view: X { sql_table_name: …; measure:/dimension:/join: }` | **Overlay** at `<connId>/X.yaml` with `measures`, computed-only `columns`, `column_overrides`, `joins`, `segments` | Manifest-backed; inherit grain/columns |
+| `view: X { sql_table_name: …; measure:/dimension:/join: }` | **Overlay** named `X` with `measures`, computed-only `columns`, `column_overrides`, `joins`, `segments` | Manifest-backed; inherit grain/columns |
 | `view: X { derived_table: { sql: … } }` | **Standalone** with top-level `sql:`, explicit `grain:` + `columns:` | No manifest entry exists |
 | `view: X { sql_always_where: <p> }` | **Standalone** with `sql: SELECT * FROM <base> WHERE <p>` | Enforcement, not opt-in |
 | `explore: { join: Y { sql_on: …; relationship: … } }` | `joins:` entry `{ to: Y, on: "<local> = Y.<col>", relationship: … }` | On the overlay or standalone |
@@ -23,7 +23,7 @@ Type map: `date`/`datetime`/`timestamp` → `time`; `yesno` → `boolean`; `numb
 
 ## Decision rules
 
-LookML writes target the run connection directly. Unlike Looker runtime ingestion, the LookML adapter is configured on the warehouse KTX connection, so do not look for `targetWarehouseConnectionId` and do not route through a mapping array.
+LookML writes target the run connection directly. Unlike Looker runtime ingestion, the LookML adapter is configured on the warehouse ktx connection, so do not look for `targetWarehouseConnectionId` and do not route through a mapping array.
 
 Before any SL write, inspect the WorkUnit notes.
 
@@ -94,7 +94,7 @@ SL source, `tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:
    schema or dataset, and table from the WorkUnit evidence.
 3. Use only those names in `sql:`, `columns:`, and `grain:`. Map each `dimension_group` to ONE `{ name: <physical_col>, type: time, role: time }` entry - never one per timeframe.
 
-| LookML input | KTX `columns:` entry |
+| LookML input | ktx `columns:` entry |
 |---|---|
 | `dimension_group: month { type: time; timeframes: [month]; sql: ${TABLE}.month_date ;; }` | `{ name: month_date, type: time, role: time }` |
 | `dimension_group: date { type: time; timeframes: [raw, date, week, month]; sql: ${TABLE}.date ;; }` | `{ name: date, type: time, role: time }` - single entry, NOT `date_raw`/`date_date`/`date_week` |
@@ -132,7 +132,7 @@ explore: fct_labs {
 }
 ```
 
-KTX overlay at `<connId>/fct_labs.yaml`:
+ktx overlay at `<connId>/fct_labs.yaml`:
 
 ```yaml
 name: fct_labs

package/dist/skills/metabase_ingest/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: metabase_ingest
-description: Convert Metabase questions, models, and metrics into KTX Semantic Layer source definitions. Covers result-metadata to KSL column type mapping, FK/PK detection, near-duplicate deduplication, pre-aggregation decomposition, join-graph connectivity, and how to react to priorProvenance from earlier ingest syncs. Load when the WorkUnit contains `cards/<id>.json` files under a Metabase bundle.
+description: Convert Metabase questions, models, and metrics into ktx Semantic Layer source definitions. Covers result-metadata to KSL column type mapping, FK/PK detection, near-duplicate deduplication, pre-aggregation decomposition, join-graph connectivity, and how to react to priorProvenance from earlier ingest syncs. Load when the WorkUnit contains `cards/<id>.json` files under a Metabase bundle.
 callers: [memory_agent]
 ---
 
-# Metabase to KTX Semantic Layer
+# Metabase to ktx Semantic Layer
 
-Each WorkUnit represents one Metabase collection's cards for one Metabase database (mapped to exactly one KTX connection). Every `cards/<id>.json` file carries the resolved SQL, result_metadata, card type, collection path, and referenced-card ids. The WU's `sync-config.json` tells you which sync mode is active and which selections apply. `databases/<id>.json` tells you the target KTX connection.
+Each WorkUnit represents one Metabase collection's cards for one Metabase database (mapped to exactly one ktx connection). Every `cards/<id>.json` file carries the resolved SQL, result_metadata, card type, collection path, and referenced-card ids. The WU's `sync-config.json` tells you which sync mode is active and which selections apply. `databases/<id>.json` tells you the target ktx connection.
 
 ## Context format
 
@@ -100,7 +100,7 @@ measures:
 
 Overlay shape: `name:` plus any of `measures:`, `segments:`, `descriptions:`, `joins:`, `disable_joins:`, `exclude_columns:`, `column_overrides:`, or computed-only `columns:` entries with `expr` + `type`. Never include `sql:`, `table:`, `grain:`, or base-table `columns:` on a manifest-backed name — those would shadow the manifest's schema and drop its joins. Use `column_overrides:` for inherited column descriptions. Overlay `joins:` are merged additively with the manifest's joins (deduped by `to` + `on`); use `disable_joins: ["<on-clause>"]` to suppress a specific manifest join. After the overlay exists, use `sl_edit_source` for further tweaks. See `sl_capture` skill for the canonical overlay rule.
 
-**Join discovery:** When your card's SQL references warehouse tables (e.g. in `FROM` or `JOIN` clauses), call `sl_discover({ query: '<table>' })` before writing. The matching manifest entry's `name` is the value you use in `joins: [- to: <name>]` only when the card output exposes a local key that matches the target source grain (for example `account_id = mart_account_segments.account_id`). Do not declare a KTX join just because the card SQL joins that table internally. If the output only exposes display fields such as `account_name`, keep the SQL source self-contained or project the key before adding the join. Use `many_to_one` for FK-to-dimension joins, `one_to_many` for the reverse.
+**Join discovery:** When your card's SQL references warehouse tables (e.g. in `FROM` or `JOIN` clauses), call `sl_discover({ query: '<table>' })` before writing. The matching manifest entry's `name` is the value you use in `joins: [- to: <name>]` only when the card output exposes a local key that matches the target source grain (for example `account_id = mart_account_segments.account_id`). Do not declare a ktx join just because the card SQL joins that table internally. If the output only exposes display fields such as `account_name`, keep the SQL source self-contained or project the key before adding the join. Use `many_to_one` for FK-to-dimension joins, `one_to_many` for the reverse.
 
 **Hard rule on join columns (prevents broken joins):** For every join you declare, the local column on the left of `on:` MUST be (a) present in your source's projected output and (b) a key/ID column, never a display value. If the natural FK isn't in your SELECT, add it to SELECT before declaring the join. Joining `account_name = mart_account_segments.account_id` is always wrong - names are not identifiers and the equality produces zero matches. The validator rejects this with a "display value to identifier" error; the tool will refuse to save it. Add `account_id` to your SELECT and join on `account_id = mart_account_segments.account_id`, or omit the join entirely.
 

package/dist/skills/metricflow_ingest/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: metricflow_ingest
-description: Map a MetricFlow semantic_model or metric into KTX semantic layer sources. Covers the MetricFlow to KTX primitive table, `extends:` inheritance flattening, metric-type handling (simple / derived / ratio / cumulative / conversion), `model: ref('x')` resolution, and four worked examples. Load when the turn contains `.yml`/`.yaml` files with top-level `semantic_models:` or `metrics:`.
+description: Map a MetricFlow semantic_model or metric into ktx semantic layer sources. Covers the MetricFlow to ktx primitive table, `extends:` inheritance flattening, metric-type handling (simple / derived / ratio / cumulative / conversion), `model: ref('x')` resolution, and four worked examples. Load when the turn contains `.yml`/`.yaml` files with top-level `semantic_models:` or `metrics:`.
 callers: [memory_agent]
 ---
 
-# MetricFlow to KTX Semantic Layer
+# MetricFlow to ktx Semantic Layer
 
-A MetricFlow `semantic_model` maps to an SL source; MetricFlow `measures` map to KTX measures; MetricFlow `entities` map to KTX `joins`; MetricFlow `metrics` (top-level) map to KTX measures OR to cross-model derived measures. Files in one WorkUnit are ALWAYS part of the same logical entity (a connected component, possibly spanning `extends:` + cross-model metric refs). Flatten inheritance and cross-file references at write time.
+A MetricFlow `semantic_model` maps to an SL source; MetricFlow `measures` map to ktx measures; MetricFlow `entities` map to ktx `joins`; MetricFlow `metrics` (top-level) map to ktx measures OR to cross-model derived measures. Files in one WorkUnit are ALWAYS part of the same logical entity (a connected component, possibly spanning `extends:` + cross-model metric refs). Flatten inheritance and cross-file references at write time.
 
 ## Mapping table
 
-| MetricFlow | KTX form | Notes |
+| MetricFlow | ktx form | Notes |
 |---|---|---|
-| `semantic_model: X { model: ref('t') }` with measures + dimensions | **Overlay** at `<connId>/X.yaml` with `measures`, computed-only `columns`, `column_overrides`, `joins` | The `model:` ref resolves to a manifest table. |
-| `semantic_model: X { model: source('s','t') }` | **Overlay** at `<connId>/X.yaml` over table `t`. | Same shape; `source()` still resolves to a physical table. |
+| `semantic_model: X { model: ref('t') }` with measures + dimensions | **Overlay** named `X` with `measures`, computed-only `columns`, `column_overrides`, `joins` | The `model:` ref resolves to a manifest table. |
+| `semantic_model: X { model: source('s','t') }` | **Overlay** named `X` over table `t`. | Same shape; `source()` still resolves to a physical table. |
 | `semantic_model: X { model: <literal> }` with no manifest entry | **Standalone** with explicit `sql:`, `grain:`, `columns:` | Happens when the dbt manifest isn't available. |
 | `semantic_model: Y { extends: X }` | **Merge** Y's measures/dimensions/entities into X's overlay, or write a single overlay named for the most-derived child (Y) containing both X's and Y's primitives | Do not emit a second overlay for X - flatten. |
 | `measures: [{ name, agg, expr }]` | `measures: [{ name, expr: "<agg>(<expr>)" }]` | Aggregation inlined. `agg: count_distinct` → `count(distinct ...)`. |
@@ -23,11 +23,11 @@ A MetricFlow `semantic_model` maps to an SL source; MetricFlow `measures` map to
 | `metrics: [{ type: simple, filter: <jinja> }]` | **New measure** on the same source, with the filter translated to SQL and attached via `filter:` | Translate Jinja `{{ Dimension('x__y') }}` to the column name `y`. |
 | `metrics: [{ type: derived, type_params: { expr, metrics } }]` | **Derived measure** on whichever source owns the referenced measures, with `expr:` referencing measure names | If the metric spans models, still write it once on the source owning the "primary" measure (the one the agent judges most central). Mention the cross-model chain in the description. |
 | `metrics: [{ type: ratio, type_params: { numerator, denominator } }]` | Same as derived; `expr: "numerator / NULLIF(denominator, 0)"` if no explicit expr | Safe-division by default. |
-| `metrics: [{ type: cumulative, type_params: { window, grain_to_date } }]` | **Standalone** source with a window-function SQL; reference the resulting column as a normal measure | KTX SL has no first-class cumulative primitive (spec Non-goals). |
-| `metrics: [{ type: conversion }]` | **Flag for human** - do NOT write. Emit a wiki note describing the intended semantics. | No KTX equivalent in v1. |
+| `metrics: [{ type: cumulative, type_params: { window, grain_to_date } }]` | **Standalone** source with a window-function SQL; reference the resulting column as a normal measure | ktx SL has no first-class cumulative primitive (spec Non-goals). |
+| `metrics: [{ type: conversion }]` | **Flag for human** - do NOT write. Emit a wiki note describing the intended semantics. | No ktx equivalent in v1. |
 | Metric not mappable | Wiki page `<metric_name>-definition.md` with the full YAML body quoted | Capture the intent even if we can't emit SL. |
 
-Type map: MetricFlow `time` to KTX `time`; `categorical` to `string`; `number` to `number`; `boolean` to `boolean`. Follow `expr` over `name` when both differ - `expr` is the physical column.
+Type map: MetricFlow `time` to ktx `time`; `categorical` to `string`; `number` to `number`; `boolean` to `boolean`. Follow `expr` over `name` when both differ - `expr` is the physical column.
 
 Verify each MetricFlow model source table with entity_details before producing
 the corresponding sl_write_source.
@@ -92,7 +92,7 @@ After every `sl_write_source`, call `sl_validate`. The warehouse will reject inv
 
 ## Cumulative metrics - sql-standalone fallback
 
-KTX SL has no first-class `window:` or `grain_to_date:` primitive in v1 (spec Non-goals). Translate a MetricFlow cumulative metric to a standalone SL source with a window-function SQL:
+ktx SL has no first-class `window:` or `grain_to_date:` primitive in v1 (spec Non-goals). Translate a MetricFlow cumulative metric to a standalone SL source with a window-function SQL:
 
 ```yaml
 # MetricFlow input:
@@ -105,7 +105,7 @@ metrics:
 ```
 
 ```yaml
-# KTX standalone output:
+# ktx standalone output:
 name: cum_revenue_7d
 source_type: sql
 sql: |
@@ -143,7 +143,7 @@ Do NOT emit SL for this. Instead:
 - Write a wiki page at `wiki/global/<metric_name>-intent.md` quoting the full YAML body and a one-line explanation of the intended semantics (base event → conversion event within window).
 - Call `emit_unmapped_fallback` with `rawPath` set to the MetricFlow file path, `reason: "conversion_metric_unsupported"`, and `fallback: "flagged"`.
 
-When KTX SL gains conversion primitives, re-ingesting will find the prior wiki note (via `priorProvenance`) and replace it with an SL source.
+When ktx SL gains conversion primitives, re-ingesting will find the prior wiki note (via `priorProvenance`) and replace it with an SL source.
 
 ## Provenance markers
 
@@ -174,7 +174,7 @@ semantic_models:
 ```
 
 ```yaml
-# KTX overlay at <connId>/orders.yaml:
+# ktx overlay at <connId>/orders.yaml:
 # <!-- from: raw-sources/.../models/orders.yml#L1-10 -->
 name: orders
 descriptions:
@@ -217,7 +217,7 @@ metrics:
 ```
 
 ```yaml
-# KTX overlay at <connId>/orders_ext.yaml (one file; inheritance flattened):
+# ktx overlay at <connId>/orders_ext.yaml (one file; inheritance flattened):
 # <!-- from: raw-sources/.../models/orders.yml#L1-10 -->
 # <!-- from: raw-sources/.../models/orders_ext.yml#L1-8 -->
 # <!-- from: raw-sources/.../metrics/orders_final.yml#L1-10 -->
@@ -256,7 +256,7 @@ metrics:
       metrics: [{name: revenue}, {name: cost}]
 ```
 
-Because the WorkUnit bundles all three files (cross-component union via the metric), write the derived measure on ONE of the two sources - pick the source whose domain "owns" the metric (here, `sales` - margin is inherently a sales metric). Cross-source references aren't native in KTX SL; treat the metric's operands as already-resolvable in the target source's query context OR emit a standalone SQL that joins the two tables:
+Because the WorkUnit bundles all three files (cross-component union via the metric), write the derived measure on ONE of the two sources - pick the source whose domain "owns" the metric (here, `sales` - margin is inherently a sales metric). Cross-source references aren't native in ktx SL; treat the metric's operands as already-resolvable in the target source's query context OR emit a standalone SQL that joins the two tables:
 
 ```yaml
 # <connId>/sales.yaml

package/dist/skills/notion_synthesize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion_synthesize
-description: Synthesize durable KTX wiki pages and semantic-layer sources from staged Notion pages, databases, data-source rows, and clustered Notion evidence. Load when a WorkUnit contains Notion raw files or Notion evidence chunks.
+description: Synthesize durable ktx wiki pages and semantic-layer sources from staged Notion pages, databases, data-source rows, and clustered Notion evidence. Load when a WorkUnit contains Notion raw files or Notion evidence chunks.
 callers: [memory_agent]
 ---
 

package/dist/skills/sl/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: sl
-description: KTX's semantic layer - a structured catalog of sources (tables/views), measures, joins, and segments expressed as YAML. Covers the schema and how to query it via `sl_query`. Use when the task involves querying pre-defined metrics (ARR, churn, retention, LTV, MAU) or reading SL source YAML to understand the catalog. Capture is handled by the `sl_capture` skill (memory-agent only).
+description: ktx's semantic layer - a structured catalog of sources (tables/views), measures, joins, and segments expressed as YAML. Covers the schema and how to query it via `sl_query`. Use when the task involves querying pre-defined metrics (ARR, churn, retention, LTV, MAU) or reading SL source YAML to understand the catalog. Capture is handled by the `sl_capture` skill (memory-agent only).
 ---
 
 # Semantic Layer
 
-KTX's semantic layer (SL) is a structured catalog. Each **source** represents a table, a SQL view, or an overlay that enriches a manifest-backed table with measures, computed columns, joins, and named segments. The catalog is the single source of truth for reusable business metrics.
+ktx's semantic layer (SL) is a structured catalog. Each **source** represents a table, a SQL view, or an overlay that enriches a manifest-backed table with measures, computed columns, joins, and named segments. The catalog is the single source of truth for reusable business metrics.
 
 This skill covers two parts:
 - **Part 1** - Schema reference (what an SL source looks like).
@@ -21,7 +21,7 @@ skills must verify warehouse identifiers with `discover_data`,
 
 ## Part 1 - Schema reference
 
-An SL source is a YAML file at `semantic-layer/<connectionId>/<source_name>.yaml`. There are three flavors:
+An SL source is a YAML file under `semantic-layer/<connectionId>/`. The file's `name:` field is the source's identity — it mirrors the warehouse identifier verbatim (e.g. Snowflake's uppercase `SIGNED_UP`); the filename is only a derived label. Always address sources by name through the `sl_*` tools, never by file path. There are three flavors:
 
 ### Overlay sources
 

package/dist/skills/sl_capture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sl_capture
-description: How to capture new reusable patterns into KTX's semantic layer - when a measure, segment, or join belongs in the catalog and how to write it generically so it stays small and useful over time. Loaded by the post-turn memory-agent only. The research agent does not write to the SL.
+description: How to capture new reusable patterns into ktx's semantic layer - when a measure, segment, or join belongs in the catalog and how to write it generically so it stays small and useful over time. Loaded by the post-turn memory-agent only. The research agent does not write to the SL.
 callers: [memory_agent]
 ---
 

package/dist/skills/wiki_capture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki_capture
-description: KTX's knowledge base - wiki pages for durable, reusable business knowledge. Covers capture workflow for user preferences, metric definitions, organizational conventions, and cross-references between wiki pages and semantic-layer sources. Loaded by the post-turn memory-agent only. The research agent reads wiki via `wiki_read`/`wiki_search` but does not write it.
+description: ktx's knowledge base - wiki pages for durable, reusable business knowledge. Covers capture workflow for user preferences, metric definitions, organizational conventions, and cross-references between wiki pages and semantic-layer sources. Loaded by the post-turn memory-agent only. The research agent reads wiki via `wiki_read`/`wiki_search` but does not write it.
 callers: [memory_agent]
 ---
 

package/dist/source-mapping.js

@@ -23,7 +23,7 @@ async function createDefaultLookerClient(project, connectionId) {
             return lookerCredentialsFromLocalConnection(lookerConnectionId, project.config.connections[lookerConnectionId]);
         },
     });
-    return factory.createClient(connectionId);
+    return factory.createLookerClient(connectionId);
 }
 function isLookerConnection(project, connectionId) {
     return String(project.config.connections[connectionId]?.driver ?? '').toLowerCase() === 'looker';

package/dist/sql.d.ts

@@ -1,3 +1,4 @@
+import { executeFederatedQuery } from './connectors/duckdb/federated-executor.js';
 import { loadKtxProject } from './context/project/project.js';
 import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
 import type { KtxCliIo } from './cli-runtime.js';
@@ -18,6 +19,7 @@ export interface KtxSqlDeps {
     loadProject?: typeof loadKtxProject;
     createSqlAnalysis?: () => SqlAnalysisPort;
     createScanConnector?: typeof createKtxCliScanConnector;
+    executeFederated?: typeof executeFederatedQuery;
 }
 export declare function runKtxSql(args: KtxSqlArgs, io?: KtxCliIo, deps?: KtxSqlDeps): Promise<number>;
 export {};

package/dist/sql.js

@@ -1,4 +1,8 @@
+import { FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
+import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
+import { resolveConfiguredConnection } from './context/connections/resolve-connection.js';
 import { loadKtxProject } from './context/project/project.js';
+import { sqlAnalysisDialectForDriver } from './context/sql-analysis/dialect.js';
 import { resolveOutputMode } from './io/mode.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { createManagedDaemonSqlAnalysisPort } from './managed-python-http.js';
@@ -8,19 +12,6 @@ import { emitTelemetryEvent, reportException } from './telemetry/index.js';
 import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:sql');
-function sqlAnalysisDialectForDriver(driver) {
-    const normalized = String(driver ?? '').trim().toLowerCase();
-    const map = {
-        postgres: 'postgres',
-        bigquery: 'bigquery',
-        snowflake: 'snowflake',
-        mysql: 'mysql',
-        sqlserver: 'tsql',
-        sqlite: 'sqlite',
-        clickhouse: 'clickhouse',
-    };
-    return map[normalized] ?? 'postgres';
-}
 function queryVerb(sql) {
     const first = sql.trim().split(/\s+/, 1)[0]?.toLowerCase();
     if (first === 'select' || first === 'explain' || first === 'show' || first === 'with') {
@@ -79,11 +70,6 @@ function printSqlResult(output, mode, io) {
     }
     printPretty(output, io);
 }
-async function cleanupConnector(connector) {
-    if (connector?.cleanup) {
-        await connector.cleanup();
-    }
-}
 function resultOutput(connectionId, result) {
     return {
         connectionId,
@@ -100,12 +86,10 @@ export async function runKtxSql(args, io = process, deps = {}) {
     let project;
     try {
         project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
-        const connection = project.config.connections[args.connectionId];
-        if (!connection) {
-            throw new Error(`Connection "${args.connectionId}" is not configured in ktx.yaml`);
-        }
-        driver = String(connection.driver ?? 'unknown').toLowerCase();
-        demoConnection = isDemoConnection(args.connectionId, connection);
+        const isFederated = args.connectionId === FEDERATED_CONNECTION_ID;
+        const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, args.connectionId);
+        driver = isFederated ? 'duckdb' : String(connection?.driver ?? 'unknown').toLowerCase();
+        demoConnection = isFederated ? false : isDemoConnection(args.connectionId, connection);
         const createSqlAnalysis = deps.createSqlAnalysis ??
             (() => createManagedDaemonSqlAnalysisPort({
                 cliVersion: args.cliVersion,
@@ -114,44 +98,42 @@ export async function runKtxSql(args, io = process, deps = {}) {
                 io,
             }));
         const analysisPort = createSqlAnalysis();
-        const dialect = sqlAnalysisDialectForDriver(connection.driver);
+        const dialect = isFederated ? 'duckdb' : sqlAnalysisDialectForDriver(connection?.driver);
         const validation = await analysisPort.validateReadOnly(args.sql, dialect);
         if (!validation.ok) {
             throw new Error(validation.error ?? 'SQL is not read-only.');
         }
         const referencedTableCount = await safeReferencedTableCount(analysisPort, args.sql, dialect);
         const createScanConnector = deps.createScanConnector ?? createKtxCliScanConnector;
-        let connector = null;
-        try {
-            connector = await createScanConnector(project, args.connectionId);
-            if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
-                throw new Error(`Connection "${args.connectionId}" does not support read-only SQL execution.`);
-            }
-            const result = await connector.executeReadOnly({
+        const result = await executeProjectReadOnlySql({
+            project,
+            input: {
                 connectionId: args.connectionId,
+                projectDir: args.projectDir,
+                connection,
                 sql: args.sql,
                 maxRows: args.maxRows,
-            }, { runId: 'cli-sql' });
-            const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
-            printSqlResult(resultOutput(args.connectionId, result), mode, io);
-            await emitTelemetryEvent({
-                name: 'sql_completed',
-                projectDir: args.projectDir,
-                io,
-                fields: {
-                    driver,
-                    isDemoConnection: demoConnection,
-                    queryVerb: queryVerb(args.sql),
-                    referencedTableCount,
-                    durationMs: Math.max(0, performance.now() - startedAt),
-                    outcome: 'ok',
-                },
-            });
-            return 0;
-        }
-        finally {
-            await cleanupConnector(connector);
-        }
+            },
+            createConnector: (connectionId) => createScanConnector(project, connectionId),
+            executeFederated: deps.executeFederated,
+            runId: 'cli-sql',
+        });
+        const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
+        printSqlResult(resultOutput(args.connectionId, result), mode, io);
+        await emitTelemetryEvent({
+            name: 'sql_completed',
+            projectDir: args.projectDir,
+            io,
+            fields: {
+                driver,
+                isDemoConnection: demoConnection,
+                queryVerb: queryVerb(args.sql),
+                referencedTableCount,
+                durationMs: Math.max(0, performance.now() - startedAt),
+                outcome: 'ok',
+            },
+        });
+        return 0;
     }
     catch (error) {
         const errorClass = scrubErrorClass(error);

package/dist/startup-profile.js

@@ -28,7 +28,7 @@ export function installStartupProfileReporter() {
     }
     process.once('beforeExit', () => {
         const total = now();
-        process.stderr.write('\nKTX startup profile\n');
+        process.stderr.write('\nktx startup profile\n');
         for (const event of events) {
             const elapsed = event.at.toFixed(1).padStart(7);
             if (event.duration === undefined) {

package/dist/status-project.d.ts

@@ -40,7 +40,6 @@ interface PipelineStatus {
 interface StorageStatus {
     state: string;
     search: string;
-    gitAutoCommit: boolean;
     gitAuthor: string;
 }
 interface ConfigStatus {
@@ -133,7 +132,6 @@ export interface ProjectStatus {
         maxConcurrency: number;
         failureMode: string;
     };
-    memoryAutoCommit: boolean;
     relationshipsDetail?: {
         acceptThreshold: number;
         reviewThreshold: number;

package/dist/status-project.js

@@ -384,7 +384,6 @@ function buildStorageStatus(config) {
     return {
         state: config.storage.state,
         search: config.storage.search,
-        gitAutoCommit: config.storage.git.auto_commit,
         gitAuthor: config.storage.git.author,
     };
 }
@@ -498,9 +497,10 @@ function buildConfigStatus(issues) {
     if (list.length === 0) {
         return { status: 'ok', detail: 'ktx.yaml schema valid', issues: [] };
     }
+    // Error-severity issues never reach here — the doctor exits on them first.
     return {
         status: 'warn',
-        detail: `${list.length} issue${list.length === 1 ? '' : 's'} in ktx.yaml`,
+        detail: `ktx.yaml schema valid · ${list.length} ignored field${list.length === 1 ? '' : 's'}`,
         issues: list,
     };
 }
@@ -713,7 +713,6 @@ export async function buildProjectStatus(project, options = {}) {
             maxConcurrency: config.ingest.workUnits.maxConcurrency,
             failureMode: config.ingest.workUnits.failureMode,
         },
-        memoryAutoCommit: config.memory.auto_commit,
         relationshipsDetail: {
             acceptThreshold: config.scan.relationships.acceptThreshold,
             reviewThreshold: config.scan.relationships.reviewThreshold,
@@ -840,7 +839,7 @@ export function renderProjectStatus(status, options = {}) {
     const sym = (level) => color(level, SYMBOL[level]);
     const lines = [];
     const dirStr = abbreviateHome(status.projectDir, env);
-    lines.push(`${bold('KTX status')} ${dim('·')} ${status.projectName} ${dim(`(${dirStr})`)}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${status.projectName} ${dim(`(${dirStr})`)}`);
     lines.push('');
     const labelPad = 'Connections'.length;
     const label = (text) => text.padEnd(labelPad);
@@ -960,8 +959,7 @@ export function renderProjectStatus(status, options = {}) {
             lines.push(`  ${bold('Relationships')}    ${dim(`accept=${r.acceptThreshold}, review=${r.reviewThreshold}, maxLlmTables=${r.maxLlmTablesPerBatch}, concurrency=${r.validationConcurrency}`)}`);
         }
         lines.push(`  ${bold('Agent')}            ${dim(`max_iterations=${status.pipeline.agentMaxIterations}, tools=${status.pipeline.agentTools.join(', ') || '(none)'}`)}`);
-        lines.push(`  ${bold('Memory')}           ${dim(`auto_commit=${status.memoryAutoCommit}`)}`);
-        lines.push(`  ${bold('Git')}              ${dim(`auto_commit=${status.storage.gitAutoCommit}, author=${status.storage.gitAuthor}`)}`);
+        lines.push(`  ${bold('Git')}              ${dim(`author=${status.storage.gitAuthor}`)}`);
         lines.push('');
     }
     // Verdict + next steps

package/dist/telemetry/events.d.ts

@@ -303,6 +303,7 @@ export declare const telemetryEventSchemas: {
         }>;
         durationMs: z.ZodNumber;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         sampleRate: z.ZodLiteral<1>;
         mcpClientName: z.ZodOptional<z.ZodString>;
         mcpClientVersion: z.ZodOptional<z.ZodString>;
@@ -357,9 +358,9 @@ export declare const telemetryEventSchemas: {
             error: "error";
         }>;
         stage: z.ZodEnum<{
+            resolve: "resolve";
             parse: "parse";
             compile: "compile";
-            resolve: "resolve";
             transpile: "transpile";
         }>;
         errorClass: z.ZodOptional<z.ZodString>;
@@ -459,7 +460,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "mcp_request_completed";
     readonly description: "Emitted for sampled MCP tool requests.";
-    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate", "mcpClientName", "mcpClientVersion"];
+    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "errorDetail", "sampleRate", "mcpClientName", "mcpClientVersion"];
 }, {
     readonly name: "daemon_started";
     readonly description: "Emitted when the long-lived ktx-daemon HTTP server starts.";

package/dist/telemetry/events.js

@@ -145,6 +145,7 @@ const mcpRequestCompletedSchema = telemetryCommonEnvelopeSchema
     outcome: outcomeSchema,
     durationMs: z.number().nonnegative(),
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     sampleRate: z.literal(1),
     // Raw, client-tool-controlled identity from the MCP initialize handshake
     // (clientInfo.name/version). Optional: clients may omit clientInfo. Stored
@@ -326,7 +327,16 @@ export const telemetryEventCatalog = [
     {
         name: 'mcp_request_completed',
         description: 'Emitted for sampled MCP tool requests.',
-        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate', 'mcpClientName', 'mcpClientVersion'],
+        fields: [
+            'toolName',
+            'outcome',
+            'durationMs',
+            'errorClass',
+            'errorDetail',
+            'sampleRate',
+            'mcpClientName',
+            'mcpClientVersion',
+        ],
     },
     {
         name: 'daemon_started',

package/dist/telemetry/exception.js

@@ -1,5 +1,6 @@
 import { inspect } from 'node:util';
 import { getKtxCliPackageInfo } from '../cli-runtime.js';
+import { KtxExpectedError } from '../errors.js';
 import { buildCommonEnvelope } from './events.js';
 import { trackTelemetryException } from './emitter.js';
 import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
@@ -24,6 +25,16 @@ function consumeHandledPrimitive(value) {
     recentHandledPrimitives.splice(index, 1);
     return true;
 }
+/**
+ * Expected operational errors are surfaced to the caller and recorded by the
+ * outcome-tagged telemetry events; they are not ktx faults, so they never reach
+ * Error Tracking. ktx marks these with KtxExpectedError at the site that knows
+ * the rejection is expected — the classification is never inferred globally from
+ * a generic error type, which would also swallow internal/fatal faults.
+ */
+function isExpectedError(error) {
+    return error instanceof KtxExpectedError;
+}
 function shouldSkipAsAlreadyReported(error, handled) {
     if ((typeof error === 'object' || typeof error === 'function') && error !== null) {
         if (reportedObjects.has(error)) {
@@ -116,6 +127,9 @@ function sanitizedError(error, secrets) {
 }
 export async function reportException(input) {
     try {
+        if (isExpectedError(input.error)) {
+            return;
+        }
         if (shouldSkipAsAlreadyReported(input.error, input.context.handled)) {
             return;
         }

package/dist/text-ingest.js

@@ -213,7 +213,7 @@ export async function runKtxTextIngest(args, io, deps = {}) {
                 const ingestInput = {
                     userId: args.userId,
                     chatId: `cli-text-ingest-${batchId}-${index + 1}`,
-                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into KTX memory.`,
+                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into ktx memory.`,
                     assistantMessage: item.content.trim(),
                     ...(args.connectionId ? { connectionId: args.connectionId } : {}),
                     sourceType: 'external_ingest',

package/dist/tree-picker-tui.d.ts

@@ -33,7 +33,6 @@ export type TreePickerResult = {
 };
 export interface TreePickerChrome {
     title: string;
-    helpText?: string;
     subtitleLines?: readonly string[];
     warningLines?: readonly string[];
     confirmSaveMessage?: (state: PickerState) => string;

package/dist/tree-picker-tui.js

@@ -3,6 +3,7 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Box, Text, render as renderInkRuntime, useApp, useInput } from 'ink';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { filterTree, flattenSelection, hasPartialChildren, isAncestorChecked, reducer, visibleNodeIds, } from './tree-picker-state.js';
+import { TREE_PICKER_NAVIGATION_HINT } from './prompt-navigation.js';
 const COLOR_THEME = {
     text: 'white',
     muted: 'gray',
@@ -17,7 +18,6 @@ const NO_COLOR_THEME = {
     selected: 'white',
     warning: 'white',
 };
-const DEFAULT_TREE_PICKER_HELP_TEXT = 'Up/Down to move, Right/Left to expand or collapse, Tab to select, Type to search, Enter to confirm, Escape to clear search or go back, Ctrl+C to exit.';
 const DEFAULT_SKIP_EMPTY_MESSAGE = 'Nothing selected. Skip this step? Press Enter to skip or Escape to go back.';
 function resolveTheme(env = process.env) {
     return env.NO_COLOR || env.TERM === 'dumb' ? NO_COLOR_THEME : COLOR_THEME;
@@ -136,7 +136,6 @@ export function TreePickerApp(props) {
     const hiddenBelow = Math.max(0, visibleIds.length - rows.offset - rows.items.length);
     const searchMatchCount = filterTree(state).visibleIds.size;
     const width = resolveTreePickerWidth(props.terminalWidth);
-    const helpText = props.chrome.helpText ?? DEFAULT_TREE_PICKER_HELP_TEXT;
     const skipEmptyMessage = props.chrome.skipEmptyMessage ?? DEFAULT_SKIP_EMPTY_MESSAGE;
     stateRef.current = state;
     useEffect(() => {
@@ -177,7 +176,7 @@ export function TreePickerApp(props) {
             app.exit();
         }
     });
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.active, children: "\u25C6" }), _jsxs(Text, { bold: true, children: [" ", props.chrome.title] })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderTop: false, borderRight: false, borderBottom: false, borderColor: theme.active, paddingLeft: 1, children: [_jsx(Text, { color: theme.muted, children: helpText }), _jsx(Text, { children: " " }), (props.chrome.subtitleLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.muted, children: line }, `subtitle-${idx}`))), (props.chrome.warningLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.warning, children: line }, `chromewarn-${idx}`))), state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: warning }, warning))), _jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "Search: " }), state.isNavigating ? (_jsx(Text, { color: theme.muted, children: state.search.query || '(type to filter)' })) : (_jsxs(Text, { children: [state.search.query, _jsx(Text, { inverse: true, children: " " })] })), _jsxs(Text, { color: theme.muted, children: ["  (", searchMatchCount, " match", searchMatchCount === 1 ? '' : 'es', ")"] })] }), _jsx(Text, { children: " " }), hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null, state.pendingConfirm === 'save-confirm' ? (_jsx(Text, { color: theme.warning, children: props.chrome.confirmSaveMessage
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { color: theme.active, children: "\u25C6" }), _jsxs(Text, { bold: true, children: [" ", props.chrome.title] })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderTop: false, borderRight: false, borderBottom: false, borderColor: theme.active, paddingLeft: 1, children: [_jsx(Text, { color: theme.muted, children: TREE_PICKER_NAVIGATION_HINT }), _jsx(Text, { children: " " }), (props.chrome.subtitleLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.muted, children: line }, `subtitle-${idx}`))), (props.chrome.warningLines ?? []).map((line, idx) => (_jsx(Text, { color: theme.warning, children: line }, `chromewarn-${idx}`))), state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: warning }, warning))), _jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "Search: " }), state.isNavigating ? (_jsx(Text, { color: theme.muted, children: state.search.query || '(type to search)' })) : (_jsxs(Text, { children: [state.search.query, _jsx(Text, { inverse: true, children: " " })] })), _jsxs(Text, { color: theme.muted, children: ["  (", searchMatchCount, " match", searchMatchCount === 1 ? '' : 'es', ")"] })] }), _jsx(Text, { children: " " }), hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null, state.pendingConfirm === 'save-confirm' ? (_jsx(Text, { color: theme.warning, children: props.chrome.confirmSaveMessage
                             ? props.chrome.confirmSaveMessage(state)
                             : 'Confirm save? Press Enter to confirm or Escape to go back.' })) : null, state.pendingConfirm === 'skip-empty' ? _jsx(Text, { color: theme.warning, children: skipEmptyMessage }) : null, state.transientHint ? _jsx(Text, { color: theme.warning, children: state.transientHint.text }) : null] }), _jsx(Text, { color: theme.active, children: "\u2514" })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Standalone ktx context layer for data agents",
   "author": {
     "name": "Kaelio",
@@ -40,6 +40,7 @@
     "@clack/prompts": "1.4.0",
     "@clickhouse/client": "^1.18.5",
     "@commander-js/extra-typings": "14.0.0",
+    "@duckdb/node-api": "1.5.3-r.3",
     "@google-cloud/bigquery": "^8.3.1",
     "@looker/sdk": "^26.8.0",
     "@looker/sdk-node": "^26.8.0",