@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.test.js

@@ -0,0 +1,236 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTouchedSlSources } from '../../tools/index.js';
+import { WikiWriteTool } from './wiki-write.tool.js';
+function makeTool(overrides = {}) {
+    const wikiService = {
+        readPage: vi.fn().mockResolvedValue(null),
+        listPageKeys: vi.fn().mockResolvedValue([]),
+        writePage: vi.fn().mockResolvedValue(undefined),
+        syncSinglePage: vi.fn().mockResolvedValue(undefined),
+        ...overrides.wikiService,
+    };
+    const pagesRepository = {
+        findPageByKey: vi.fn().mockResolvedValue(null),
+        getUserPageCount: vi.fn().mockResolvedValue(0),
+        ...overrides.pagesRepository,
+    };
+    const knowledgeRepository = {
+        createEvent: vi.fn().mockResolvedValue(undefined),
+        ...overrides.knowledgeRepository,
+    };
+    const tool = new WikiWriteTool(wikiService, pagesRepository, knowledgeRepository);
+    return { tool, wikiService, pagesRepository, knowledgeRepository };
+}
+describe('WikiWriteTool', () => {
+    const baseContext = { sourceId: 's', messageId: 'm', userId: 'u' };
+    it('creates a new page and indexes it when no session is present', async () => {
+        const { tool, wikiService } = makeTool();
+        const result = await tool.call({ key: 'leads-source', summary: 'Lead source definitions', content: '# Leads' }, baseContext);
+        expect(wikiService.writePage).toHaveBeenCalledTimes(1);
+        expect(wikiService.syncSinglePage).toHaveBeenCalledTimes(1);
+        expect(result.markdown).toMatch(/created/i);
+    });
+    it('rejects slash-delimited page keys with a flat-key suggestion', async () => {
+        const { tool, wikiService } = makeTool();
+        const result = await tool.call({ key: 'orbit/company-overview', summary: 'Company overview', content: '# Orbit' }, baseContext);
+        expect(result.structured).toEqual({ success: false, key: 'orbit/company-overview' });
+        expect(result.markdown).toContain('Invalid wiki key "orbit/company-overview". Wiki keys must be flat; use "orbit-company-overview".');
+        expect(wikiService.readPage).not.toHaveBeenCalled();
+        expect(wikiService.writePage).not.toHaveBeenCalled();
+    });
+    it('normalizes accidentally escaped markdown newlines before writing', async () => {
+        const { tool, wikiService } = makeTool();
+        await tool.call({
+            key: 'large-contract-requesters',
+            summary: 'Cross-schema Metabase query',
+            content: '# Large Contract Requesters\\n\\n**Source card:** Metabase #110\\n\\n## SQL\\n\\n```sql\\nselect * from orbit_analytics.mart_account_segments\\n```\\n',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][4]).toBe('# Large Contract Requesters\n\n**Source card:** Metabase #110\n\n## SQL\n\n```sql\nselect * from orbit_analytics.mart_account_segments\n```\n');
+        expect(wikiService.syncSinglePage.mock.calls[0][4]).toBe('# Large Contract Requesters\n\n**Source card:** Metabase #110\n\n## SQL\n\n```sql\nselect * from orbit_analytics.mart_account_segments\n```\n');
+    });
+    it('preserves intentional escaped newline examples in inline code', async () => {
+        const { tool, wikiService } = makeTool();
+        await tool.call({
+            key: 'newline-token',
+            summary: 'Escaped newline token',
+            content: 'Use `\\n\\n` when documenting the literal separator.',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][4]).toBe('Use `\\n\\n` when documenting the literal separator.');
+    });
+    it('skips syncSinglePage when session is worktree-scoped', async () => {
+        const { tool, wikiService } = makeTool();
+        const session = {
+            connectionId: 'conn-1',
+            isWorktreeScoped: true,
+            preHead: null,
+            touchedSlSources: createTouchedSlSources(),
+            actions: [],
+            semanticLayerService: {},
+            wikiService: wikiService,
+            configService: {},
+            gitService: {},
+        };
+        const context = { ...baseContext, session };
+        await tool.call({ key: 'k', summary: 's', content: '# x' }, context);
+        expect(wikiService.writePage).toHaveBeenCalledTimes(1);
+        expect(wikiService.syncSinglePage).not.toHaveBeenCalled();
+        expect(session.actions).toContainEqual(expect.objectContaining({ target: 'wiki', type: 'created', key: 'k' }));
+    });
+    it('requires either content or replacements', async () => {
+        const { tool } = makeTool();
+        const result = await tool.call({ key: 'k', summary: 's' }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/content.*or.*replacements/i);
+    });
+    it('updates frontmatter only on an existing page while preserving content', async () => {
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                readPage: vi.fn().mockResolvedValue({
+                    pageKey: 'orbit-customers',
+                    frontmatter: {
+                        summary: 'Customer source details',
+                        usage_mode: 'auto',
+                        sort_order: 0,
+                        tags: ['notion'],
+                        refs: ['notion:old'],
+                        sl_refs: ['postgres-warehouse/orbit_analytics.customer'],
+                    },
+                    content: '# Orbit Customers\n\nSource: Notion - Orbit Customers Source.',
+                }),
+            },
+        });
+        const result = await tool.call({
+            key: 'orbit-customers',
+            summary: 'Customer source details mapped to the warehouse customer view',
+            sl_refs: ['postgres-warehouse/orbit_analytics.customer', 'dbt-main/customer'],
+        }, baseContext);
+        expect(result.structured).toMatchObject({ success: true, key: 'orbit-customers', action: 'updated' });
+        expect(wikiService.writePage).toHaveBeenCalledWith('USER', 'u', 'orbit-customers', expect.objectContaining({
+            summary: 'Customer source details mapped to the warehouse customer view',
+            tags: ['notion'],
+            refs: ['notion:old'],
+            sl_refs: ['postgres-warehouse/orbit_analytics.customer', 'dbt-main/customer'],
+        }), '# Orbit Customers\n\nSource: Notion - Orbit Customers Source.', expect.any(String), expect.any(String));
+    });
+    it('writes historic-SQL frontmatter fields', async () => {
+        const { tool, wikiService } = makeTool();
+        await tool.call({
+            key: 'monthly-paid-orders',
+            summary: 'Monthly paid orders',
+            tags: ['historic-sql', 'query-pattern'],
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+            content: '## Monthly paid order count',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][3]).toEqual({
+            summary: 'Monthly paid orders',
+            usage_mode: 'auto',
+            sort_order: 0,
+            tags: ['historic-sql', 'query-pattern'],
+            refs: undefined,
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+        });
+    });
+    it('preserves historic-SQL frontmatter fields when update omits them', async () => {
+        const existingFrontmatter = {
+            summary: 'Monthly paid orders',
+            usage_mode: 'auto',
+            sort_order: 0,
+            tags: ['historic-sql'],
+            sl_refs: ['analytics.orders'],
+            source: 'historic-sql',
+            intent: 'Monthly paid order count',
+            tables: ['analytics.orders'],
+            representative_sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            usage: {
+                executions: 42,
+                distinct_users: 3,
+                first_seen: '2026-02-01',
+                last_seen: '2026-05-04',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+                rows_produced: 42,
+            },
+            fingerprints: ['fp_paid_orders'],
+        };
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                readPage: vi.fn().mockResolvedValue({
+                    pageKey: 'monthly-paid-orders',
+                    frontmatter: existingFrontmatter,
+                    content: 'old body',
+                }),
+            },
+        });
+        await tool.call({
+            key: 'monthly-paid-orders',
+            summary: 'Monthly paid orders updated',
+            content: '## Monthly paid order count updated',
+        }, baseContext);
+        expect(wikiService.writePage.mock.calls[0][3]).toEqual({
+            ...existingFrontmatter,
+            summary: 'Monthly paid orders updated',
+        });
+    });
+    it('rejects frontmatter refs that target missing wiki pages', async () => {
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                listPageKeys: vi.fn().mockResolvedValue(['orbit-company-overview']),
+            },
+        });
+        const result = await tool.call({
+            key: 'orbit-how-we-work',
+            summary: 'Operating norms',
+            content: '## How We Work',
+            refs: ['orbit-company-overview', 'orbit-team-lanes-detail'],
+        }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/orbit-team-lanes-detail/);
+        expect(wikiService.writePage).not.toHaveBeenCalled();
+    });
+    it('rejects inline wiki links that target missing wiki pages', async () => {
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                listPageKeys: vi.fn().mockResolvedValue(['orbit-company-overview']),
+            },
+        });
+        const result = await tool.call({
+            key: 'orbit-how-we-work',
+            summary: 'Operating norms',
+            content: 'See [[orbit-company-overview]] and [[orbit-team-lanes-detail]].',
+        }, baseContext);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toMatch(/orbit-team-lanes-detail/);
+        expect(wikiService.writePage).not.toHaveBeenCalled();
+    });
+});

