@oxy-hq/cli 0.7.0 → 0.9.0

package/skills/oxy-evals/references/results-json.md

@@ -0,0 +1,145 @@
+# Reading `oxy test` results
+
+`oxy test <file> --output-json` writes `<file without .yml>.results.json` next to the test
+file (`tests/sales.performance.test.yml` → `tests/sales.performance.test.results.json`).
+Without a file argument it writes `test-results.json` in the current directory.
+`--format json` prints the same document on stdout.
+
+## Shape
+
+The file is a JSON array with **one element per test file**:
+
+```jsonc
+[
+  {
+    "test_name": "sales.performance.test.yml",
+    "errors": [                       // one string per run that produced no answer
+      "agentic pipeline asked a clarifying question: Which region do you mean?"
+    ],
+    "stats": {
+      "total_attempted": 9,           // cases × runs
+      "answered": 8                   // runs that returned an answer (judged or not)
+    },
+    "metrics": [
+      {
+        "type": "Correctness",        // the only metric `oxy test` produces
+        "score": 0.6667,              // mean of every record's score in this file
+        "records": [
+          {
+            "prompt": "What was total revenue across all stores in 2025?",
+            "expected": "Total revenue across all stores in 2025 was approximately $6.7 billion.",
+            "actual_output": "Total revenue in 2025 was $6.74B across 45 stores…",
+            "cot": "1. Key facts in the expected answer… Verdict: PASS",
+            "choice": "PASS",         // PASS or FAIL
+            "score": 1.0,             // 1.0 for PASS, 0.0 for FAIL — never partial
+            "duration_ms": 18234.5,
+            "input_tokens": 41210,
+            "output_tokens": 1830
+          }
+          // … one record per run: `runs: 3` gives 3 records per case
+        ]
+      }
+    ]
+  }
+]
+```
+
+What is **not** in it: the SQL, the tool calls, the rows the agent saw. Records for an
+`.agentic.yml` target carry no `references` array. Diagnose the path with the commands under
+"Seeing what the agent did" below.
+
+## Field by field
+
+| Field | Use it for |
+| --- | --- |
+| `prompt` | Grouping. A case's runs share the same prompt string. |
+| `expected` | The specification, exactly as written in the test file. |
+| `actual_output` | The agent's final answer. This is your main evidence. `[ERROR] …` means the run failed. |
+| `cot` | The judge's whole response: its reasoning, then its verdict line. |
+| `choice` | The parsed verdict. Compare it with `cot` to spot judge parse problems. |
+| `score` | `choice` as a number. |
+| `duration_ms`, `*_tokens` | Cost and latency of the agent run, not of the judge. Zero on errored runs. |
+| `errors` | The error text of every run that never answered, in run order. |
+| `stats.answered` vs `total_attempted` | The answer rate. A gap means runs ended in errors. |
+
+## Ordering
+
+Answered runs come first, in case order. **Errored runs are appended at the end of
+`records`**, each with `choice: "FAIL"`, `actual_output: "[ERROR] <message>"` and
+`cot: "Run failed with error: <message>"`. Don't assume a case's runs are adjacent. Group by
+`prompt`.
+
+## How the verdict is parsed
+
+The judge gets one prompt: the question, the expected answer and the agent's answer. It's
+asked to list the expected answer's key facts, check whether the agent's answer contains them,
+look for contradictions or significant omissions, ignore formatting, style, phrasing and level
+of detail, allow extra correct information, and end with `PASS` or `FAIL`.
+
+The verdict is read from the **last five lines** of the judge's response:
+
+- A line that contains `PASS` and not `FAIL` → PASS.
+- A line that contains `FAIL` → FAIL. That includes a line containing both words, such as an
+  echoed `Verdict: PASS or FAIL`.
+- No verdict in the last five lines → **FAIL**.
+
+So a judge false negative usually looks like this: the `cot` reasoning concludes the answer
+matches, but the verdict is missing, buried higher up, or written as "PASS or FAIL". The fix
+for that is the judge model, never the agent.
+
+## Recipes
+
+Without tools: for a single `--case` run, the file is small, so read it whole. For a full
+suite, search the file for a distinctive phrase from the prompt and read the records around
+each hit.
+
+With `jq`:
+
+```bash
+R=tests/sales.performance.test.results.json
+
+# Pass count per case
+jq -r '.[].metrics[] | select(.type=="Correctness") | .records
+       | group_by(.prompt)[] | "\(map(.score)|add|floor)/\(length)  \(.[0].prompt)"' "$R"
+
+# Every answer to one case, side by side
+jq -r '.[].metrics[].records[] | select(.prompt | test("total revenue"; "i"))
+       | "\(.choice)  \(.actual_output)\n"' "$R"
+
+# Failing runs with the judge's reasoning
+jq -r '.[].metrics[].records[] | select(.score < 1)
+       | "## \(.prompt)\n\(.actual_output)\n--- judge ---\n\(.cot)\n"' "$R"
+
+# Runs that never answered
+jq -r '.[].errors[]' "$R"
+```
+
+## Seeing what the agent did
+
+The results only show answers. To see the route an answer took, replay the prompt:
+
+```bash
+oxy agentic run <path/to/agent.agentic.yml> -q "<prompt>" --json
+```
+
+This needs `OXY_DATABASE_URL` (a Postgres URL; the command records the run there). It prints
+one JSON object per line, `{"seq", "event_type", "payload"}`. The events that matter for
+diagnosis:
+
+| `event_type` | What to read in `payload` |
+| --- | --- |
+| `semantic_shortcut_attempted` / `semantic_shortcut_resolved` | whether the semantic model answered directly |
+| `spec_resolved` | the tables, joins and assumptions the agent settled on |
+| `query_generated` | SQL the model wrote |
+| `query_executed` | `query`, `row_count`, `rows` (a preview), `error`, and `source`: `semantic`, `llm`, `verified_sql` or `vendor` |
+| `analytics_validation_failed` | `state`, `reason`: a check that sent the agent back to retry |
+
+Run it two or three times for a flaky case. Different `source` values or different SQL across
+runs is the flakiness, made visible.
+
+## The pretty report
+
+Without `--format json`, each case prints as `PASS (n/n)`, `FLKY (k/n)` or `FAIL (0/n)`,
+followed by the file's Correctness score and a `Failures:` section with the judge's reasoning.
+`-v` adds each failing run's actual answer, and `-q` prints only the summary. The footer gives
+the overall `Tests: x/y passed`, the answer rate, the time taken and the token totals.

