@kaelio/ktx 0.10.0 → 0.12.0

package/dist/context/sl/tools/sl-warehouse-validation.js

@@ -2,8 +2,8 @@ import YAML from 'yaml';
 import { SYSTEM_GIT_AUTHOR } from '../../../context/tools/authors.js';
 import { sourceOverlaySchema } from '../schemas.js';
 import { SemanticLayerService } from '../semantic-layer.service.js';
+import { resolveSlSourceFile, slSourceFilePath } from '../source-files.js';
 import { sourceDefinitionSchema } from './base-semantic-layer.tool.js';
-const slSourcePath = (connectionId, sourceName) => `semantic-layer/${connectionId}/${sourceName}.yaml`;
 function resolveDialect(warehouse) {
     if (!warehouse) {
         return null;
@@ -33,32 +33,28 @@ function wrapWithSingleRowQuery(sql, dialect) {
 export async function validateSingleSource(deps, connectionId, sourceName) {
     const errors = [];
     const warnings = [];
-    let content;
-    try {
-        const result = await deps.semanticLayerService.readSourceFile(connectionId, sourceName);
-        content = result.content;
-    }
-    catch {
-        errors.push(`${sourceName}.yaml: file not found`);
+    const file = await deps.semanticLayerService.readSourceFile(connectionId, sourceName);
+    if (!file) {
+        errors.push(`${sourceName}: no standalone or overlay file found`);
         return { errors, warnings };
     }
     let parsed;
     try {
-        parsed = YAML.parse(content);
+        parsed = YAML.parse(file.content);
     }
     catch (e) {
-        errors.push(`${sourceName}.yaml: invalid YAML — ${e instanceof Error ? e.message : String(e)}`);
+        errors.push(`${sourceName}: invalid YAML — ${e instanceof Error ? e.message : String(e)}`);
         return { errors, warnings };
     }
     if (!parsed || typeof parsed !== 'object') {
-        errors.push(`${sourceName}.yaml: top-level content is not an object`);
+        errors.push(`${sourceName}: top-level content is not an object`);
         return { errors, warnings };
     }
     const isOverlay = !parsed.table && !parsed.sql;
     if (!isOverlay) {
         const isManifestBacked = await deps.semanticLayerService.isManifestBacked(connectionId, sourceName);
         if (isManifestBacked) {
-            errors.push(`${sourceName}.yaml: standalone source shadows an existing manifest entry — ` +
+            errors.push(`${sourceName}: standalone source shadows an existing manifest entry — ` +
                 `writing it as-is drops the manifest's columns and joins. ` +
                 `Remove "sql:", "table:", "grain:", and base-table "columns:" and keep only ` +
                 `"name:" plus overlay fields such as "measures:", "segments:", "descriptions:", ` +
@@ -71,16 +67,16 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
     const result = schema.safeParse(parsed);
     if (!result.success) {
         const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
-        errors.push(`${sourceName}.yaml: schema — ${issues}`);
+        errors.push(`${sourceName}: schema — ${issues}`);
         const errorPaths = new Set(result.error.issues.map((i) => String(i.path[0])));
         if (errorPaths.has('joins')) {
-            warnings.push(`${sourceName}.yaml: hint — join format: {to, on: 'local_col = TARGET.col', relationship: 'many_to_one|one_to_many|one_to_one'}`);
+            warnings.push(`${sourceName}: hint — join format: {to, on: 'local_col = TARGET.col', relationship: 'many_to_one|one_to_many|one_to_one'}`);
         }
         if (errorPaths.has('columns')) {
-            warnings.push(`${sourceName}.yaml: hint — overlay columns must be computed: {name, expr, type}. Use column_overrides for manifest column descriptions or metadata.`);
+            warnings.push(`${sourceName}: hint — overlay columns must be computed: {name, expr, type}. Use column_overrides for manifest column descriptions or metadata.`);
         }
         if (errorPaths.has('measures')) {
-            warnings.push(`${sourceName}.yaml: hint — measure format: {name, expr, description (optional), filter (optional)}`);
+            warnings.push(`${sourceName}: hint — measure format: {name, expr, description (optional), filter (optional)}`);
         }
         return { errors, warnings };
     }
@@ -93,7 +89,7 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
     const seenMeasures = new Set();
     for (const m of measures) {
         if (seenMeasures.has(m.name)) {
-            errors.push(`${sourceName}.yaml: duplicate measure name "${m.name}"`);
+            errors.push(`${sourceName}: duplicate measure name "${m.name}"`);
         }
         seenMeasures.add(m.name);
     }
@@ -125,7 +121,7 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
             const actual = new Set((probe.headers ?? []).map((h) => h.toLowerCase()));
             const missing = sourceColumns.map((c) => c.name).filter((n) => !actual.has(n.toLowerCase()));
             if (missing.length > 0) {
-                errors.push(`${sourceName}.yaml: declared columns absent from sql result — ${missing.join(', ')} (warehouse returned: ${[...actual].slice(0, 10).join(', ')}${actual.size > 10 ? ', …' : ''})`);
+                errors.push(`${sourceName}: declared columns absent from sql result — ${missing.join(', ')} (warehouse returned: ${[...actual].slice(0, 10).join(', ')}${actual.size > 10 ? ', …' : ''})`);
             }
         }
         catch (e) {
@@ -151,7 +147,7 @@ function formatProbeError(args) {
     const errMsg = error instanceof Error ? error.message : String(error);
     const refColumns = sourceColumns.filter((c) => referencesColumn(probeSql, c.name));
     const lines = [
-        measureName ? `${sourceName}.yaml: measure "${measureName}" ${headline}.` : `${sourceName}.yaml: ${headline}.`,
+        measureName ? `${sourceName}: measure "${measureName}" ${headline}.` : `${sourceName}: ${headline}.`,
     ];
     if (warehouse) {
         lines.push(`  Warehouse: ${warehouse}`);
@@ -179,7 +175,7 @@ async function probeOverlayMeasures(deps, connectionId, sourceName, warehouse) {
         composed = all.find((s) => s.name === sourceName);
     }
     catch (e) {
-        errors.push(`${sourceName}.yaml: failed to load composed source for probe — ${e instanceof Error ? e.message : String(e)}`);
+        errors.push(`${sourceName}: failed to load composed source for probe — ${e instanceof Error ? e.message : String(e)}`);
         return errors;
     }
     if (!composed?.table || composed.measures.length === 0) {
@@ -214,22 +210,54 @@ async function probeOverlayMeasures(deps, connectionId, sourceName, warehouse) {
     }
     return errors;
 }
+/**
+ * A read-only view of the config repo at one commit, shaped for
+ * `resolveSlSourceFile` so name→file resolution runs against history exactly as
+ * it does against the working tree — one resolver, two backing stores. Used to
+ * recover the path a source occupied at `preHead` after the live file is gone.
+ */
+function gitCommitFileStore(git, commitHash) {
+    return {
+        async listFiles(path) {
+            return { files: await git.listFilesAtCommit(path, commitHash) };
+        },
+        async readFile(path) {
+            return { content: await git.getFileAtCommit(path, commitHash) };
+        },
+    };
+}
 /**
  * Restore `sourceName` to the content it had at `preHead`, or delete it if it didn't
  * exist then. Used by sl_rollback (agent-driven) and the pre-squash revert gate
  * (automatic). Returns a short human-readable description of what happened.
  */
 export async function revertSourceToPreHead(deps, connectionId, preHead, sourceName) {
-    const relPath = slSourcePath(connectionId, sourceName);
+    // Find the file that defines this source. While it is still on disk
+    // (invalid-but-present) the live resolver finds it by its in-file `name:`.
+    // Once the session deleted it, the path is gone too — and humans rename files
+    // freely, so it is NOT the writer-derived filename. Recover it from history by
+    // resolving the name against the preHead commit instead of guessing.
+    const live = await resolveSlSourceFile(deps.configService, connectionId, sourceName);
+    let relPath;
     let preContent = null;
-    if (preHead) {
-        try {
-            preContent = await deps.gitService.getFileAtCommit(relPath, preHead);
-        }
-        catch {
-            preContent = null;
+    if (live) {
+        relPath = live.path;
+        if (preHead) {
+            try {
+                preContent = await deps.gitService.getFileAtCommit(relPath, preHead);
+            }
+            catch {
+                preContent = null;
+            }
         }
     }
+    else {
+        const atPreHead = preHead
+            ? await resolveSlSourceFile(gitCommitFileStore(deps.gitService, preHead), connectionId, sourceName)
+            : null;
+        relPath = atPreHead?.path ?? slSourceFilePath(connectionId, sourceName);
+        preContent = atPreHead?.content ?? null;
+    }
     if (preContent !== null) {
         await deps.configService.writeFile(relPath, preContent, SYSTEM_GIT_AUTHOR.name, SYSTEM_GIT_AUTHOR.email, `Revert SL source to pre-session state: ${sourceName}`, { skipLock: true });
         return 'restored to pre-session content';

package/dist/context/sl/tools/sl-write-source.tool.js

@@ -12,8 +12,10 @@ const slWriteSourceInputSchema = z.object({
     connectionId: slToolConnectionIdSchema.describe('Data source connection ID'),
     sourceName: z
         .string()
-        .regex(/^[a-z0-9][a-z0-9_]*$/, 'Source name must be snake_case (lowercase alphanumeric and underscores)')
-        .describe('Name of the source to create, edit, or delete'),
+        .min(1)
+        .describe("Name of the source to create, edit, or delete. Must equal the source's `name:`. Use the verbatim " +
+        'warehouse identifier when overlaying a manifest source (e.g. SIGNED_UP); snake_case is recommended ' +
+        'for new standalone sources.'),
     source: sourceInputSchema
         .optional()
         .describe('Source definition (standalone with table/sql) or overlay (measures, column_overrides, computed columns, etc.)'),
@@ -122,6 +124,12 @@ Do NOT join back to a table that the SQL already aggregates from if the grain co
         if (!input.source) {
             return this.buildOutput(false, ['Provide `source` to create or rewrite. For targeted edits, use sl_edit_source.'], sourceName);
         }
+        // The in-file `name:` is the source's identity; the file is written under
+        // source.name while the orphan/shadow checks key on sourceName — a mismatch
+        // would validate one source and save another.
+        if (input.source.name !== sourceName) {
+            return this.buildOutput(false, [`source.name "${input.source.name}" does not match sourceName "${sourceName}" — they must be identical.`], sourceName);
+        }
         return this.writeFullSource(connectionId, input.source, sourceName, author, authorEmail, context, semanticLayerService, skipIndex, rawPathValidation.rawPaths);
     }
     async writeFullSource(connectionId, source, sourceName, author, authorEmail, context, semanticLayerService, skipIndex, rawPaths) {
@@ -183,13 +191,8 @@ Do NOT join back to a table that the SQL already aggregates from if the grain co
         }
     }
     async readSourceYamlFromService(service, connectionId, sourceName) {
-        try {
-            const { content } = await service.readSourceFile(connectionId, sourceName);
-            return content;
-        }
-        catch {
-            return null;
-        }
+        const file = await service.readSourceFile(connectionId, sourceName);
+        return file?.content ?? null;
     }
     async rejectOrphanOverlay(semanticLayerService, connectionId, sourceName, content) {
         let parsed;

package/dist/context/sql-analysis/dialect.d.ts

@@ -0,0 +1,2 @@
+import type { SqlAnalysisDialect } from './ports.js';
+export declare function sqlAnalysisDialectForDriver(driver: string | undefined): SqlAnalysisDialect;

package/dist/context/sql-analysis/dialect.js

@@ -0,0 +1,20 @@
+// One mapping from ktx connection identity to the sqlglot dialect name used by
+// the Python daemon (SQL analysis, read-only validation) and semantic-layer
+// compute. Keys cover both vocabularies that name a connection's engine:
+// ktx.yaml driver names ("postgres", "sqlserver") and the local connection-type
+// spellings exposed by KtxConnectionInfo.connectionType ("POSTGRESQL").
+const SQLGLOT_DIALECTS = {
+    postgres: 'postgres',
+    postgresql: 'postgres',
+    bigquery: 'bigquery',
+    snowflake: 'snowflake',
+    mysql: 'mysql',
+    sqlserver: 'tsql',
+    sqlite: 'sqlite',
+    duckdb: 'duckdb',
+    clickhouse: 'clickhouse',
+    databricks: 'databricks',
+};
+export function sqlAnalysisDialectForDriver(driver) {
+    return SQLGLOT_DIALECTS[(driver ?? '').toLowerCase()] ?? 'postgres';
+}

package/dist/context/tools/base-tool.d.ts

@@ -1,4 +1,5 @@
-import { z, type ZodType } from 'zod';
+import { type Tool } from 'ai';
+import { z } from 'zod';
 import { type KtxLogger } from '../../context/core/config.js';
 import type { KtxRuntimeToolDescriptor } from '../llm/runtime-port.js';
 import type { IngestToolMetadata, ToolSession } from './tool-session.js';
@@ -56,30 +57,16 @@ interface MethodologyEntry {
 /**
  * SECURITY: All tools require authentication. userId must always be provided in ToolContext.
  */
-export declare abstract class BaseTool<TInput extends ZodType = ZodType> {
+export declare abstract class BaseTool<TInput extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
     protected readonly logger: KtxLogger;
     abstract readonly name: string;
     constructor(logger?: KtxLogger);
     abstract get description(): string;
     abstract get inputSchema(): TInput;
-    abstract call(input: z.infer<TInput>, context: ToolContext): Promise<any>;
-    getParametersSchema(): {
-        type: 'object';
-        properties: Record<string, any>;
-        required?: string[];
-    };
-    toAnthropicFormat(): {
-        name: string;
-        description: string;
-        input_schema: {
-            type: 'object';
-            properties: Record<string, any>;
-            required?: string[];
-        };
-    };
-    toAiSdkTool(context: ToolContext): any;
+    abstract call(input: z.infer<TInput>, context: ToolContext): Promise<unknown>;
+    toAiSdkTool(context: ToolContext): Tool;
     toRuntimeTool(context: ToolContext): KtxRuntimeToolDescriptor;
-    parseInput(input: Record<string, any>): z.infer<TInput>;
+    parseInput(input: Record<string, unknown>): z.infer<TInput>;
     protected getCurrentUserQuery(context: ToolContext): string | null;
 }
 export {};

package/dist/context/tools/base-tool.js

@@ -1,5 +1,4 @@
 import { tool } from 'ai';
-import { z } from 'zod';
 import { noopLogger } from '../../context/core/config.js';
 import { normalizeKtxRuntimeToolOutput } from '../llm/runtime-tools.js';
 /**
@@ -10,19 +9,6 @@ export class BaseTool {
     constructor(logger = noopLogger) {
         this.logger = logger;
     }
-    getParametersSchema() {
-        const jsonSchema = z.toJSONSchema(this.inputSchema, {
-            target: 'draft-7',
-        });
-        return jsonSchema;
-    }
-    toAnthropicFormat() {
-        return {
-            name: this.name,
-            description: this.description,
-            input_schema: this.getParametersSchema(),
-        };
-    }
     toAiSdkTool(context) {
         const toolName = this.name;
         const logger = this.logger;

package/dist/context-build-view.js

@@ -260,7 +260,7 @@ export function renderContextBuildView(state, options = {}) {
     const totalCount = allTargets.length;
     const hasActive = allTargets.some((t) => t.status === 'running' || t.status === 'queued');
     const allDone = totalCount > 0 && !hasActive;
-    const headerParts = [options.title ?? 'Building KTX context'];
+    const headerParts = [options.title ?? 'Building ktx context'];
     if (totalCount > 0) {
         const progressParts = [`${doneCount}/${totalCount}`];
         if (state.totalElapsedMs > 0)
@@ -550,7 +550,7 @@ function failedStepDetail(result) {
     return result.steps.find((step) => step.status === 'failed')?.detail ?? null;
 }
 const INTERNAL_FAILURE_LINE_RE = /^(Report|Run|Job|Status|Adapter|Connection|Sync|Mode|Dry run|Diff|Tasks|Work units|Failed tasks|Saved memory|Provenance rows):\s*/;
-const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|KTX Python runtime is required|KTX daemon HTTP|Error:|Failed\b|Could not\b|Cannot\b)/;
+const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|ktx Python runtime is required|ktx daemon HTTP|Error:|Failed\b|Could not\b|Cannot\b)/;
 function trimErrorPrefix(line) {
     return line.replace(/^Error:\s*/, '');
 }
@@ -559,7 +559,7 @@ function firstCapturedFailureLine(output) {
         .split(/\r?\n/)
         .map((candidate) => candidate.trim())
         .filter((candidate) => candidate.length > 0)
-        .filter((candidate) => !candidate.startsWith('KTX scan completed'))
+        .filter((candidate) => !candidate.startsWith('ktx scan completed'))
         .filter((candidate) => !INTERNAL_FAILURE_LINE_RE.test(candidate));
     const line = lines.find((candidate) => ACTIONABLE_FAILURE_LINE_RE.test(candidate)) ?? lines.at(-1) ?? null;
     return line ? trimErrorPrefix(line) : null;
@@ -584,7 +584,7 @@ function failureTextForTarget(input) {
     const code = networkErrorCode(input.error, input.capturedOutput);
     if (code && isLocalSqlAnalysisConnectionRefused({ capturedOutput: input.capturedOutput, fallback: input.fallback })) {
         return [
-            `KTX could not reach the local SQL analysis runtime while processing query history for ${input.target.connectionId}.`,
+            `ktx could not reach the local SQL analysis runtime while processing query history for ${input.target.connectionId}.`,
             `Reason: ${NETWORK_ERROR_REASONS[code]} (${code}).`,
             `Retry: ${retryCommand({
                 projectDir: input.projectDir,
@@ -598,7 +598,7 @@ function failureTextForTarget(input) {
     if (code) {
         const operation = input.target.operation === 'database-ingest' ? 'reading schema for' : 'ingesting';
         return [
-            `KTX lost its connection to ${friendlyDriverName(input.target.driver)} while ${operation} ${input.target.connectionId}.`,
+            `ktx lost its connection to ${friendlyDriverName(input.target.driver)} while ${operation} ${input.target.connectionId}.`,
             `Reason: ${NETWORK_ERROR_REASONS[code]} (${code}).`,
             `Retry: ${retryCommand({
                 projectDir: input.projectDir,

package/dist/database-tree-picker.js

@@ -1,5 +1,7 @@
 import { parseDottedTableEntry } from './context/scan/enabled-tables.js';
+import { createStaticCliSpinner } from './clack.js';
 import { profileMark } from './startup-profile.js';
+import { withSearchableMultiselectNavigation } from './prompt-navigation.js';
 import { buildInitialState, buildPickerTree, } from './tree-picker-state.js';
 import { renderTreePickerTui, } from './tree-picker-tui.js';
 profileMark('module:database-tree-picker');
@@ -167,7 +169,7 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
     let selectedSchemas = initialStageOneSchemas(args);
     while (true) {
         const pickedSchemas = await args.prompts.autocompleteMultiselect({
-            message: `Choose ${args.schemaNounPlural} to enable for ${args.connectionId}\nType to filter. Space to select. Enter when done.`,
+            message: withSearchableMultiselectNavigation(`Choose ${args.schemaNounPlural} to enable for ${args.connectionId}`),
             placeholder: `Search ${args.schemaNounPlural}`,
             options: schemaOptions(args),
             initialValues: selectedSchemas,
@@ -178,7 +180,7 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
         }
         selectedSchemas = pickedSchemas;
         if (selectedSchemas.length === 0) {
-            io.stderr.write(`Nothing selected - type to filter, or Escape to skip ${args.schemaNoun} scope.\n`);
+            io.stderr.write(`Nothing selected - type to search, or Escape to skip ${args.schemaNoun} scope.\n`);
             continue;
         }
         const selectedNoun = selectedSchemas.length === 1 ? args.schemaNoun : args.schemaNounPlural;
@@ -193,7 +195,20 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
         if (action === 'back') {
             continue;
         }
-        const discovered = await args.listTablesForSchemas(selectedSchemas);
+        // Static (stderr-only) spinner: the stage-two table picker below is a raw-mode
+        // Ink TUI, and an animated clack spinner would leave stdin dirty so Ink reads a
+        // stray Escape and exits immediately.
+        const tablesSpinner = createStaticCliSpinner(io);
+        tablesSpinner.start(`Listing tables in ${selectedSchemas.length} ${selectedNoun}…`);
+        let discovered;
+        try {
+            discovered = await args.listTablesForSchemas(selectedSchemas);
+        }
+        catch (error) {
+            tablesSpinner.error('Could not list tables');
+            throw error;
+        }
+        tablesSpinner.stop(`Found ${discovered.length} ${discovered.length === 1 ? 'table' : 'tables'}`);
         if (action === 'save' && args.existing.enabledTables.length === 0) {
             return {
                 kind: 'selected',

package/dist/demo-assets.js

@@ -46,7 +46,6 @@ function demoConfig(databasePath) {
         '  state: sqlite',
         '  search: sqlite-fts5',
         '  git:',
-        '    auto_commit: true',
         '    author: ktx <ktx@example.com>',
         'llm:',
         '  provider:',

package/dist/doctor.d.ts

@@ -67,7 +67,7 @@ interface RenderOptions {
 }
 export declare function formatDoctorReport(report: DoctorReport, options?: Partial<RenderOptions>): string;
 export declare function renderInvalidConfigMessage(projectDir: string, issues: KtxConfigIssue[], outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
-export declare function renderValidConfigMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
+export declare function renderValidConfigMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo, warnings?: KtxConfigIssue[]): void;
 export declare function renderMissingProjectMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
 export declare function runKtxDoctor(args: KtxDoctorArgs, io?: KtxDoctorIo, deps?: KtxDoctorDeps): Promise<number>;
 export {};

package/dist/doctor.js

@@ -4,6 +4,7 @@ import { access, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { shouldUseColorOutput } from './io/tty.js';
 import { KTX_NEXT_STEP_DIRECT_COMMANDS } from './next-steps.js';
 const execFileAsync = promisify(execFile);
 function workspaceRootDir() {
@@ -121,12 +122,6 @@ const GROUP_LABEL = {
     search: 'Semantic search',
     history: 'Query history',
 };
-function shouldUseColor(io) {
-    if (io.stdout.isTTY !== true)
-        return false;
-    const env = process.env;
-    return !env.NO_COLOR && env.TERM !== 'dumb' && !env.CI;
-}
 function styleStatus(useColor, status, text) {
     if (!useColor)
         return text;
@@ -322,17 +317,20 @@ export function renderInvalidConfigMessage(projectDir, issues, outputMode, io) {
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const status = (s, text) => styleStatus(useColor, s, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
+    const errorCount = issues.filter((issue) => issue.severity === 'error').length;
+    const warningCount = issues.length - errorCount;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  ${status('fail', '✗')} ${bold('Config')}    ktx.yaml has ${issues.length} schema issue${issues.length === 1 ? '' : 's'}`);
+    lines.push(`  ${status('fail', '✗')} ${bold('Config')}    ktx.yaml has ${errorCount} schema issue${errorCount === 1 ? '' : 's'}${warningCount > 0 ? ` · ${warningCount} ignored field${warningCount === 1 ? '' : 's'}` : ''}`);
     for (const issue of issues) {
-        lines.push(`      ${status('fail', '✗')} ${issue.message}`);
+        const glyph = issue.severity === 'error' ? status('fail', '✗') : status('warn', '⚠');
+        lines.push(`      ${glyph} ${issue.message}`);
         if (issue.fix) {
             lines.push(`        ${dim(`→ ${issue.fix}`)}`);
         }
@@ -342,23 +340,35 @@ export function renderInvalidConfigMessage(projectDir, issues, outputMode, io) {
     lines.push('');
     io.stdout.write(lines.join('\n'));
 }
-export function renderValidConfigMessage(projectDir, outputMode, io) {
+export function renderValidConfigMessage(projectDir, outputMode, io, warnings = []) {
     if (outputMode === 'json') {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             projectDir,
+            ...(warnings.length > 0 ? { warnings } : {}),
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const status = (s, text) => styleStatus(useColor, s, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  ${status('pass', '✓')} ${bold('Config')}    ${dim('ktx.yaml schema valid')}`);
+    if (warnings.length > 0) {
+        lines.push(`  ${status('warn', '⚠')} ${bold('Config')}    ktx.yaml schema valid · ${warnings.length} ignored field${warnings.length === 1 ? '' : 's'}`);
+        for (const warning of warnings) {
+            lines.push(`      ${status('warn', '⚠')} ${warning.message}`);
+            if (warning.fix) {
+                lines.push(`        ${dim(`→ ${warning.fix}`)}`);
+            }
+        }
+    }
+    else {
+        lines.push(`  ${status('pass', '✓')} ${bold('Config')}    ${dim('ktx.yaml schema valid')}`);
+    }
     lines.push('');
     io.stdout.write(lines.join('\n'));
 }
@@ -371,15 +381,15 @@ export function renderMissingProjectMessage(projectDir, outputMode, io) {
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
     const envProjectDir = process.env.KTX_PROJECT_DIR;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  No KTX project here yet. ${dim('(ktx.yaml not found)')}`);
+    lines.push(`  No ktx project here yet. ${dim('(ktx.yaml not found)')}`);
     lines.push('');
     lines.push(`  Run  ${bold('ktx setup')}  to create one.`);
     if (envProjectDir !== undefined) {
@@ -402,14 +412,13 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
                 return 1;
             }
             const { validateKtxProjectConfig } = await import('./context/project/config.js');
-            ;
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
             if (!validation.ok) {
                 renderInvalidConfigMessage(args.projectDir, validation.issues, args.outputMode, io);
                 return 1;
             }
-            renderValidConfigMessage(args.projectDir, args.outputMode, io);
+            renderValidConfigMessage(args.projectDir, args.outputMode, io, validation.issues);
             return 0;
         }
         if (args.command === 'project') {
@@ -420,7 +429,6 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             }
             const { loadKtxProject } = await import('./context/project/project.js');
             const { validateKtxProjectConfig } = await import('./context/project/config.js');
-            ;
             const { buildProjectStatus, renderProjectStatus } = await import('./status-project.js');
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
@@ -445,7 +453,7 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             else {
                 io.stdout.write(renderProjectStatus(projectStatus, {
                     verbose,
-                    useColor: shouldUseColor(io),
+                    useColor: shouldUseColorOutput(io.stdout),
                     durationMs: Date.now() - startedAt,
                     toolchainChecks,
                 }));
@@ -453,10 +461,10 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             return projectStatus.verdict === 'blocked' ? 1 : 0;
         }
         const setupChecks = await runSetupChecks();
-        const report = { title: 'KTX status', checks: setupChecks };
+        const report = { title: 'ktx status', checks: setupChecks };
         const renderOptions = {
             verbose: args.verbose ?? false,
-            useColor: shouldUseColor(io),
+            useColor: shouldUseColorOutput(io.stdout),
             durationMs: Date.now() - startedAt,
             command: args.command,
         };

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Marks an error as an expected operational outcome that ktx surfaces to its
+ * caller (a connected agent or the CLI user) rather than an unexpected ktx
+ * fault. Examples: invalid agent input, a warehouse rejecting a query, or a
+ * validation guard rejecting a request.
+ *
+ * `reportException` skips PostHog Error Tracking for these so the bug stream
+ * stays free of routine, caller-driven failures. The failure is still surfaced
+ * to the caller (as a tool-error result or CLI error) and still recorded by the
+ * outcome-tagged telemetry events, so no diagnostic signal is lost.
+ */
+export declare class KtxExpectedError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A query was rejected at the warehouse/driver boundary — the warehouse refused
+ * to compile or run it, or a read-only guard rejected it. Reuses the underlying
+ * error's message so the caller still sees the original warehouse diagnostics,
+ * and keeps the driver error as `cause`.
+ */
+export declare class KtxQueryError extends KtxExpectedError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * True for the native JavaScript error types that signal a programming fault — a
+ * bug in ktx code rather than an operational outcome. These are universal
+ * language invariants (a `TypeError` never means "the warehouse rejected the
+ * query"), so callers can use this to keep genuine faults out of the
+ * expected-error classification and let them reach Error Tracking unchanged.
+ */
+export declare function isNativeProgrammingFault(error: unknown): boolean;

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Marks an error as an expected operational outcome that ktx surfaces to its
+ * caller (a connected agent or the CLI user) rather than an unexpected ktx
+ * fault. Examples: invalid agent input, a warehouse rejecting a query, or a
+ * validation guard rejecting a request.
+ *
+ * `reportException` skips PostHog Error Tracking for these so the bug stream
+ * stays free of routine, caller-driven failures. The failure is still surfaced
+ * to the caller (as a tool-error result or CLI error) and still recorded by the
+ * outcome-tagged telemetry events, so no diagnostic signal is lost.
+ */
+export class KtxExpectedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'KtxExpectedError';
+    }
+}
+/**
+ * A query was rejected at the warehouse/driver boundary — the warehouse refused
+ * to compile or run it, or a read-only guard rejected it. Reuses the underlying
+ * error's message so the caller still sees the original warehouse diagnostics,
+ * and keeps the driver error as `cause`.
+ */
+export class KtxQueryError extends KtxExpectedError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'KtxQueryError';
+    }
+}
+/**
+ * True for the native JavaScript error types that signal a programming fault — a
+ * bug in ktx code rather than an operational outcome. These are universal
+ * language invariants (a `TypeError` never means "the warehouse rejected the
+ * query"), so callers can use this to keep genuine faults out of the
+ * expected-error classification and let them reach Error Tracking unchanged.
+ */
+export function isNativeProgrammingFault(error) {
+    return (error instanceof TypeError ||
+        error instanceof RangeError ||
+        error instanceof ReferenceError ||
+        error instanceof SyntaxError ||
+        error instanceof EvalError ||
+        error instanceof URIError);
+}