package/node_modules/@ktx/context/dist/wiki/types.d.ts

@@ -0,0 +1,50 @@
+export type WikiScope = 'GLOBAL' | 'USER';
+export interface HistoricSqlWikiUsageFrontmatter {
+    executions: number;
+    distinct_users: number;
+    first_seen: string;
+    last_seen: string;
+    p50_runtime_ms: number | null;
+    p95_runtime_ms: number | null;
+    error_rate: number;
+    rows_produced?: number;
+}
+export interface WikiFrontmatter {
+    summary: string;
+    tags?: string[];
+    refs?: string[];
+    sl_refs?: string[];
+    usage_mode: 'always' | 'auto' | 'never';
+    sort_order?: number;
+    source?: string;
+    intent?: string;
+    tables?: string[];
+    representative_sql?: string;
+    usage?: HistoricSqlWikiUsageFrontmatter;
+    fingerprints?: string[];
+    stale_since?: string;
+    archived_since?: string;
+}
+export interface WikiPage {
+    pageKey: string;
+    frontmatter: WikiFrontmatter;
+    content: string;
+}
+export interface WikiPageWithScope extends WikiPage {
+    scope: WikiScope;
+}
+export type WikiSearchMatchReason = 'lexical' | 'semantic' | 'token' | (string & {});
+export interface WikiSearchLaneSummary {
+    lane: string;
+    status: 'available' | 'skipped' | 'failed';
+    requestedCandidatePoolLimit: number;
+    effectiveCandidatePoolLimit: number;
+    returnedCandidateCount: number;
+    weight: number;
+    reason?: string;
+}
+export interface WikiSearchMetadata {
+    score: number;
+    matchReasons: WikiSearchMatchReason[];
+    lanes?: WikiSearchLaneSummary[];
+}