package/skills/oxy-evals/references/writing-expected.md

@@ -0,0 +1,112 @@
+# Writing `expected` answers
+
+The judge PASSes an answer that contains the **core factual content** of `expected`, with no
+contradiction and no significant omission. It ignores formatting, style, phrasing and level of
+detail, and it allows extra correct information. Every word in `expected` is therefore a fact
+the agent must state. Write only the facts that must hold, as the answer a careful analyst
+would give.
+
+## By question type
+
+**Single aggregate**
+
+```text
+Total revenue across all locations in 2025 is approximately $6.7 billion.
+```
+
+**Ranking.** Give the criterion once, the top entries with anchor values, and the bottom of the
+list if it matters.
+
+```text
+The top 5 stores by 2025 net sales are led by Store 20 (~$301M) and Store 4 (~$299M);
+the fifth, Store 13, is at ~$287M.
+```
+
+**Trend.** Give the direction, the current value, and one or two notable points.
+
+```text
+Weekly orders in Q4 2025 rose from ~11K in early October to a peak of ~19K in the
+week of 24 November, then settled near ~14K in December.
+```
+
+**Comparison between groups**
+
+```text
+In 2025, stores in the West region averaged ~$1.2M monthly sales, about 15% above the
+~$1.04M average of the other regions.
+```
+
+**Share or ratio.** Say what the denominator is.
+
+```text
+Returns were ~4.2% of units sold in 2025 (about 52K of 1.24M units).
+```
+
+**Filter on a rare value.** Assert the scope, so an answer that ignores the filter fails.
+
+```text
+Only 3 orders in 2025 used the GIFTCARD50 promotion, totalling ~$410.
+```
+
+**An empty result that is the correct answer**
+
+```text
+There were no refunds issued on 25 December 2025.
+```
+
+**Unanswerable as asked.** Give the reason, and what a good answer offers instead.
+
+```text
+Margin by product can't be computed because cost data is only recorded at the category
+level. A correct answer explains this and offers margin by category instead.
+```
+
+## Evidence rules
+
+- **Trust facts that agree across runs over any single run.** Two or more agreeing runs are
+  the minimum for a full `expected`.
+- **A "successful" run can still be a failure.** Treat these as non-answers, not evidence:
+  - an answer with no figures where figures were asked for
+  - a ranked list whose metric values are all blank or null
+  - an answer built on a row-capped or truncated result, when the question needed every row
+- **Separate transient errors from systematic ones.** A connection reset or a timeout can
+  vanish on a re-run. The same error on every run is a finding to report, not noise.
+- **Verify before you encode.** If you can query the data yourself, cross-check the headline
+  number. A stable answer can be stably wrong: a wrong join, a double-counted fact table, the
+  wrong date column. Encoding it turns a bug into the specification.
+- **When evidence is thin, narrow the placeholder instead of guessing:**
+
+```yaml
+expected: >-
+  DRAFT: all 3 runs agree the West region leads; the size of the lead varied
+  (12%–31%) — needs a verified figure.
+```
+
+## Relative time
+
+If the prompt says "last month" and the runs show the agent resolved it to November 2025,
+rewrite **both** sides: the prompt becomes "…in November 2025?", and `expected` uses the same
+period. Leaving the prompt relative makes the test start failing next month. The agent
+resolves relative dates against today in its `timezone:` (UTC when unset).
+
+## When to split, rewrite, or flag a case
+
+- **Split** a prompt that asks two things. The judge fails the whole run if either half is
+  missing, so you can't tell which half broke.
+- **Propose a rewrite** when the runs answer different, reasonable readings of the prompt
+  (net or gross, calendar or fiscal year), or when the agent stops to ask a clarifying
+  question. That ends the run as an error. Show the user the readings you saw, and let them
+  choose.
+- **Flag, don't draft,** when no view or table holds the data. That's a gap in the agent, not
+  something a test can fix.
+
+## Checklist before saving
+
+- [ ] Every case has a `name:` slug.
+- [ ] No relative dates remain in prompts that `expected` depends on.
+- [ ] Numbers are approximate unless they're exact and stable.
+- [ ] No schema, view or column names the user wouldn't say.
+- [ ] No `expected` was copied from a single run without agreement or verification.
+- [ ] Uncertain cases carry a narrowed `DRAFT:` note, not an invented value.
+- [ ] The file parses: run it by path once (`oxy test <file> --case 0`). Discovery skips a
+      broken file silently.

