@kaelio/ktx 0.6.0 → 0.8.0

package/dist/context/mcp/context-tools.js

@@ -30,7 +30,7 @@ const toolDescriptions = {
     entity_details: 'Read table and column metadata from the latest live-database scan snapshot. Example: entity_details({ connectionId: "warehouse", entities: [{ table: { catalog: null, db: "public", name: "orders" }, columns: ["id"] }] }).',
     dictionary_search: 'Search profile-sampled warehouse values to locate likely source columns for business values. Example: dictionary_search({ values: ["Acme Corp"], connectionId: "warehouse" }).',
     sl_read_source: 'Read a semantic-layer YAML source by connection id and source name. Example: sl_read_source({ connectionId: "warehouse", sourceName: "orders" }).',
-    sl_query: 'Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }] }).',
+    sl_query: 'Execute a semantic-layer query and return headers, rows, and total row count, plus correctness notes (e.g. compile-only or fan-out) when relevant. The generated SQL and full query plan are omitted by default; request them with include: ["sql"] and/or include: ["plan"]. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }], include: ["sql"] }).',
     sql_execution: 'Execute one parser-validated read-only SQL query against a configured KTX connection. Example: sql_execution({ connectionId: "warehouse", sql: "select count(*) from public.orders", maxRows: 100 }).',
     memory_ingest: 'Ingest free-form markdown knowledge into durable KTX memory. Use this for business rules, metric definitions, schema gotchas, recurring findings, or explicit user requests to remember something. Example: memory_ingest({ connectionId: "warehouse", content: "ARR is reported in cents in this warehouse." }).',
     memory_ingest_status: 'Read the current or final status for a memory ingest run. Example: memory_ingest_status({ runId: "memory-run-1" }).',
@@ -38,7 +38,7 @@ const toolDescriptions = {
 const connectionListSchema = z.object({});
 const knowledgeSearchSchema = z.object({
     query: z.string().min(1).describe('Natural-language wiki search query, e.g. "revenue recognition policy".'),
-    limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return. Defaults to 10.'),
+    limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return.'),
 });
 const knowledgeReadSchema = z.object({
     key: z.string().min(1).describe('Wiki page key returned by wiki_search, e.g. "global/revenue".'),
@@ -67,10 +67,7 @@ const slQueryOrderBySchema = z.object({
         .string()
         .min(1)
         .describe('Field/measure/dimension id to order by, e.g. "orders.created_at", a dimension key like "mart_nrr_quarterly.quarter_label", or a measure alias.'),
-    direction: z
-        .enum(['asc', 'desc'])
-        .default('asc')
-        .describe('Sort direction: "asc" or "desc". Defaults to "asc".'),
+    direction: z.enum(['asc', 'desc']).default('asc').describe('Sort direction for this field.'),
 });
 const slQuerySchema = z.object({
     connectionId: connectionIdSchema
@@ -93,8 +90,12 @@ const slQuerySchema = z.object({
         .array(slQueryOrderBySchema)
         .default([])
         .describe('Sort clauses. Use {field, direction?} entries.'),
-    limit: z.number().int().min(0).default(1000).describe('Maximum rows to return. Defaults to 1000.'),
-    include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups. Defaults to true.'),
+    limit: z.number().int().min(0).default(1000).describe('Maximum rows to return.'),
+    include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups.'),
+    include: z
+        .array(z.enum(['plan', 'sql']))
+        .default([])
+        .describe('Extra detail to attach to the response: "sql" for the generated SQL, "plan" for the full query plan.'),
 });
 const entityDetailsTableRefSchema = z.object({
     catalog: z.string().nullable().describe('Catalog/project/database. Use null when not applicable.'),
@@ -134,12 +135,12 @@ const discoverDataSchema = z.object({
         .optional()
         .describe('Optional connection id. Pass it when user intent pins a specific warehouse.'),
     kinds: z.array(discoverDataKindSchema.describe('Reference kind to include.')).optional().describe('Optional kind filter.'),
-    limit: z.number().int().min(1).max(50).default(15).optional().describe('Maximum refs to return. Defaults to 15.'),
+    limit: z.number().int().min(1).max(50).default(10).optional().describe('Maximum refs to return.'),
 });
 const sqlExecutionSchema = z.object({
     connectionId: connectionIdSchema.describe('Connection id to execute against. Required for raw SQL.'),
     sql: z.string().min(1).describe('Parser-validated read-only SQL, e.g. "select count(*) from public.orders".'),
-    maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return. Defaults to 1000.'),
+    maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return.'),
 });
 const memoryIngestSchema = z.object({
     content: z
@@ -198,10 +199,14 @@ const slReadSourceOutputSchema = z.object({
 const slQueryOutputSchema = z.object({
     connectionId: z.string().optional(),
     dialect: z.string().optional(),
-    sql: z.string(),
     headers: z.array(z.string()),
     rows: z.array(z.array(z.unknown())),
     totalRows: z.number(),
+    // Correctness signals hoisted out of `plan` so they survive default projection (e.g. compile-only
+    // status, fan-out warnings). Present only when there is something to report.
+    notes: z.array(z.string()).optional(),
+    // Opt-in detail, attached only when requested via the `include` input.
+    sql: z.string().optional(),
     plan: unknownRecordSchema.optional(),
 });
 const entityDetailsSnapshotOutputSchema = z.object({
@@ -321,11 +326,54 @@ const memoryIngestStatusOutputSchema = z.object({
 });
 /** @internal */
 export function jsonToolResult(structuredContent) {
+    // Compact (non-indented) JSON: this `content` text is the copy the model reads. Pretty-printing
+    // arrays-of-arrays (every `rows` payload) puts one scalar per line, inflating tabular results by
+    // a large constant factor. `structuredContent` carries the same data for structured-output clients.
     return {
-        content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
         structuredContent,
     };
 }
+/**
+ * Pull the correctness-critical signals out of a query plan so they survive even when the caller
+ * did not opt into the full `plan`. Returns an empty list when there is nothing to flag.
+ */
+function slQueryNotes(plan) {
+    if (!plan) {
+        return [];
+    }
+    const notes = [];
+    const execution = plan.execution;
+    if (execution &&
+        typeof execution === 'object' &&
+        execution.mode === 'compile_only') {
+        const reason = execution.reason;
+        notes.push(typeof reason === 'string' ? reason : 'Compiled SQL only; no rows were executed.');
+    }
+    if (plan.has_fan_out === true) {
+        const description = typeof plan.fan_out_description === 'string' ? plan.fan_out_description.trim() : '';
+        notes.push(description.length > 0 ? description : 'Fan-out detected: measure totals may be inflated by joins.');
+    }
+    return notes;
+}
+/**
+ * Default sl_query response is the minimum the agent needs to read the result: connection, headers,
+ * rows, totals, plus any correctness notes. The generated `sql` and the full `plan` are attached only
+ * when explicitly requested via `include`, since both are large and echo information the caller already has.
+ */
+function projectSlQueryResult(result, include) {
+    const notes = slQueryNotes(result.plan);
+    return {
+        ...(result.connectionId !== undefined ? { connectionId: result.connectionId } : {}),
+        ...(result.dialect !== undefined ? { dialect: result.dialect } : {}),
+        headers: result.headers,
+        rows: result.rows,
+        totalRows: result.totalRows,
+        ...(notes.length > 0 ? { notes } : {}),
+        ...(include.includes('sql') ? { sql: result.sql } : {}),
+        ...(include.includes('plan') && result.plan ? { plan: result.plan } : {}),
+    };
+}
 function jsonErrorToolResult(text) {
     return {
         content: [{ type: 'text', text }],
@@ -367,6 +415,18 @@ function registerParsedTool(server, name, config, schema, handler) {
         }
     });
 }
+/**
+ * Resolves the connected client's identity into the raw telemetry fields. The
+ * strings are client-controlled and untrusted, so they only ever land in the
+ * telemetry property bag — never in paths, logs, or error messages.
+ */
+function clientTelemetryFields(getClientInfo) {
+    const client = getClientInfo?.();
+    return {
+        ...(client?.name ? { mcpClientName: client.name } : {}),
+        ...(client?.version ? { mcpClientVersion: client.version } : {}),
+    };
+}
 function instrumentMcpServer(server, telemetry) {
     return {
         registerTool(name, config, handler) {
@@ -385,6 +445,7 @@ function instrumentMcpServer(server, telemetry) {
                                 outcome: isError ? 'error' : 'ok',
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
                     }
@@ -403,6 +464,7 @@ function instrumentMcpServer(server, telemetry) {
                                 ...(errorClass ? { errorClass } : {}),
                                 durationMs: Math.max(0, performance.now() - startedAt),
                                 sampleRate: mcpTelemetrySampleRate(),
+                                ...clientTelemetryFields(telemetry.getClientInfo),
                             },
                         });
                     }
@@ -414,7 +476,11 @@ function instrumentMcpServer(server, telemetry) {
 }
 export function registerKtxContextTools(deps) {
     const { ports, userContext } = deps;
-    const server = instrumentMcpServer(deps.server, { projectDir: deps.projectDir, io: deps.io });
+    const server = instrumentMcpServer(deps.server, {
+        projectDir: deps.projectDir,
+        io: deps.io,
+        getClientInfo: deps.getClientInfo,
+    });
     if (ports.connections) {
         const connections = ports.connections;
         registerParsedTool(server, 'connection_list', {
@@ -471,7 +537,7 @@ export function registerKtxContextTools(deps) {
             annotations: toolAnnotations.sl_query,
         }, slQuerySchema, async (input, context) => {
             const onProgress = mcpProgressCallback(context);
-            return jsonToolResult(await semanticLayer.query({
+            const result = await semanticLayer.query({
                 connectionId: input.connectionId,
                 query: {
                     measures: input.measures,
@@ -482,7 +548,8 @@ export function registerKtxContextTools(deps) {
                     limit: input.limit,
                     include_empty: input.include_empty,
                 },
-            }, onProgress ? { onProgress } : undefined));
+            }, onProgress ? { onProgress } : undefined);
+            return jsonToolResult(projectSlQueryResult(result, input.include));
         });
     }
     if (ports.entityDetails) {

package/dist/context/mcp/server.js

@@ -9,6 +9,7 @@ export function createKtxMcpServer(deps) {
             userContext: deps.userContext,
             projectDir: deps.projectDir,
             io: deps.io,
+            getClientInfo: deps.getClientInfo,
         });
     }
     return deps.server;
@@ -24,6 +25,9 @@ export function createDefaultKtxMcpServer(deps) {
         contextTools: deps.contextTools,
         projectDir: deps.projectDir,
         io: deps.io,
+        // The SDK populates the client identity after the initialize handshake, so
+        // read it lazily at emit time rather than at registration (undefined here).
+        getClientInfo: () => server.server.getClientVersion(),
     });
     return server;
 }

package/dist/context/mcp/types.d.ts

@@ -46,6 +46,15 @@ export interface MemoryIngestPort {
 export interface KtxMcpUserContext {
     userId: string;
 }
+/**
+ * Identity of the connected MCP client tool (e.g. Claude Desktop, Cursor),
+ * read from the initialize handshake. Untrusted, client-controlled strings —
+ * use only as telemetry properties, never to build paths or log lines.
+ */
+export interface KtxMcpClientInfo {
+    name: string;
+    version: string;
+}
 export interface KtxMcpServerLike {
     registerTool(name: string, config: {
         title?: string;
@@ -101,7 +110,10 @@ interface KtxSemanticLayerReadResponse {
     sourceName: string;
     yaml: string;
 }
-interface KtxSemanticLayerQueryResponse {
+/** @internal */
+export interface KtxSemanticLayerQueryResponse {
+    connectionId?: string;
+    dialect?: string;
     sql: string;
     headers: string[];
     rows: unknown[][];
@@ -165,5 +177,7 @@ export interface KtxMcpServerDeps {
     contextTools?: KtxMcpContextPorts;
     projectDir?: string;
     io?: KtxCliIo;
+    /** Reads the connected client's identity once the initialize handshake completes. */
+    getClientInfo?: () => KtxMcpClientInfo | undefined;
 }
 export {};

package/dist/context/project/config.d.ts

@@ -395,6 +395,7 @@ declare const ktxProjectConfigSchema: z.ZodObject<{
                 continue: "continue";
             }>>;
         }, z.core.$strict>>;
+        profile: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"json">]>>;
     }, z.core.$strict>>;
     agent: z.ZodPrefault<z.ZodObject<{
         run_research: z.ZodPrefault<z.ZodObject<{

package/dist/context/project/config.js

@@ -96,6 +96,10 @@ const ingestSchema = z
         .prefault({ backend: 'none' })
         .describe('Embedding configuration used when ingest adapters need to embed documents.'),
     workUnits: workUnitsSchema.prefault({}).describe('Concurrency and failure handling for ingest work units.'),
+    profile: z
+        .union([z.boolean(), z.literal('json')])
+        .default(false)
+        .describe('Print a timing breakdown to stderr at the end of each ingest run. `true` prints a human table; `"json"` prints the raw structured profile for coding agents; `false` disables it. Equivalent to the KTX_PROFILE_INGEST environment variable (`1`/`true`/`json`).'),
 })
     .describe('Ingest pipeline configuration: adapters, embeddings, and work-unit policy.');
 const scanEnrichmentSchema = z

package/dist/context/project/driver-schemas.js

@@ -21,7 +21,7 @@ function warehouseConnectionSchema(driver) {
         enabled_tables: z
             .array(z.string().min(1))
             .optional()
-            .describe('Optional allowlist of fully-qualified table names ("schema.table") to ingest. When set, live-database ingest discards any table whose schema-qualified name is not in this list. Useful for smoke-testing deep ingest on a single table.'),
+            .describe('Optional allowlist of fully-qualified table names ("schema.table") to ingest. When set, live-database ingest discards any table whose schema-qualified name is not in this list. Useful for smoke-testing ingest on a single table.'),
     })
         .describe(`${driver} warehouse connection. Additional driver-tunable fields (e.g. context.queryHistory) are accepted and passed through.`);
 }

package/dist/context/search/discover.js

@@ -95,7 +95,7 @@ async function wikiCandidates(project, input, options, terms) {
         query: input.query,
         userId: options.userId,
         embeddingService: options.embeddingService ?? null,
-        limit: Math.max(input.limit ?? 15, 25),
+        limit: Math.max(input.limit ?? 10, 25),
     });
     const records = [];
     for (const result of searchResults) {
@@ -300,7 +300,8 @@ function hydrate(fused, refsByKey) {
         }
         return {
             ...ref,
-            score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(6)) : 0,
+            // 3 decimals is plenty for a relative-rank hint; 6 just spent bytes on noise.
+            score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(3)) : 0,
         };
     })
         .filter((result) => result !== null);
@@ -308,7 +309,7 @@ function hydrate(fused, refsByKey) {
 export function createKtxDiscoverDataService(project, options = {}) {
     return {
         async search(input) {
-            const limit = Math.max(1, Math.min(input.limit ?? 15, 50));
+            const limit = Math.max(1, Math.min(input.limit ?? 10, 50));
             const query = input.query.trim();
             if (!query) {
                 return [];

package/dist/context/sl/local-sl.d.ts

@@ -28,6 +28,7 @@ export interface LocalSlSearchInput {
     backend?: 'pglite-owner-prototype';
     pglite?: PgliteSlSearchPrototypeOwnerOptions;
 }
+/** @internal */
 export interface LocalSlSource extends LocalSlSourceSummary {
     yaml: string;
 }
@@ -38,6 +39,15 @@ export interface LocalSlValidationResult {
     valid: boolean;
     errors: string[];
 }
+export type ResolvedSlSource = {
+    kind: 'found';
+    source: LocalSlSource;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'ambiguous';
+    connectionIds: string[];
+};
 export declare function loadLocalSlSourceRecords(project: KtxLocalProject, input: {
     connectionId: string;
 }): Promise<LocalSlSourceRecord[]>;
@@ -52,10 +62,15 @@ export declare function writeLocalSlSource(project: KtxLocalProject, input: {
     sourceName: string;
     yaml: string;
 }): Promise<KtxFileWriteResult>;
+/** @internal */
 export declare function readLocalSlSource(project: KtxLocalProject, input: {
     connectionId: string;
     sourceName: string;
 }): Promise<LocalSlSource | null>;
+export declare function resolveLocalSlSource(project: KtxLocalProject, input: {
+    sourceName: string;
+    connectionId?: string;
+}): Promise<ResolvedSlSource>;
 export declare function listLocalSlSources(project: KtxLocalProject, input?: {
     connectionId?: string;
 }): Promise<LocalSlSourceSummary[]>;

package/dist/context/sl/local-sl.js

@@ -204,6 +204,7 @@ export async function writeLocalSlSource(project, input) {
     const path = slPath(input.connectionId, input.sourceName);
     return project.fileStore.writeFile(path, input.yaml.endsWith('\n') ? input.yaml : `${input.yaml}\n`, LOCAL_AUTHOR, LOCAL_AUTHOR_EMAIL, `Write semantic-layer source: ${input.connectionId}/${input.sourceName}`);
 }
+/** @internal */
 export async function readLocalSlSource(project, input) {
     const path = slPath(input.connectionId, input.sourceName);
     try {
@@ -221,6 +222,35 @@ export async function readLocalSlSource(project, input) {
         return record ? { ...record } : null;
     }
 }
+export async function resolveLocalSlSource(project, input) {
+    if (input.connectionId !== undefined) {
+        const source = await readLocalSlSource(project, {
+            connectionId: input.connectionId,
+            sourceName: input.sourceName,
+        });
+        return source ? { kind: 'found', source } : { kind: 'not-found' };
+    }
+    const summaries = await listLocalSlSources(project, {});
+    const matches = summaries.filter((summary) => summary.name === input.sourceName);
+    if (matches.length === 0) {
+        return { kind: 'not-found' };
+    }
+    if (matches.length > 1) {
+        return {
+            kind: 'ambiguous',
+            connectionIds: [...new Set(matches.map((match) => match.connectionId))].sort(),
+        };
+    }
+    const match = matches[0];
+    if (match === undefined) {
+        return { kind: 'not-found' };
+    }
+    const source = await readLocalSlSource(project, {
+        connectionId: match.connectionId,
+        sourceName: input.sourceName,
+    });
+    return source ? { kind: 'found', source } : { kind: 'not-found' };
+}
 export async function listLocalSlSources(project, input = {}) {
     if (input.connectionId) {
         return (await loadLocalSlSourceRecords(project, { connectionId: input.connectionId })).map(({ source: _source, yaml: _yaml, ...summary }) => summary);

package/dist/context/wiki/local-knowledge.d.ts

@@ -50,6 +50,16 @@ export declare function readLocalKnowledgePage(project: KtxLocalProject, input:
 export declare function listLocalKnowledgePages(project: KtxLocalProject, input?: {
     userId?: string;
 }): Promise<LocalKnowledgeSummary[]>;
+/**
+ * List wiki page keys without reading or parsing file contents.
+ *
+ * Keys are derived purely from file paths, so this stays cheap enough for
+ * shell tab-completion (unlike `listLocalKnowledgePages`, which reads every
+ * page to populate summaries).
+ */
+export declare function listLocalKnowledgePageKeys(project: KtxLocalProject, input?: {
+    userId?: string;
+}): Promise<string[]>;
 export declare function searchLocalKnowledgePages(project: KtxLocalProject, input: {
     query: string;
     userId?: string;

package/dist/context/wiki/local-knowledge.js

@@ -118,6 +118,28 @@ export async function listLocalKnowledgePages(project, input = {}) {
     }
     return pages.sort((left, right) => left.path.localeCompare(right.path));
 }
+/**
+ * List wiki page keys without reading or parsing file contents.
+ *
+ * Keys are derived purely from file paths, so this stays cheap enough for
+ * shell tab-completion (unlike `listLocalKnowledgePages`, which reads every
+ * page to populate summaries).
+ */
+export async function listLocalKnowledgePageKeys(project, input = {}) {
+    const userId = input.userId ?? 'local';
+    const keys = new Set();
+    for (const scope of ['GLOBAL', 'USER']) {
+        const root = scope === 'GLOBAL' ? 'wiki/global' : `wiki/user/${assertSafePathToken('user id', userId)}`;
+        const listed = await project.fileStore.listFiles(root);
+        for (const path of listed.files.filter((file) => file.endsWith('.md'))) {
+            const key = keyFromKnowledgePath(path, scope, userId);
+            if (key) {
+                keys.add(key);
+            }
+        }
+    }
+    return [...keys].sort();
+}
 function scorePage(page, terms) {
     const haystack = buildKnowledgeSearchText(page.key, page.summary, page.content, page.tags).toLowerCase();
     return terms.some((term) => haystack.includes(term)) ? 3 : 0;

package/dist/context-build-view.d.ts

@@ -39,9 +39,6 @@ export interface ContextBuildArgs {
     targetConnectionId?: string;
     all?: boolean;
     entrypoint?: 'setup' | 'ingest';
-    depth?: Extract<KtxPublicIngestArgs, {
-        command: 'run';
-    }>['depth'];
     queryHistory?: Extract<KtxPublicIngestArgs, {
         command: 'run';
     }>['queryHistory'];

package/dist/context-build-view.js

@@ -241,12 +241,11 @@ function renderMessageGroup(label, messages, styled) {
 function retryCommand(input) {
     const projectPart = input.projectDir ? ` --project-dir ${input.projectDir}` : '';
     if (input.entrypoint === 'ingest' && input.connectionId) {
-        const depthPart = input.depth ? ` --${input.depth}` : '';
         const queryHistoryPart = input.queryHistory ? ' --query-history' : '';
         const windowPart = input.queryHistory && input.queryHistoryWindowDays !== undefined
             ? ` --query-history-window-days ${input.queryHistoryWindowDays}`
             : '';
-        return `ktx ingest ${input.connectionId}${projectPart}${depthPart}${queryHistoryPart}${windowPart}`;
+        return `ktx ingest ${input.connectionId}${projectPart}${queryHistoryPart}${windowPart}`;
     }
     return input.projectDir ? `ktx setup --project-dir ${input.projectDir}` : 'ktx setup';
 }
@@ -563,7 +562,6 @@ function appendRetryIfNeeded(input) {
         projectDir: input.projectDir,
         entrypoint: input.entrypoint,
         connectionId: input.target.connectionId,
-        depth: input.target.databaseDepth,
         queryHistory: input.target.queryHistory?.enabled === true,
         queryHistoryWindowDays: input.target.queryHistory?.windowDays,
     })}`;
@@ -578,7 +576,6 @@ function failureTextForTarget(input) {
                 projectDir: input.projectDir,
                 entrypoint: input.entrypoint,
                 connectionId: input.target.connectionId,
-                depth: input.target.databaseDepth,
                 queryHistory: input.target.queryHistory?.enabled === true,
                 queryHistoryWindowDays: input.target.queryHistory?.windowDays,
             })}`,
@@ -593,7 +590,6 @@ function failureTextForTarget(input) {
                 projectDir: input.projectDir,
                 entrypoint: input.entrypoint,
                 connectionId: input.target.connectionId,
-                depth: input.target.databaseDepth,
                 queryHistory: input.target.queryHistory?.enabled === true,
                 queryHistoryWindowDays: input.target.queryHistory?.windowDays,
             })}`,
@@ -659,7 +655,6 @@ export async function runContextBuild(project, args, io, deps = {}) {
         projectDir: args.projectDir,
         ...(args.targetConnectionId ? { targetConnectionId: args.targetConnectionId } : {}),
         all: args.all ?? true,
-        ...(args.depth ? { depth: args.depth } : {}),
         ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
         ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
         ...(args.scanMode ? { scanMode: args.scanMode } : {}),
@@ -721,7 +716,6 @@ export async function runContextBuild(project, args, io, deps = {}) {
         all: args.all ?? true,
         json: false,
         inputMode: args.inputMode,
-        ...(args.depth ? { depth: args.depth } : {}),
         ...(args.queryHistory ? { queryHistory: args.queryHistory } : {}),
         ...(args.queryHistoryWindowDays !== undefined ? { queryHistoryWindowDays: args.queryHistoryWindowDays } : {}),
         ...(args.scanMode ? { scanMode: args.scanMode } : {}),

package/dist/ingest.js

@@ -2,7 +2,7 @@ import { buildMemoryFlowViewModel } from './context/ingest/memory-flow/view-mode
 import { createMemoryFlowLiveBuffer, sanitizeMemoryFlowError } from './context/ingest/memory-flow/live-buffer.js';
 import { formatMemoryFlowFinalSummary } from './context/ingest/memory-flow/summary.js';
 import { getLatestLocalIngestStatus, getLocalIngestStatus, runLocalIngest, runLocalMetabaseIngest } from './context/ingest/local-ingest.js';
-import { savedMemoryCountsForReport } from './context/ingest/reports.js';
+import { ingestReportOutcome, savedMemoryCountsForReport } from './context/ingest/reports.js';
 import { ingestReportToMemoryFlowReplay } from './context/ingest/memory-flow/events.js';
 import { renderMemoryFlowReplay } from './context/ingest/memory-flow/render.js';
 import { loadKtxProject } from './context/project/project.js';
@@ -17,9 +17,6 @@ import { renderMemoryFlowTui, startLiveMemoryFlowTui, } from './memory-flow-tui.
 import { resolveVizFallback, warnVizFallbackOnce } from './viz-fallback.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:ingest');
-function reportStatus(report) {
-    return report.body.status === 'failed' || report.body.failedWorkUnits.length > 0 ? 'error' : 'done';
-}
 const REPORT_SOURCE_LABELS = new Map([
     ['live-database', 'Database schema'],
     ['historic-sql', 'Query history'],
@@ -106,7 +103,7 @@ function writeReportStatus(report, io) {
     if (report.body.tracePath) {
         io.stdout.write(`Trace: ${report.body.tracePath}\n`);
     }
-    io.stdout.write(`Status: ${reportStatus(report)}\n`);
+    io.stdout.write(`Status: ${ingestReportOutcome(report)}\n`);
     io.stdout.write(`Source: ${reportSourceLabel(report.sourceKey)}\n`);
     io.stdout.write(`Connection: ${report.connectionId}\n`);
     io.stdout.write(`Sync: ${report.body.syncId}\n`);
@@ -138,7 +135,7 @@ function writeMetabaseFanoutStatus(result, io) {
     }
     io.stdout.write(`Saved memory: ${counts.wikiCount} wiki, ${counts.slCount} SL\n`);
     for (const child of result.children) {
-        const status = reportStatus(child.report);
+        const status = ingestReportOutcome(child.report);
         io.stdout.write(`- target=${child.targetConnectionId} database=${child.metabaseDatabaseId} status=${status} job=${child.jobId} report=${child.report.id}\n`);
     }
 }
@@ -425,7 +422,7 @@ function initialRunMemoryFlowInput(args, runId) {
     };
 }
 function finalRunMemoryFlowInput(snapshot, report) {
-    const status = reportStatus(report);
+    const status = ingestReportOutcome(report) === 'error' ? 'error' : 'done';
     return {
         ...snapshot,
         runId: report.runId,
@@ -574,7 +571,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                 finally {
                     plainProgress?.flush();
                 }
-                return result.status === 'all_succeeded' ? 0 : 1;
+                return result.status === 'all_failed' ? 1 : 0;
             }
             const jobId = deps.jobIdFactory?.();
             let liveTui = null;
@@ -636,7 +633,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     liveTui?.close();
                     liveTui = null;
                     io.stdout.write(formatMemoryFlowFinalSummary(latestMemoryFlowSnapshot));
-                    return reportStatus(result.report) === 'done' ? 0 : 1;
+                    return ingestReportOutcome(result.report) === 'error' ? 1 : 0;
                 }
                 plainProgress?.flush();
                 await writeReportRecord(result.report, runOutputMode, io, {
@@ -644,7 +641,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     renderStoredMemoryFlow: deps.renderStoredMemoryFlow,
                     env,
                 });
-                return reportStatus(result.report) === 'done' ? 0 : 1;
+                return ingestReportOutcome(result.report) === 'error' ? 1 : 0;
             }
             finally {
                 plainProgress?.flush();

package/dist/knowledge.d.ts

@@ -18,6 +18,11 @@ export type KtxKnowledgeArgs = {
     limit?: number;
     debug?: boolean;
     cliVersion: string;
+} | {
+    command: 'read';
+    projectDir: string;
+    key: string;
+    userId: string;
 };
 type KtxKnowledgeIo = import('./cli-runtime.js').KtxCliIo;
 interface KtxKnowledgeDeps {

package/dist/knowledge.js

@@ -1,6 +1,6 @@
 import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
 import { loadKtxProject } from './context/project/project.js';
-import { listLocalKnowledgePages, searchLocalKnowledgePages as defaultSearchLocalKnowledgePages } from './context/wiki/local-knowledge.js';
+import { listLocalKnowledgePages, readLocalKnowledgePage, searchLocalKnowledgePages as defaultSearchLocalKnowledgePages, } from './context/wiki/local-knowledge.js';
 import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
 import { resolveOutputMode } from './io/mode.js';
 import { createRankBadgeFormatter, printList } from './io/print-list.js';
@@ -72,6 +72,15 @@ export async function runKtxKnowledge(args, io = process, deps = {}) {
             });
             return 0;
         }
+        if (args.command === 'read') {
+            const page = await readLocalKnowledgePage(project, { key: args.key, userId: args.userId });
+            if (!page) {
+                throw new Error(`No wiki page found for key '${args.key}'`);
+            }
+            const raw = await project.fileStore.readFile(page.path);
+            io.stdout.write(raw.content);
+            return 0;
+        }
         if (args.command === 'search') {
             const embeddingService = await wikiSearchEmbeddingService(project, deps, { cliVersion: args.cliVersion }, io);
             const search = deps.searchLocalKnowledgePages ?? defaultSearchLocalKnowledgePages;

package/dist/public-ingest-copy.js

@@ -11,7 +11,7 @@ const DATABASE_INGEST_REPLACEMENTS = [
         'Database enrichment failed after schema context completed',
     ],
     [/\bstructural scan\b/gi, 'schema context'],
-    [/\benriched scan\b/gi, 'deep database ingest'],
+    [/\benriched scan\b/gi, 'database ingest'],
     [/\bscan results\b/gi, 'database context'],
 ];
 export function publicDatabaseIngestMessage(message) {