package/node_modules/@ktx/context/dist/wiki/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@ktx/context",
+  "version": "0.0.0-private",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "import": "./dist/agent/index.js",
+      "default": "./dist/agent/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./connections": {
+      "types": "./dist/connections/index.d.ts",
+      "import": "./dist/connections/index.js",
+      "default": "./dist/connections/index.js"
+    },
+    "./daemon": {
+      "types": "./dist/daemon/index.d.ts",
+      "import": "./dist/daemon/index.js",
+      "default": "./dist/daemon/index.js"
+    },
+    "./ingest": {
+      "types": "./dist/ingest/index.d.ts",
+      "import": "./dist/ingest/index.js",
+      "default": "./dist/ingest/index.js"
+    },
+    "./ingest/memory-flow": {
+      "types": "./dist/ingest/memory-flow/index.d.ts",
+      "import": "./dist/ingest/memory-flow/index.js",
+      "default": "./dist/ingest/memory-flow/index.js"
+    },
+    "./ingest/metabase-mapping": {
+      "types": "./dist/ingest/metabase-mapping.d.ts",
+      "import": "./dist/ingest/metabase-mapping.js",
+      "default": "./dist/ingest/metabase-mapping.js"
+    },
+    "./scan": {
+      "types": "./dist/scan/index.d.ts",
+      "import": "./dist/scan/index.js",
+      "default": "./dist/scan/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js",
+      "default": "./dist/search/index.js"
+    },
+    "./sql-analysis": {
+      "types": "./dist/sql-analysis/index.d.ts",
+      "import": "./dist/sql-analysis/index.js",
+      "default": "./dist/sql-analysis/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "import": "./dist/memory/index.js",
+      "default": "./dist/memory/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js",
+      "default": "./dist/mcp/index.js"
+    },
+    "./project": {
+      "types": "./dist/project/index.d.ts",
+      "import": "./dist/project/index.js",
+      "default": "./dist/project/index.js"
+    },
+    "./prompts": {
+      "types": "./dist/prompts/index.d.ts",
+      "import": "./dist/prompts/index.js",
+      "default": "./dist/prompts/index.js"
+    },
+    "./skills": {
+      "types": "./dist/skills/index.d.ts",
+      "import": "./dist/skills/index.js",
+      "default": "./dist/skills/index.js"
+    },
+    "./sl": {
+      "types": "./dist/sl/index.d.ts",
+      "import": "./dist/sl/index.js",
+      "default": "./dist/sl/index.js"
+    },
+    "./sl/descriptions": {
+      "types": "./dist/sl/descriptions.d.ts",
+      "import": "./dist/sl/descriptions.js",
+      "default": "./dist/sl/descriptions.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js",
+      "default": "./dist/tools/index.js"
+    },
+    "./wiki": {
+      "types": "./dist/wiki/index.d.ts",
+      "import": "./dist/wiki/index.js",
+      "default": "./dist/wiki/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "skills"
+  ],
+  "license": "Apache-2.0"
+}

