@kaelio/ktx 0.13.1 → 0.15.0

package/dist/skills/gdrive_synthesize/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gdrive_synthesize
+description: Synthesize durable KTX wiki pages from staged Google Drive document pulls. Load when a WorkUnit contains Google Doc raw files from `docs/**`.
+callers: [memory_agent]
+---
+
+# Google Drive Doc Synthesis
+
+Use this skill when a WorkUnit contains staged Google Drive content from `docs/**`.
+
+## Role
+
+Each WorkUnit is one Google Doc plus its metadata. Read the assigned raw files, then write a small set of durable wiki entries that capture reusable organizational knowledge. Write final memory directly; do not write candidates.
+
+## Required Workflow
+
+1. Read the WorkUnit notes and `rawFiles` list. Document content lives in `page.md`; `metadata.json` holds title, path, url, modified time, and Drive folder context.
+2. For each assigned doc, call `read_raw_file`, or `read_raw_span` for oversized docs when the notes specify a span.
+3. Search `wiki_search` for existing pages that overlap the WorkUnit topics. Prefer updating an existing page over creating a duplicate.
+4. Use `context_evidence_search`, `context_evidence_read`, and `context_evidence_neighbors` when indexed document chunks would help reconcile related facts. Pass `chunkId` and `documentId` values verbatim as returned by the evidence tools.
+5. Write durable business knowledge with `wiki_write`. Aim for a small number of high-quality pages per doc. Include `rawPaths` with the exact Google Drive raw files that support each page.
+6. If a doc references warehouse, dbt, Looker, Metabase, or MetricFlow objects, you may verify them with `discover_data`, `entity_details`, `sql_execution`, `sl_discover`, or `sl_read_source`, but Google Drive docs are knowledge-only in v1. Do not create semantic-layer sources under the `gdrive` connection.
+7. For every deleted raw path in the Eviction Set, call `eviction_list`, decide retention, then `emit_eviction_decision`. Do this even when no wiki write is needed.
+
+## What To Capture
+
+Capture durable, reusable company knowledge:
+
+- policies, workflows, process rules, ownership conventions, and operating procedures
+- product definitions, business terminology, and organizational guidance
+- source-of-truth statements, caveats, conflict notes, and supersession guidance
+- cross-system aliases that connect doc terminology to warehouse, dbt, Looker, Metabase, or MetricFlow names
+
+Skip noisy or transient content:
+
+- brainstorming notes with no durable rule
+- task lists, meeting scheduling details, and time-bounded status updates
+- duplicate docs with no new fact
+- shallow summaries that add no reusable policy or definition
+
+## Quality
+
+Prefer fewer, stronger entries. Every wiki entry must cite at least one Google Doc using its title or path and last modified date when available. When evidence conflicts, write a conflict note inside the wiki page rather than choosing silently.
+
+If one doc covers several related ideas, synthesize the shared durable rules instead of writing one thin page per paragraph. For oversized spans, read only the assigned span unless the WorkUnit explicitly asks for neighboring context.
+
+Search existing wiki pages for the same `tables:` or `sl_refs:` frontmatter and for source-of-truth aliases before creating a new page. If an existing page already documents the same warehouse object or business concept, update it instead of creating a differently named duplicate.
+
+## Citation Style
+
+```md
+## Agentic Harness
+- The harness provides the operational framework that turns an agent prototype into a production system.
+- Source: Google Doc - Herness, last modified 2026-05-24.
+- Conflict note: An older internal note uses a narrower definition focused only on tool wiring; treat the current Google Doc as the durable operating definition unless replaced explicitly.
+```
+
+## Semantic-Layer Rules
+
+- Google Drive docs are knowledge-only in v1; keep durable output in wiki pages.
+- Do not create semantic-layer sources under the `gdrive` connection.
+- If a doc references an existing warehouse or semantic-layer object and you can verify it, you may attach `sl_refs` in wiki output after confirmation.
+- If a doc mentions a table or source that cannot be verified, keep the identifier in wiki text as unverified or use `emit_unmapped_fallback` only when the missing physical object itself is the important durable fact.
+
+## Identifier Verification Protocol
+
+Before writing a wiki page on any topic:
+
+1. `discover_data({query: "<topic>"})` - see what wikis, SL sources, and raw
+   tables already exist. Prefer updating existing pages over creating new ones.
+
+Before emitting any `schema.table` or `schema.table.column` into a wiki body,
+`tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:
+
+2. `entity_details({connectionId, targets: [{display: "<identifier>"}]})` -
+   confirm the identifier resolves; inspect native types, FK/PK, and
+   sampleValues.
+3. For literal values from the doc, such as status codes or plan tiers,
+   check whether they appear in `entity_details` sampleValues for the relevant
+   column. If sampleValues is short or the sample may have missed real values,
+   run a `sql_execution` probe with the same warehouse connection id:
+   `sql_execution({connectionId, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"})`.
+4. If the candidate identifier still does not resolve, do one of:
+   - Use `sql_execution({connectionId, sql: "SELECT 1 FROM <ref> LIMIT 0"})`.
+     If it errors, the identifier is fictional.
+   - Wrap the identifier in `[unverified - from <rawPath>]` in the wiki body,
+     citing the exact raw path that mentioned it.
+   - When recording `emit_unmapped_fallback` with `no_physical_table`, include
+     the failing probe error in `clarification`.
+5. Never copy `<schema>.<table>` placeholder strings from these instructions
+   into output.
+
+## Tools
+
+Allowed: `read_raw_file`, `read_raw_span`, `wiki_search`, `wiki_read`, `wiki_write`, `discover_data`, `entity_details`, `sql_execution`, `sl_discover`, `sl_read_source`, `context_evidence_search`, `context_evidence_read`, `context_evidence_neighbors`, `emit_unmapped_fallback`, `eviction_list`, `emit_eviction_decision`.
+
+Not allowed: `context_candidate_write`, `context_candidate_mark`, `sl_write_source`, `sl_edit_source`, `sl_validate`.

package/dist/skills/sigma_ingest/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: sigma_ingest
+description: Extract durable ktx wiki knowledge from staged Sigma data model specs and workbook summaries. Load for WorkUnits with unitKey sigma-data-models or sigma-workbooks.
+callers: [memory_agent]
+---
+
+# Sigma Ingest
+
+Sigma ingest turns staged data model specs and workbook summaries into durable ktx wiki knowledge. The deterministic `project()` step has already written semantic-layer YAML for all warehouse-table data model elements before this skill runs — do not re-write those SL sources.
+
+## Work unit structure
+
+Sigma produces at minimum two work units per ingest run:
+
+- `sigma-data-models` or `sigma-data-models-N`
+  - `rawFiles`: `data-models/<id>.json` files (one per data model in this batch)
+  - `peerFileIndex`: `workbooks/<id>.json` files + `sigma-manifest.json` + `sigma-projection-config.json`
+  - When the workspace has more than 50 data models, split into batches: `sigma-data-models-0`, `sigma-data-models-1`, … with `displayLabel` like `"Sigma: data models (1/8)"`. When ≤50 data models, the unitKey is simply `sigma-data-models` with no suffix.
+- `sigma-workbooks` or `sigma-workbooks-N`
+  - `rawFiles`: `workbooks/<id>.json` files (one per workbook in this batch)
+  - `peerFileIndex`: `data-models/<id>.json` files + `sigma-manifest.json` + `sigma-projection-config.json`
+  - When the workspace has more than 2000 workbooks, split into batches: `sigma-workbooks-0`, `sigma-workbooks-1`, … with `displayLabel` like `"Sigma: workbooks (1/4)"`. When ≤2000 workbooks, the unitKey is simply `sigma-workbooks` with no suffix.
+
+`sigma-manifest.json` and `sigma-projection-config.json` are never in `rawFiles`. They live at the staged dir root and always appear in `peerFileIndex`.
+
+## Staged file shapes
+
+**`data-models/<id>.json`** — one per data model (in `rawFiles` for data-model units):
+```json
+{
+  "sigmaId": "abc-123",
+  "name": "Revenue Model",
+  "path": "Finance/Revenue Model",
+  "latestVersion": 3,
+  "updatedAt": "2026-01-15T00:00:00Z",
+  "isArchived": false,
+  "spec": {
+    "name": "Revenue Model",
+    "pages": [{
+      "id": "p1",
+      "name": "Main",
+      "elements": [{
+        "id": "elem1",
+        "kind": "table",
+        "name": "Opportunities",
+        "hidden": false,
+        "source": {
+          "kind": "warehouse-table",
+          "connectionId": "<sigma-internal-uuid>",
+          "path": ["DATABASE", "SCHEMA", "OPPORTUNITIES"]
+        },
+        "columns": [
+          { "id": "c1", "name": "Deal Amount", "formula": "[OPPORTUNITIES/Amount]", "description": "Net contract value in USD" },
+          { "id": "c2", "name": "Total ARR", "formula": "Sum([OPPORTUNITIES/ARR])", "description": "Annualised recurring revenue" }
+        ]
+      }]
+    }]
+  }
+}
+```
+
+`source.kind` discriminates:
+- `warehouse-table` — element maps directly to a warehouse table. Has `connectionId` and `path` (array of path segments forming the fully-qualified table name). `project()` writes an SL source when `connectionMappings` covers this `connectionId`.
+- `table` — element is a derived view layered on top of another element; identified by `source.elementId`. No warehouse path. Wiki-only.
+
+**`workbooks/<id>.json`** — one per workbook, in `rawFiles` for workbook units (summary only; no spec endpoint exists):
+```json
+{
+  "sigmaId": "wb-abc",
+  "name": "ARR Tracker",
+  "path": "Finance/Dashboards",
+  "latestVersion": 2,
+  "updatedAt": "2026-01-16T00:00:00Z",
+  "isArchived": false,
+  "workbookUrlId": "57a96EMo3G...",
+  "description": "Tracks ARR by segment and cohort for the finance team"
+}
+```
+
+**Peer files (available via `peerFileIndex`, not `rawFiles`):**
+
+**`sigma-manifest.json`** — fetch summary; use for provenance only.
+
+**`sigma-projection-config.json`** — written by `fetch()`, contains two fields the skill must read:
+
+- `connectionMappings`: `{sigmaInternalUuid: ktxWarehouseConnectionId}`. Use the mapped warehouse connection ID for `entity_details` when verifying warehouse identifiers found in data model specs.
+- `workbookFilter`: the filter settings that were active when workbooks were last fetched:
+  - `includeArchived` (default `false`) — when `false`, archived workbooks are not in `workbooks/`; `isArchived: true` files will only appear when this was `true`.
+  - `includeExplorations` (default `false`) — when `false`, exploration-type workbooks (unsaved analyses) are excluded; treat present workbooks as intentional, curated reports.
+  - `updatedSince` (optional ISO 8601 string) — when set, only workbooks updated on or after this date are staged; the set is a recent-changes slice, not the full workspace. Do not infer that absent workbooks were deleted.
+
+`sigma-manifest.json` also reflects any active `dataModelFilter`. When `dataModelFilter.updatedSince` was set during fetch, `dataModelCount` reflects only matching models, not the full workspace. Do not infer that absent data models were deleted.
+
+Read `sigma-projection-config.json` first and keep `workbookFilter` in scope while processing the WorkUnit.
+
+## Required workflow
+
+1. Read every `rawFiles` entry for the WorkUnit.
+2. Read `sigma-projection-config.json` from the staged dir to get `connectionMappings`.
+3. For each data model file: extract business semantics from element names, column descriptions, and the domain context of the model. Skip hidden elements and hidden columns.
+4. For each workbook file: extract business domain knowledge from the name and description. When `workbookFilter.updatedSince` is set, treat the staged set as a recent-changes slice — absent workbooks were not deleted, they were simply outside the filter window.
+5. Use `discover_data` before writing to find existing wiki pages on the same topic.
+6. Write wiki candidates with `context_candidate_write`. Do not call `wiki_write` directly from a Sigma WorkUnit; Stage 4 reconciliation promotes candidates.
+7. Do not write or edit SL sources. The `project()` step owns all SL output for Sigma.
+
+## Identifier Verification Protocol
+
+Before writing a wiki page or SL source on any topic:
+
+1. `discover_data({query: "<topic>"})` - see what wikis, SL sources, and raw
+   tables already exist. Prefer updating existing pages over creating new ones.
+
+Before emitting any `schema.table` or `schema.table.column` into a wiki body,
+SL source, `tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:
+
+2. `entity_details({connectionId, targets: [{display: "<identifier>"}]})` -
+   confirm the identifier resolves; inspect native types, FK/PK, and
+   sampleValues. Use the warehouse `connectionId` from `connectionMappings` in
+   `sigma-projection-config.json`, not the Sigma connection ID. If
+   `connectionMappings` has no entry for the element's `source.connectionId`,
+   skip `entity_details` — there is no mapped warehouse to verify against —
+   and wrap any identifier references with `[unverified - from <rawPath>]`.
+3. For literal values from the source, such as status codes or plan tiers,
+   check whether they appear in `entity_details` sampleValues for the relevant
+   column. If sampleValues is short or the sample may have missed real values,
+   run a `sql_execution` probe with the same warehouse connection id:
+   `sql_execution({connectionId, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"})`.
+4. If the candidate identifier still does not resolve, do one of:
+   - Use `sql_execution({connectionId, sql: "SELECT 1 FROM <ref> LIMIT 0"})`.
+     If it errors, the identifier is fictional.
+   - Wrap the identifier in `[unverified - from <rawPath>]` in the wiki body,
+     citing the exact raw path that mentioned it.
+   - When recording `emit_unmapped_fallback` with `no_physical_table`, include
+     the failing probe error in `clarification`.
+5. Never copy `<schema>.<table>` placeholder strings from these instructions
+   into output.
+
+## Data model elements
+
+### Warehouse-table elements (`source.kind === "warehouse-table"`)
+
+`project()` writes an SL source for a warehouse-table element **only when** the element's `source.connectionId` has an entry in `connectionMappings`. When no mapping exists, no SL source is written and the element is wiki-only.
+
+To determine whether an SL source exists: check whether `connectionMappings[element.source.connectionId]` resolves. If it does, use `sl_discover` to find the source by its slugified name (`<dataModelName>_<elementName>`), then:
+
+- Read the existing SL source with `sl_read_source` to understand what columns and measures are captured.
+- Write a wiki candidate about the business domain if the element name, column descriptions, or data model description reveals durable knowledge not already in the wiki.
+- `sl_refs` in the wiki candidate should point to the already-written SL source name.
+
+If `connectionMappings` has no entry for the element's `source.connectionId`, treat the element as wiki-only — do not attempt `sl_discover` or `sl_read_source` for it, as no source was written.
+
+### Joins within a data model
+
+Joins are not projected in v1; `joins: []` is always written by `project()`. `Lookup()` formulas may be described in wiki prose instead.
+
+### Non-warehouse elements (`source.kind === "table"`)
+
+These reference another element by `elementId` — they are derived views layered on top of a warehouse-table element. They have no warehouse path of their own. Do not attempt SL writes for these elements. They may produce wiki candidates if their column names or descriptions reveal business semantics not captured by the underlying warehouse-table element.
+
+## Workbooks
+
+Workbooks have summary metadata only. There is no spec endpoint.
+
+Extract business domain knowledge from:
+- `name`: the workbook's primary topic (e.g. "ARR Tracker" → ARR tracking concepts)
+- `description`: business context and intended audience
+- `path`: team or functional area (e.g. `Finance/Dashboards`)
+
+Write wiki candidates when the name or description reveals a reusable business concept, metric definition, or domain convention. Write one candidate per distinct concept, not one per workbook.
+
+Skip workbooks whose name or description contains no durable business semantics (e.g. "Untitled Workbook", "Test Dashboard").
+
+## Capture rules
+
+Write wiki candidates for:
+- Metric definitions mentioned in element names or column descriptions (e.g. "Net ARR", "Churned MRR")
+- Domain conventions such as cohort definitions, segment taxonomies, or fiscal calendar rules
+- Relationships between business entities revealed by data model joins
+
+Skip:
+- Visualization settings, layout, colors, chart types
+- Owner names, folder paths, and version numbers as wiki narrative
+- Hidden elements and hidden columns
+- Data model names that are purely technical with no business meaning
+- When `workbookFilter.includeExplorations` is `false` (the default), all staged workbooks are intentional reports — no extra exploration filter needed. When it is `true`, workbooks without a description or with a generic auto-generated name are likely ephemeral explorations; skip those.
+
+## Usage signals
+
+Sigma workbooks carry `latestVersion` but no usage counts. Treat a higher `latestVersion` as weak evidence of continued maintenance; do not include version numbers in wiki prose.

package/dist/skills/wiki_capture/SKILL.md

@@ -112,6 +112,30 @@ All three fields use REPLACE semantics on update:
 - Pass `[]` → field is cleared.
 - Pass `[values]` → replaces existing with exactly those values (no merging).
 
+## Connection scoping
+
+A project may have several databases whose schemas reuse the same concept names
+(two warehouses each with `orders`, `customers`, …). The `connections`
+frontmatter field keeps database-specific pages from polluting searches about
+other databases.
+
+- The `wiki_write` tool accepts a `connections` field (list of connection ids,
+  same REPLACE semantics as `tags`). Absent or empty ⇒ the page is **unscoped**
+  and applies to every connection.
+- When this ingest/turn is scoped to a connection (its id appears in the prompt
+  context — e.g. `connectionId: warehouse` in the SL Sources header or the
+  `<context>` block), set `connections: [<that id>]` on pages whose content is
+  **specific to that database** ("in this warehouse `user_id` is the device id,
+  not the account id"). Pair this with a connection-distinctive key so two
+  databases' same-concept pages can coexist: `orders_sales_db`, not `orders`.
+- Leave `connections` empty for clearly **org-wide** knowledge ("fiscal year
+  starts in February") so it stays visible everywhere. Do not scope a page to a
+  connection just because the turn happened to be connection-scoped.
+- Keys are still a flat, global namespace; `connections` does not namespace
+  them. A connection-scoped write whose key already belongs to a page scoped to
+  a *different* connection is rejected to prevent silently overwriting it — pick
+  a connection-distinctive key instead.
+
 ## Editing existing pages
 
 Two modes:

package/dist/sql.js

@@ -1,5 +1,6 @@
 import { FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
 import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
+import { assertSqlQueryableConnection } from './context/connections/dialects.js';
 import { resolveConfiguredConnection } from './context/connections/resolve-connection.js';
 import { loadKtxProject } from './context/project/project.js';
 import { sqlAnalysisDialectForDriver } from './context/sql-analysis/dialect.js';
@@ -90,6 +91,9 @@ export async function runKtxSql(args, io = process, deps = {}) {
         const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, args.connectionId);
         driver = isFederated ? 'duckdb' : String(connection?.driver ?? 'unknown').toLowerCase();
         demoConnection = isFederated ? false : isDemoConnection(args.connectionId, connection);
+        if (!isFederated) {
+            assertSqlQueryableConnection(args.connectionId, connection?.driver);
+        }
         const createSqlAnalysis = deps.createSqlAnalysis ??
             (() => createManagedDaemonSqlAnalysisPort({
                 cliVersion: args.cliVersion,

package/dist/status-project.d.ts

@@ -75,6 +75,10 @@ interface LocalStatsIngestPerConnection {
     connectionId: string;
     adapter: string;
     lastCompletedAt: string;
+    skippedObjects: Array<{
+        name: string;
+        reason: string;
+    }>;
 }
 interface LocalStatsSemanticLayerEntry {
     connectionId: string;

package/dist/status-project.js

@@ -4,6 +4,7 @@ import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
 import { CODEX_ISOLATION_WARNING, CODEX_ISOLATION_WARNING_FIX, } from './context/llm/codex-isolation.js';
 import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
+import { listReferencedConnectionIds } from './context/wiki/local-knowledge.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
 import { formatClaudeCodePromptCachingFix, formatClaudeCodePromptCachingWarning, ignoredClaudeCodePromptCachingFields, } from './claude-code-prompt-caching.js';
@@ -387,6 +388,29 @@ function buildStorageStatus(config) {
         gitAuthor: config.storage.git.author,
     };
 }
+/**
+ * Warn (never fail) when stored wiki pages reference connection ids that are no
+ * longer in `ktx.yaml`. Config and page content evolve independently, so a
+ * dangling reference is a soft condition — the pages still load, search, and
+ * read; it just signals a typo or a removed connection.
+ */
+async function buildUnknownConnectionWarning(project) {
+    let referenced;
+    try {
+        referenced = await listReferencedConnectionIds(project);
+    }
+    catch {
+        return null;
+    }
+    const unknown = referenced.filter((id) => !Object.hasOwn(project.config.connections, id));
+    if (unknown.length === 0) {
+        return null;
+    }
+    return {
+        message: `Wiki pages reference connection id(s) not in ktx.yaml: ${unknown.join(', ')}. Those pages still load and search.`,
+        fix: 'Add the connection(s) via `ktx setup`, or update the pages’ `connections` frontmatter.',
+    };
+}
 function buildWarnings(config, connections, llm, embeddings) {
     const warnings = [];
     for (const adapter of config.ingest.adapters) {
@@ -555,6 +579,21 @@ function tryQuery(run, fallback) {
         return fallback;
     }
 }
+function skippedObjectsFromReportBody(bodyJson) {
+    try {
+        const body = JSON.parse(bodyJson);
+        const skipped = body.fetch?.skipped;
+        if (!Array.isArray(skipped))
+            return [];
+        return skipped.map((issue) => ({
+            name: typeof issue.entityId === 'string' && issue.entityId.length > 0 ? issue.entityId : 'object',
+            reason: typeof issue.message === 'string' ? issue.message : 'introspection failed',
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 /** @internal */
 export async function buildLocalStatsStatus(project) {
     const dbPath = ktxLocalStateDbPath(project);
@@ -581,8 +620,10 @@ export async function buildLocalStatsStatus(project) {
         const totalCompletedRuns = tryQuery(() => db
             .prepare(`SELECT COUNT(*) AS n FROM local_ingest_reports WHERE status = 'done'`)
             .get()?.n ?? 0, 0);
-        const ingestRows = tryQuery(() => db
-            .prepare(`SELECT connection_id, adapter, MAX(completed_at) AS last_completed_at
+        const ingestRows = tryQuery(() => 
+        // SQLite returns body_json from the MAX(completed_at) row for each group.
+        db
+            .prepare(`SELECT connection_id, adapter, MAX(completed_at) AS last_completed_at, body_json
              FROM local_ingest_reports
              WHERE status = 'done'
              GROUP BY connection_id, adapter`)
@@ -595,6 +636,7 @@ export async function buildLocalStatsStatus(project) {
                     connectionId: row.connection_id,
                     adapter: row.adapter,
                     lastCompletedAt: row.last_completed_at,
+                    skippedObjects: skippedObjectsFromReportBody(row.body_json),
                 });
             }
         }
@@ -683,6 +725,10 @@ export async function buildProjectStatus(project, options = {}) {
     const queryHistory = await buildQueryHistoryStatus(project, options);
     const pipeline = buildPipelineStatus(config);
     const warnings = buildWarnings(config, connections, llm, embeddings);
+    const unknownConnectionWarning = await buildUnknownConnectionWarning(project);
+    if (unknownConnectionWarning) {
+        warnings.push(unknownConnectionWarning);
+    }
     const localStats = await buildLocalStatsStatus(project);
     const { verdict, reason, nextActions } = buildVerdict(llm, embeddings, connections, queryHistory, warnings);
     return {
@@ -796,6 +842,12 @@ function renderLocalStats(lines, stats, dim, bold) {
         const adapterWidth = Math.max(...ingest.perConnection.map((entry) => entry.adapter.length));
         for (const entry of ingest.perConnection) {
             lines.push(`      ${entry.connectionId.padEnd(nameWidth)}   ${dim(entry.adapter.padEnd(adapterWidth))}   ${dim(`last ${formatRelativeFromNow(entry.lastCompletedAt)}`)}`);
+            if (entry.skippedObjects.length > 0) {
+                const first = entry.skippedObjects[0];
+                const extra = entry.skippedObjects.length - 1;
+                const detail = `${first.name}: ${first.reason}${extra > 0 ? ` (+${extra} more)` : ''}`;
+                lines.push(`      ${' '.repeat(nameWidth)}   ${dim(`${entry.skippedObjects.length} object${entry.skippedObjects.length === 1 ? '' : 's'} skipped — ${detail}`)}`);
+            }
         }
     }
     if (stats.wikiPages.length === 0) {

package/dist/telemetry/events.d.ts

@@ -62,10 +62,10 @@ export declare const telemetryEventSchemas: {
         isCi: z.ZodBoolean;
         step: z.ZodEnum<{
             embeddings: "embeddings";
+            databases: "databases";
             project: "project";
             models: "models";
             sources: "sources";
-            databases: "databases";
             context: "context";
             runtime: "runtime";
             secrets: "secrets";
@@ -254,9 +254,9 @@ export declare const telemetryEventSchemas: {
         queryVerb: z.ZodEnum<{
             show: "show";
             with: "with";
+            explain: "explain";
             select: "select";
             other: "other";
-            explain: "explain";
         }>;
         referencedTableCount: z.ZodNumber;
         durationMs: z.ZodNumber;

package/dist/text-ingest.d.ts

@@ -2,6 +2,7 @@ import type { MemoryAgentInput } from './context/memory/types.js';
 import type { MemoryIngestStatus } from './context/memory/memory-runs.js';
 import { type KtxLocalProject } from './context/project/project.js';
 import type { KtxCliIo } from './cli-runtime.js';
+import { type VerbatimIngestorPort } from './verbatim-ingest.js';
 export interface KtxTextIngestArgs {
     projectDir: string;
     texts: string[];
@@ -10,6 +11,8 @@ export interface KtxTextIngestArgs {
     userId: string;
     json: boolean;
     failFast: boolean;
+    /** Code-driven verbatim ingest: store the document body unchanged, LLM derives metadata only. */
+    verbatim?: boolean;
 }
 /** @internal */
 export interface TextMemoryIngestPort {
@@ -24,6 +27,7 @@ export interface KtxTextIngestDeps {
         projectDir: string;
     }) => Promise<KtxLocalProject>;
     createMemoryIngest?: (project: KtxLocalProject) => TextMemoryIngestPort;
+    createVerbatimIngestor?: (project: KtxLocalProject) => VerbatimIngestorPort;
     readFile?: (path: string) => Promise<string>;
     readStdin?: () => Promise<string>;
     now?: () => number;