@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,134 @@
+{
+  "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"
+  ],
+  "dependencies": {
+    "@looker/sdk": "^26.6.1",
+    "@looker/sdk-node": "^26.6.1",
+    "@looker/sdk-rtl": "^21.6.5",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@notionhq/client": "^5.20.0",
+    "ai": "^6.0.168",
+    "better-sqlite3": "^12.6.2",
+    "handlebars": "^4.7.8",
+    "lookml-parser": "7.1.0",
+    "minimatch": "^10.2.4",
+    "p-limit": "^7.3.0",
+    "pg": "^8.19.0",
+    "simple-git": "3.32.2",
+    "yaml": "^2.8.2",
+    "zod": "^4.1.13"
+  },
+  "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 `knowledge_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,27 @@
+<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) decide what happens to each evicted artifact (remove vs retain with a deprecation marker), (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` + `knowledge_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. For each pair of WUs that wrote overlapping SL source names or wiki keys, call `stage_diff` to see the actual difference. If they're the same content, leave it. 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. Call `eviction_list()` for deleted raw paths. For each eviction: if inbound refs are empty, remove the artifact (`sl_delete`, `wiki_remove`); if inbound refs exist, retain with a deprecation marker. Then call `emit_eviction_decision` for every removed or retained artifact.
+6. 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.
+7. Use `read_raw_span` to zoom into specific raw files when you need to resolve what two contested measures actually compute.
+8. 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.
+</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,28 @@
+<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, 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 searchable via `wiki_sl_search`.
+</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 `knowledge_capture`, and `ingest_triage` last. The triage skill tells you how to react when `wiki_sl_search` 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 `wiki_sl_search` for each candidate name to find prior-WU writes; apply `ingest_triage` when you hit one, and apply any matching canonical pin before deciding whether to edit, rename, or skip.
+5. 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.
+6. 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.
+7. 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.
+</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 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 `knowledge_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 `knowledge_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,102 @@
+# 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.
+
+Historic SQL query-history evidence is durable when usage signals show a repeated pattern worth memory work. For `signals.objectType === "historic_sql_template"`:
+
+- If `propertyHints.executions_bucket=low AND distinct_users_bucket=solo`, return `skip`. A one-off query by one user is indexed evidence, but it is too weak to produce durable knowledge candidates.
+- Else if `propertyHints.service_account_only=true AND below the frequency floor`, return `light`. Treat `executions_bucket=low` or `distinct_users_bucket=solo` as below the frequency floor for this rule. Service-account-only templates can preserve useful SQL evidence, but should not occupy a full WorkUnit unless other signals show shared human usage.
+- Otherwise apply the standard full/light/skip logic to the page excerpt. Favor `full` for shared human usage with mid or high execution volume, especially when `tables_touched`, normalized SQL, and slot classifications define a reusable metric, segment, threshold, or operational query pattern.
+
+Historic-SQL synthetic signal examples:
+
+- skip low solo template:
+
+```json
+{
+  "objectType": "historic_sql_template",
+  "propertyHints": {
+    "executions_bucket": "low",
+    "distinct_users_bucket": "solo",
+    "error_rate_bucket": "ok",
+    "recency_bucket": "active",
+    "service_account_only": "false",
+    "slot_summary": "1 constant, 1 runtime"
+  }
+}
+```
+
+-> `skip`
+
+- light service-account-only template:
+
+```json
+{
+  "objectType": "historic_sql_template",
+  "propertyHints": {
+    "executions_bucket": "high",
+    "distinct_users_bucket": "solo",
+    "error_rate_bucket": "ok",
+    "recency_bucket": "active",
+    "service_account_only": "true",
+    "slot_summary": "1 constant, 0 runtime"
+  }
+}
+```
+
+-> `light`
+
+- full shared human template:
+
+```json
+{
+  "objectType": "historic_sql_template",
+  "propertyHints": {
+    "executions_bucket": "high",
+    "distinct_users_bucket": "team",
+    "error_rate_bucket": "ok",
+    "recency_bucket": "active",
+    "service_account_only": "false",
+    "slot_summary": "2 constant, 1 runtime"
+  }
+}
+```
+
+-> `full`
+
+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`.

package/node_modules/@ktx/context/skills/dbt_ingest/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: dbt_ingest
+description: Map dbt `schema.yml` / `properties.yml` models and sources into KTX semantic-layer overlays and column notes. Covers `sources:` vs `models:`, column `data_tests` (not_null, unique, accepted_values, relationships), and how bundle-time writes complement manifest backfill from git sync. Load when the WorkUnit's `skillNames` includes `dbt_ingest` or when raw files are dbt YAML under `models/` / `sources/`.
+callers: [memory_agent]
+---
+
+# dbt → KTX (bundle ingest)
+
+Use this skill for **uploaded** dbt projects (`dbt_project.yml` at stage root, `models/**`, `sources/**`, `schema.yml`). There is **no** `fetch()` in v1 — scheduled `dbt parse` / `manifest.json` pulls are out of scope; host-provided dbt sync may still backfill structured test metadata into `_schema` on the next sync.
+
+## Mapping (models / sources → SL)
+
+| dbt | KTX | Notes |
+|-----|--------|--------|
+| `models:` entry with `columns:` | **Overlay** on the manifest table with the same name (after `wiki_sl_search` / `sl_describe_table`) | One SL source per physical table; model name may differ from DB name — resolve with `read_raw_file` + warehouse context. |
+| `sources:` → `tables:` | Same as models; use `identifier` when present instead of logical `name`. | Schema + name must match how the connection sees tables. |
+| Column `description` | `descriptions.user` or merged `descriptions` map on the column | Do not overwrite `dbt` description keys from sync. |
+| `data_tests: not_null` / `unique` | Short hint in column `descriptions` or notes: “dbt: not null”, “dbt: unique” | Full structured metadata lands in manifest via **sync**; the skill keeps bundle-time SL text useful for the agent. |
+| `accepted_values` | Add a **brief** line in the column description: allowed values (truncate long lists) | Also mention enum-like use in `wiki_sl_search` / filters. |
+| `relationships` | Add or confirm `joins:` on the overlay **only** when `to` resolves to a real table via `read_raw_file` + `wiki_sl_search` / `sl_describe_table` | If the ref cannot be resolved, capture the intent in a wiki page instead. |
+
+## 1.1 test hints (descriptions / meta)
+
+When YAML shows `accepted_values` or `not_null`, add **short** hints into `columns[].descriptions` (e.g. under `user`) or freeform column notes so chat and validation see intent before the next git sync refreshes `constraints` / `enum_values` in `_schema`. Keep hints under a few words when possible.
+
+## Overlap with MetricFlow
+
+If the same bundle also has MetricFlow `semantic_models:` / `metrics:`, the **`metricflow_ingest`** skill owns semantic/metric shapes. This skill focuses on **raw dbt schema** YAML (`models`, `sources`, tests). If both apply, load `metricflow_ingest` first when the file is clearly MetricFlow; otherwise use `dbt_ingest` for `schema.yml` without semantic_models.
+
+## Do not
+
+- Do not run `dbt` CLI or assume `target/` / `manifest.json` exists in the upload.
+- Do not invent joins from `relationships` tests if the target model/table is not found in SL or the warehouse.
+- Do not read `peerFileIndex` paths — use `read_raw_file` only on `rawFiles` and `dependencyPaths` from the WorkUnit.

package/node_modules/@ktx/context/skills/historic_sql_curator/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: historic_sql_curator
+description: Reconcile historic-SQL query knowledge pages by deduping collapsed intents, cross-linking categorical sub-clusters, and demoting stale low-signal pages.
+callers: [memory_agent]
+---
+
+# Historic SQL Curator
+
+Use this skill during Stage 4 reconciliation for the `historic-sql` source. It runs after `historic_sql_ingest` has written query knowledge pages from full-tier template WorkUnits. The Stage 4 runner may use curator pagination, so treat the current prompt as one bounded page of work and finish every listed item you inspect.
+
+## Input Shape
+
+The reconciliation prompt normally exposes:
+
+- `# Stage Index` with WorkUnit keys, raw paths, and wiki or SL actions from Stage 3.
+- `# Eviction Set` with deleted raw paths from retired templates.
+- `# Curator Pass State` when curator pagination splits reconciliation into multiple passes.
+- `# Source Reconciliation Notes` with run-level notes such as staged template count.
+
+Use tools instead of guessing:
+
+- `stage_list` shows every WorkUnit raw path and action.
+- `stage_diff` compares two WorkUnits by written artifact overlap.
+- `read_raw_span` reads staged `metadata.json`, `page.md`, `usage.json`, and `manifest.json` snippets when page content is not enough.
+- `wiki_search`, `wiki_read`, and `wiki_write` inspect and update query knowledge pages.
+- `emit_artifact_resolution` records merged or subsumed wiki pages for provenance.
+- `eviction_list` and `emit_eviction_decision` handle deleted raw paths.
+
+## Required Workflow
+
+1. Read the `# Stage Index`, `# Eviction Set`, `# Curator Pass State`, and `# Source Reconciliation Notes` sections first.
+2. Call `stage_list` when the prompt omits raw paths or when more than one WorkUnit wrote a `queries/...` page.
+3. For each successful historic-SQL WorkUnit that wrote a wiki page, call `wiki_read` on that page before deciding whether to merge, cross-link, or demote it.
+4. If the page body does not show fingerprint, sub-cluster, tables, or usage clearly enough, call `read_raw_span` on that WorkUnit's `metadata.json` and `usage.json` raw paths.
+5. Build intent clusters using table overlap, representative SQL shape, page summaries, fingerprints, sub-cluster IDs, and usage. Same table is not enough to merge; the business intent must collapse.
+6. Deduplicate collapsed intents by electing one canonical page, merging useful variant details into it with `wiki_write`, and recording each merged loser with `emit_artifact_resolution`.
+7. Cross-link categorical sub-cluster pages that share the same base fingerprint but differ by `__cat_...` sub-cluster ID.
+8. Demote pages whose underlying cluster has decayed below the floor in the most recent 3 windows, or in the current window plus eviction evidence showing the template retired.
+9. For every deleted raw path in the Eviction Set that you inspect, call `eviction_list` and then `emit_eviction_decision`.
+
+## Canonical Page Election
+
+When two or more pages describe the same query intent, choose the canonical page with this order:
+
+1. The clearest human-readable intent summary.
+2. The page with broader non-service-account usage.
+3. The page covering more fingerprints or categorical variants of the same intent.
+4. The page with the most recent successful usage.
+5. Lexicographically first page key.
+
+After electing the canonical page:
+
+- Read every page that will be merged.
+- Update the canonical page so it contains one "Historic SQL Variants" section with fingerprints, sub-cluster IDs, tables, usage summaries, and links to sibling page keys when retained.
+- Keep `tags` including `historic-sql` and `query-pattern`.
+- Preserve useful `sl_refs`; when replacing refs, include the union of cleanly matched SL refs from merged pages.
+- For each merged loser, call `emit_artifact_resolution` with:
+
+```json
+{
+  "rawPath": "<loser WorkUnit metadata.json or page.md raw path>",
+  "artifactKind": "wiki",
+  "artifactKey": "<loser wiki page key>",
+  "actionType": "merged",
+  "reason": "Historic-SQL query intent collapsed into <canonical wiki page key>."
+}
+```
+
+Use `actionType: "subsumed"` only when the loser page is a thin duplicate with no unique facts worth retaining in the canonical body.
+
+## Categorical Sub-Cluster Cross-Links
+
+A categorical sub-cluster normally has a staged ID like `<fingerprint>__cat_<hash>` or page content that says `Sub-cluster: <value>`. For sibling pages that share the same base fingerprint:
+
+1. Read all sibling pages visible in the current Stage Index or found through `wiki_search`.
+2. Keep one page per meaningful category value.
+3. Add or update a "Categorical Variants" section in each sibling page:
+
+```markdown
+### Categorical Variants
+- `<category value>`: [[queries/<sibling_key>]] - <short intent or parameter note>
+```
+
+4. Use `wiki_write` with `refs` containing the sibling page keys so cross-links also live in frontmatter.
+5. Do not merge categorical siblings only because they share a fingerprint. Merge them only when the category value no longer changes intent.
+
+## Demotion
+
+Demotion preserves history; it is not deletion. A page is demoted when evidence shows its underlying cluster has fallen below the historic-SQL floor:
+
+- `executions < 3`, or
+- `distinct_users < 2`, or
+- service-account-only usage below the frequency floor, or
+- the template was evicted and no active sibling or replacement page supports the same intent.
+
+Require the low-signal state across the most recent 3 windows when page history is available. If only the current window is visible, demote only when eviction evidence confirms the raw template retired; otherwise add a caveat and leave the page active.
+
+Use `wiki_write` to express demotion with the current wiki frontmatter fields:
+
+- Add the `historic-sql-demoted` tag while preserving `historic-sql` and `query-pattern`.
+- Prefix the summary with `Demoted historic-SQL pattern: ` unless it already begins with that phrase.
+- Add a `### Demotion` section in the body with the last observed usage window, the floor that failed, and the raw path or fingerprint that supports the decision.
+
+When demoting because of an eviction, also call `emit_eviction_decision`:
+
+```json
+{
+  "rawPath": "<deleted raw path>",
+  "artifactKind": "wiki",
+  "artifactKey": "<wiki page key>",
+  "action": "retained_deprecated",
+  "reason": "Historic-SQL template retired or decayed below the floor; page retained with historic-sql-demoted frontmatter tag."
+}
+```
+
+## What To Write
+
+Use `wiki_write` for every page update. The tool supports `summary`, `content`, `tags`, `refs`, and `sl_refs` frontmatter fields.
+
+Canonical pages should keep this body shape:
+
+```markdown
+## <Canonical Query Intent>
+- Source: historic-sql
+- Tables: <tables>
+- Fingerprints: <fingerprints and sub-clusters>
+- Usage: <executions>, <distinct users>, first seen <date>, last seen <date>
+
+### Representative SQL
+```sql
+<representative SQL or parameterized SQL>
+```
+
+### Historic SQL Variants
+- `<fingerprint or sub-cluster>`: <what differs and when to use it>
+
+### Categorical Variants
+- `<category value>`: [[queries/<sibling_key>]] - <short intent or parameter note>
+
+### Demotion
+- Omit this section unless the page is demoted.
+```
+
+## Boundaries
+
+- Do not call `context_candidate_write`; historic-SQL Stage 3 writes query pages directly.
+- Do not create new artifact types, stores, ports, or tables.
+- Do not group low-tier templates that triage already filtered out.
+- Do not merge pages on table overlap alone.
+- Do not delete a query page solely because usage is low; demote it unless eviction rules and inbound-reference evidence make removal clearly safer.
+- Do not copy unredacted sample `bound_sql`, user emails, account IDs, tokens, or free-text literal values into wiki or SL output.
+- Do not edit SL unless the reconciliation prompt shows a concrete same-intent conflict or duplicate that requires an existing SL artifact resolution.
+- Do not finish a curator pagination pass while a merged page, demoted page, or inspected eviction lacks the corresponding provenance call.