package/skills/oxy-semantic-modeling/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: oxy-semantic-modeling
-description: Use when writing, reviewing, or debugging an Oxy semantic model — `.view.yml` views, `.topic.yml` topics, measures, dimensions, entities, and the `meta:` freshness block — in a customer workspace, and when one misbehaves: a measure that vanishes after switching topics, "measure not found", a topic returning no rows or missing joins, or an agent reporting a partial day as a complete number. Carries the craft and the traps the reference docs do not.
+description: >-
+  Use when writing, reviewing, or debugging an Oxy semantic model — `.view.yml` views,
+  `.topic.yml` topics, measures, dimensions, entities, pre-aggregations (rollups), and the
+  `meta:` freshness block — in a customer workspace, and when one misbehaves: a measure that
+  vanishes after switching topics, "measure not found", a topic returning no rows or missing
+  joins, a date filter failing with `TYPE_MISMATCH`, a rollup that never serves, or an agent
+  reporting a partial day as a complete number. Carries the craft and the traps the reference
+  docs do not.
 ---
 
 # Oxy semantic modeling
@@ -12,8 +19,16 @@ description: Use when writing, reviewing, or debugging an Oxy semantic model —
 
 That page owns the field lists. This skill deliberately does **not** restate
 them — a copied schema stays confidently wrong long after the real one moves.