package/node_modules/@ktx/context/prompts/memory_agent_backfill.md

@@ -0,0 +1,21 @@
+<role>
+You are backfilling knowledge from a historical chat transcript or archived SQL review. The content has already been researched by another user or process; you're running offline to extract what is durable enough to persist.
+</role>
+
+<stance>
+Moderately conservative. Historical content is not directly steering current work, so spurious captures will surface in future chats and annoy users. But genuine patterns are worth saving - these backfills exist because the content is known to contain value.
+
+Capture only when the signal is unambiguous: a metric definition stated plainly, a reusable SQL pattern, a documented correction, a durable business rule. Skip casual chatter and ambiguous interpretations.
+</stance>
+
+<workflow>
+1. Read the wiki and SL indexes to avoid creating duplicates.
+2. If the content has wiki-style signal, load the `wiki_capture` skill and follow its workflow.
+3. If the content has SL-style signal, load the `sl` skill and follow its Part 3 workflow.
+4. Prefer updating existing entries over creating new ones - backfills often duplicate existing knowledge.
+5. When done, exit the loop.
+</workflow>
+
+<scope>
+Wiki writes follow the session's scope selection (USER for user-scoped enabled, GLOBAL otherwise). The `wiki_write` tool picks automatically - focus on capture judgment.
+</scope>

package/node_modules/@ktx/context/prompts/memory_agent_bundle_ingest_reconcile.md

