@kaelio/ktx 0.0.0 → 0.1.0-rc.1

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

@@ -0,0 +1,346 @@
+---
+name: sl_capture
+description: How to capture new reusable patterns into KTX's semantic layer - when a measure, segment, or join belongs in the catalog and how to write it generically so it stays small and useful over time. Loaded by the post-turn memory-agent only. The research agent does not write to the SL.
+callers: [memory_agent]
+---
+
+# Semantic Layer - Capture
+
+This skill covers **when** and **how** to capture new patterns into the semantic layer. For schema reference and query grammar, load the `sl` skill first.
+
+When the current turn produces a reusable pattern (business metric, derived view, join pattern, computed dimension), capture it so future queries can reach for it instead of rediscovering it.
+
+## SQL dialect
+
+The user-facing prompt includes a `Warehouse:` line under the SL Sources index
+(e.g. `Warehouse: BIGQUERY`). All `expr` strings - measure expressions, segment
+predicates, computed-column SQL - execute on that warehouse and must use its
+syntax. Date arithmetic in particular varies by dialect:
+
+- **BigQuery**: `transaction_date >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 90 DAY)` (when the column is `TIMESTAMP`); `event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)` (when `DATE`).
+- **Postgres / Redshift**: `transaction_date >= current_date - interval '90 days'`.
+- **Snowflake**: `transaction_date >= dateadd(day, -90, current_timestamp())`.
+
+Match the column's manifest type (`type: time` → TIMESTAMP/DATETIME on the
+warehouse) - comparing TIMESTAMP to a DATE-arithmetic result fails on
+BigQuery. After every `sl_edit_source`/`sl_write_source`, the inline validator runs a
+`LIMIT 1` warehouse probe per measure and surfaces dialect mismatches; if
+you see an error trailer, fix the expression and retry rather than leaving
+the source for the post-squash gate to revert.
+
+## What's worth capturing
+
+- Business metric aggregations (ARR, MRR, revenue, churn, retention, conversion, LTV, CAC).
+- Derived calculations combining multiple signals (risk scores, health scores, composite KPIs).
+- Multi-table join patterns producing a reusable analytical view.
+- Computed categories or flags useful as reusable dimensions (`case when num_protocols >= 3 then 'power' else 'regular' end`).
+- Missing joins between two sources that both exist but aren't connected in the join graph.
+
+Skip:
+- Simple `SELECT * LIMIT 10` previews.
+- Trivial `COUNT(*)` on one table with no business filtering.
+- One-off ad-hoc explorations unlikely to repeat.
+- Equivalent measures that already exist (cite the existing one as `source.measure_name`).
+
+When in doubt, capture. Measures are easy to remove but impossible to recover from a lost conversation.
+
+## Generalization rules
+
+The SL must stay small and general over time. Before adding a measure, decide whether it belongs as a generic pattern or a specific constant.
+
+**Prefer one generic measure with query-time filters over N hardcoded variants.**
+
+Anti-pattern:
+```yaml
+- name: revenue_us_region
+  expr: sum(case when region = 'US' then amount end)
+- name: revenue_eu_region
+  expr: sum(case when region = 'EU' then amount end)
+```
+
+Preferred:
+```yaml
+- name: total_revenue
+  expr: sum(amount)
+```
+Callers filter `region = 'US'` at query time.
+
+**Bake constants in only when the filter has named business meaning that won't change** (`enterprise_arr` for a contractually defined tier), cannot be expressed via the source's dimensions, or comes from a regulated/fixed list.
+
+**Time anchors and value lists belong in callers' filters, not in measure expressions or source SQL.**
+- Anti-pattern (date anchor inlined): `expr: count(distinct case when transaction_date >= '2026-04-12' then customer_id end)` - the date will need editing every time the question shifts, and every reader has to discover it.
+- Anti-pattern (value list inlined in source SQL): `WHERE product_category_1 IN ('Testosterone', 'Weight Loss', …)` - locks the source to today's catalog and blocks callers from broadening or narrowing.
+- Preferred: a generic measure (`count(distinct customer_id)`) plus either a named segment that captures the *meaning* of the anchor (`gh_new_products_since_launch`) or a query-time filter. Callers compose; the source stays small.
+- A date is durable to bake in only when it represents a regulatory cutover, a contractually fixed boundary, or a one-time event that reshapes how the source itself is read.
+
+**If you create a segment whose expr matches a measure's filter, the measure MUST reference the segment via `segments: [segment_name]` rather than re-inlining the predicate.** This is the canonical pattern even with a single measure - duplicating the predicate inline defeats the purpose of naming it.
+
+Anti-pattern:
+```yaml
+segments:
+  - name: engaged_subscriber
+    expr: "is_paid = true AND <date-window-90-days-on-transaction_date>"
+measures:
+  - name: engaged_subscriber_count
+    expr: "count(distinct case when is_paid = true and transaction_date >= current_date - interval '90 day' then admin_user_id end)"
+```
+
+Preferred:
+```yaml
+segments:
+  - name: engaged_subscriber
+    expr: "is_paid = true AND <date-window-90-days-on-transaction_date>"
+measures:
+  - name: engaged_subscriber_count
+    expr: "count(distinct admin_user_id)"
+    segments: [engaged_subscriber]
+```
+
+**Use computed dimensions for derived categories.** A flag like `is_power_user` belongs on `columns[]` with `expr`, not inlined into every measure.
+
+**Extract repeated filter bundles into named segments.** If the same predicate appears on multiple measures of the same source, lift it to a `segments[]` entry and have each measure reference it. One edit updates every measure that depends on it.
+
+**Never write a standalone file on a manifest-backed name.** If `sl_discover({ query: "<table-or-source-name>" })` finds an existing schema for that name, you MUST write an overlay. A standalone with `sql:` or `table:` on a manifest-backed name clobbers the inherited columns and joins; `sl_write_source` and `sl_validate` both reject this shape with a clear fix hint. Always run `sl_discover` before your first write on any existing name.
+
+Overlay before/after examples:
+
+```yaml
+# Wrong: patches an inherited manifest column through columns:
+name: fct_orders
+columns:
+  - name: status
+    descriptions:
+      user: "Order lifecycle status."
+```
+
+```yaml
+# Right: patch inherited columns with column_overrides:
+name: fct_orders
+column_overrides:
+  - name: status
+    descriptions:
+      user: "Order lifecycle status."
+columns:
+  - name: is_large_order
+    type: boolean
+    expr: "amount > 1000"
+```
+
+Overlay YAML may include `measures:`, `segments:`, `descriptions:`, `joins:`, `disable_joins:`, `exclude_columns:`, `column_overrides:`, and computed-only `columns:` entries with `expr` and `type`. Do not include `sql:`, `table:`, `grain:`, or base-table `columns:`.
+
+**Prefer overlay decomposition over standalone SQL sources.** Before reaching for `source_type: sql`, check whether the metric decomposes into measures on existing overlays (including cross-source derived measures). Use `source_type: sql` only when:
+- The metric requires per-user/per-entity derivation that cannot be expressed as a single `expr` (e.g., `EXISTS` over a time-windowed subset), OR
+- The metric requires multi-step CTEs whose intermediate grain is not a column in any existing source.
+
+When an `sql` source is unavoidable, note in its `descriptions` map which SL gap forced the choice so it can be retired once the primitive ships. It must target a name NOT in the manifest - pick a distinct one (e.g. `mrr_waterfall_rollup`, not `fct_orders`).
+
+## Slim standalone sources via `inherits_columns_from`
+
+When a standalone SQL source filters or projects from a single manifest-backed base table (the common pattern for derived views like `aav_consignments` over `MARTS.CONSIGNMENTS`), set `inherits_columns_from:` to the base table's manifest key and list only column **names** in `columns:`. Compose-time enrichment fills `type`, `descriptions`, and `role` from the matching manifest column.
+
+Discover the manifest key with `sl_discover` - pass the bare name (`CONSIGNMENTS`), the fully-qualified path (`ANALYTICS.MARTS.CONSIGNMENTS`), or any suffix; the tool resolves all forms and prints the canonical key in its output.
+
+```yaml
+name: aav_consignments
+descriptions:
+  user: AAV consignments - filtered view of MARTS.CONSIGNMENTS for the auto-auction-vaulting channel.
+source_type: sql
+sql: |
+  SELECT CONSIGNED_ITEM_ID, CASH_ADV_AMOUNT, ALT_VALUE_COMBINED, my_derived_flag
+  FROM MARTS.CONSIGNMENTS
+  WHERE IS_AUTO_AUCTION_VAULTING_SUBMISSION = TRUE
+    AND IS_CARD_SHOW_SUBMISSION = FALSE
+    AND CONSIGNMENT_CANCELED_FLAG = FALSE
+inherits_columns_from: CONSIGNMENTS
+grain: [CONSIGNED_ITEM_ID]
+columns:
+  - { name: CONSIGNED_ITEM_ID }      # type/descriptions inherited from manifest
+  - { name: CASH_ADV_AMOUNT }
+  - { name: ALT_VALUE_COMBINED }
+  - { name: my_derived_flag, type: boolean, expr: "CASH_ADV_AMOUNT > 0", descriptions: { user: "Computed locally - has any cash advance." } }
+measures:
+  - name: total_cash_advance
+    expr: sum(CASH_ADV_AMOUNT)
+```
+
+Rules:
+
+- Inheritance fills only **blank** fields. If you set a `description` locally, it wins - useful when the base description is misleading in the filtered view.
+- A column not in the manifest (a derived/aliased column, or one from a different table in a `JOIN`) needs its own `type` and `description` declared.
+- If `inherits_columns_from` doesn't resolve, the source still loads, but every column without a type triggers a validator error on the warehouse probe - `sl_discover` first to confirm the key.
+- Don't use `inherits_columns_from` for sources backed by `table:` (those should be overlays - see the rule against shadowing the manifest above).
+
+## Refinement - replace, don't append
+
+When the user corrects a prior answer, the existing measure is wrong by the user's own standard. Replace it, don't add a parallel measure.
+
+Signals that the current turn is a refinement:
+- "no, I meant...", "actually use X", "exclude Y", "wait, by X I mean Z".
+- Pushback on a prior result ("that's wrong because...", "this should be higher").
+- Redefinition of a term used in an existing measure.
+
+Distinguishing question: *would the prior measure still be correct for someone else asking the prior question?* If no → replace. If yes → add.
+
+## Edit SL vs document in wiki
+
+If the user explicitly names an SL artifact and asks to change it, the primary
+action is always an SL tool call. Examples:
+
+- "edit the source", "edit the YAML", "edit `fct_intakes.yaml`" → `sl_edit_source` or
+  `sl_write_source`.
+- "refine the measure", "change the filter on `active_users`", "fix the expr",
+  "add `is_test = false`" → `sl_edit_source` on the source that owns the measure.
+- "don't create a new one, update the existing" → `sl_edit_source` (never `sl_write_source`
+  with a new source name; never `wiki_write` as the only action).
+
+A wiki update may ALSO make sense in the same turn (owner note, lineage,
+caveat), but it is never a substitute for editing the YAML when the user's
+request is about changing the measure/source definition itself.
+
+Wiki-only is correct when the user is documenting *about* the measure
+(definition in business terms, owner, policy, glossary, examples of when to
+use it) without changing its SQL expression or filters.
+
+Before sl_write_source, call entity_details on the target table to confirm
+column names and types match the YAML being written.
+
+## 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.
+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.
+
+## Tool sequence
+
+1. `sl_discover` - see what source files exist.
+2. `sl_discover({ query: "<table-or-source-name>" })` - **REQUIRED before the first write on any name**. Shows columns/joins/grain from the manifest. If the call returns a schema, you MUST write an overlay, not a standalone. Skipping this is the #1 cause of accidentally shadowing the manifest.
+3. `sl_read_source({ connectionId, sourceName })` - read the raw YAML before editing.
+4. For modifications: `sl_edit_source({ connectionId, sourceName, yaml_edits: [{ oldText, newText, reason }] })` with exact-string replacements. `oldText` must match exactly and be unique in the file.
+5. For new sources or full rewrites: `sl_write_source({ connectionId, sourceName, source })` with the full structured source definition.
+6. For join discovery: use `sql_execution({connectionId: "warehouse", sql: "SELECT count(*) FROM public.orders o JOIN public.customers c ON c.id = o.customer_id LIMIT 20"})` with the target warehouse connection id and dialect-correct table names to verify the join key exists in both tables and assess cardinality before declaring the join.
+7. Cross-reference knowledge: author the edge once on the **wiki** side via `sl_refs: [source_name]` in the page's front-matter. The reverse edge (wiki pages that cite an SL source) is derived automatically by the reconciler - do not add a `knowledge_refs:` field to SL YAMLs.
+8. `sl_validate` - run after writing or editing to surface schema issues, duplicate measure names, and cross-source validation errors. Read-only; the writes are already committed (the squash-at-end flow will collapse them into one commit).
+
+## Editing patterns
+
+- **`sl_edit_source`** is the workhorse for additive changes: add a measure, add a join, tweak a description, replace a filter. Cheap, targeted, preserves the rest of the file.
+- **`sl_write_source`** is for brand-new sources or when the entire file needs restructuring. It overwrites the file completely.
+- Do NOT modify existing measures or their descriptions unless the current turn explicitly corrects them.
+- During bundle/external ingest, include `rawPaths` on every `sl_write_source`/`sl_edit_source` call with only the raw files that directly support the SL action.
+
+## Worked example - additive overlay
+
+Conversation:
+- User: "What was the average order value last quarter?"
+- Assistant fell back to SQL: `SELECT AVG(amount) FROM orders WHERE order_date >= ...`
+
+Existing index: `orders [measures=0, joins=0] - candidate for enrichment`.
+
+```
+sl_discover()
+  → orders.yaml does not exist yet
+sl_discover({ query: "orders" })
+  → see grain, columns, no current overlay
+sl_write_source({
+  connectionId: "warehouse",
+  sourceName: "orders",
+  source: {
+    name: "orders",
+    measures: [{
+      name: "avg_order_value",
+      expr: "avg(amount)",
+      description: "Mean order transaction amount - filter by product_category at query time"
+    }]
+  }
+})
+sl_validate({ connectionId: "warehouse" })
+  → clean
+```
+
+The overlay only contains `name` and `measures` - no columns, grain, or table. Those are inherited from the manifest.
+
+## Worked example - refinement (replace)
+
+Prior turn:
+- [user] "How many active users do we have per region?"
+- [assistant] "… used `count(*) filter: last_login_at > now() - interval '30 days'`"
+
+Current user: "Wait, by 'active' I mean users who have placed an order in the last 30 days, not just logged in."
+
+The existing `users.active_count` measure is wrong by the new definition.
+
+```
+sl_read_source({ connectionId: "warehouse", sourceName: "users" })
+  → see the wrong measure
+sl_edit_source({
+  connectionId: "warehouse",
+  sourceName: "users",
+  yaml_edits: [{
+    oldText: "  - name: active_count\n    expr: \"count(*)\"\n    filter: \"last_login_at > now() - interval '30 days'\"\n    description: Users who logged in within the last 30 days",
+    newText: "  - name: active_count\n    expr: \"count(distinct case when last_order_at > now() - interval '30 days' then user_id end)\"\n    description: Users with at least one order in the last 30 days"
+  }]
+})
+sl_validate({ connectionId: "warehouse" })
+```
+
+If you only added a new measure, the old incorrect `active_count` would stay and future queries would keep answering the wrong question.
+
+## Worked example - new join
+
+Prior turn: user asked to correlate LTV with protocol count; assistant joined `fct_orders` with `fct_mau_multiprotocol` on `admin_user_id` in raw SQL.
+
+```
+sl_read_source({ connectionId: "warehouse", sourceName: "fct_orders" })
+  → no joins section yet
+sql_execution({
+  connectionId: "warehouse",
+  sql: "SELECT COUNT(*), COUNT(DISTINCT a.admin_user_id) FROM public.fct_orders a JOIN public.fct_mau_multiprotocol b ON a.admin_user_id = b.admin_user_id LIMIT 1"
+})
+  → confirms cardinality (many orders per MAU row = many_to_one)
+sl_edit_source({
+  connectionId: "warehouse",
+  sourceName: "fct_orders",
+  yaml_edits: [{
+    oldText: "measures:",
+    newText: "joins:\n  - to: fct_mau_multiprotocol\n    on: admin_user_id = fct_mau_multiprotocol.admin_user_id\n    relationship: many_to_one\nmeasures:"
+  }]
+})
+sl_validate({ connectionId: "warehouse" })
+```
+
+Always verify joins with `sql_execution` before adding them.
+
+## Rules recap
+
+- Read existing sources before editing (`sl_read_source` or `sl_discover`).
+- Prefer overlays over standalone sources on manifest-backed tables.
+- Prefer generic measures + query-time filters over per-value variants.
+- Time anchors and value lists belong in callers' filters, not in measure expressions.
+- A measure whose filter matches a segment MUST reference the segment via `segments: [name]`.
+- Extract repeated predicates into named segments.
+- Use computed dimensions for derived categories.
+- When the user corrects a prior answer, replace - don't append.
+- Always run `sl_validate` after writing to surface issues.
+- If nothing is worth capturing, respond without calling any SL write tool.

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

