@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,274 @@
+---
+name: metricflow_ingest
+description: Map a MetricFlow semantic_model or metric into KTX semantic layer sources. Covers the MetricFlow to KTX primitive table, `extends:` inheritance flattening, metric-type handling (simple / derived / ratio / cumulative / conversion), `model: ref('x')` resolution, and four worked examples. Load when the turn contains `.yml`/`.yaml` files with top-level `semantic_models:` or `metrics:`.
+callers: [memory_agent]
+---
+
+# MetricFlow to KTX Semantic Layer
+
+A MetricFlow `semantic_model` maps to an SL source; MetricFlow `measures` map to KTX measures; MetricFlow `entities` map to KTX `joins`; MetricFlow `metrics` (top-level) map to KTX measures OR to cross-model derived measures. Files in one WorkUnit are ALWAYS part of the same logical entity (a connected component, possibly spanning `extends:` + cross-model metric refs). Flatten inheritance and cross-file references at write time.
+
+## Mapping table
+
+| MetricFlow | KTX form | Notes |
+|---|---|---|
+| `semantic_model: X { model: ref('t') }` with measures + dimensions | **Overlay** at `<connId>/X.yaml` with `measures`, `columns` (computed), `joins` | The `model:` ref resolves to a manifest table. |
+| `semantic_model: X { model: source('s','t') }` | **Overlay** at `<connId>/X.yaml` over table `t`. | Same shape; `source()` still resolves to a physical table. |
+| `semantic_model: X { model: <literal> }` with no manifest entry | **Standalone** with explicit `sql:`, `grain:`, `columns:` | Happens when the dbt manifest isn't available. |
+| `semantic_model: Y { extends: X }` | **Merge** Y's measures/dimensions/entities into X's overlay, or write a single overlay named for the most-derived child (Y) containing both X's and Y's primitives | Do not emit a second overlay for X — flatten. |
+| `measures: [{ name, agg, expr }]` | `measures: [{ name, expr: "<agg>(<expr>)" }]` | Aggregation inlined. `agg: count_distinct` → `count(distinct ...)`. |
+| `entities: [{ name, type: primary }]` | `grain: [<entity_name-or-expr>]` on the overlay/standalone | Primary/unique entities drive grain. |
+| `entities: [{ name, type: foreign }]` | `joins:` entry joining to the primary-entity's semantic_model | Only when a matching primary is discoverable. |
+| `metrics: [{ type: simple, type_params: { measure: X } }]` | If the base measure is labeled/described by the metric: in-place edit to the existing measure. Otherwise leave as-is. | Same-name metrics can absorb metadata. |
+| `metrics: [{ type: simple, filter: <jinja> }]` | **New measure** on the same source, with the filter translated to SQL and attached via `filter:` | Translate Jinja `{{ Dimension('x__y') }}` to the column name `y`. |
+| `metrics: [{ type: derived, type_params: { expr, metrics } }]` | **Derived measure** on whichever source owns the referenced measures, with `expr:` referencing measure names | If the metric spans models, still write it once on the source owning the "primary" measure (the one the agent judges most central). Mention the cross-model chain in the description. |
+| `metrics: [{ type: ratio, type_params: { numerator, denominator } }]` | Same as derived; `expr: "numerator / NULLIF(denominator, 0)"` if no explicit expr | Safe-division by default. |
+| `metrics: [{ type: cumulative, type_params: { window, grain_to_date } }]` | **Standalone** source with a window-function SQL; reference the resulting column as a normal measure | KTX SL has no first-class cumulative primitive (spec Non-goals). |
+| `metrics: [{ type: conversion }]` | **Flag for human** — do NOT write. Emit a wiki note describing the intended semantics. | No KTX equivalent in v1. |
+| Metric not mappable | Wiki page `<metric_name>-definition.md` with the full YAML body quoted | Capture the intent even if we can't emit SL. |
+
+Type map: MetricFlow `time` to KTX `time`; `categorical` to `string`; `number` to `number`; `boolean` to `boolean`. Follow `expr` over `name` when both differ — `expr` is the physical column.
+
+## Flattening `extends:`
+
+Within one WorkUnit, multiple semantic_models linked by `extends:` are guaranteed to be present (the chunker groups them). Resolve inheritance **before** writing:
+
+1. Start with the most-derived child (the one that no other semantic_model extends).
+2. Walk the `extends:` chain upward, accumulating measures, dimensions, entities.
+3. Write ONE overlay/standalone, named for the most-derived child's SL-appropriate name (not the base).
+4. Parents that lack their own distinctive content should NOT get a separate overlay. If a parent has unique measures a child doesn't inherit, consider whether the base is used elsewhere — if yes, write both; if no, still one overlay.
+5. Measure/dimension name collisions: child wins, but note the overridden parent in the overlay's description or in a sibling wiki page.
+
+The spec's worked example has `orders`, `orders_ext` (extends orders), and `metrics/orders_final.yml` (defines `revenue` referencing both). The right output is ONE overlay named `orders_ext` (or `orders` if the team's naming favors the base) containing `order_count`, `gross_amount`, `refund_amount`, and a derived `revenue` measure. Provenance tags point to all three source files.
+
+## `model:` ref resolution
+
+The `model:` field on a semantic_model is a string like `ref('table_name')`, `source('src','table_name')`, or a literal. Resolve:
+
+- `ref('x')` → table name `x`. Verify via `sl_discover(x)`.
+- `source('s','t')` → table name `t`. Verify via `sl_discover(t)`.
+- Literal (no `ref(...)` / `source(...)`) → treat as the table name directly.
+
+If `sl_discover` errors (no such table), fall back to `sql_execution({ sql: "SELECT column_name FROM <dataset>.INFORMATION_SCHEMA.COLUMNS WHERE table_name = '<x>'" })` (session shape — a connection is already pinned by the ingest session). **Never invent column names** — every column in `columns:`, `grain:`, and `sql:` must be sourced from a real probe.
+
+After every `sl_write_source`, call `sl_validate`. The warehouse will reject invented columns with `Unrecognized name: <name>` — treat as a hard failure and re-read the schema.
+
+## Cumulative metrics — sql-standalone fallback
+
+KTX SL has no first-class `window:` or `grain_to_date:` primitive in v1 (spec Non-goals). Translate a MetricFlow cumulative metric to a standalone SL source with a window-function SQL:
+
+```yaml
+# MetricFlow input:
+metrics:
+  - name: cum_revenue_7d
+    type: cumulative
+    type_params:
+      measure: gross_amount
+      window: 7 days
+```
+
+```yaml
+# KTX standalone output:
+name: cum_revenue_7d
+source_type: sql
+sql: |
+  SELECT
+    ordered_at,
+    SUM(amount) OVER (ORDER BY ordered_at RANGE BETWEEN INTERVAL '7' DAY PRECEDING AND CURRENT ROW) AS cum_revenue_7d,
+    order_id
+  FROM analytics.orders
+grain: [order_id]
+columns:
+  - {name: ordered_at, type: time, role: time}
+  - {name: cum_revenue_7d, type: number}
+  - {name: order_id, type: string}
+measures:
+  - {name: cum_revenue_7d, expr: "max(cum_revenue_7d)"}
+```
+
+Pick the time column based on the semantic_model's `defaults.agg_time_dimension` (e.g. `ordered_at`). If the MetricFlow config omits it, probe the base table for time-typed columns and choose the most obvious. After writing the standalone SQL source, call `emit_unmapped_fallback` with `rawPath` set to the MetricFlow file path, `reason: "cumulative_metric_unsupported"`, and `fallback: "sql_standalone"`.
+
+## Conversion metrics — flag for human
+
+```yaml
+metrics:
+  - name: signup_to_first_order
+    type: conversion
+    type_params:
+      conversion_type_params:
+        entity: customer
+        base_measure: signup_count
+        conversion_measure: first_order_count
+        window: 30 days
+```
+
+Do NOT emit SL for this. Instead:
+- Write a wiki page at `knowledge/global/<metric_name>-intent.md` quoting the full YAML body and a one-line explanation of the intended semantics (base event → conversion event within window).
+- Call `emit_unmapped_fallback` with `rawPath` set to the MetricFlow file path, `reason: "conversion_metric_unsupported"`, and `fallback: "flagged"`.
+
+When KTX SL gains conversion primitives, re-ingesting will find the prior wiki note (via `priorProvenance`) and replace it with an SL source.
+
+## Provenance markers
+
+Every overlay/standalone/wiki page emitted from a MetricFlow source carries HTML-comment provenance tags. When one overlay derives from multiple files (e.g. an extends chain), emit one tag per contributing file:
+
+```yaml
+# <!-- from: raw-sources/conn-1/metricflow/<syncId>/models/orders.yml#L1-20 -->
+# <!-- from: raw-sources/conn-1/metricflow/<syncId>/models/orders_ext.yml#L1-12 -->
+# <!-- from: raw-sources/conn-1/metricflow/<syncId>/metrics/orders_final.yml#L1-10 -->
+name: orders_ext
+...
+```
+
+Line ranges (`#L<start>-<end>`) point to the exact YAML span within the file (the `semantic_models:` entry for its own `name`). Use `read_raw_span` to identify those ranges before writing.
+
+## Example 1 — single semantic_model to overlay
+
+```yaml
+# MetricFlow:
+semantic_models:
+  - name: orders
+    model: ref('orders')
+    entities:
+      - {name: order_id, type: primary}
+    measures:
+      - {name: order_count, agg: count, expr: order_id}
+      - {name: gross_amount, agg: sum, expr: amount}
+```
+
+```yaml
+# KTX overlay at <connId>/orders.yaml:
+# <!-- from: raw-sources/.../models/orders.yml#L1-10 -->
+name: orders
+description: Order fact table.
+measures:
+  - {name: order_count, expr: "count(order_id)"}
+  - {name: gross_amount, expr: "sum(amount)"}
+grain: [order_id]
+```
+
+## Example 2 — extends chain → one flattened overlay
+
+```yaml
+# MetricFlow:
+# models/orders.yml
+semantic_models:
+  - name: orders
+    model: ref('orders')
+    measures:
+      - {name: order_count, agg: count, expr: order_id}
+      - {name: gross_amount, agg: sum, expr: amount}
+
+# models/orders_ext.yml
+semantic_models:
+  - name: orders_ext
+    model: ref('orders_ext')
+    extends: orders
+    measures:
+      - {name: refund_amount, agg: sum, expr: refund_amt}
+
+# metrics/orders_final.yml
+metrics:
+  - name: revenue
+    type: derived
+    type_params:
+      expr: gross_amount - refund_amount
+      metrics:
+        - {name: gross_amount}
+        - {name: refund_amount}
+```
+
+```yaml
+# KTX overlay at <connId>/orders_ext.yaml (one file; inheritance flattened):
+# <!-- from: raw-sources/.../models/orders.yml#L1-10 -->
+# <!-- from: raw-sources/.../models/orders_ext.yml#L1-8 -->
+# <!-- from: raw-sources/.../metrics/orders_final.yml#L1-10 -->
+name: orders_ext
+description: Extended order fact including refund handling; `revenue` = gross - refund.
+measures:
+  - {name: order_count, expr: "count(order_id)"}
+  - {name: gross_amount, expr: "sum(amount)"}
+  - {name: refund_amount, expr: "sum(refund_amt)"}
+  - {name: revenue, expr: "gross_amount - refund_amount"}
+grain: [order_id]
+```
+
+## Example 3 — derived metric spanning two semantic_models
+
+```yaml
+# models/sales.yml
+semantic_models:
+  - name: sales
+    model: ref('sales')
+    measures:
+      - {name: revenue, agg: sum, expr: revenue_cents}
+# models/costs.yml
+semantic_models:
+  - name: costs
+    model: ref('costs')
+    measures:
+      - {name: cost, agg: sum, expr: cost_cents}
+# metrics/margin.yml
+metrics:
+  - name: margin
+    type: derived
+    type_params:
+      expr: revenue - cost
+      metrics: [{name: revenue}, {name: cost}]
+```
+
+Because the WorkUnit bundles all three files (cross-component union via the metric), write the derived measure on ONE of the two sources — pick the source whose domain "owns" the metric (here, `sales` — margin is inherently a sales metric). Cross-source references aren't native in KTX SL; treat the metric's operands as already-resolvable in the target source's query context OR emit a standalone SQL that joins the two tables:
+
+```yaml
+# <connId>/sales.yaml
+# <!-- from: .../models/sales.yml#L1-8 -->
+# <!-- from: .../models/costs.yml#L1-8 -->
+# <!-- from: .../metrics/margin.yml#L1-8 -->
+name: sales
+measures:
+  - {name: revenue, expr: "sum(revenue_cents)"}
+```
+
+```yaml
+# <connId>/margin.yaml — standalone because it spans two tables
+# <!-- from: .../models/sales.yml#L1-8 -->
+# <!-- from: .../models/costs.yml#L1-8 -->
+# <!-- from: .../metrics/margin.yml#L1-8 -->
+name: margin
+source_type: sql
+sql: |
+  SELECT s.period_id, s.revenue_cents, COALESCE(c.cost_cents, 0) AS cost_cents
+  FROM analytics.sales s
+  LEFT JOIN analytics.costs c ON c.period_id = s.period_id
+grain: [period_id]
+columns:
+  - {name: period_id, type: string}
+  - {name: revenue_cents, type: number}
+  - {name: cost_cents, type: number}
+measures:
+  - {name: revenue, expr: "sum(revenue_cents)"}
+  - {name: cost, expr: "sum(cost_cents)"}
+  - {name: margin, expr: "sum(revenue_cents) - sum(cost_cents)"}
+```
+
+Also write a wiki page at `knowledge/global/margin-metric.md` explaining the cross-source origin.
+
+## Example 4 — filtered metric creates a new measure
+
+```yaml
+metrics:
+  - name: paid_order_count
+    type: simple
+    type_params:
+      measure: order_count
+    filter: "{{ Dimension('orders__status') }} = 'paid'"
+```
+
+```yaml
+# <connId>/orders.yaml
+measures:
+  - {name: order_count, expr: "count(order_id)"}
+  - {name: paid_order_count, expr: "count(order_id)", filter: "status = 'paid'"}
+```
+
+Translate `{{ Dimension('orders__status') }}` to the bare column name `status` (the table alias prefix is implicit within the SL source's scope).

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

@@ -0,0 +1,69 @@
+---
+name: notion_synthesize
+description: Synthesize durable KTX wiki pages and semantic-layer sources from staged Notion pages, databases, data-source rows, and clustered Notion evidence. Load when a WorkUnit contains Notion raw files or Notion evidence chunks.
+callers: [memory_agent]
+---
+
+# Notion Cluster Synthesis
+
+Use this skill when a WorkUnit contains staged Notion content from `pages/**`, `databases/**`, `data-sources/**`, or clustered Notion evidence.
+
+## Role
+
+Each WorkUnit is either a single Notion page/span or a topical cluster of related Notion pages, pre-grouped by embedding similarity. Read the assigned raw files, then write a small set of durable wiki entries and, when applicable, semantic-layer sources that synthesize the WorkUnit's knowledge. Write final memory directly; do not write candidates.
+
+## Required Workflow
+
+1. Read the WorkUnit notes and rawFiles list. Page content lives in `page.md`; `metadata.json` holds title, path, object type, data-source ids, last edited metadata, and properties.
+2. For each assigned page, call `read_raw_file`, or `read_raw_span` for oversized pages when the notes specify a span.
+3. Search `wiki_search` for existing pages that overlap the WorkUnit topics. Prefer updating an existing page over creating a duplicate.
+4. Use `context_evidence_search`, `context_evidence_read`, and `context_evidence_neighbors` to pull supporting chunks when indexed evidence is relevant. Pass `chunkId` and `documentId` values verbatim as returned by the evidence tools.
+5. Write durable business knowledge with `wiki_write`. Aim for a small number of high-quality pages per WorkUnit or cluster.
+6. When the Notion content defines a reusable dataset, metric, segment, join rule, source-of-truth mapping, or table with explicit columns, load `sl_capture`, discover existing sources first with `sl_discover` or `sl_read_source`, then use `sl_write_source` or `sl_edit_source`.
+7. For every deleted raw path in the Eviction Set, call `eviction_list`, decide retention, then `context_eviction_decision_write`. Do this even when no wiki write is needed.
+
+## What To Capture
+
+Capture durable, reusable company knowledge:
+
+- metric definitions, KPI formulas, named business concepts, and reusable filters
+- workflows, policies, ownership rules, approval conventions, and source-of-truth mappings
+- data-source row pages that describe tables, columns, semantic models, dashboards, or business entities
+- cross-system aliases connecting Notion terms to warehouse, dbt, Looker, Metabase, or MetricFlow names
+- caveats, conflicts, supersession notes, and customer/product assumptions affecting future analysis
+
+Skip noisy or transient content:
+
+- meeting notes with no reusable rule
+- task lists, project status updates, and time-bounded snapshots
+- duplicate docs with no new fact
+- database metadata pages when row pages contain the actual business content
+- transient announcements and long page summaries
+
+## Quality
+
+Prefer fewer, stronger entries. Every wiki entry must cite at least one Notion page or row using its path and last edited date when available. When evidence conflicts, write a conflict note inside the wiki page rather than choosing silently.
+
+If a clustered WorkUnit includes several related pages, synthesize the shared rule or concept instead of writing one thin page per source. For oversized page spans, read only the assigned span unless the WorkUnit explicitly asks for neighboring context.
+
+## Citation Style
+
+```md
+## Revenue Recognition
+- Booked revenue excludes refunds and test accounts.
+- Source: Notion - Company Handbook / Finance / Revenue Recognition, last edited 2026-04-12.
+- Conflict note: An older Sales Ops page uses gross revenue before refunds; treat the Finance Handbook as current unless Finance says otherwise.
+```
+
+## Semantic-Layer Rules
+
+- Load `sl_capture` before writing or editing SL sources.
+- Discover existing sources first with `sl_discover`; read existing source YAML before editing.
+- Prefer overlays on manifest-backed sources over standalone SQL.
+- If Notion describes a dashboard or metric but does not define executable logic, write a wiki page and attach `sl_refs` only after confirming the referenced source exists.
+
+## Tools
+
+Allowed: `read_raw_file`, `read_raw_span`, `wiki_search`, `wiki_read`, `wiki_write`, `sl_discover`, `sl_read_source`, `sl_write_source`, `sl_edit_source`, `sl_validate`, `context_evidence_search`, `context_evidence_read`, `context_evidence_neighbors`, `eviction_list`, `context_eviction_decision_write`.
+
+Not allowed: `context_candidate_write`, `context_candidate_mark`.

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

@@ -0,0 +1,240 @@
+---
+name: sl
+description: KTX's semantic layer — a structured catalog of sources (tables/views), measures, joins, and segments expressed as YAML. Covers the schema and how to query it via `semantic_query`. Use when the task involves querying pre-defined metrics (ARR, churn, retention, LTV, MAU) or reading SL source YAML to understand the catalog. Capture is handled by the `sl_capture` skill (memory-agent only).
+---
+
+# Semantic Layer
+
+KTX's semantic layer (SL) is a structured catalog. Each **source** represents a table, a SQL view, or an overlay that enriches a manifest-backed table with measures, computed columns, joins, and named segments. The catalog is the single source of truth for reusable business metrics.
+
+This skill covers two parts:
+- **Part 1** — Schema reference (what an SL source looks like).
+- **Part 2** — Querying via `semantic_query`.
+
+Capture (when and how to add new patterns to the SL) is a separate concern handled by the memory-agent — see the `sl_capture` skill if you are running in capture mode. The research agent **reads** and **queries** the SL via the tools described here; it does not write to it.
+
+---
+
+## Part 1 — Schema reference
+
+An SL source is a YAML file at `semantic-layer/<connectionId>/<source_name>.yaml`. There are three flavors:
+
+### Overlay sources
+
+Enrich a manifest-backed table with measures, computed columns, joins, and segments. No `table` or `sql` field. The base table's columns and grain are inherited from the manifest.
+
+```yaml
+name: fct_orders           # must match an existing manifest table
+description: "Overlay adding business measures to the orders fact table."
+measures:
+  - name: total_revenue
+    expr: sum(amount)
+    description: Total order revenue — filter by status or region at query time
+columns:                    # computed dimensions only
+  - name: is_large_order
+    type: boolean
+    expr: "amount > 1000"
+segments:
+  - name: paid_non_refunded
+    expr: "is_paid = true AND is_refunded = false"
+joins:
+  - to: customers
+    on: "customer_id = customers.id"
+    relationship: many_to_one
+```
+
+Rules:
+- Do **not** repeat base-table columns, grain, `table`, or `source_type` in an overlay — those are inherited.
+- Overlay columns MUST be computed (`expr` + `type`).
+- `exclude_columns` hides specific manifest columns; `disable_joins` suppresses specific auto-detected joins.
+
+### Standalone table sources
+
+Self-contained; own their schema. Has `source_type: table` and `table:`.
+
+```yaml
+name: account_health_scores
+source_type: table
+table: "analytics.account_health_scores"
+grain: [account_id, snapshot_date]
+columns:
+  - name: account_id
+    type: string
+  - name: snapshot_date
+    type: time
+    role: time
+  - name: health_score
+    type: number
+measures:
+  - name: avg_health_score
+    expr: avg(health_score)
+```
+
+### Standalone SQL sources
+
+Self-contained; schema derived from a SQL query. Has `source_type: sql` and `sql:`.
+
+```yaml
+name: monthly_cancellations
+source_type: sql
+sql: |
+  SELECT
+    date_trunc('month', cancelled_at) AS month,
+    customer_id,
+    plan_name,
+    mrr_amount
+  FROM subscriptions
+  WHERE status = 'cancelled'
+grain: [customer_id, month]
+columns:
+  - name: month
+    type: time
+    role: time
+  - name: customer_id
+    type: string
+  - name: plan_name
+    type: string
+  - name: mrr_amount
+    type: number
+measures:
+  - name: cancellation_count
+    expr: count(*)
+```
+
+An SQL source is a one-shot answer: the aggregation is frozen, callers cannot re-group or re-filter by columns the SQL has collapsed, and the source is disconnected from the join graph. Prefer overlays + measures over SQL sources when possible — the `sl_capture` skill covers when SQL is justified.
+
+### Columns
+
+Every standalone column requires `name` and `type`. Overlays have computed columns only.
+
+- `type`: one of `string`, `number`, `boolean`, `time`. Map LookML `date`/`datetime`/`timestamp` → `time`. Map LookML `yesno` → `boolean`.
+- `role` (optional): `time` enables time-granularity queries (month, week, day). `default` is the implicit fallback.
+- `visibility` (optional): `public`, `internal`, or `hidden`.
+- `expr` (optional for standalone, required for overlay columns): SQL expression that computes the value. Expanded by sqlglot before generating SQL, so you can reference other columns on the same source.
+
+### Grain
+
+`grain: [col_a, col_b]` — the set of columns that uniquely identify one row. The query engine uses grain to prevent fan-out in joins. Overlays inherit grain from the manifest unless they override.
+
+### Joins
+
+```yaml
+joins:
+  - to: customers                                    # target source name
+    on: "customer_id = customers.id"                 # local_col = TARGET.target_col
+    relationship: many_to_one                        # or one_to_many, one_to_one
+    alias: primary_customer                          # optional — lets you join the same target twice
+```
+
+- `on` format: `local_col = TARGET.target_col`. Always qualify the right side with the target source name.
+- `relationship` is the cardinality **from this source to the target**. Most joins are `many_to_one` (FK → PK on the parent).
+
+### Measures
+
+```yaml
+measures:
+  - name: total_arr
+    expr: sum(arr_amount)
+    description: Sum of ARR — filter by plan_name at query time
+    filter: "is_active = true"
+    segments: [paid_non_refunded]
+```
+
+- `name` (required, snake_case).
+- `expr` (required): any valid SQL aggregate — `sum(x)`, `count(*)`, `count(distinct user_id)`, `avg(score)`.
+- `description` (required on capture): what the measure computes and how to use it.
+- `filter` (optional): SQL predicate applied as a WHERE clause specific to this measure.
+- `segments` (optional): names of segments defined on the same source. The engine AND-composes each segment's `expr` into this measure's effective filter.
+
+Use `safe_divide(num, den)` for ratio measures to avoid division by zero.
+
+### Segments
+
+```yaml
+segments:
+  - name: paid_non_refunded
+    expr: "is_paid = true AND is_refunded = false"
+    description: Orders that were paid and not refunded
+```
+
+Named, reusable boolean predicates scoped to one source. Reference by bare name in a measure's `segments: []`, or by dotted form `source.segment_name` in a `semantic_query`. Segments are predicates only — they are NOT selectable as dimensions. If you need to group by the predicate, add a `columns[]` entry instead.
+
+### Cross-references with the wiki
+
+The reverse edge (wiki pages that cite this source) is derived automatically from each wiki's `sl_refs:` — you don't emit anything on the SL side. Author the edge once on the wiki via `sl_refs:`; the post-write reconciler populates the knowledge↔SL index.
+
+---
+
+## Part 2 — Querying via `semantic_query`
+
+The `semantic_query` tool generates correct SQL from a structured query. It handles joins, fan-out prevention, aggregation correctness, and filter classification automatically. Prefer it over writing raw SQL whenever the SL has the relevant sources.
+
+### When to prefer semantic_query over raw SQL
+
+- A pre-defined measure already exists (`source.measure_name` appears in the catalog).
+- The question combines fields from multiple sources — the engine resolves the join path automatically.
+- The question asks for a standard metric (revenue, ARR, churn, retention, LTV, conversion, MAU, etc.) — even if no pre-defined measure exists, a runtime aggregation over a catalog column is usually correct.
+
+Use raw SQL (`sql_execution`) only when:
+- The computation requires multi-step CTEs whose intermediate grain is not a column in any source.
+- The question explicitly asks for a one-off exploration that will never be asked again.
+
+### Input shape
+
+```json
+{
+  "connectionId": "uuid-of-the-connection",
+  "reasoning": "Brief note on what this query analyzes",
+  "query": {
+    "measures": ["orders.total_revenue", "sum(orders.amount)"],
+    "dimensions": ["customers.segment", { "field": "orders.created_at", "granularity": "month" }],
+    "filters": ["orders.status != 'cancelled'", "orders.total_revenue > 10000"],
+    "segments": ["orders.paid_non_refunded"],
+    "order_by": [{ "field": "orders.created_at", "direction": "desc" }],
+    "limit": 1000
+  }
+}
+```
+
+- **`measures`**: mix pre-defined refs (`source.measure`) and runtime aggregations (`sum(source.column)`).
+- **`dimensions`**: column refs or `{ field, granularity }` objects for time grains (`day`, `week`, `month`, `quarter`, `year`).
+- **`filters`**: free-form SQL predicates. The engine auto-classifies each as WHERE or HAVING based on whether it references an aggregated measure.
+- **`segments`**: dotted `source.segment_name`. Each segment is AND-ed into the effective filter of every measure whose base source matches. Segments never become a global WHERE — use `filters` for cross-source predicates.
+- **`order_by`**: string or `{ field, direction }`. Direction defaults to `asc`.
+- **`limit`**: integer row cap.
+
+### Join resolution
+
+You don't specify a base table. The engine infers the set of sources needed from the fields you reference and resolves the shortest join path through the catalog's declared joins. If no path exists between two sources, the query fails with a path-not-found error — check `discover_data` or `sl_discover` to see which sources are connected.
+
+### Worked examples
+
+Cross-source query — engine resolves `account_health_scores → accounts ← opportunities` automatically:
+
+```json
+{
+  "measures": ["account_health_scores.avg_health_score"],
+  "dimensions": ["opportunities.stage"],
+  "filters": ["opportunities.stage != 'Closed Won'"]
+}
+```
+
+Monthly ARR trend with a segment:
+
+```json
+{
+  "measures": ["subscriptions.arr"],
+  "dimensions": [{ "field": "subscriptions.month", "granularity": "month" }],
+  "segments": ["subscriptions.paid_non_refunded"],
+  "order_by": [{ "field": "subscriptions.month", "direction": "asc" }]
+}
+```
+
+Multi-source with runtime aggregation:
+
+```json
+{
+  "measures": ["sum(orders.amount)", "count(support_tickets.ticket_id)"],
+  "dimensions": ["customers.segment"]
+}
+```