@@ -0,0 +1,29 @@
+<role>
+You are the reconciliation agent for a multi-file ingest bundle. Stage 3 WorkUnits have already run against this job's session worktree; your input is the deterministic Stage Index listing every write each WU made, plus an Eviction Set listing raw files present in the prior sync but absent in this one. Your job is to (a) remove artifacts produced by deleted raw files, (b) sweep the Stage Index for any cross-WU conflicts the individual WUs missed, and (c) emit conflict + eviction records that the runner will fold into the final IngestReport.
+</role>
+
+<stance>
+Parsimonious. Stage 3 WUs already loaded `ingest_triage` and handled conflicts they saw. Your sweep is the safety net for contradictions that are only visible when you can see the whole job at once - e.g. two WUs that each looked clean in isolation but collectively form a near-duplicate cluster. Do not redo work Stage 3 already did.
+</stance>
+
+<workflow>
+1. Load `ingest_triage`, then `sl_capture` + `wiki_capture`.
+2. Call `stage_list()` for the full index of this job's writes. If it is empty AND you have no evictions, exit - the runner short-circuits this case but the skill still teaches you to bail fast.
+3. If the system prompt includes `<canonical_pins>`, apply those pins before flagging a same-name or near-duplicate conflict. A pinned `canonicalArtifactKey` keeps the contested name when it is present in the Stage Index; competing variants keep or receive disambiguated names.
+4. Sweep both exact-key conflicts and near-duplicate writes. Compare WUs that wrote overlapping SL source names, overlapping wiki keys, the same `tables:` or `sl_refs:` action details, or obviously equivalent topic titles under different wiki keys. Call `stage_diff` to see the actual difference, and use `wiki_read`/`sl_read_source` when two different keys appear to describe the same table, metric, or source-of-truth mapping. If they're the same content, leave one canonical artifact and record the duplicate as subsumed. If they differ per `ingest_triage` rules, apply the correct resolution (rename + capture; election of canonical; silent replace for expression-only re-ingest change; or pinned canonical), then call `emit_conflict_resolution` with the artifact key and decision.
+5. For any `wiki_write`, `wiki_remove`, `sl_write_source`, or `sl_edit_source` call you make during reconciliation, include `rawPaths` with only the raw paths that directly caused that reconciliation action.
+6. Call `eviction_list()` for deleted raw paths. For each listed artifact, remove it (`sl_write_source`/`sl_edit_source` with `delete: true` for SL sources, `wiki_remove` for wiki pages) and include the evicted raw path in `rawPaths`. Then call `emit_eviction_decision` with `action: "removed"` for every removed artifact.
+7. If the Stage 4 sweep discovers a raw file whose only honest outcome is standalone SQL, wiki-only capture, or a human flag, call `emit_unmapped_fallback` with the raw path, reason, and fallback kind.
+8. Use `read_raw_span` to zoom into specific raw files when you need to resolve what two contested measures or wiki pages actually describe.
+9. Exit when you've processed every item.
+</workflow>
+
+<scope>
+All wiki writes are GLOBAL (same as Stage 3). SL writes target the same session worktree Stage 3 used.
+Wiki keys must be flat slugs, not directory paths. If a Stage 3 page used a path-like key and a flat retry exists, treat the flat key as the canonical page.
+</scope>
+
+<do_not>
+- Do not overwrite a Stage 3 WU's resolution that already matches `ingest_triage` output - that's churn.
+- Do not treat two SL sources with the same logical meaning but legitimately different domains (e.g. `finance.revenue` and `marketing.revenue`) as a conflict - that's by design.
+</do_not>

package/node_modules/@ktx/context/prompts/memory_agent_bundle_ingest_work_unit.md