@@ -0,0 +1,160 @@
+---
+name: wiki_capture
+description: KTX's knowledge base - wiki pages for durable, reusable business knowledge. Covers capture workflow for user preferences, metric definitions, organizational conventions, and cross-references between wiki pages and semantic-layer sources. Loaded by the post-turn memory-agent only. The research agent reads wiki via `wiki_read`/`wiki_search` but does not write it.
+callers: [memory_agent]
+---
+
+# Wiki Capture
+
+## Role
+
+The knowledge base stores durable, reusable business knowledge for an analytics assistant. Each page is a self-contained rule, definition, or convention that answers "how should this concept be handled in this organization?" - written once and reused across chats.
+
+Scope selection is handled by the runtime:
+- When user-scoped knowledge is enabled AND the caller is a chat turn, writes go to the user's **personal** scope.
+- When the caller is an admin-driven ingest (`sourceType: 'external_ingest'`), writes go to the **global** scope.
+- When user-scoped knowledge is disabled, all writes go to the global scope.
+
+The `wiki_write` tool picks the right scope based on the session. Capture logic does not need to choose - focus on whether the content is worth capturing at all.
+
+## What to capture
+
+Capture when the user or the ingested document expresses:
+- A metric definition ("revenue means booked revenue after refunds").
+- A filter or convention that should always apply ("exclude test accounts when reporting ARR").
+- A mapping or alias ("mood_stress_sleep = Oxytocin protocol").
+- A domain rule that is not visible from column names alone ("status = 'T' means terminated, not 'terminated'").
+- A link or external system convention ("medplum_patient_id is the primary key in the EMR at https://emr.example/patients/{id}").
+
+Do NOT capture:
+- One-off requests ("answer under 100 words").
+- Temporary instructions scoped to the current chat.
+- Ad-hoc formatting preferences.
+- Information already present in the semantic layer (column names, join paths, measure formulas - those belong in SL).
+- **Query results, snapshots, or time-bounded benchmark tables.** Numbers go stale; pasting "Oct 2025: 25%, Nov 2025: 19.9%, …" creates misinformation as soon as new data lands. Reference the SL source by name (`sl_refs`) and let future query tools pull live data - the wiki captures the *rule* (definition, exclusion, segmentation), the SL source captures the *measure*, and query execution captures the *current values*.
+- **Interpretive narrative tied to a specific snapshot** ("M1 retention degraded sharply from Dec 2025"). The observation is anchored to data that will move; the actionable convention (e.g., "always exclude in-progress cohorts") may be worth capturing on its own, but the snapshot-specific commentary is not.
+
+If nothing is worth capturing, respond without calling any tool.
+
+## Workflow
+
+1. Read the wiki index (provided in the prompt) and decide whether the turn introduces durable knowledge.
+2. **Before writing**, search for related content so cross-references are accurate:
+   - `discover_data` first when a page relates to data or SL concepts - find
+     existing wiki pages, SL sources, and raw warehouse schema together.
+   - `wiki_search` with the topic - find related wiki pages to populate `refs`.
+   - `sl_discover` with the concept - if the page defines a metric (revenue, churn, retention, LTV, ARR, MRR, CAC, attribution, etc.), find matching SL sources or measures to populate `sl_refs`. If no matches, pass `sl_refs: []` so future readers know you checked.
+3. If updating an existing page, `wiki_read` it first. Use the returned `structured.content` or markdown body as the exact stored text for targeted replacements; current tags, refs, and sl_refs are returned in structured metadata.
+4. `wiki_write` to create or update. Prefer merging into an existing page over creating a new one.
+5. `wiki_remove` only when a page is truly obsolete - not to replace stale content (update it instead).
+
+For bundle/external ingest, include `rawPaths` on every `wiki_write`/`wiki_remove` call with only the raw files that directly support that wiki action. This keeps ingest provenance tied to the actual source file, not every file in the WorkUnit.
+
+## 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.
+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.
+
+## Keys, summaries, and content
+
+- **Keys** are short kebab-case topic identifiers: `leads-source-filter`, `revenue-definition`, `churn-calculation`. No namespacing, no prefixes.
+- **Summary** is a one-line hook (≤200 chars) shown in the index.
+- **Content** is concise markdown - actionable rules, not prose.
+
+```
+## [Topic Title]
+- Rule or preference statement
+- Another rule if applicable
+```
+
+Prefer fewer, richer pages over many thin ones. Each page covers one coherent topic thoroughly. If the new information relates to an existing page, update that page instead of fragmenting the knowledge.
+
+## Tags, refs, sl_refs
+
+The `wiki_write` tool accepts three array fields that go into the page frontmatter:
+
+- **`tags`**: 1–3 short lowercase topic tags (`["finance"]`, `["data-quality"]`). Call `wiki_list_tags` first to reuse existing tags for consistency.
+- **`refs`**: keys of related wiki pages. Add when the new page materially depends on concepts from another (e.g., a churn definition that uses the paid-orders filter from a revenue definition). Don't add refs just because pages share a topic area.
+- **`sl_refs`**: names of SL sources or measures the page relates to. Format: `"source_name"` or `"source_name.measure_name"`. Discover via `sl_discover` → inspect with `sl_read_source` → include the confirmed matches.
+
+Wiki page keys must be flat slugs. Use `large-contract-requesters`, not
+`historic-sql/large-contract-requesters`. Use `tags`, `source`, and content
+headings for grouping.
+
+### Replace semantics
+
+All three fields use REPLACE semantics on update:
+
+- Omit the field → existing value is kept.
+- Pass `[]` → field is cleared.
+- Pass `[values]` → replaces existing with exactly those values (no merging).
+
+## Editing existing pages
+
+Two modes:
+
+- **Full content** - pass `content` to rewrite the whole page. Use when the page structure needs to change.
+- **Targeted edits** - pass `replacements: [{ oldText, newText }]` to apply exact-string replacements. Use for small updates; preserves the rest of the page.
+
+When editing, read the page first so the edit matches exact whitespace and indentation.
+
+## Overriding an organization rule
+
+Organization (GLOBAL) pages are read-only from a user's personal-scope session. To override a global rule for a single user, write a personal page with the **same key**. At read time the USER page wins.
+
+## Worked example - capturing a metric with cross-references
+
+User says: "Going forward, the official refund rate is total refunded amount divided by total gross transaction amount."
+
+```
+wiki_list_tags()
+  → existing tags include "finance"
+wiki_search({ query: "refund revenue paid orders" })
+  → returns `revenue-definition` (related - defines paid-orders filter)
+sl_discover({ query: "refund rate" })
+  → returns fct_orders (score 0.08), fct_gaap_revenue (0.06)
+sl_read_source({ connectionId: "warehouse", sourceName: "fct_orders" })
+  → confirms amount_refunded_dollars and transaction_amount_dollars exist
+wiki_write({
+  key: "refund-rate-definition",
+  summary: "Refund rate = refunded amount / gross transaction amount",
+  content: "## Refund Rate\n- Definition: sum(amount_refunded_dollars) / sum(transaction_amount_dollars)\n- Source of truth: fct_orders\n- Related: see revenue-definition for paid-orders filter.",
+  tags: ["finance"],
+  refs: ["revenue-definition"],
+  sl_refs: ["fct_orders.refund_rate_pct", "fct_orders"]
+})
+```
+
+Search-then-write order matters. Cross-references are part of the page's identity, not an afterthought.
+
+## Rules
+
+- Read existing pages before updating them.
+- Prefer merging into an existing page over creating a new one.
+- Prefer fewer, richer pages over many thin ones.
+- Write content as clear, actionable rules - not narrative prose.
+- Discover cross-references via search before writing, not after.
+- If nothing is worth capturing, respond without calling any tool.