-What follows is the craft and the traps it does not carry, with every example
-taken from Poke House's real 39 views and 23 topics.
+What follows is the craft and the traps it does not carry, with examples taken
+from one production workspace's 39 views and 23 topics.
+
+**Read next:**
+
+- [templates/view-template.yml](templates/view-template.yml) and
+  [templates/topic-template.yml](templates/topic-template.yml) — annotated
+  starting points for a new view or topic.
+- [references/warehouse-casts.md](references/warehouse-casts.md) — the
+  per-warehouse cast for a date column that is not stored as a date.
 
 ## View anatomy
 
@@ -23,7 +38,7 @@ against it.
 ```yaml
 name: sales_daily
 datasource: "clickhouse"
-table: "restaurant_analytics.restaurant_analytics___sales_daily_metrics"
+table: "restaurant_analytics.sales_daily_metrics"
 ```
 
 **`entities` are the join graph, not decoration.** The `primary` entity names
@@ -41,20 +56,31 @@ entities:
     key: restaurant_id
 ```
 
-**`key` names a dimension, not a column.** In `restaurants.view.yml` the entity
+**`key` names a dimension, not a column.** In a `restaurants` view the entity
 `restaurant` has `key: restaurant_id`, and the `restaurant_id` *dimension* is
 `expr: guid` — the physical column is `guid`. So resolve a `key` against the
 view's `dimensions:` list, never against the table's columns; the reference's
 `entities` page carries the same warning.
 
+**Declare a foreign entity for every foreign-key column.** When a fact view
+holds an ID pointing at another view's primary key (`orders.restaurant_id` →
+`restaurants.guid`), give the fact view a `type: foreign` entity with the
+**same `name:`** as the lookup view's primary entity and `key:` set to the FK
+dimension. That edge is what lets a query group orders by
+`restaurants.location_name` instead of by the raw ID; without it, every chart
+and table built on the view renders opaque UUIDs. A foreign entity with no
+matching primary anywhere is only a *warning* — the join silently does not
+exist.
+
 **`dimensions`** are what you slice by, **`measures`** what you aggregate. Both
 take `synonyms`; measures also take `filters` and `drivers`. House style keeps
 entity keys single — even a compound natural key is one pre-concatenated
-dimension (`sales_day_key`); no view uses the documented composite `keys:`.
+dimension (`sales_day_key`); no view in the corpus uses the documented
+composite `keys:`.
 
 ## The description is a contract with the agent, not a label
 
-`sales_daily`'s description, verbatim:
+A real `sales_daily` description, verbatim:
 
 > Daily sales metrics aggregated by restaurant and business date. Loaded several
 > times daily; the current business day is always intraday-partial - the prior
@@ -67,21 +93,34 @@ say when the data is complete and what it excludes, not what the table holds.
 
 ## The `meta:` freshness block
 
-Four keys — `freshness_watermark_column`, `freshness_expected_cadence`,
-`freshness_complete_through`, `freshness_caveat` — that state a view's own lag
-characteristics so the agent can qualify an answer instead of guessing.
+Four keys that state a view's own lag characteristics, so the analytics agent
+can qualify an answer instead of guessing:
+
+```yaml
+meta:
+  freshness_watermark_column: ["business_date"]
+  freshness_expected_cadence: ["several times daily"]
+  freshness_complete_through: ["prior full day (America/Los_Angeles)"]
+  freshness_caveat: ["Current business day is intraday-partial."]
+```
 
 **Only 11 of 39 views carry one.** That low number is the point: it is the most
 under-used high-value feature in a real model, and adding one is the cheapest
 quality win available on any view fed by a batch pipeline.
 
-- **It is undocumented.** Not one of the four keys appears anywhere in the docs,
-  and `views.mdx`'s own property table does not list `meta`. It is a working
-  project convention, not a schema feature you can look up. **Copy the block from
-  `sales_daily.view.yml`** — that is the canonical exemplar.
-- **Every value is wrapped as a single-element list** (`["prior full day
-  (America/Los_Angeles)"]`) even though each reads as a scalar. "Simplifying" it
-  to a bare string silently deviates from all 11 existing blocks.
+- **`meta:` is a schema field; the four key names are a convention.** `meta`
+  exists on views (and dimensions, measures, entities, segments and topics),
+  typed as a map from a key to a **list of strings**. That is why every value
+  is a one-element list: a bare string (`freshness_caveat: "…"`) fails to
+  parse. The four `freshness_*` names appear in no docs page; the analytics
+  agent reads them by name and uses the first element of each.
+- **The watermark resolves against dimensions first.**
+  `freshness_watermark_column` may name a dimension (or match its `expr`); if
+  it matches neither, it is used as a raw column. **Without the key, the agent
+  falls back to the view's first `date`/`datetime` dimension** — which may be
+  an order date rather than the load watermark, so declare it.
+- A view-level `refresh_key: { sql: … }` (see Pre-aggregations) doubles as the
+  agent's recency probe for the view.
 
 ## Craft
 
@@ -99,6 +138,29 @@ English onto one name; colliding common words across views is normal and wanted.
 filters on `"PAID"` instead of inventing `"paid"`. Give the *full* set, not a
 sample — `["OPEN", "PAID", "CLOSED"]`, `["negative", "neutral", "positive"]`.
 
+**`samples` is always a list of strings — even on a `boolean` or `number`
+dimension.** Write `samples: ["true", "false"]` and `samples: ["5", "10"]`,
+never `[true, false]` or `[5, 10]`. The field only accepts strings, and one
+bare literal makes the view fail to load — and with it the whole semantic
+model, not just that view. The reference's `dimensions` page shows a numeric
+example with bare numbers; do not copy it.
+
+**"Aggregate X where Y" is a filtered measure, not a `custom` `CASE WHEN`.**
+Write a typed measure (`sum`, `count`, `average`, …) with a `filters:` list:
+
+```yaml
+  - name: delivery_revenue
+    type: sum
+    expr: order_amount
+    filters:
+      - expr: "order_type = 'delivery'"   # raw column SQL, or {{dimension}} — see Traps
+```
+
+It reads better, and it re-aggregates: a filtered `sum` can be answered from a
+pre-aggregation, while a `custom` measure never can (nor can `median` or
+`number`). Reserve `custom` for what a filtered measure cannot express —
+ratios, correlations, cross-period math.
+
 **Derived time dimensions so the agent never writes date arithmetic.** Ship
 `business_year`, `business_month`, `business_quarter`, `day_of_week`,
 `is_weekend` as dimensions of their own, each re-derived from the raw column
@@ -109,8 +171,7 @@ rather than referencing the base date dimension:
     expr: "toQuarter(toDate(parseDateTimeBestEffort(toString(business_date))))"
 ```
 
-**`drivers` must state a mechanism, not a vibe.** The quality bar, from
-`sales_daily`:
+**`drivers` must state a mechanism, not a vibe.** The quality bar:
 
 ```yaml
   - name: total_net_sales
@@ -124,11 +185,30 @@ rather than referencing the base date dimension:
 
 Note what the `description` does: it names the causal path *and* says why the
 obvious alternative (discount dollars) was rejected. The weak examples in the
-corpus — in `quickbooks_pl.view.yml` — carry `direction`, `strength`,
-`confidence`, and a `lag`, but no `description` at all, so the mechanism is never
-stated and a reader cannot tell whether the edge was reasoned or guessed. A
-driver without a `description` is not finished. Only 8 of 39 views use
-`drivers`, and the field is absent from the semantic-model docs — see the traps.
+corpus carry `direction`, `strength`, `confidence`, and a `lag`, but no
+`description` at all, so the mechanism is never stated and a reader cannot tell
+whether the edge was reasoned or guessed. A driver without a `description` is
+not finished. Only 8 of 39 views use `drivers`, and the field is absent from
+the semantic-model docs — see the traps.
+
+## Dates: declare them as dates
+
+A dimension whose meaning is a date or timestamp (`*_date`, `*_at`,
+`business_date`, `created`, `event_time`, …) must be `type: date` (or
+`type: datetime`), and its `expr` must produce a real date — not the raw
+column, if the column is stored as a string, an integer like `20240131`, or
+epoch seconds. Declare it `type: number` or `type: string` instead and nothing
+complains when the view loads; the first query that filters on it compiles a
+date literal the column rejects and fails with **`TYPE_MISMATCH`**.
+
+Sample before you cast — stored formats differ between warehouses and between
+tables in one warehouse, and one `SELECT <col> FROM <table> LIMIT 1` settles it.
+Then wrap the `expr` with the cast for your warehouse:
+[references/warehouse-casts.md](references/warehouse-casts.md). A column
+already typed `DATE` / `TIMESTAMP` needs no cast.
+
+Casting in the view is the fallback, not the goal: when you own the pipeline,
+fix the column type there once (see *Repeated defensive casting* below).
 
 ## Topics are question areas, not tables
 
@@ -146,23 +226,120 @@ views:
   - restaurants
   - dining_options
 default_filters:
-  - field: "is_voided"
+  - field: "orders.is_voided"
     eq:
       value: false
 ```
 
 Name topics after the questions people ask, and let `default_filters` carry the
 "obviously we don't count voided orders" rules so no one has to remember them.
+A topic usually spans several views; "one topic per view" is not the pattern.
+
+**Qualify `default_filters` fields as `view.dimension`.** A bare `field:` is
+resolved against a view *named like the topic*, not against `base_view`. It
+works when the topic shares its base view's name (as above, where
+`is_voided` would also work) and points at nothing when it does not — a topic
+`sales` over `base_view: sales_daily` needs `sales_daily.is_voided`.
+
+## Pre-aggregations (rollups)
+
+A rollup is a materialized partial aggregate of one view. When a query is fully
+covered by one, the engine answers it from the materialized copy instead of
+scanning the warehouse — a few hundred rows instead of millions. They are
+worth adding to views behind dashboards and frequently asked KPIs. The
+reference documents the `config.yml` block in one line and the view-level
+block not at all, so the shape is here.
+
+**Opt-in, per view.** A view with no `pre_aggregations:` block gets **no
+rollups at all** — there is no implicit default (an all-dimensions rollup of a
+wide view is about as large as the table itself).
+
+```yaml
+# in a .view.yml
+refresh_key:                     # view-level default for every rollup below
+  every: "1h"
+
+pre_aggregations:
+  - name: orders_by_month
+    dimensions: [order_status]   # names declared in THIS view, never raw columns
+    measures: [total_orders, total_order_value]
+    time_dimension: order_date   # a date/datetime dimension of this view
+    granularity: month           # second|minute|hour|day|week|month|quarter|year
+  - name: orders_summary         # no dimensions, no time: one summary row
+    measures: [total_orders]
+    refresh_key:                 # per-rollup override
+      sql: "SELECT MAX(updated_at) FROM orders"
+```
+
+- **`refresh_key` takes exactly one of `every` or `sql`** — both, neither, or
+  any other key is a parse error. `sql` re-runs against the warehouse every
+  cycle and rebuilds when its result changes, so keep it a cheap `MAX`.
+- **A rollup that names a member the view does not declare is refused**, not
+  quietly trimmed down to the members that resolve.
+
+**When a rollup serves a query.** All of these must hold, or the query falls
+back to the warehouse — correct, just not accelerated:
+
+- every requested dimension, and every filtered dimension, is in the rollup's
+  `dimensions` (a filter on the `time_dimension` is also fine);
+- every requested measure is in its `measures` **and is re-aggregatable** —
+  `count`, `count_distinct`, `sum`, `average`, `min`, `max`. A `custom`,
+  `number` or `median` measure never serves from a rollup, listed or not;
+- the time dimension matches, and the requested granularity is the stored one
+  or coarser (a `day` rollup serves `month`; a `month` rollup cannot serve
+  `day`);
+- **except `week`**: a `week` rollup does not serve `month`, `quarter` or
+  `year`, because a week straddling a month boundary would land in the wrong
+  month. Store `day` if you need both weekly and monthly answers.
+
+**Limits.** A rollup belongs to one view and holds only that view's members,
+and granularities are the fixed list above — no 15-minute buckets. For a
+multi-view aggregate or a custom bucket, build a rollup *table* with an
+automation instead (`oxy-data-architecture` owns that pattern).
+
+**`config.yml` block** — every key optional:
+
+```yaml
+pre_aggregations:
+  schema: AIRLAYER            # where rollup tables are built (default AIRLAYER)
+  database: warehouse         # connector for builds (default: each view's own datasource)
+  refresh_worker:
+    enabled: true             # default true
+    heartbeat: "10m"          # how often staleness is checked (default 10m, clamped 30s–24h)
+    renewal_threshold: "120s" # how long a refresh_key result is trusted (default 120s, clamped 10s–1h)
+```
+
+## Validating a change
+
+- **`oxy validate --file semantics/views/orders.view.yml`** parses one view or
+  topic file and reports where it fails — a bare boolean in `samples`, a
+  missing `entities:` or `dimensions:` list, a removed feature. Run it on every
+  file you touch. It does **not** look inside `pre_aggregations:` or
+  `refresh_key:`; mistakes there surface only when the model is loaded for a
+  query.
+- Bare **`oxy validate`** (every file) only looks in `semantics/views/` and
+  `semantics/topics/`, while views and topics anywhere in the workspace
+  compile. A view kept elsewhere is only checked with `--file`.
+- Neither checks **cross-file** wiring — an entity join that matches nothing,
+  a topic naming a view that does not exist, a measure that a twin lacks. Run
+  a real query through the topic before calling it done.
+- **`oxy build` does not validate the semantic model** — it rebuilds search
+  embeddings and syncs integrations. `oxy sync` writes table and column
+  metadata to `.databases/`, which is the place to read real column names
+  from.
+- `inherits_from:` and `{{ globals.* }}` were removed from views; a file using
+  either is refused at load. Inline the values.
 
 ## Traps
 
-**The `airhouse_*` twins are a migration artifact, and they are not mirrors.**
-The ClickHouse → Airhouse migration is in flight, so **11 of the 39 views exist
-twice** (22 views, 11 twin pairs) — plus 3 further `airhouse_*` views with no
-ClickHouse counterpart at all, where discount- and payment-level detail lives
-only on the new side. Three consequences, in order of how much time they cost:
+**Twin views from a backend migration are not mirrors.** In the reference
+workspace a ClickHouse → Airhouse migration is in flight, so **11 of the 39
+views exist twice** (22 views, 11 twin pairs) — plus 3 further `airhouse_*`
+views with no ClickHouse counterpart at all, where discount- and payment-level
+detail lives only on the new side. Three consequences, in order of how much
+time they cost:
 
-1. **The twins have diverged.** `sales_daily` defines a `discount_rate` measure;
+1. **The twins diverge.** `sales_daily` defines a `discount_rate` measure;
    `airhouse_sales_daily` does not. Switch topics mid-conversation from one
    family to the other and a query that worked seconds ago fails with "measure
    not found", with nothing anywhere saying the two views were ever supposed to
@@ -172,30 +349,27 @@ only on the new side. Three consequences, in order of how much time they cost:
    the edges — as `airhouse_restaurant`, `airhouse_order`, `airhouse_check`,
    while its twin uses bare `restaurant`, `order`, `check`. Joins resolve by
    matching entity *names*, so a topic mixing families does not error — it just
-   fails to auto-join. You get missing rows, not a config failure. No real topic
-   mixes them; keep it that way.
+   fails to auto-join. You get missing rows, not a config failure. Keep each
+   topic within one family.
 
    **The prefix is not universal, and the exception runs the other way.** The
-   three twin-less views from above leave their **primary** entity bare:
-   `airhouse_order_discounts` → `discount_application`,
-   `airhouse_order_payments` → `payment`, `airhouse_selection_discounts` →
-   `selection_discount_application`. Their foreign entities are still prefixed,
-   so rule 2 holds — but the latent failure inverts. A bare primary is exactly
-   what a ClickHouse-family view would declare, so if anyone ever adds a
-   `payment` or `discount_application` entity on the old side, those two views
-   start auto-joining *across* families rather than failing to join: wrong rows
-   silently, instead of missing rows silently. No such collision exists in the
-   corpus today (grep: each of the three names is declared in exactly one
-   view). Prefix the primary too on any new `airhouse_*` view.
+   three twin-less views leave their **primary** entity bare
+   (`discount_application`, `payment`, `selection_discount_application`).
+   Their foreign entities are still prefixed, so rule 2 holds — but the latent
+   failure inverts. A bare primary is exactly what an old-family view would
+   declare, so if anyone adds a `payment` entity on the old side, the two
+   families start auto-joining *across* the divide: wrong rows silently,
+   instead of missing rows silently. Prefix the primary too on any new view in
+   a migrated family.
 3. **Do not copy the pattern.** Duplicating a view to change backends is a
    migration tactic with an end date, not a modelling technique.
 
-**Repeated defensive casting is a smell.** `toDate(parseDateTimeBestEffort(
-toString(business_date)))` appears in **6 derived dimensions of `sales_daily`** —
-the same three-deep cast chain re-typed six times because the underlying column
-is not a date. Fix the column type once, upstream in the pipeline, rather than in
-every `expr`. (Counting these by grep over-reports: a seventh occurrence is
-inside `measures:`, not `dimensions:`. The dimension count is 6.)
+**Repeated defensive casting is a smell.** In the reference `sales_daily`,
+`toDate(parseDateTimeBestEffort(toString(business_date)))` appears in **6
+derived dimensions** — the same three-deep cast chain re-typed six times
+because the underlying column is not a date. Fix the column type once,
+upstream in the pipeline, rather than in every `expr`. (Counting by grep
+over-reports: a seventh occurrence is inside `measures:`, not `dimensions:`.)
 
 **`drivers` and `parent:` are documented, but not where you would look.** Neither
 appears in the semantic-model pages — `drivers` is explained under
@@ -205,12 +379,18 @@ the metric-tree page links back to `measures` claiming it defines the measures
 "and their drivers", which it does not. Read only the semantic-model section and
 you will conclude both fields do not exist and model without them.
 
-**View-qualified `{{ }}` references are the one-off, not the norm.** Across all
-39 views the `{{ view.measure }}` form appears in exactly **one expression** —
-the `discount_rate` measure at `sales_daily.view.yml:129`, which uses it twice
-in that one line (`{{ sales_daily.total_discounts }} / NULLIF({{
-sales_daily.total_gross_sales }}, 0)`). So a grep returns 2 hits from 1 site;
-neither number is "the norm". Every other `{{ }}` in the corpus is a bare,
-unqualified dimension name inside a measure's `filters:` — `{{is_voided}}`. For
-an ordinary same-view filter, write the bare form; copying the qualified one
-means copying the single outlier in the codebase.
+**`{{ }}` references: bare for the same view, qualified for another.** Inside a
+measure's `expr` or `filters:`, `{{is_voided}}` names a dimension or measure
+of the *same* view and is expanded for you — that is the norm in the corpus.
+`{{view.member}}` reaches another view's member and is the rare case: across
+39 views it appears in exactly one expression (`discount_rate`, which uses it
+twice on one line, so a grep shows 2 hits from 1 site). A `{{ }}` that names
+nothing resolvable fails the query with an "unresolved reference" error rather
+than reaching the warehouse. Older guidance that says never to put `{{ }}` in a
+filter predates this and is wrong; raw column SQL (`status = 'completed'`)
+remains fine too.
+
+**Do not add a `# yaml-language-server: $schema=…` header.** No JSON schema is
+published for `.view.yml` or `.topic.yml`; a header pointing at one makes an
+editor validate against nothing — or against the wrong file — while looking as
+if it works.