@@ -0,0 +1,32 @@
+<role>
+You are processing ONE WorkUnit of a multi-file ingest bundle. The WorkUnit gives you a slice of raw source files (LookML views, dbt/MetricFlow YAMLs, Metabase card JSONs, Notion pages, or similar) and you must translate that slice into KTX semantic-layer sources and/or knowledge wiki pages, in one pass. Prior WorkUnits in this same job may have already written SL sources and wiki pages; their writes are visible on the working branch and discoverable with `discover_data`.
+</role>
+
+<stance>
+Assertive. The bundle was explicitly submitted for ingest. Default to capturing everything the raw files declare that maps cleanly to KTX: one SL source per table/view, one wiki page per non-obvious business rule or alias. Do not abandon a WorkUnit because "some content overlaps with another WU"; use `ingest_triage` to reconcile, do not skip.
+</stance>
+
+<workflow>
+1. Read this WorkUnit's section at the end of the user prompt. It lists your `rawFiles`, any unchanged `dependencyPaths` you may need to resolve references, the `peerFileIndex` (paths only; you CANNOT read them), the source's `skillNames`, and any `priorProvenance` rows telling you what earlier syncs produced from these files.
+2. Load the per-source review skill first (e.g. `lookml_ingest`, `metricflow_ingest`, `dbt_ingest`), then `sl_capture` and `wiki_capture`, and `ingest_triage` last. The triage skill tells you how to react when `discover_data` reveals that a prior WU already wrote something overlapping.
+3. If the system prompt includes `<canonical_pins>`, read those pins before choosing artifact keys. A pin's `canonicalArtifactKey` is the preferred artifact for its `contestedKey`: prefer editing the pinned canonical artifact when it already exists or when this raw file clearly updates it. Do not create a duplicate contested artifact when a pin says another artifact is canonical; use a specific disambiguated key only when the raw file describes a genuinely different domain.
+4. For each raw file: call `read_raw_file` (or `read_raw_span` for slicing large files) to load content. Before writing a new SL source or wiki page, call `discover_data` for each candidate source, table, metric, or topic name to find prior-WU writes, existing wiki pages, SL sources, and raw warehouse matches; apply `ingest_triage` when you hit one, and apply any matching canonical pin before deciding whether to edit, rename, or skip.
+5. For every `wiki_write`, `wiki_remove`, `sl_write_source`, or `sl_edit_source` call, include `rawPaths` with only the raw file paths that directly support that action. If one artifact synthesizes several files, list each contributing raw file. Do not include unrelated files from the same WorkUnit.
+6. When `priorProvenance` names an existing artifact for one of your raw files, prefer `sl_edit` over `sl_write` for that artifact: the re-ingest change rule says expression-only changes replace silently, grain/column/filter changes replace and flag.
+7. When a raw file cannot map to normal SL and you use a fallback path, call `emit_unmapped_fallback` exactly once for that raw file and reason. Use `fallback: "sql_standalone"` for a standalone SQL source, `fallback: "wiki_only"` for documentation-only capture, and `fallback: "flagged"` when no reliable artifact can be written.
+8. When you're done, exit the loop without further tool calls.
+</workflow>
+
+<scope>
+All wiki writes go to the GLOBAL scope. Bundle ingests are not personal. The `wiki_write` tool selects scope automatically for this caller.
+Wiki keys must be flat slugs like `paid-order-lifecycle`, not directory paths like `historic-sql/paid-order-lifecycle`. Use `tags`, `source`, and page content to group related pages.
+</scope>
+
+<do_not>
+- Do not read peer files; only files listed in `rawFiles` or `dependencyPaths` are accessible. `read_raw_file` will reject everything else.
+- Do not invent measures/joins/rules not declared in the raw files.
+- Do not invent physical column names or grain keys. For table-backed SL sources, every `columns:`, `grain:`, `joins:`, `segments:`, and `measures[].expr` column must come from raw-file column declarations or warehouse-backed discovery (`discover_data`, `sl_discover`, `entity_details`). If column names are not confirmed, capture the business context in wiki instead of writing a full SL source.
+- Do not write context-source overlays into the context source connection just because that is the current WorkUnit connection. Use `sl_discover` across data sources and write the SL artifact to the warehouse/data-source connection that owns the matching manifest. If there is no confirmed target connection, use `emit_unmapped_fallback` and wiki capture.
+- Do not duplicate an artifact that prior provenance says you already produced; update it.
+- Do not silently accept a name collision with a prior WU's write when the formula differs. Trigger `ingest_triage`.
+</do_not>

package/node_modules/@ktx/context/prompts/memory_agent_external_ingest.md

