@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,170 @@
+---
+name: historic_sql_ingest
+description: Convert one full-tier historic-SQL template WorkUnit into a canonical query knowledge page, linked SL refs, and optional semantic-layer proposals.
+callers: [memory_agent]
+---
+
+# Historic SQL Ingest
+
+Use this skill when the WorkUnit contains files under `raw-sources/<connectionId>/historic-sql/<syncId>/templates/<templateId>/`.
+
+Read exactly one historic-SQL template WorkUnit. Each WorkUnit represents one staged template or categorical sub-cluster that already survived full-tier page triage. It is not an intent cluster.
+
+## Input Shape
+
+The WorkUnit normally exposes:
+
+- `metadata.json` in `rawFiles`.
+- `page.md` in `rawFiles`.
+- `usage.json` in `dependencyPaths`.
+- `manifest.json` in `dependencyPaths`.
+- `peerFileIndex` containing sibling templates that you cannot read.
+
+`metadata.json` has the stable identity:
+
+```json
+{
+  "id": "fp_1",
+  "title": "snowflake - analytics.orders [fp_1]",
+  "path": "templates/fp_1/page.md",
+  "objectType": "historic_sql_template",
+  "lastEditedAt": null,
+  "properties": {
+    "fingerprint": "fp_1",
+    "sub_cluster_id": null,
+    "dialect": "snowflake",
+    "tables_touched": ["analytics.orders"],
+    "literal_slots": [
+      { "position": 1, "type": "string", "classification": "constant" },
+      { "position": 2, "type": "date", "classification": "runtime" }
+    ],
+    "triage_signals": {
+      "executions_bucket": "high",
+      "distinct_users_bucket": "team",
+      "error_rate_bucket": "ok",
+      "recency_bucket": "active",
+      "service_account_only": "false",
+      "slot_summary": "1 constant, 1 runtime"
+    }
+  }
+}
+```
+
+`page.md` contains mechanically generated normalized SQL and touched tables:
+
+```text
+# fp_1
+
+## Normalized SQL
+SELECT date_trunc(?, created_at), count(*) FROM analytics.orders WHERE status = ? AND created_at >= ? GROUP BY 1
+
+## Tables touched
+- analytics.orders
+```
+
+`usage.json` contains volatile stats, literal top values, and redacted samples. Use it for intent inference and usage summaries. Do not treat usage-only drift as a reason to group this template with siblings.
+
+## Required Workflow
+
+1. Read the WorkUnit section in the prompt first.
+2. Call `read_raw_file` for `metadata.json`, `page.md`, `usage.json`, and `manifest.json`.
+3. Confirm `metadata.objectType === "historic_sql_template"`. If it is not, call `emit_unmapped_fallback` with `reason: "parse_error"`, `fallback: "flagged"`, and the `metadata.json` raw path.
+4. Extract `fingerprint`, `sub_cluster_id`, `dialect`, `tables_touched`, `literal_slots`, normalized SQL, usage stats, top literal values, and sample timestamps.
+5. Infer one canonical query intent from this template only. Use table names, selected expressions, aggregations, joins, grouping, constant literal slots, and repeated successful samples. Runtime literal slots are parameters, not fixed business rules.
+6. Build a short intent slug in kebab-case. Use `queries/<intent_slug>` as the wiki key.
+7. Search existing knowledge with `wiki_search` using the intent phrase and the primary table. Prefer updating an existing `queries/...` page when it is the same intent.
+8. Discover touched tables with `sl_discover`. Add cleanly matched source names to `sl_refs`. If a table does not map cleanly, keep it in the page body and do not include it in `sl_refs`.
+9. Write or update the query page with `wiki_write`.
+10. Apply the SL proposal threshold below. If it passes and a useful generic measure, segment, join, or overlay is clear, update the semantic layer and run `sl_validate`.
+11. Exit without reading peer files or grouping sibling templates.
+
+## Wiki Page Shape
+
+Use `wiki_write` for pages. Emit the spec frontmatter fields directly on the query page.
+
+Use this shape:
+
+```json
+{
+  "key": "queries/<intent_slug>",
+  "summary": "<one sentence canonical intent>",
+  "tags": ["historic-sql", "query-pattern"],
+  "sl_refs": ["<clean_source_name>"],
+  "source": "historic-sql",
+  "intent": "<human-readable canonical intent>",
+  "tables": ["<tables_touched>"],
+  "representative_sql": "<parameterized representative SQL>",
+  "usage": {
+    "executions": 47812,
+    "distinct_users": 12,
+    "first_seen": "2026-02-01",
+    "last_seen": "2026-04-30",
+    "p50_runtime_ms": 320,
+    "p95_runtime_ms": 1180,
+    "error_rate": 0.0007
+  },
+  "fingerprints": ["<fingerprint or sub-cluster id>"],
+  "content": "## <Canonical Intent Title>\n\n### Parameters\n- <constant/runtime/categorical slot notes>\n\n### When To Use\n- <concise reusable guidance>\n\n### Caveats\n- <redaction, service-account, low-confidence, or mapping notes if present>"
+}
+```
+
+For Snowflake templates include `usage.rows_produced` when present in `usage.json`; for BigQuery v1 omit `usage.rows_produced`.
+
+The `key: "queries/<intent_slug>"` value writes to `knowledge/global/queries/<intent_slug>.md` during external ingest because bundle ingests write global wiki pages.
+
+## Representative SQL Rules
+
+- Start from normalized SQL in `page.md`.
+- For constant slots, use the dominant `usage.literal_slots[].top_values[0][0]` when it has definitional meaning. Quote string and date values in the representative SQL.
+- For runtime slots, render named parameters such as `:start_date`, `:as_of`, `:status`, or `:threshold`.
+- For categorical slots, document the known categories and write this WorkUnit's sub-cluster value when `sub_cluster_id` is present.
+- Preserve the warehouse dialect named by `metadata.properties.dialect`.
+- Do not copy sample bound_sql into the wiki unless it is visibly redacted and safer than the normalized SQL. Prefer normalized SQL plus parameter notes.
+
+## SL Proposal Threshold
+
+Only propose semantic-layer changes when all are true:
+
+1. This WorkUnit reached Stage 3 full tier. The runner normally guarantees this, but treat `executions_bucket=low` plus `distinct_users_bucket=solo` or `service_account_only=true` as a reason to write wiki only.
+2. At least one `literal_slots[]` entry has `classification: "constant"` and the value has durable business meaning, such as a status, plan tier, channel, threshold, or fixed category.
+3. Every table in `tables_touched` maps cleanly through `sl_discover` to an existing SL source.
+
+When the threshold passes:
+
+- Call `sl_read_source` before editing an existing source.
+- Prefer adding a measure, segment, computed dimension, join, or manifest-backed overlay over creating a standalone SQL source.
+- Use `sl_write_source` for a manifest-backed overlay only with `name:` plus additive fields such as `measures:`, `segments:`, `description:`, or `joins:`. Do not include `sql:`, `table:`, `grain:`, or `columns:` on manifest-backed overlays.
+- Use `sl_edit_source` for targeted edits when the source file already exists.
+- Run `sl_validate` after every SL write or edit.
+- Keep runtime parameters as caller filters. Do not bake dates, user ids, ids, search strings, or other runtime slots into SL measures.
+
+When the threshold does not pass, write the wiki page and set `sl_refs` for any cleanly discovered touched tables. A wiki-only result is valid.
+
+## Intent Inference Guidance
+
+Prefer canonical intent names that describe the business question, not the SQL shape:
+
+- Good: `queries/monthly-paid-order-count`
+- Good: `queries/enterprise-contract-renewal-risk`
+- Good: `queries/support-ticket-first-response-time`
+- Weak: `queries/fp-1`
+- Weak: `queries/count-orders-group-by-date`
+
+Use the SQL shape to infer intent:
+
+- `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `GROUP BY`, and date truncation usually indicate metrics or rollups.
+- Constant slots often name segments, statuses, tiers, regions, or thresholds.
+- Runtime slots usually represent time windows, selected entities, or caller filters.
+- Repeated successful samples from multiple human users make the page more durable.
+- High error rates, service-account-only use, or old `last_seen` values belong in caveats.
+
+## Boundaries
+
+- Do not group sibling templates. Stage 4 `historic_sql_curator` owns cross-template clustering and dedupe.
+- Do not read paths listed only in `peerFileIndex`.
+- Do not create or update `historic_sql_curator`.
+- Do not call `context_candidate_write`; historic-SQL Stage 3 writes final wiki and optional SL artifacts directly.
+- Do not invent joins, measures, or definitions that are not supported by the normalized SQL, touched tables, literal slots, or existing SL sources.
+- Do not copy unredacted sample `bound_sql`, user emails, account ids, tokens, or free-text literal values into wiki or SL output.
+- Do not write SL changes when any touched table lacks a clean SL mapping.
+- Do not finish after only an SL write. Always write or update the query knowledge page first so the canonical SQL pattern is searchable.

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

@@ -0,0 +1,77 @@
+---
+name: ingest_triage
+description: Classify and resolve conflicts detected during bundle ingest (structural duplicates, definitional contradictions, near-duplicate clusters, re-ingest changes, evictions).
+callers: [memory_agent]
+---
+
+# Ingest Triage — conflict classification and resolution
+
+This skill is loaded in two contexts:
+- By a Stage 3 WorkUnit agent when `sl_discover` or an `sl_discover` reveals that a prior WU (or a prior sync) already wrote something that overlaps with what the current WU is about to write.
+- By the Stage 4 reconciliation agent for cross-WU sweeps and for eviction decisions.
+
+Apply the rules below before every write that could collide with an existing artifact.
+
+## Decision tree
+
+1. **Is this the same artifact I'm producing now, or a different one with the same name?**
+   Read both. If names match and content matches (modulo whitespace): no conflict — skip the write, the prior one stands.
+
+2. **If content differs, is it an expression-only change (e.g. a different `sql:` body for the same measure name, same grain, same columns)?**
+   Re-ingest change (expression-only): silently replace via `sl_edit_source`. No flag.
+
+3. **If the difference is structural — grain, columns, filter, join shape — is the current bundle the re-ingest of a previously-ingested bundle (i.e. `priorProvenance` has a row for this raw file and artifact)?**
+   Re-ingest change (semantic break): replace + flag. Record in the IngestReport's `conflicts_resolved` list with `flagged_for_human: true`.
+
+4. **If there's no prior-sync row (both are from THIS job), check for same-ingest contradictions:**
+
+   | Kind | Detection | Resolution |
+   |---|---|---|
+   | Structural duplicate | Same name, near-identical expression | Elect canonical by: (a) highest inbound-ref count from other sources; tiebreak: (b) lexicographically first unit key; (c) lexicographically first source name. Subsume losers into `<canonical>-variants.md` wiki page. Do NOT flag unless ambiguous. |
+   | Near-duplicate cluster | Different names, overlapping shape (same table, similar formulas) | Same as structural; one canonical, others subsumed. Flag only if no canonical emerges. |
+   | Definitional contradiction | Same name, substantively different formulas (different aggregation, different filters, different columns) | **Rename + capture**: disambiguate ALL variants with suffix derived from the domain (`churn_risk_engagement_based`, `churn_risk_billing_based`) and write a unified wiki page listing every variant with provenance. The contested name does NOT land in the SL. **Always flag.** |
+
+5. **Eviction (Stage 4 only)**: for each entry in `eviction_list()`:
+   - `inbound_refs: []` → remove the artifact (`sl_delete` for SL sources, `wiki_remove` for wiki pages).
+   - `inbound_refs: [...]` → retain the artifact, set `deprecated: true` on SL sources (via `sl_edit_source`), write a wiki note "origin file removed in <syncId>; preserved because referenced by: …". Flag in the IngestReport so the user can plan migration.
+
+## Why same-ingest vs re-ingest differs
+
+Within ONE bundle there's no user signal telling us which duplicate wins — we capture all variants and flag. Across bundles, re-uploading IS the signal that the new state is intended — we replace silently for expression changes and flag for semantic breaks.
+
+## Naming disambiguation hints
+
+When you rename to disambiguate, prefer domain suffixes that match the containing view/table/collection name: `customers.churn_risk_score` → `customers.churn_risk_engagement_based` (if the `customer_churn` view computes it from engagement); `billing.churn_risk_score` → `billing.churn_risk_billing_based`. Avoid numeric suffixes (`churn_risk_1`, `churn_risk_2`) — they disclose nothing.
+
+## Applying canonical pins
+
+When the Stage 4 system prompt includes a `<canonical_pins>` block, treat each pin as a prior user decision for that `contestedKey`.
+
+- If the pinned `canonicalArtifactKey` is present in the Stage Index or already exists in SL, keep it as the canonical artifact for that contested key.
+- Disambiguate competing artifacts instead of using the contested name for them.
+- Do not flag the pinned contested key solely because the variants disagree; the user has already chosen the canonical artifact.
+- If the pinned artifact cannot be found and no current WU can recreate it, emit `emit_conflict_resolution` with `flaggedForHuman: true` and explain that the pin references a missing canonical artifact.
+
+When a pin applies cleanly, call `emit_conflict_resolution` with `kind: "definitional_contradiction"`, `artifactKey` set to the pinned `canonicalArtifactKey`, `detail` describing the pinned election, and `flaggedForHuman: false`.
+
+## What to write in the unified wiki page
+
+When you perform rename + capture, also write one page named `<canonical-concept>-definitions.md` under the wiki GLOBAL scope. Structure:
+
+- One heading per variant, referencing the disambiguated SL name.
+- One paragraph per variant: what it computes, where it came from (raw file + line range), when to use it.
+- A closing "Choosing between these" paragraph if the variants are legitimately domain-specific.
+
+Do not attempt to rank variants or pick a "best" — that's user-override territory.
+
+## Silence rules
+
+Flag for human review when:
+- You did rename + capture for a definitional contradiction (kind 3 above).
+- You performed an eviction retention (kind 5, second row).
+- An override constraint (from a Stage 4 re-run) conflicts with current inbound refs.
+
+Do NOT flag:
+- Same-content duplicate skip (trivial).
+- Structural duplicate with clear canonical election.
+- Expression-only re-ingest replace.

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

@@ -0,0 +1,124 @@
+---
+name: knowledge_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 knowledge 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]
+---
+
+# Knowledge 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 queries pull live data — the wiki captures the *rule* (definition, exclusion, segmentation), the SL source captures the *measure*, and `semantic_query` 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:
+   - `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. The read result begins with `[scope: ... | tags: ... | refs: ... | sl_refs: ...]` showing current frontmatter.
+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).
+
+## 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.
+
+### 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({ 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/context/skills/live_database_ingest/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: live_database_ingest
+description: Capture semantic-layer and knowledge updates from a live database schema snapshot.
+callers: [memory_agent]
+---
+
+# Live Database Ingest
+
+Use this skill when the ingest work unit contains raw files under
+`raw-sources/<connectionId>/live-database/<syncId>/`.
+
+## Workflow
+
+1. Read the table JSON file listed in the work unit.
+2. Read `connection.json` to understand the snapshot metadata.
+3. Read `foreign-keys.json` when the table has a foreign key or when joins are
+   needed for the semantic-layer source.
+4. Create or update one semantic-layer source for the table with
+   `sl_write_source`.
+5. Use the physical table name from the raw JSON as the source `table` field.
+6. Preserve database comments as `descriptions.db` on tables and columns.
+7. Add joins only when the foreign key index names both sides.
+8. Write wiki pages only for durable business meaning that is present in table
+   or column comments.
+9. Run `sl_validate` for the table source before the work unit completes.
+
+## Source shape
+
+For a raw table with this shape:
+
+```json
+{
+  "name": "orders",
+  "db": "public",
+  "columns": [
+    { "name": "id", "type": "integer", "nullable": false, "primaryKey": true }
+  ]
+}
+```
+
+Write a semantic-layer source with this shape:
+
+```yaml
+name: orders
+table: public.orders
+grain: id
+columns:
+  - name: id
+    type: number
+```
+
+Use `string`, `number`, `time`, or `boolean` for column types. When a database
+type is ambiguous, use `string`.
+
+## Boundaries
+
+The raw snapshot is structural evidence. Do not invent measures, segments,
+business definitions, or joins that are not present in the snapshot files.

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