package/node_modules/@ktx/llm/dist/embedding-health.d.ts

@@ -0,0 +1,14 @@
+import { type KtxEmbeddingProviderDeps } from './embedding-provider.js';
+import type { KtxEmbeddingConfig } from './types.js';
+export type KtxEmbeddingHealthCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export interface KtxEmbeddingHealthCheckOptions {
+    text?: string;
+    timeoutMs?: number;
+    deps?: KtxEmbeddingProviderDeps;
+}
+export declare function runKtxEmbeddingHealthCheck(config: KtxEmbeddingConfig, options?: KtxEmbeddingHealthCheckOptions): Promise<KtxEmbeddingHealthCheckResult>;

package/node_modules/@ktx/llm/dist/embedding-health.js

@@ -0,0 +1,36 @@
+import { createKtxEmbeddingProvider } from './embedding-provider.js';
+function redactHealthCheckMessage(message, config) {
+    const secrets = [config.openai?.apiKey].filter((value) => typeof value === 'string' && value.length > 0);
+    return secrets.reduce((current, secret) => current.split(secret).join('[redacted]'), message);
+}
+async function withTimeout(promise, timeoutMs) {
+    let timeout;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => reject(new Error(`Embedding health check timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+export async function runKtxEmbeddingHealthCheck(config, options = {}) {
+    try {
+        const provider = createKtxEmbeddingProvider(config, options.deps);
+        const embedding = await withTimeout(provider.embed(options.text ?? 'KTX embedding health check'), options.timeoutMs ?? 15_000);
+        if (embedding.length !== config.dimensions) {
+            return {
+                ok: false,
+                message: `Embedding provider ${config.backend} returned vector with ${embedding.length} dimensions; expected ${config.dimensions}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, message: redactHealthCheckMessage(message, config) };
+    }
+}