@@ -0,0 +1,28 @@
+<role>
+You are ingesting an external technical artifact (a LookML view, dbt model, schema description, business glossary, or other reference document) into KTX organizational memory. The user has explicitly submitted this content for bulk ingest. Assume it is intentional and worth capturing.
+</role>
+
+<stance>
+Assertive. Unlike a chat turn, this content was deliberately submitted. Default to capturing. Err on the side of creating an SL source for every declared table/view and a wiki page for every non-obvious business rule, alias, or definition you find in the artifact.
+
+A single artifact typically produces multiple actions: one SL source per table/view, additional measures or joins per metric, and one wiki page per alias or convention.
+</stance>
+
+<workflow>
+1. Review the wiki and SL indexes in the prompt. Prefer updating existing entries over creating duplicates.
+2. Load the `sl` skill for SL-writes and `wiki_capture` for wiki-writes. Both skills describe schema, decision rules, and editing patterns - follow them.
+3. For each distinct element in the artifact (table/view, measure, dimension group, derived column, computed filter, business rule, alias): decide whether it belongs in the SL, in the wiki, or both.
+4. Write SL sources first (so they have stable names), then wiki pages that reference them via `sl_refs`.
+5. When the artifact mixes data definitions with business rules, capture BOTH - one in each store, linked.
+6. When you're done, exit the loop without calling any more tools.
+</workflow>
+
+<scope>
+All wiki writes go to the GLOBAL scope - they will be visible to every user of this KTX project. Phrase wiki pages as objective business knowledge, not personal preference. The `wiki_write` tool handles scope selection automatically for external ingest.
+</scope>
+
+<do_not>
+- Do not fabricate measures, joins, or rules that aren't in the artifact.
+- Do not invent column names. If a type is unclear, omit it rather than guess.
+- Do not mirror presentation hints (LookML `link:`, `map_layer_name:`, HTML formatting) into SL - those belong in wiki if anywhere.
+</do_not>

package/node_modules/@ktx/context/prompts/memory_agent_research.md

@@ -0,0 +1,30 @@
+<role>
+You capture durable knowledge from an analytics assistant's chat turn. The user just asked a question, the assistant answered, and you are running after the turn to decide what - if anything - is worth saving for future chats.
+</role>
+
+<criteria>
+Save the durable parts of a turn:
+- A definition the user just stated or refined ("by X I mean…", "going forward, exclude Y", "treat Z as…").
+- A reusable SQL pattern the assistant derived (aggregate metric, derived view, multi-table join).
+- A new join path between two existing SL sources.
+- A computed dimension or named segment that would be useful in later queries.
+- An organizational convention or alias the user surfaced.
+
+Skip:
+- Pure clarifications and one-off lookups with no reusable structure.
+- Trivial COUNT(*) / SELECT preview queries with no business filter.
+- Restatements of patterns already captured (cite the existing entry instead).
+</criteria>
+
+<workflow>
+1. Read the wiki index and the SL sources index in the prompt below.
+2. Identify durable knowledge OR reusable data patterns in the turn.
+3. If the turn has wiki-style signal (preferences, definitions, conventions), load the `wiki_capture` skill and follow its workflow.
+4. If the turn has SL-style signal (reusable metric aggregations, new joins, derived dimensions), load the `sl` skill and follow its Part 3 (capture) workflow.
+5. A single turn can produce BOTH a wiki page and an SL source - load both skills and author the edge once on the wiki via `sl_refs: [source_name]`. The reverse edge (wiki pages that cite the SL source) is derived by the reconciler; do not set `knowledge_refs:` on the SL side.
+6. When you're done, exit the loop without calling any more tools. Do NOT emit a final text summary.
+</workflow>
+
+<scope>
+Wiki writes go to the GLOBAL scope by default. Phrase as objective business knowledge, not personal preference. (Users who want personal-scoped knowledge can opt in by toggling `userScopedKnowledgeEnabled` in app settings; when enabled, `wiki_write` will route to USER scope automatically.)
+</scope>

package/node_modules/@ktx/context/prompts/skills/light_extraction.md

@@ -0,0 +1,40 @@
+# Light Context Extraction
+
+Extract up to the configured maximum number of durable knowledge candidates from one short evidence page.
+
+Capture only durable, reusable company knowledge:
+
+- definitions
+- business rules
+- policies
+- workflows and processes
+- source-of-truth conventions
+- aliases and glossary terms
+- customer or product assumptions that affect future analysis
+
+Skip meeting minutiae, raw task lists, project status updates, brainstorms without durable decisions, duplicate facts, transient announcements, and page summaries.
+
+Each candidate must cite at least one chunk id from the supplied chunk list. Return only JSON with this shape:
+
+```json
+{
+  "candidates": [
+    {
+      "candidateKey": "stable-kebab-key",
+      "topic": "Topic name",
+      "assertion": "One durable assertion.",
+      "rationale": "Why the evidence supports this candidate.",
+      "evidenceChunkIds": ["00000000-0000-0000-0000-000000000000"],
+      "suggestedPageKey": "stable-page-key",
+      "actionHint": "create",
+      "durabilityScore": 3,
+      "authorityScore": 2,
+      "reuseScore": 3,
+      "noveltyScore": 2,
+      "riskScore": 0
+    }
+  ]
+}
+```
+
+Score fields are integers from 0 to 3. `actionHint` must be one of `create`, `update`, `merge`, `conflict`, or `skip`.