@@ -0,0 +1,217 @@
+---
+name: looker_ingest
+description: Extract durable KTX knowledge and semantic-layer contribution proposals from staged Looker runtime dashboard, Look, and explore JSON. Load for WorkUnits whose raw files are under explores/, dashboards/, or looks/.
+callers: [memory_agent]
+---
+
+# Looker Runtime Ingest
+
+Looker runtime ingest turns API-staged dashboards, Looks, and explores into durable KTX memory. Runtime entities are evidence. They are not themselves the final knowledge shape.
+
+## Required Workflow
+
+1. Read every `rawFiles` entry for the WorkUnit.
+2. Read relevant `dependencyPaths` before making a decision. For dashboard and Look WUs this usually includes the referenced explore JSON, signal files, `folders/tree.json`, and `users/<id>.json`.
+3. Treat `signals/*.json`, owners, folders, schedules, and favorites as prioritization or provenance context only.
+4. Extract generalizable metric formulas, segment definitions, field semantics, and domain conventions.
+5. Use `wiki_search`, `sl_discover`, and `sl_read_source` before writing so new content merges with existing memory instead of duplicating it.
+6. Use `context_evidence_search` or `context_evidence_read` to obtain evidence chunk IDs for any wiki-bound knowledge candidate.
+7. Use `context_candidate_write` for durable wiki-bound knowledge. Do not call `wiki_write` from a Looker WorkUnit; Stage 4 reconciliation promotes candidates and writes wiki pages.
+8. Use `looker_query_to_sl` for each Look query or dashboard tile query that has a `query` object.
+9. Write SL from Looker runtime evidence only through the staged warehouse target contract. For explores and inherited dashboard/Look queries, branch on `targetTable.ok`; when it is true, write on `targetWarehouseConnectionId` and use `targetTable.canonicalTable` as `source.table`. When it is false or missing, write wiki knowledge candidates and record `emit_unmapped_fallback` with the staged reason.
+10. Run `sl_validate` after every SL write. If validation fails, fix the source or roll it back before the WorkUnit ends.
+
+## Explore WorkUnits
+
+Explore WUs have raw files like `explores/<model>/<explore>.json` and usually depend on `lookml_models.json`.
+
+Use the deterministic API-derived source key:
+
+```text
+looker__<model>__<explore>
+```
+
+For example, `modelName: "b2b"` and `exploreName: "sales_pipeline"` map to `looker__b2b__sales_pipeline`.
+
+Mapped explore write shape:
+
+```json
+{
+  "connectionId": "22222222-2222-4222-8222-222222222222",
+  "sourceName": "looker__b2b__sales_pipeline",
+  "source": {
+    "name": "looker__b2b__sales_pipeline",
+    "table": "proj.dataset.opportunities",
+    "grain": ["opportunity_id"],
+    "columns": [
+      {
+        "name": "opportunity_id",
+        "type": "string"
+      },
+      {
+        "name": "arr",
+        "type": "number"
+      }
+    ],
+    "measures": [
+      {
+        "name": "total_arr",
+        "expr": "sum(arr)"
+      }
+    ]
+  }
+}
+```
+
+Every concrete value in that example must be backed by raw Looker field SQL, `source_tables` preflight, `source_columns`, or existing SL when applied to a real WorkUnit. If the evidence is not present, write wiki candidates and emit `emit_unmapped_fallback`.
+
+The staged explore file carries warehouse target fields populated before the WU starts:
+
+- `connectionName`: the Looker runtime connection name.
+- `targetWarehouseConnectionId`: the resolved warehouse connection id, or `null` when the Looker connection is unmapped.
+- `rawSqlTableName`: Looker's verbatim `sql_table_name`. Keep it as provenance only.
+- `targetTable`: the parsed target-table union. Use this as the sole branch condition.
+
+When `targetTable.ok === true`, the explore has a complete KTX backing target. Before writing:
+
+1. Use `targetTable.catalog`, `targetTable.schema`, and `targetTable.name` for `source_tables` preflight matching through `sl_discover` or `sl_read_source`.
+2. Use Looker field `sql`, labels, descriptions, and type metadata to derive source columns, measures, segments, joins, and grain.
+3. Call `sl_write_source` or `sl_edit_source` with `connectionId: targetWarehouseConnectionId`.
+4. Set `source.name` to the deterministic API-derived source key, for example `looker__b2b__sales_pipeline`.
+5. Set `source.table` to `targetTable.canonicalTable`.
+6. Run `sl_validate` after every SL write.
+
+The `table` field is `targetTable.canonicalTable`, not `rawSqlTableName`. Raw Looker values can contain aliases such as `schema.table AS x`, Looker templates such as `${TABLE}`, or derived-table SQL. Those raw forms do not compose safely with SL generation. `targetTable.canonicalTable` is the dialect-quoted identifier rebuilt by the parser.
+
+Use `targetTable.{catalog,schema,name}` only for source_tables preflight. Do not put those tuple fields separately into the SL source unless the SL schema already asks for them.
+
+When `targetTable.ok === false`, keep the WU wiki-only for SL purposes. Capture durable domain semantics with `context_candidate_write`, then emit a fallback with the EXACT structured `reason` code from `targetTable.reason`. Put any human-readable context in `detail`, NOT in `reason`:
+
+```json
+{
+  "rawPath": "explores/b2b/sales_pipeline.json",
+  "reason": "no_connection_mapping",
+  "detail": "Looker connection b2b_sandbox_bq is not mapped to a warehouse connection",
+  "fallback": "wiki_only"
+}
+```
+
+Valid `reason` codes (use exactly one, no other strings allowed): `no_connection_mapping`, `looker_template_unresolved`, `derived_table_not_supported`, `no_physical_table`, `multiple_table_references`, `unsupported_dialect`, `parse_error`, `missing_target_table`.
+
+When `targetTable` is `null`, read the raw explore file again. If the target is still absent, emit the same fallback with `"reason": "missing_target_table"`.
+
+## Look And Dashboard WorkUnits
+
+Looks have raw files like `looks/<id>.json`. Dashboards have raw files like `dashboards/<id>.json`. Dashboard tiles with inline `query` objects follow the same decision rules as Looks.
+
+For each query:
+
+1. Call `looker_query_to_sl` with the query JSON, title, content type, and usage counts if available.
+2. Read the proposal's `targetStatus`, `targetWarehouseConnectionId`, `targetTable`, `sourceTable`, and `canWriteStandaloneSource`.
+3. If `canWriteStandaloneSource` is true, use `targetWarehouseConnectionId` for SL tools and `sourceTable` / `targetTable.canonicalTable` as the source table. Verify the proposal against the parent explore dependency and existing SL before writing.
+4. If the proposal decision is `measure_added`, add or edit a measure only after verifying the expression against the explore field SQL or an existing source column.
+5. If the proposal decision is `source_created`, create a source only when `canWriteStandaloneSource` is true and the filter is canonical. Use `source.table = targetTable.canonicalTable`.
+6. If `targetStatus` is `unmapped`, `unparseable`, or `missing_target_table`, keep SL wiki-only for this query and call `emit_unmapped_fallback` with the proposal's target reason or status.
+7. If the proposal decision is `wiki_only`, write a context candidate only when the Look or dashboard names a reusable business concept.
+
+## Capture Rules
+
+Write SL for:
+
+- reusable aggregations with clear formulas;
+- reusable segment predicates that appear canonical;
+- calculated dimensions that are stable and backed by raw Looker query evidence;
+- joins or source relationships that are explicit in the explore JSON.
+
+Write wiki for:
+
+- metric definitions in dashboard or Look titles, descriptions, axis labels, and filter semantics;
+- business meaning of an explore;
+- concept aliases used by teams;
+- caveats about multiple competing definitions.
+
+Skip:
+
+- point-in-time values and chart screenshots;
+- dashboard layout, tile positions, colors, visualization types, and render settings;
+- owner names, top users, recipient counts, favorite counts, schedules, and usage counts as narrative content;
+- ad-hoc low-usage queries with no durable business semantics;
+- simple saved views of fields with no metric, segment, or concept definition.
+
+## Usage Signals
+
+Use usage only to prioritize:
+
+- zero or near-zero usage lowers priority and often means skip;
+- high usage raises confidence that a metric or segment is canonical;
+- schedules and favorites can break ties between otherwise similar candidates.
+
+When calling `context_candidate_write`, usage can affect scoring:
+
+- High usage (`queryCount30d >= 10` or `uniqueUsers30d >= 3`) can justify `authorityScore: 3` and `reuseScore: 3` when the evidence is otherwise durable.
+- Zero recent usage should usually use `actionHint: "skip"` or lower `reuseScore` unless the content clearly defines a canonical business concept.
+- Schedules and favorites can raise `reuseScore` by 1 when deciding between otherwise similar candidate scores.
+
+Never include the usage counts themselves in `assertion`, `rationale`, or eventual wiki prose.
+
+Never write usage numbers, owner names, folder names, top users, schedule counts, or recipients into wiki article prose. If attribution is needed, keep it in provenance through the normal ingest action trail.
+
+## Provenance And Cross-References
+
+When writing candidates from Looker evidence, cite chunk IDs from `context_evidence_search` or `context_evidence_read`. Stage 4 reconciliation writes wiki pages from promoted candidates and sets `sl_refs` when the source exists or was created in the run.
+
+When an SL action is written on `targetWarehouseConnectionId`, the runner records `targetConnectionId` on the action and syncs `knowledge_sl_refs` to the warehouse connection. The wiki article still belongs to the Looker run connection; the SL ref belongs to the warehouse. Do not rewrite the source name or connection id in wiki frontmatter by hand. Use normal SL tool calls and let Stage 4 reconcile refs from actions.
+
+Use these source-key conventions:
+
+- API-derived explore source: `looker__<model>__<explore>`
+- API-derived segment source: `looker__<explore>__<slug>`
+- File-adapter source, when present: `<model>__<explore>` without the `looker__` prefix
+
+During Stage 4 reconciliation, when both `looker__<model>__<explore>` and `<model>__<explore>` exist for the same connection, treat the unprefixed file-adapter source as canonical. Rewrite wiki `sl_refs` to the unprefixed source, remove the API-derived source if it was created in this run, and call `emit_artifact_resolution` with `actionType: "subsumed"`, `artifactKind: "sl"`, `artifactKey: "looker__<model>__<explore>"`, and the raw explore path that produced it.
+
+If a file-adapter source already exists and clearly subsumes the API-derived source, prefer the file-adapter source in `sl_refs` and mention the API entity only as evidence in the wiki content.
+
+## Examples
+
+Measure proposal from a Look:
+
+```json
+{
+  "title": "Open Pipeline ARR",
+  "query": {
+    "model": "b2b",
+    "view": "sales_pipeline",
+    "fields": ["opportunities.arr", "opportunities.stage"],
+    "filters": { "opportunities.stage": "open" }
+  }
+}
+```
+
+Expected handling:
+
+- call `looker_query_to_sl`;
+- verify `opportunities.arr` and `opportunities.stage` against the explore dependency and existing SL;
+- add or update a measure only if the resulting expression validates;
+- write wiki for the durable definition "open pipeline ARR" if it is not already captured;
+- avoid mentioning query counts or users in wiki prose.
+
+Simple saved view:
+
+```json
+{
+  "title": "Accounts By Region",
+  "query": {
+    "model": "b2b",
+    "view": "accounts",
+    "fields": ["accounts.region", "accounts.segment"],
+    "filters": {}
+  }
+}
+```
+
+Expected handling:
+
+- no SL write;
+- wiki only if the title or description defines a reusable company concept;
+- otherwise skip.