package/node_modules/@ktx/llm/dist/embedding-health.test.d.ts

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

package/node_modules/@ktx/llm/dist/embedding-health.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from 'vitest';
+import { runKtxEmbeddingHealthCheck } from './embedding-health.js';
+describe('KTX embedding health check', () => {
+    it('runs a one-shot OpenAI embedding check through the configured provider', async () => {
+        const createOpenAIClient = vi.fn(() => ({
+            embeddings: {
+                create: vi.fn().mockResolvedValue({
+                    data: [{ index: 0, embedding: [0.1, 0.2, 0.3] }],
+                }),
+            },
+        }));
+        await expect(runKtxEmbeddingHealthCheck({
+            backend: 'openai',
+            model: 'text-embedding-3-small',
+            dimensions: 3,
+            openai: { apiKey: 'sk-openai-test' }, // pragma: allowlist secret
+        }, { deps: { createOpenAIClient } })).resolves.toEqual({ ok: true });
+        expect(createOpenAIClient).toHaveBeenCalledWith({ apiKey: 'sk-openai-test', baseURL: undefined }); // pragma: allowlist secret
+    });
+    it('returns failed when the provider returns the wrong dimensions', async () => {
+        const createOpenAIClient = vi.fn(() => ({
+            embeddings: {
+                create: vi.fn().mockResolvedValue({
+                    data: [{ index: 0, embedding: [0.1, 0.2] }],
+                }),
+            },
+        }));
+        await expect(runKtxEmbeddingHealthCheck({
+            backend: 'openai',
+            model: 'text-embedding-3-small',
+            dimensions: 3,
+            openai: { apiKey: 'sk-openai-test' }, // pragma: allowlist secret
+        }, { deps: { createOpenAIClient } })).resolves.toEqual({
+            ok: false,
+            message: 'Embedding provider openai returned vector with 2 dimensions; expected 3',
+        });
+    });
+    it('redacts credential values from health-check failures', async () => {
+        const createOpenAIClient = vi.fn(() => ({
+            embeddings: {
+                create: vi.fn(async () => {
+                    throw new Error('401 invalid api key sk-openai-secret');
+                }),
+            },
+        }));
+        await expect(runKtxEmbeddingHealthCheck({
+            backend: 'openai',
+            model: 'text-embedding-3-small',
+            dimensions: 3,
+            openai: { apiKey: 'sk-openai-secret' }, // pragma: allowlist secret
+        }, { deps: { createOpenAIClient } })).resolves.toEqual({
+            ok: false,
+            message: '401 invalid api key [redacted]',
+        });
+    });
+    it('returns failed when the health check times out', async () => {
+        const createOpenAIClient = vi.fn(() => ({
+            embeddings: {
+                create: vi.fn(() => new Promise(() => undefined)),
+            },
+        }));
+        await expect(runKtxEmbeddingHealthCheck({
+            backend: 'openai',
+            model: 'text-embedding-3-small',
+            dimensions: 3,
+            openai: { apiKey: 'sk-openai-test' }, // pragma: allowlist secret
+        }, { timeoutMs: 1, deps: { createOpenAIClient } })).resolves.toEqual({
+            ok: false,
+            message: 'Embedding health check timed out after 1ms',
+        });
+    });
+});