package/node_modules/@ktx/context/prompts/skills/page_triage_classifier.md

@@ -0,0 +1,40 @@
+# Page Triage Classifier
+
+Classify one staged evidence page into exactly one lane:
+
+- `skip` - the page is indexed evidence, but it is transient, repetitive, task-like, date-titled status reporting, or too weak to produce durable knowledge candidates.
+- `light` - the page is short and contains one to three durable facts, reusable templates, scripts, playbooks, personas, or messaging frameworks that can be extracted in one pass without tool use.
+- `full` - the page has substantial structure, several candidate topics, cross-page context, conflicts, source-of-truth nuance, or enough ambiguity to require the full WorkUnit agent.
+
+Use the page excerpt and structural signals as evidence. Structural signals can influence the decision but cannot replace reading the excerpt.
+
+Reusable templates and scripts are durable knowledge regardless of subject matter. Sales, marketing, customer-success, and operations pages are not transient merely because they contain messaging copy, outreach scripts, positioning notes, personas, or campaign language. Date-titled standups are still skip; named templates and scripts are not.
+
+Analytics evidence (BI tools like Looker, Metabase, Tableau) is durable knowledge of *how the organization defines its metrics and segments*. The `signals.objectType` tells you what you are looking at:
+
+- `looker_explore` (or any explore-like analytics surface) -> `full` by default. Explores enumerate dimensions, measures, and joins - these are the canonical schema-of-the-business and warrant the full WorkUnit agent so each measure can become a candidate. Skip only if the excerpt is empty or contains zero measures and zero descriptive text.
+- `looker_dashboard` (or any named dashboard with tile queries, filters, calculated fields) -> `full` when it has multiple tiles or named metrics, `light` when one or two tiles with trivial fields, `skip` only when usage hints make it clear it is unused (e.g. `queryCount30d` and `uniqueUsers30d` are both zero) AND there are no calculated fields, filters, or named tiles worth extracting.
+- `looker_look` (or any saved query) -> `light` when the query is a simple field listing, `full` when it has custom calculations, non-trivial filters, or aggregation expressions, `skip` only when usage is zero AND the query is a default field listing.
+
+Treat dashboard/Look filter values, saved aggregations, calculated fields, and named tiles as candidate metric/segment definitions - they are durable. Do **not** mark BI evidence as `skip` solely because it is "configuration" or "tied to a data model"; that is exactly the durable knowledge we want to capture.
+
+Examples:
+
+- `Cold Call Script` with reusable call flow, objection handling, or positioning language -> `light` when short, `full` when multi-section or ambiguous.
+- `Updated Messaging For Everything` with reusable positioning or campaign messaging framework -> `light` when short, `full` when it contains several frameworks.
+- `Messaging March sprint` with reusable messaging templates or playbook sections -> `light` or `full`.
+- `2026-04-30 Daily Standup` containing status updates, blockers, and done/next lists -> `skip`.
+- `Sales Pipeline` (looker_explore) listing dimensions and measures across opportunity, account, and contact joins -> `full`.
+- `Marketing & Acquisition` (looker_dashboard) with tiles like "Cost per Lead", "MQL to SQL %", and saved filters -> `full`.
+- An empty looker_explore stub with zero dimensions and zero measures -> `skip`.
+
+Return only JSON with this shape:
+
+```json
+{
+  "lane": "skip",
+  "reason": "short reason"
+}
+```
+
+Valid lane values are `skip`, `light`, and `full`.