@kaelio/ktx 0.10.0 → 0.12.0

package/dist/setup.js

@@ -6,6 +6,7 @@ import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { loadKtxProject } from './context/project/project.js';
 import { readKtxSetupState } from './context/project/setup-config.js';
 import { getKtxCliPackageInfo } from './cli-runtime.js';
+import { SLACK_SETUP_NOTE } from './community-cta.js';
 import { formatNextStepLines, formatSetupNextStepLines } from './next-steps.js';
 import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
@@ -36,6 +37,61 @@ function setupTelemetryOutcome(status) {
         return 'skipped';
     return 'abandoned';
 }
+/**
+ * Classify a terminal non-ready setup status into the `command` telemetry
+ * outcome. The setup flow is the decision-maker and knows the difference:
+ * - `failed` is a genuine error; attach a step-scoped reason so the dashboard
+ *   shows an actionable signature instead of a blank.
+ * - `missing-input` from a *non-interactive* run is an automation error
+ *   (required flags absent and no prompt was possible); attach a reason too.
+ * - `missing-input` from an interactive prompt, or a project `cancelled`, is the
+ *   user backing out of the wizard — an abort, not a failure. Keep it out of
+ *   error telemetry so it stops inflating the error count.
+ *
+ * `interactive` must reflect whether a prompt could actually be shown — input
+ * is enabled AND a TTY is attached. `inputMode: 'auto'` alone is not enough: a
+ * piped/CI run without `--no-input` is still non-interactive, and steps such as
+ * the project step return `missing-input` ("pass --yes …") there without ever
+ * prompting. Treating that as an abort would make a broken automation run exit
+ * 0, so it must classify as an error.
+ *
+ * Reasons are synthetic, step-scoped strings (no user input), so they satisfy
+ * the telemetry privacy rules. The step's own `errorDetail`, when present, has
+ * already been vetted for the `setup_step` event and is safe to reuse.
+ */
+function setupCommandOutcomeAnnotation(input) {
+    if (input.status === 'failed') {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupStepFailed',
+            errorDetail: input.errorDetail ?? `${input.step} setup step failed`,
+        };
+    }
+    if (input.status === 'missing-input' && !input.interactive) {
+        return {
+            outcome: 'error',
+            errorClass: 'KtxSetupMissingInput',
+            errorDetail: `${input.step} setup step requires input not provided in a non-interactive run`,
+        };
+    }
+    return { outcome: 'aborted' };
+}
+/**
+ * Single source of truth for how a non-ready setup step ends: the process exit
+ * code and the telemetry annotation are both derived from one classification,
+ * so they can never disagree. A genuine failure (`error`) exits non-zero; an
+ * abort — the user leaving an interactive wizard — exits 0, matching the entry
+ * menu's "Exit", a project cancellation, and a confirmed Ctrl+C.
+ */
+/** @internal */
+export function setupTerminalOutcome(input) {
+    const annotation = setupCommandOutcomeAnnotation(input);
+    return { exitCode: annotation.outcome === 'error' ? 1 : 0, annotation };
+}
+async function annotateSetupCommandOutcome(annotation) {
+    const { annotateCommandOutcome } = await import('./telemetry/index.js');
+    annotateCommandOutcome(annotation);
+}
 async function recordSetupStep(input) {
     const { emitTelemetryEvent } = await import('./telemetry/index.js');
     await emitTelemetryEvent({
@@ -56,16 +112,16 @@ async function runKtxSetupEntryMenu(status, deps = {}) {
     const options = status.project.ready
         ? [
             { value: 'setup', label: 'Resume or change an existing setup' },
-            { value: 'new-project', label: 'Create a new KTX project' },
-            { value: 'agents', label: 'Connect a coding agent to KTX' },
+            { value: 'new-project', label: 'Create a new ktx project' },
+            { value: 'agents', label: 'Connect a coding agent to ktx' },
             { value: 'status', label: 'Check setup status' },
-            { value: 'demo', label: 'Explore a pre-built KTX project' },
+            { value: 'demo', label: 'Explore a pre-built ktx project' },
             { value: 'exit', label: 'Exit' },
         ]
         : [
-            { value: 'setup', label: 'Set up KTX for my data' },
+            { value: 'setup', label: 'Set up ktx for my data' },
             { value: 'status', label: 'Check setup status' },
-            { value: 'demo', label: 'Explore a pre-built KTX project' },
+            { value: 'demo', label: 'Explore a pre-built ktx project' },
             { value: 'exit', label: 'Exit' },
         ];
     const action = (await prompts.select({
@@ -226,16 +282,16 @@ function formatContextBuilt(status) {
 export function formatKtxSetupStatus(status) {
     if (!status.project.ready) {
         return [
-            `No KTX project found at ${status.project.path}.`,
+            `No ktx project found at ${status.project.path}.`,
             '',
             'Check another project: ktx --project-dir <folder> status',
             'Or from that folder: ktx status',
-            'Create a new KTX project here: ktx setup',
+            'Create a new ktx project here: ktx setup',
             '',
         ].join('\n');
     }
     const lines = [
-        `KTX project: ${status.project.path}`,
+        `ktx project: ${status.project.path}`,
         `Project ready: ${formatReady(status.project.ready)}`,
         `LLM ready: ${formatReady(status.llm.ready)}${status.llm.model ? ` (${status.llm.model})` : ''}`,
         `Embeddings ready: ${formatReady(status.embeddings.ready)}${status.embeddings.model ? ` (${status.embeddings.model})` : ''}`,
@@ -246,7 +302,7 @@ export function formatKtxSetupStatus(status) {
                 `Runtime ready: ${formatReady(status.runtime.ready)}${status.runtime.features.length > 0 ? ` (${status.runtime.features.join(', ')})` : ''}`,
             ]
             : []),
-        `KTX context built: ${formatContextBuilt(status.context)}`,
+        `ktx context built: ${formatContextBuilt(status.context)}`,
         `Agent integration ready: ${formatReady(status.agents.some((agent) => agent.ready))}${status.agents.length > 0 ? ` (${status.agents.map((agent) => `${agent.target}:${agent.scope}`).join(', ')})` : ''}`,
     ];
     if (!status.context.ready && status.context.status === 'failed' && status.context.detail) {
@@ -271,7 +327,7 @@ export function formatKtxSetupCompletionSummary(status, options = {}) {
         lines.push('', 'REQUIRED BEFORE USING AGENTS', '', ...agentNextActions.split('\n').map((line) => (line ? `  ${line}` : '')));
     }
     lines.push('', agentNextActions ? 'After that, try' : 'Try it');
-    lines.push('  Ask your agent: "Use KTX to show me the available tables."');
+    lines.push('  Ask your agent: "Use ktx to show me the available tables."');
     return lines.join('\n');
 }
 function setupStatusReady(status) {
@@ -301,7 +357,7 @@ function setupRuntimeInstallPolicy(args) {
 }
 async function commitSetupConfigChanges(projectDir) {
     const project = await loadKtxProject({ projectDir });
-    await project.git.commitFile('ktx.yaml', 'setup: update KTX project config', 'ktx setup', 'setup@ktx.local');
+    await project.git.commitFile('ktx.yaml', 'setup: update ktx project config', 'ktx setup', 'setup@ktx.local');
 }
 export async function runKtxSetup(args, io, deps = {}) {
     try {
@@ -316,7 +372,7 @@ export async function runKtxSetup(args, io, deps = {}) {
 }
 async function runKtxSetupInner(args, io, deps = {}) {
     const setupUi = deps.setupUi ?? createKtxSetupUiAdapter();
-    setupUi.intro('KTX setup', io);
+    setupUi.intro('ktx setup', io);
     setupUi.note(KTX_DOCS_URL, '📚 Docs', io);
     let entryAction;
     let projectResult;
@@ -325,6 +381,10 @@ async function runKtxSetupInner(args, io, deps = {}) {
         args.inputMode !== 'disabled' &&
         !args.agents &&
         (io.stdout.isTTY === true || deps.entryMenuDeps?.prompts !== undefined);
+    // A prompt is only possible when input is enabled AND a TTY is attached. A
+    // piped/CI `ktx setup` without `--no-input` is still `inputMode: 'auto'` but
+    // cannot prompt, so its `missing-input` is an automation error, not an abort.
+    const interactive = args.inputMode !== 'disabled' && io.stdout.isTTY === true;
     setupLoop: while (true) {
         entryAction = undefined;
         if (canShowEntryMenu) {
@@ -363,7 +423,13 @@ async function runKtxSetupInner(args, io, deps = {}) {
             continue;
         }
         if (projectResult.status !== 'ready') {
-            return projectResult.status === 'cancelled' ? 0 : 1;
+            const terminal = setupTerminalOutcome({
+                status: projectResult.status,
+                step: 'project',
+                interactive,
+            });
+            await annotateSetupCommandOutcome(terminal.annotation);
+            return terminal.exitCode;
         }
         const agentsRequested = args.agents || entryAction === 'agents';
         const currentStatus = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
@@ -576,11 +642,15 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 cliVersion: args.cliVersion,
                 ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
             });
-            if (stepResult.status === 'failed') {
-                return 1;
-            }
-            if (stepResult.status === 'missing-input') {
-                return 1;
+            if (stepResult.status === 'failed' || stepResult.status === 'missing-input') {
+                const terminal = setupTerminalOutcome({
+                    status: stepResult.status,
+                    step,
+                    interactive,
+                    ...(stepResult.errorDetail ? { errorDetail: stepResult.errorDetail } : {}),
+                });
+                await annotateSetupCommandOutcome(terminal.annotation);
+                return terminal.exitCode;
             }
             if (stepResult.status === 'back') {
                 const previousIndex = previousNavigableStepIndex(stepIndex);
@@ -614,7 +684,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
     const focusedOnAgents = args.agents || entryAction === 'agents';
     if (!focusedOnAgents) {
         if (shouldPrintConciseReadySummary(status)) {
-            setupUi.note(formatKtxSetupCompletionSummary(status, { agentNextActions }), agentNextActions ? 'Finish KTX agent setup' : 'KTX project ready', io, {
+            setupUi.note(formatKtxSetupCompletionSummary(status, { agentNextActions }), agentNextActions ? 'Finish ktx agent setup' : 'ktx project ready', io, {
                 format: (line) => line,
             });
         }
@@ -630,5 +700,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }).join('\n'), 'What you can do next', io);
         }
     }
+    setupUi.note(SLACK_SETUP_NOTE.body, SLACK_SETUP_NOTE.title, io);
     return 0;
 }

package/dist/skills/analytics/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ktx-analytics
-description: Use when answering a question that needs data from a KTX-connected database - investigating, analyzing, "how many", "show me", "what's the breakdown of", finding records by value, exploring tables, comparing periods, explaining metrics, or any data-analysis request. Triggers even when the user does not say "analytics"; if the answer requires querying a configured KTX connection, this skill applies.
+description: Use when answering a question that needs data from a ktx-connected database - investigating, analyzing, "how many", "show me", "what's the breakdown of", finding records by value, exploring tables, comparing periods, explaining metrics, or any data-analysis request. Triggers even when the user does not say "analytics"; if the answer requires querying a configured ktx connection, this skill applies.
 ---
 
-# KTX Analytics Workflow
+# ktx Analytics Workflow
 
-You have access to KTX MCP tools for data discovery, semantic-layer analysis, raw read-only SQL, wiki context, and memory ingest. Follow this workflow.
+You have access to ktx MCP tools for data discovery, semantic-layer analysis, raw read-only SQL, wiki context, and memory ingest. Follow this workflow.
 
 <workflow>
 1. **Discover** - call `discover_data` first to see what exists across wiki pages, semantic-layer sources, metrics, dimensions, raw tables, and columns. Returns refs only.

package/dist/skills/dbt_ingest/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: dbt_ingest
-description: Map dbt `schema.yml` / `properties.yml` models and sources into KTX semantic-layer overlays and column notes. Covers `sources:` vs `models:`, column `data_tests` (not_null, unique, accepted_values, relationships), and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's `skillNames` includes `dbt_ingest` or when raw files are dbt YAML under `models/` / `sources/`.
+description: Map dbt `schema.yml` / `properties.yml` models and sources into ktx semantic-layer overlays and column notes. Covers `sources:` vs `models:`, column `data_tests` (not_null, unique, accepted_values, relationships), and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's `skillNames` includes `dbt_ingest` or when raw files are dbt YAML under `models/` / `sources/`.
 callers: [memory_agent]
 ---
 
-# dbt → KTX (bundle ingest)
+# dbt → ktx (bundle ingest)
 
 Use this skill for **uploaded** dbt projects (`dbt_project.yml` at stage root, `models/**`, `sources/**`, `schema.yml`). There is **no** `fetch()` in v1 - scheduled `dbt parse` / `manifest.json` pulls are out of scope; host-provided dbt sync may still backfill structured test metadata into `_schema` on the next sync.
 
 ## Mapping (models / sources → SL)
 
-| dbt | KTX | Notes |
+| dbt | ktx | Notes |
 |-----|--------|--------|
 | `models:` entry with `columns:` | **Overlay** on the manifest table with the same name (after `discover_data` / `entity_details`) | One SL source per physical table; model name may differ from DB name - resolve with `read_raw_file` + warehouse context. |
 | `sources:` → `tables:` | Same as models; use `identifier` when present instead of logical `name`. | Schema + name must match how the connection sees tables. |

package/dist/skills/looker_ingest/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: looker_ingest
-description: Extract durable KTX knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/.
+description: Extract durable ktx knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/.
 callers: [memory_agent]
 ---
 
 # Looker Runtime Ingest
 
-Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable KTX memory. Runtime entities are evidence. They are not themselves the final knowledge shape.
+Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable ktx memory. Runtime entities are evidence. They are not themselves the final knowledge shape.
 
 ## Required Workflow
 
@@ -103,7 +103,7 @@ The staged explore file carries warehouse target fields populated before the WU
 - `rawSqlTableName`: Looker's verbatim `sql_table_name`. Keep it as provenance only.
 - `targetTable`: the parsed target-table union. Use this as the sole branch condition.
 
-When `targetTable.ok === true`, the explore has a complete KTX backing target. Before writing:
+When `targetTable.ok === true`, the explore has a complete ktx backing target. Before writing:
 
 1. Use `targetTable.catalog`, `targetTable.schema`, and `targetTable.name` for `source_tables` preflight matching through `sl_discover` or `sl_read_source`.
 2. Use Looker field `sql`, labels, descriptions, and type metadata to derive source columns, measures, segments, joins, and grain.

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/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/command-hook.d.ts

@@ -6,6 +6,9 @@ interface CommandSpan {
     hasProject: boolean;
     attachProjectGroup: boolean;
     startedAt: number;
+    annotatedOutcome?: CommandOutcome;
+    annotatedErrorClass?: string;
+    annotatedErrorDetail?: string;
 }
 export interface CompletedCommandSpan {
     commandPath: string[];
@@ -19,6 +22,27 @@ export interface CompletedCommandSpan {
     projectGroupAttached: boolean;
 }
 export declare function beginCommandSpan(input: CommandSpan): void;
+/**
+ * Let a command action record the true outcome and reason on the active span.
+ *
+ * The Commander wrapper can only derive an outcome from a thrown error or the
+ * process exit code, so a command that exits non-zero *without throwing* (e.g.
+ * `ktx setup` when the user abandons the wizard) lands as `outcome: 'error'`
+ * with no `errorClass`/`errorDetail` — an unactionable blank in the dashboard.
+ * The action is the decision-maker: it can mark the run `aborted`, or attach a
+ * scrubbed reason so the next occurrence is self-diagnosing. A later thrown
+ * error still wins (see {@link completeCommandSpan}), since that is the most
+ * authoritative signal and also feeds the `$exception` stream. No-ops when no
+ * span is active so call sites stay safe in tests and bare-help paths.
+ *
+ * Values are emitted verbatim and must already satisfy the telemetry privacy
+ * rules — pass synthetic or already-scrubbed strings, never raw user input.
+ */
+export declare function annotateCommandOutcome(input: {
+    outcome?: CommandOutcome;
+    errorClass?: string;
+    errorDetail?: string;
+}): void;
 export declare function completeCommandSpan(input: {
     completedAt: number;
     outcome: CommandOutcome;