diff --git a/dex/README.md b/dex/README.md
deleted file mode 100644
index 2387472..0000000
--- a/dex/README.md
+++ /dev/null
@@ -1,6 +0,0 @@
-# Generated documentation section
-
-Built by `scripts/build_docs_site.py` in https://github.com/exmergo/dex at `v1.18.0`,
-and published here by its release workflow. Do not edit this folder:
-every release replaces it. Change `docs/`, `references/`,
-`CHANGELOG.md` or the CLI in https://github.com/exmergo/dex instead.
diff --git a/dex/changelog.mdx b/dex/changelog.mdx
deleted file mode 100644
index fc46b53..0000000
--- a/dex/changelog.mdx
+++ /dev/null
@@ -1,1377 +0,0 @@
----
-title: Changelog
-description: 'Release notes for exmergo-dex-core and the dex skills: what was added, changed, and fixed in each of the recent releases, with links to the pull requests.'
-rss: true
-og:title: Changelog · Exmergo Dex
-twitter:title: Changelog · Exmergo Dex
----
-
-
-
-### Added
-
-- **`maintain verify` judges a project format's declared foreign keys without dbt
- artifacts.** A project format other than dbt (one named under `project.format`)
- can declare foreign keys, but nothing measured them: verify suppressed the join
- contract and parent population for want of a dbt `target/`, and dbt's own
- `relationships` test result was the only judge. Each declared foreign key is now
- measured against its parent with the join contract's coverage probe, placed
- where the format's `model_relations` puts each side, and reported as one record
- per key under `data.foreign_key_coverage` (`model`, `column`, `to_model`,
- `to_column`, and a `status` of `satisfied`, `contradicted`, `not_applicable` or
- `unchecked` with a `reason_code`). Any non-NULL child value the parent lacks is a
- high `foreign_key_orphans` finding, since a foreign key states containment. A
- model the format places in no relation is `unchecked` with
- `no_declared_relation`, never found by name. On a metered connector the probe is
- priced in verify's one offer. A dbt project is unchanged: dbt still judges these
- through its own `relationships` tests. ([#1217](https://github.com/exmergo/dex/pull/1217))
-- **`dex maintain coverage` inventories the tests a dbt project declares.** It
- reads a fresh `dbt parse` of a copy of the project, so it is free on every
- connector, opens no connection and needs no baseline. For each enabled model,
- source, snapshot and seed it counts its own generic, singular, unit and
- freshness tests (with each test's severity), lists the tests on downstream
- resources apart, says whether an incremental model has a unit test that takes
- its `is_incremental()` branch, and splits documented columns into asserted and
- unasserted. Every ratio in `data.summary` names its numerator, denominator and
- what the denominator counts; package and disabled resources are counted and
- named under `excluded`. It takes the `maintain verify` selector and `--full`,
- reports only (never fails on low coverage), and is reviewed for values-free
- mode. `DexEngine.coverage()` is the library spelling. ([#1328](https://github.com/exmergo/dex/pull/1328))
-- `transform build --verify --for-plan` now measures what a plan did to the models below its edits (#1231). The models the plan rewrote and every unedited model below them are re-executed against the tree before the plan, which `transform apply` now records on the plan as `baseline_sources` (else the git `HEAD` blob whose hash the plan recorded). Per model, `data.verification.impact` counts rows and keys on each side (kept, removed, added, duplicated; keys compared as text, so a retyped key still matches) and, on a mart, the kept keys each column changed on; counts and names only. An unedited model whose rows or keys moved is a `downstream_population_changed` finding naming the edit upstream, attributed `introduced`, and an `unverified` reason that keeps the build from reading `validated`, unless its declaration records the population as an assumption at `request` or `contract` tier. `data.completion.impact` leads with the largest changes. On billed connectors the statements are priced with the build as `(downstream impact)`, and a model above a quarter of the command ceiling is `unchecked: cost`. `data.change_scope.downstream` names, at plan time and for free, the unedited models below each rewrite. ([#1333](https://github.com/exmergo/dex/pull/1333))
-- **`dex maintain coverage` reports last-run status, recorded mutation strength
- and declared-fact coverage beside the test inventory.** Each test carries its
- status in the newest `run_results.json` a dbt build wrote (Dex's or a plain
- `dbt build`'s), `not_run` where that run did not include it, with the run's
- invocation and age. `transform test --mutate` now records each model's result
- in `.dex/`, and coverage reads it back as the model's `strength`: `fresh`,
- `stale` (naming whether the model's SQL, its tests or a downstream test it ran
- changed), `missing` or `untestable`, counted per status with score bands and
- no project score. A `declarations` section names, for each declared fact, the
- dbt tests and `maintain verify` checks that can judge it, or that nothing does.
- All of it is free and connectionless. Store backends gain an optional
- `MutationRecords` capability, held to the conformance suite as
- `MutationRecordsContract`. ([#1343](https://github.com/exmergo/dex/pull/1343))
-- **`maintain coverage --mutate` refreshes stale and missing mutation scores, and coverage lists the columns singular tests read.** `--mutate` runs `transform test --mutate` for each model whose recorded score is `stale` or `missing`, in selector order (else missing first, upstream first), at most 25 per run (`--max-models` narrows), and reports what it did under `data.refresh`. On a metered connector the whole batch is priced and confirmed once, each run draws on what the budget has left, and the models it did not reach are `not_run`; it is free on DuckDB, dev target only, and refused in values-free mode. Without `--mutate` the command still opens no connection. A model with no SQL to plant a defect in is now recorded and reads `untestable` until it changes, so a refresh always moves on. Each resource's `columns.referenced_columns` lists the columns its singular tests read, with the role each is read in (`predicate`, `join`, `aggregation`, `grouping`, `projection`), counted apart as `columns_referenced_only` and never as asserted; `data.singular_tests` names every test that could not be read, with a reason code. ([#1349](https://github.com/exmergo/dex/pull/1349))
-- **Governed `explore semantic query` and `values` on Snowflake Semantic Views, and `explore semantic list --deployed`.** Under `semantic.vendor: snowflake`, Dex renders `SELECT * FROM SEMANTIC_VIEW( DIMENSIONS ... METRICS ... [WHERE ...])` from the repository's catalog and runs it through its own Snowflake connector under the cost guard (`execution: dex`); every other connector is refused by name. Tokens are the catalog's (`sales.orders.revenue`, `sales.revenue_per_customer`), one view per query, and result columns carry them. A grain-suffixed time dimension (`sales.orders.order_date__month`) renders as `DATE_TRUNC`, `--where` is a Snowflake predicate over dimensions and facts, and a query of facts alone takes `--group-by ` and no metric. Refused by name before anything is sent: facts beside metrics or dimensions, a private, window, level-of-detail or `using_relationships` member, a view declaring `variables`, a dimension the metric's table does not reach many-to-one, a grain on a categorical dimension, a bare `--grain`, and a `--where` naming a metric or one Dex cannot read. The PII gate screens grouped and filtered members and the inputs of a metric that returns one of its values, through the catalog's lineage. Before the cost handshake, Dex locates the deployed view with a warehouse-free `SHOW SEMANTIC VIEWS` over the source allowlist, reads it back with `SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW` (which resumes no warehouse), and refuses the query when anything it relies on differs from the repository's file, naming the member and the field; a view defined only in the repository, or in two allowlisted schemas, is refused by name. The statement is priced from the base tables the members reach, since Snowflake keeps no bytes for a semantic view. `explore semantic list --deployed` reads the deployed views instead of the files, with `source: deployed` and per-view `coverage` (`full`, `limited`, `refused`); a plain `list` never contacts Snowflake. ([#1355](https://github.com/exmergo/dex/pull/1355))
-- **A live integration suite for Snowflake Semantic Views, and the CI role it deploys with.** `tests/integration/test_snowflake_semantic_views.py` deploys two corpus views over the TPC-H sample data into a scratch schema and holds Dex to them: the read-back comparing clean, `list --deployed`, five governed queries and values against SQL written by hand over the base tables, the stale-definition refusal, and the `maintain` drift loop through `reconcile` and `apply`. `scripts/setup_snowflake_ci.sh` provisions `DEX_CI_SV_DEPLOYER`, the role the suite deploys with, kept apart from the role Dex runs as, and `scripts/setup_snowflake_semantic_views.sh` grants the read role OPERATE on its warehouse so `snowflake.suspend_after_command` works. The docs now state plainly what the Snowflake Semantic View vendor does not do in this release. ([#1356](https://github.com/exmergo/dex/pull/1356))
-- **`maintain coverage` lists a native semantic layer's declarations.** Under `semantic.vendor` set to Ossie, SLayer, Cube, Databricks or Snowflake, the declarations section adds the layer's own facts beside the dbt manifest's, and every record names its `source`. The keys and joins the layer declares are the ones `maintain grain` re-verifies, so they read `dex_verify` with `declared_grain_not_unique`, `declared_join_orphans` and, for a join declared `many_to_one` or `one_to_one`, `join_cardinality_exceeded`. What the layer's `dex` metadata states (roles, references, population, unit, additivity) reads `none`, since nothing checks it on that layer. A fact a dbt model and the layer both declare on the same relation, spelled alike, is listed once per source with `also_declared_by` and counted once. Still free and connectionless, and no population value or rule text is shown. ([#1358](https://github.com/exmergo/dex/pull/1358))
-- **Snowflake Semantic Views read from the account alone: `semantic.deployment: snowflake_account`.** Under `semantic.vendor: snowflake`, the new deployment reads the catalog from every semantic view in the source allowlist's scopes, with no repository file needed: a warehouse-free `SHOW SEMANTIC VIEWS` per scope, then `SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW` per view, each read-back checked by the same validator that reads a file. It is the Snowflake counterpart of `dbt_cloud` and, like it, is read only by `explore semantic list|values|query` and by `explore relationships|map --use-hosted-semantic-layer`, which now fold in the account's keys and joins on their base tables. Dex still renders `SEMANTIC_VIEW(...)` and runs it through its own Snowflake connector (`execution: dex`), so the cost guard, the source allowlist and the PII gate apply exactly as under `local`. What changes is trust. The deployed definition is the only one, so nothing is checked against a file, and every result says so: `list` carries `source: account`, `query` and `values` carry `definition_source: account`, and each carries a warning. `coverage` names every view: `full`; `limited`, where a read-back reads a member it does not carry; or `refused`, for a read-back that was refused or failed validation, or for a name held in two allowlisted scopes, with both copies named and `--scope` suggested. The deployment is opt-in only and never a fallback when `semantic.snowflake.files` is empty. Configured files stay optional and keep serving `maintain`, `transform`, `--use-project` and `--local`, which checks the deployment against them. A deployed view that a configured file describes is named on its result (`repository_file`), takes the file's spelling, and is never silently passed over. ([#1360](https://github.com/exmergo/dex/pull/1360))
-
-### Changed
-
-- **A build says what the plan introduced, and an unfinished change no longer reads as validated.**
- A `transform build --verify --for-plan` now classifies each finding as
- `introduced`, `unattributed` or `existing`, judged against the last `--verify`
- build recorded before the plan was applied and against the manifest's lineage,
- and lists the introduced ones first, in `data.verification.introduced` and at the
- head of `data.completion.verification`, so a new high-severity finding is never
- cut or buried below inherited ones. Where every deliverable built but part of the
- change is still open (a rewrite applied uncompared while its baseline was ready,
- an undeclared population change, or an introduced high-severity finding),
- `data.outcome` reads `built_unverified` with each reason under
- `data.completion.unverified`; `data.evidence.outcome` keeps `validated`.
- `transform apply` now refuses a plan whose change scope records an undeclared
- population change, naming each under `data.undeclared_population_changes`, until
- an assumption records it or `--accept-population-change ""` accepts it,
- which is recorded on the plan. ([#1329](https://github.com/exmergo/dex/pull/1329))
-- **The skills stay on a supported Python when your newest is 3.15.** Dex supports
- Python 3.11 to 3.14. The skill wrappers now hold both their own interpreter and
- the engine's environment to that range, so uv picks an installed 3.14 or older,
- or downloads one, instead of installing the engine on 3.15, where dependencies
- that ship no 3.15 wheels fail to build (the Databricks extra did). An explicit
- `UV_PYTHON` still wins. The README, the installation page and the package README
- state the range, and the installation page shows `uv tool install --python 3.14`
- for a standalone install on a machine whose newest Python is 3.15. ([#1335](https://github.com/exmergo/dex/pull/1335))
-- **Query results now serialize list and array cells as JSON arrays instead of Python repr strings.** Cells with array types previously fell back to string coercion in `json_safe`, emitting Python repr strings like `"[1, 2]"`. Array cells now serialize as JSON arrays, with nested cell-width truncation applied to long string elements and payload-byte caps preserved. ([#1337](https://github.com/exmergo/dex/pull/1337))
-
-### Fixed
-
-- **Qualifying a GROUP BY key is no longer reported as a grain change.**
- Table qualifiers on GROUP BY keys are stripped during comparison so alias-only
- refactors do not trigger `group_by_changed` and keep the population classified
- as kept. Real grain changes, including case changes in quoted identifiers and
- string literals, continue to be reported. ([#1174](https://github.com/exmergo/dex/pull/1174))
-- **Honor runtime error and partial success dbt statuses in standalone maintain verify.** The standalone build status sweep now reuses shared build status classification, reporting `runtime error` and `failed` as `node_failed` findings, tracing skipped descendants back to their failed ancestors, and noting unrecognized statuses like `partial success` and `no-op` as unchecked rather than omitting them. ([#1338](https://github.com/exmergo/dex/pull/1338))
-- **Establish build completion and coverage for plans that only add dbt tests.** `required_nodes` now resolves singular test edits (`EditKind.TEST_SQL`) and native unit test definitions (`unit_tests:` in schema YAML) to their expected test nodes, including across configured test paths. Build completion recognizes passing and warning test runs as satisfied test deliverables without conflating test execution with model rebuilds. Skipped, disabled, failed, or missing tests are reported explicitly and prevent validated completion, while unrelated model builds report `unrelated` outcome. ([#1340](https://github.com/exmergo/dex/pull/1340))
-- **SLayer authoring and retype checks resolve measure references read through joins.** Saved measures that aggregate a column across single-hop or multi-hop joins now evaluate that column's allowed aggregation rules, including primary key restrictions and type defaults for ARRAY and TEXT columns. When a joined column is retyped, maintain schema lists affected dependent measures under `breaks_measures` and advises on the required measure rewrites. Unknown or unresolvable joins remain explicitly unchecked during authoring validation. ([#1344](https://github.com/exmergo/dex/pull/1344))
-- **Reconcile links covered advisories to the native semantic plan.**
- When a mechanical semantic plan is validated during reconcile, advisories that
- the plan already repairs are linked to it instead of being repeated as
- independent manual proposals. Uncovered advisories, such as removals held back
- by guards or unrepresentable repairs, remain separate manual proposals. ([#1345](https://github.com/exmergo/dex/pull/1345))
-- **A nation, country, region or continent name is no longer flagged as a personal name.** The generic `*_name` PII match now treats `nation`, `country`, `region` and `continent` as non-person qualifiers, so `nation_name` can be grouped by in a governed semantic query instead of being refused as PII. A bare `name`, a `customer_name`, an ambiguous `n_name` and a `city_name` (address data) are still flagged. ([#1356](https://github.com/exmergo/dex/pull/1356))
-- **Ossie snapshots record which key is the primary key and which are `unique_keys`.** A violated or lapsed `unique_keys` entry was worded as a primary-key claim, in the finding and in the `maintain reconcile` advice. The snapshot now records `key_claims` for each Ossie key, so both say the layer declares the columns unique. A key left out because a field links no column drops its claim too. Snapshots taken before this read as they did.
-
-
-
-
-
-### Added
-
-- **`semantic derivation` normalizes double underscores in derived semantic model names.**
- Marts following Fivetran naming conventions (such as `intercom__threads`) derive
- valid MetricFlow semantic model names (`intercom_threads`) while preserving the
- underlying `ref('intercom__threads')` reference. ([#1214](https://github.com/exmergo/dex/pull/1214))
-- **Ambiguous `ref()` inputs resolve through compiled dbt manifest.** When an input matches multiple cached relations (such as legacy and dev builds), `transform plan` and `transform declare` resolve it against the compiled manifest's relation for target when fresh and matching. ([#1242](https://github.com/exmergo/dex/pull/1242))
-- **`semantic.vendor: snowflake` reads Snowflake Semantic View files as the
- semantic layer.** Name the Semantic View YAML files in
- `semantic.snowflake.files` (the form `SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML` takes
- and `SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW` returns) and `explore semantic list`
- (with `--metric`, `--for-dimension` and `--search`, which also matches
- synonyms) answers from them. The files are read statically with no Snowflake
- connection, and validated by dex's own port of Snowflake's specification and
- validation rules, qualified against `verify_only` on a live account. Every
- refusal names the file and the element, and a `.sql` file and a legacy Cortex
- Analyst model are refused by name.
-
- Every name carries its view:
- - logical tables are semantic models `view.table`;
- - dimensions, time dimensions and facts are `view.table.member`, with facts
- marked never groupable;
- - a metric that is one aggregate is a measure and a simple metric, and one
- metric over another is a ratio.
-
- Primary keys are entities, and every primary and unique key and every
- relationship (with its arity) reach
- `explore relationships|map|profile --use-project` at confidence 1.0.
- `maintain snapshot` fingerprints the layer so
- that a view read back from Snowflake matches its file, and `maintain grain`
- measures the keys and arities. Sample values are never surfaced. Governed `query`
- and `values` are not available yet and refuse by name. Install with
- `exmergo-dex-core[semantic-views]`.
-
- A deployed semantic view is never inventoried or probed: `SHOW VIEWS` does not
- list one, and the inventory skips its members in `SHOW COLUMNS`. The dev-namespace
- check still counts it as content.
-
- ([#1313](https://github.com/exmergo/dex/pull/1313))
-- **`semantic snowflake define|update|plan` authors Snowflake Semantic View files,
- and a declared mart derives a logical table.** Whole files listed in
- `semantic.snowflake.files` are validated together with dex's port of Snowflake's
- rules and stored as a reviewable plan that `transform apply` writes byte for
- byte, keeping each file's mode. A path off the list, a `.sql` file, another
- suffix and a delete are refused by name, the first with the `dex config set`
- that adopts it. Every error anywhere in the set refuses the plan. In a file the
- plan writes, an unknown key, `access_modifier` on a dimension, and a read
- qualified with its own table that names no member also refuse it. Reading
- reports that last one as the new `unresolved_member` warning.
-
- Each logical table and derived metric is reported `defined`, `updated` or
- `unchanged`, compared as YAML 1.2, so reformatting is not a change. Nothing is
- deployed: dex runs no `CREATE SEMANTIC VIEW`, no YAML procedure and no grant, and
- opens no Snowflake connection.
-
- On `transform plan`, a declared mart becomes a logical table:
- - the grain as its primary key;
- - dimensions and time dimensions from its roles;
- - a fact per measure, and a metric per declared aggregation, held non-additive
- over time where the measure is semi-additive;
- - a relationship to each parent table keyed on its foreign key.
-
- The table is spliced into the file that holds its parents, or proposed as a view
- of its own. A `declarations` payload on `semantic snowflake plan` annotates an
- existing table, rewriting only the lines it changes, comments inside the table
- included. The population is the last sentence of the table's description, which
- the catalog withholds. Units, NULL rules and assumptions are reported as not
- carried.
-
- ([#1314](https://github.com/exmergo/dex/pull/1314))
-- **`maintain` holds Snowflake Semantic Views to the warehouse, and reconciles them
- through `semantic snowflake update`.** Under `semantic.vendor: snowflake`,
- `maintain schema` reports four codes, with no Snowflake object created. Each
- names the view and the element; a column finding also names the column, and a
- dependency finding lists the elements it takes under `data.reasons`:
-
- - `declared_column_missing`: a dimension, time dimension, fact, metric,
- relationship column, key or `base_table.definition` reads a column its table
- lost.
- - `declared_relation_missing`: a logical table's `base_table` is gone since the
- baseline.
- - `declared_type_conflict`: `SUM`/`AVG` over text, a time dimension over a
- column that is not temporal, or a declared `data_type` in another family.
- - `declared_dependency_dropped`: whatever Dex's reader then refuses, to a
- fixpoint.
-
- The severities follow what Snowflake does with each conflict, probed on an
- account. It fails every query that sums text. It answers a text time dimension
- with the column's values, so that finding is advised, never cut. It ignores a
- declared `data_type`.
-
- `maintain reconcile` cuts the removals out of the files as a plan the reader
- validates, with the comments written directly above each removed entry, keeping
- every other byte. A gone `base_table`, a key or `definition` naming a dropped
- column, and a removal that empties the view stay advisory.
-
- The fingerprint records which key is the primary key and which a uniqueness
- claim (`key_claims`), and each table's primary key as its declaration, so a
- changed primary key is `declaration_changed`. A contradicted key or
- relationship arity is worded as the view's claim and carries `declared_by` and
- `claim`, since Snowflake trusts a declared key without checking it.
- `key_lost_uniqueness` names the claim too, and `join_cardinality_exceeded`
- carries `declared_by` and `claim` for every native vendor.
-
- ([#1315](https://github.com/exmergo/dex/pull/1315))
-
-### Fixed
-
-- **Metric View query sources with an aggregate or `HAVING` claim no relation.** A `source` query that aggregates its table (for example `SELECT SUM(b) AS a FROM t`), or filters with `HAVING` and no `GROUP BY`, no longer claims that table as its relation, since the view holds fewer rows than the table. A window function keeps the claim, as it keeps the row count. ([#1302](https://github.com/exmergo/dex/pull/1302))
-- **`maintain reconcile` no longer refuses a repository whose only layer is a
- native semantic layer without a schema route of its own.** Its findings are
- advisory there, as they already were for vendors with one. A contradicted primary
- key's advice now names a `semantic update` route only where dex authors
- that vendor, and says to change the key in its file otherwise. ([#1313](https://github.com/exmergo/dex/pull/1313))
-- **`maintain reconcile` advice follows the semantic layer's claim, and no longer
- promises a test edit with no project to put it in.**
-
- - A lapsed key a semantic layer declares used to get the dbt advice ("change
- the declared grain"). It now names the layer's route to change the key.
- - A Snowflake relationship's arity is no longer advised as a cardinality to
- declare. It is inferred from the referenced table's key.
- - In a repository whose only layer is a semantic one, a lost key no longer
- warns that a `unique` test has nowhere to go.
-
- ([#1315](https://github.com/exmergo/dex/pull/1315))
-
-
-
-
-
-### Added
-
-- Make `dex init` a complete project setup command: create a dbt-backed Dex project or local demo, adopt existing dbt, or configure exploration without dbt. Generate managed README and agent instructions, preserve existing content on reruns, verify the connection, and report readiness and recovery steps in one JSON envelope. Terminal users get guided setup and a concise Enterprise handoff. The legacy `dex transform init` scaffolder and repository-level `.dex/` layout remain available. ([#1232](https://github.com/exmergo/dex/pull/1232))
-- **`semantic databricks define|update|plan` authors Databricks Metric View files,
- and a declared mart derives one.** Whole Metric View YAML files on
- `semantic.databricks.files` are validated by dex's port of the YAML 1.1 rules,
- stored as a plan and written byte-for-byte by `transform apply`, with no
- workspace connection and nothing deployed. Writing is stricter than reading: an
- unknown key (`rely` included) and `fields` beside `dimensions` refuse a file the
- plan writes, since Databricks refuses the first and drops `fields` for the second.
- Under `semantic.vendor: databricks`, `transform plan` on a declared mart derives a
- Metric View (fields, `date`/`date_time` formats, measures `_` with
- currency or percentage formats, `many_to_one` joins with `rely.at_most_one_match`
- where the parent declares that key), included as a second plan where its path is
- configured and proposed otherwise; a `declarations` payload on `semantic
- databricks plan` annotates an existing view, splicing only what changes. A Metric
- View has no metadata key, so a population is carried only as the last sentence
- of the view's `comment`, never as a `filter`, and the catalog withholds it. Dex's
- own writers read and write YAML 1.2, so a join's `on:` key stays text.
- `maintain reconcile` now names `semantic databricks update` as the route. ([#1258](https://github.com/exmergo/dex/pull/1258))
-- **`maintain` holds Databricks Metric Views to the warehouse, and reconciles them
- through `semantic databricks update`.** Under `semantic.vendor: databricks`,
- `maintain schema` reports `declared_column_missing` (a field, measure, `filter`,
- join condition or query `source` reading a column its table lost),
- `declared_relation_missing` (a view's or a join's `source` gone since the
- baseline), `declared_type_conflict` (a `date`/`date_time` format on a column that
- is not temporal, a numeric format on text, `SUM`/`AVG` over text) and
- `declared_dependency_dropped` (a field, measure, window or nested join that loses
- an input, `MEASURE()` included), each naming the view, the element and the
- column, with no workspace connection. `maintain reconcile` cuts the removals out
- of the view files as a `semantic databricks update` plan the reader validates,
- keeping every other byte; a gone `source`, a `filter` or query source reading a
- dropped column, a removal a `materialization` lists, and one that would empty the
- view stay advisory. A view re-saved in a spec version Dex does not read is
- `semantic_format_changed`, naming the file. A contradicted `rely` key on
- `maintain grain` is now worded as the Metric View's uniqueness claim, not the
- project's grain, and every `declared_grain_not_unique` carries `declared_by` and
- `claim`. ([#1259](https://github.com/exmergo/dex/pull/1259))
-- **Ordinary plan and declare drafting carry an unchanged key from tested or declared input keys.** When an input model is not profiled in the cache, drafting now carries through an unchanged single-column or composite key declared (`meta.dex.grain`) or tested (`unique`, `unique_combination_of_columns`) on that input, without requiring a warehouse profile. The drafted grain evidence records its actual source without implying test execution. Aliases preserve key mappings, while transformations or fan-out joins that can destroy uniqueness do not inherit keys without supporting rules. When profiled warehouse data contradicts a stated key, measured evidence takes precedence and retains relevant warnings and verification obligations. ([#1261](https://github.com/exmergo/dex/pull/1261))
-- **`semantic.vendor: databricks` reads Databricks Metric View files as the
- semantic layer.** Name the Metric View YAML files in `semantic.databricks.files`
- and `explore semantic list` (with `--metric`, `--for-dimension` and `--search`)
- answers from them, read statically with no workspace connection and validated by
- dex's own port of the Metric View YAML 1.1 rules. Every refusal names the file and
- the element. Each file is one view, named after its stem, and a `.sql`
- `CREATE VIEW ... WITH METRICS` file is refused by name. Fields are dimensions keyed
- `view.field`, single-aggregate measures are measures and metrics, and
- `MEASURE(a) / MEASURE(b)` is a ratio.
- `explore relationships|map|profile --use-project` carry each join and each
- `rely.at_most_one_match` key at confidence 1.0, `maintain snapshot` fingerprints
- the layer, and `maintain grain` measures those keys and each join's declared
- arity. `explore semantic list --search` also matches the `synonyms` a field or
- measure declares. Governed
- `query` and `values` are not available yet and refuse by name. Install with
- `exmergo-dex-core[metric-views]`. ([#1262](https://github.com/exmergo/dex/pull/1262))
-- **The Ossie bridge proposes a Databricks Metric View from an Ossie document, and an
- Ossie document from a Metric View.**
- `semantic databricks define|update|plan --from-ossie ` and
- `semantic ossie define|update|plan --from-metric-view ` convert one file of
- the other format into the configured layer, through
- dex's port of the apache/ossie-converters `databricks` spoke. The port is held to
- the converter's fixtures in both directions, with the same notices and the stash
- JSON byte for byte, and to its example, dialect and round-trip suites. Every
- dropped or rewritten element is named in `data.bridge`, each notice marked as the
- converter's or dex's. Dex adds only what its own validators need: a field marked
- `key_only` for a join column no field exposes, which its export leaves out again;
- a key or metric naming a field reads its column, and an imported metric names
- the fields its columns are exposed by; `expression.sql` is read; and a fact
- dataset's metrics become measures. Each flag takes several files; those with
- configured outputs are stored as one plan. `--dataset-metrics` writes fact-only measures
- as dataset-scoped metrics on import (#957). `--fact` names the dataset a view is
- on, and `--into` places the file. A configured output path is validated and
- stored as a plan for `transform apply`. Any other path stores no plan and comes
- back with the `dex config set` that adopts it. Nothing is deployed. ([#1275](https://github.com/exmergo/dex/pull/1275))
-- **`dex feedback`, and a report link on Dex's own failures.** `dex feedback` prints what a bug report or a feature request needs, with no project, connection or extra: the environment (versions, OS, and the connector and semantic-layer names your config writes; never a target, credential, path or value, so it can be pasted into a public issue as it stands) and links that prefill the issue forms from it. Nothing is sent. An error with `reason: internal`, an exception Dex did not anticipate, now carries `data.report`: a prefilled bug link naming the command, connector and exception class, never the error text. The issue forms add Trino, the semantic layer, how Dex is run and whether an agent filed on a person's behalf, and `SUPPORT.md` says where questions and security reports go. Reports drafted by your agent are welcome. (#1299) ([#1300](https://github.com/exmergo/dex/pull/1300))
-
-### Fixed
-
-- **A Metric View `date` format without `date_format`, or a `date_time` format
- without both `date_format` and `time_format`, is refused.** Databricks refuses
- both on `CREATE VIEW ... WITH METRICS`; dex read them as valid temporal fields.
- **A derived semantic definition is placed by the siblings the same plan
- creates.** `transform plan` now counts a model the plan itself writes when it
- looks for the catalog and schema a native layer's views already read, so a mart
- planned beside its staging model is no longer placed on a bare table name. ([#1258](https://github.com/exmergo/dex/pull/1258))
-- **A deployed Databricks Metric View no longer breaks `maintain check` or a
- profile.** The Databricks connector inventoried a Metric View in the source scope
- as a relation, and Databricks refuses a plain `SELECT` of its measure columns
- (`METRIC_VIEW_MISSING_MEASURE_FUNCTION`), so the grain axis failed the whole
- command. Unity Catalog objects of type `METRIC_VIEW` are now left out of the
- inventory; their YAML is read from the repository under
- `semantic.vendor: databricks`. `maintain reconcile` in a repository whose only
- layer is a semantic one no longer refuses when none of its findings is a schema
- one: they are advisory. A plan's notes are no longer repeated in reconcile's
- warnings. ([#1259](https://github.com/exmergo/dex/pull/1259))
-- **Moving an unchanged aggregate into a CTE is no longer an aggregate change.** In `data.change_scope`, `transform plan` compared each output column's aggregates as written, so extracting `count(*) as part_count` into a grouped CTE and reading `p.part_count` in the final select reported an undeclared `aggregate_changed` ("aggregates nothing"). The comparison now follows the column through the top-level CTEs it reads. When the rows reaching the aggregate are produced alike on both sides (the same filters, the same grouping and `HAVING` where the aggregate is computed and elsewhere, the same row `DISTINCT` columns and join conditions, each column compared as the table it reads, the same tables read as often, and no outer join, `LIMIT`, sample, window function, `QUALIFY` or derived table on the way), an aggregate that only moved is listed as `expression_changed` ("reads the same calculation through a CTE"), which needs no decision. A changed aggregate, a new cast or new NULL handling is still flagged, also when it was added inside the CTE, and any other move, or a column that cannot be traced, is compared as written. An output whose text is unchanged but that now reads a differently named CTE is compared through it too, so a calculation changed there is reported. The moved query's grouping and join changes are still reported under population. (#1253) ([#1264](https://github.com/exmergo/dex/pull/1264))
-- **A semantic file that does not parse is named instead of hiding its definitions.** The semantic verbs read every project YAML file for the definitions it declares, and one that failed to parse was skipped silently: a metric living in it read as "not in the project" and a definition edit with no `path` was told to "give it a path", sending the caller looking for a missing definition or writing a duplicate when the real problem was a syntax error. The read now reports each skipped file and why, and a refusal that would claim a name is absent names the files it could not read: "`models/semantic.yml` could not be read (does not parse as YAML at line 44), so definitions in it are not visible". (#1268) ([#1277](https://github.com/exmergo/dex/pull/1277))
-- **Reconcile finds the declaration of a mart that lost its key.** After `maintain check` reported `key_lost_uniqueness` on a mart such as `dim_customers`, `maintain reconcile` looked for `models/staging/stg_dim_customers.yml`, found nothing, and only advised adding a `unique` test by hand. It now resolves the model the project builds as that relation, wherever it lives, and proposes the `unique` test in the YAML that declares it. When the key already has a `unique` test, the proposal now says so: that this test fails on the duplicates (unless they are NULL keys, which dbt's `unique` ignores) when the finding is on the model's own relation and the test is a plain `unique`, and otherwise that it is already declared. A relation the project also declares as a source table keeps the staging convention. ([#1278](https://github.com/exmergo/dex/pull/1278))
-
-
-
-
-
-### Fixed
-
-- **`*emphasis*` in semantic YAML no longer blocks a definition edit.**
- `semantic define|update|plan --definitions-file` refused a file whose comments or
- descriptions held Markdown emphasis such as `*active*`, saying it used YAML anchors
- or aliases, so the caller had to restate the whole file. `maintain reconcile` had
- the same false positive in a `schema.yml`, and dropped the test edit it proposes
- for a lost key. Anchors and aliases are now read from the YAML parse, so a real
- anchor, alias or `<<: *base` merge is still refused. A file that does not parse
- now gets its own refusal, naming the line. ([#1256](https://github.com/exmergo/dex/pull/1256))
-
-
-
-
-
-### Added
-
-- **The toggle check names the tests and semantic definitions that break with
- the flag off.** `data.toggle` judged models only, so a `not_null` on a governed
- column failed the off build with no warning at plan time, and a dimension or
- measure over one stopped resolving with nothing said. It now reports
- `governed_column_tested_when_off` for each test the off branch still runs over
- a producer's governed column (a test disabled at the off value, such as
- `enabled: "{{ var('enable_fees') }}"`, is not reported), and
- `governed_column_in_semantic_layer` for each dimension, measure or entity over
- one, with the metrics drawing on a measure. Each names its file and line and
- contradicts the verdict like a model finding. A computed semantic `expr` the
- reference index cannot resolve is listed in `data.toggle.limits`. ([#1195](https://github.com/exmergo/dex/pull/1195))
-- **`dex transform build --select` accepts several values.** Passing multiple space-separated selectors or model names is joined as dbt reads them, matching dbt CLI syntax while preserving quoted lists. ([#1227](https://github.com/exmergo/dex/pull/1227))
-- **A model with no declared `population.parent` is measured against a drafted one.** `transform plan` drafts the entity each model is about (`data.declarations..drafted.population_parent`): the model, seed or snapshot whose tested, declared or profiled unique key is the model's grain, else the parent a `relationships` test, `references` or clean verified join names, else the "one row per" noun of its description, else its driving relation. It is labelled `drafted` with its evidence, never written, and a declared parent always wins. `transform build --verify` measures the built model against it on the relation dbt wrote, so an aggregate CTE joined to its parent is no longer a blind spot: `data.verification.population_delta` counts orphan keys, missing parents and rows whose child columns are all NULL or zero (a signal of parents kept with no children, not proof: children can sum to zero), and a non-trivial count is `needs_decision`, a `population_delta` finding and an entry under `data.completion.obligations.needs_decision`, settled by declaring the parent or by an assumption naming the key at `request`, `contract` or `precedent` tier. Counts and key column names only. In `data.change_scope`, re-driving a model (a new driving relation, or a declared parent removed or replaced, against the applied model or an earlier unapplied plan) is a `redriven` change that only a `request` or `contract` assumption settles, and the procedure now routes NULL or zero aggregates on a parent-driven model to the join key rather than to a new driving relation (#1228). ([#1228](https://github.com/exmergo/dex/pull/1228))
-- **`dex transform repair ` drafts the override that repairs a failing package model.** It restates the package's SQL as a project model (package macros qualified, `var()` reads given the package's values, a relation var inlined so a project var cannot cycle, the package's materialization restated), disables the package's node in `dbt_project.yml` in place, and converts only the columns the warehouse error names, where the cached profile settles what they hold: all NULL is a cast through text, epoch seconds or milliseconds are read as such and flagged as meaning-changing, ISO text is parsed, and anything else is left `unresolved`. The draft is compiled and bound on dev reading no row before it is stored as an unapplied plan. A failed build's `completion.blockers[]` and `data.prerequisites[]` now carry a `next` line naming the repair, the refactor offer names the command instead of a key plans never emit, a `--for-plan` build of the repair carries `obligations.repair`, and the procedure treats repairing a blocker of the request's own deliverables as in scope. ([#1241](https://github.com/exmergo/dex/pull/1241))
-- **SLayer list columns (`type: ARRAY` with `element_type`) work end to end.** `explore semantic list` lists a list column with `groupable: false` and its `element_type`, and lists its elements as the groupable dimension `model.column.value`, typed from `element_type`, so `--for-dimension posts.tags.value` answers. A list whose `element_type` is `UNKNOWN` (a list of lists or structs, or a semi-structured Snowflake `ARRAY`, which derivation types that way) has no `.value` dimension until its element type is declared. `explore semantic query --group-by posts.tags.value` and `values posts.tags.value` run through the full spine. A grouping by elements is sent with SLayer's `to_many_handling: associate`, so each element row counts the parents holding that element; SLayer's default repeated the metric's whole total on every element row. A note says the rows overlap. Grouping by, or reading the values of, the whole list is refused before anything renders, naming the `.value` token. `contains_any` and `contains_all` filters are now read and screened like `contains`. On Redshift, which has no native lists, a list column is refused by name. `maintain schema` reports a column that became a list as `declared_type_conflict` with `remedy_kind: reingest` and the warehouse's `element_type`, and `maintain reconcile` states it as the `type: ARRAY` declaration to make through `semantic slayer update`.
-
-### Changed
-
-- **The `[slayer]` extra now pins SLayer 1.8.2 (was 1.2.0).** The model format is still version 15, so existing SLayer model files read unchanged. Results can change, and the new ones are correct: a query that filters through a join now applies the joined model's own filters, which SLayer 1.2.0 silently dropped. A query that groups and names no order is now sorted by its grouped columns, distinct values included. A metric query renders the model's filters in a subquery under the query's filter, which changes the statement's shape and not its rows. Also, a declared column whose warehouse type moved to another bucket (`declared_type_conflict` from `maintain schema`) is now reported with SLayer's remedy (`remedy_kind`, `remedy`) instead of a removal, so `maintain reconcile` proposes changing the declared type as advisory rather than cutting the column and the measures on it. Because that remedy alone can leave a measure summing a TEXT column, the finding lists the measures it would break under `breaks_measures`, `semantic slayer define|update|plan` now refuses a saved measure whose aggregation SLayer does not allow on its column's type (it would validate and fail every query), and the catalog names such a measure in a file dex did not author. Installing the extra now resolves SQLAlchemy below 2.1, which SLayer 1.8 requires.
-
-### Fixed
-
-- maintain verify and transform build: report column_undeclared on an
- override of a package-documented model against the package's yaml entry,
- explaining that the project cannot declare the override (#1205). ([#1233](https://github.com/exmergo/dex/pull/1233))
-- **`transform plan` compiles models using column-listing macros to verify their
- SELECT list against `schema.yml`.** A model using column-introspection macros
- (`dbt_utils.star`, `dbt_utils.get_filtered_columns_in_relation`,
- `adapter.get_columns_in_relation`, or `fill_staging_columns`) is now compiled
- alongside control-flow models so its expanded SELECT list is checked against
- declared column contracts. Where compilation is not possible, the plan reports
- that the SELECT list could not be checked statically. ([#1234](https://github.com/exmergo/dex/pull/1234))
-- **drafting hints name derived dev namespaces for package models and post-build guidance for created inputs.** when a model reads an unprofiled package model or seed on a warehouse connector, drafting now derives the package model's dev-qualified relation with its custom schema and appends `--target dev`. when an input is created or edited by the plan itself, drafting omits an unexecutable exploration command and instead names the post-build sequence to profile it after `transform build`. ([#1236](https://github.com/exmergo/dex/pull/1236))
-- **`--verify` reads layer schemas scaffolded by `transform init --layered-schemas`.**
- the verification sweep and dev-target reads derive `_`
- schemas alongside `_`, so warehouse models built across
- staging, intermediate and mart schemas are judged instead of suppressed. ([#1238](https://github.com/exmergo/dex/pull/1238))
-- **bigquery non-groupable types are skipped from distinct queries and single-object
- profile failures are noted instead of failing explore runs (#925).** nested and
- non-groupable column types like geography, json, and struct are excluded from
- distinct count and combination queries in bigquery, and explore map and explore
- relationships turn per-object profile failures into notes while reporting the
- remaining objects. ([#1239](https://github.com/exmergo/dex/pull/1239))
-- transform: allow group by on attributes of declared grain when cache proves
- dependence, and name the upstream profile that would confirm it when unprofiled (#1204). ([#1240](https://github.com/exmergo/dex/pull/1240))
-- **`dex maintain verify` reads a quoted list of model names.** A scope spelled
- as one quoted argument separated by spaces names the same models as the same
- names given as separate arguments or comma-separated, so a quoted list no
- longer narrows the verification to a model nobody has (#1243). ([#1243](https://github.com/exmergo/dex/pull/1243))
-- **`maintain verify` skips naming-guess grain checks on spine-driven and generated models.**
- When a model declares no grain, `maintain verify` skips falling back to an id-shaped naming guess if the model is a time spine, generated in SQL, or driven off one (such as a calendar crossed with customers), aligning with `transform build --verify`. In addition, naming-guess grain findings on other models are capped at medium severity. ([#1244](https://github.com/exmergo/dex/pull/1244))
-- **A flow-style `config`, `meta` or entry no longer blocks a declaration.**
- `transform plan` and `transform declare` refused to write a declaration whose
- entry, `config` or `config.meta` mapping was written in flow style
- (`config: {meta: {dex: {grain: [event_id]}}}`), quoting the style instead of
- recording the decision; in live agent runs, three of three agents stopped
- there and the assumption went unrecorded. Dex now converts just that mapping
- to block style in the same `schema.yml` edit, keeping its keys and values and
- every byte outside it, so the plan writes the declaration and the diff shows
- the restyle. A mapping that an alias references (used more than once) still
- refuses with the reason named, and an entry nested in a flow-style `models:`
- list still does, because a block entry cannot sit inside one.
-- **A list of personal data is screened as personal data.** `explore profile` now reads a list column's element type for its PII type gates, so `email VARCHAR[]` or a repeated BigQuery `ARRAY` named like an email, name or phone column is flagged as a string column of that name is. Before, it was never flagged, so once profiled it read as cleared. On a SLayer layer, `.value` was screened against an internal placeholder with the name heuristic instead of the list column's profile; it is now screened as the list column, so its profiled flag, confidence and any `pii_overrides` entry apply, and a refusal names `model.column.value`. A SLayer saved measure that answers with a column's values (`min`, `max`, `first`, `last`, `median`, `percentile`, SLayer 1.8's `collect`, or a model's custom aggregation) now has the columns it aggregates screened like grouped columns, so `collect(email.value)` is refused where grouping by `email.value` is. Mart derivation under `semantic.vendor: slayer` no longer declares a list as a scalar (`VARCHAR[]` as `TEXT`, `BIGINT[]` as `INT`): it writes `type: ARRAY` with the `element_type` the warehouse names.
-- **Postgres refactor comparison supports `citext` columns.** Postgres extension
- types that psycopg reports only by OID are now named in comparison schemas and
- diagnostics. `citext` is compared as case-sensitive text, while extension types
- without a safe grouping operator class remain refused with their readable name.
-
-
-
-
-
-### Added
-
-- **The procedure diagnoses the value a report names, not only its rows.** A new
- "Diagnose the value the request names" step in the shared procedure (#1048,
- #1116): finding the entity is one branch rather than the verdict, so an agent
- checks the attributes, category memberships and derived measures the symptom
- points at, follows the expression the model returns under the requested column
- name through its aliases and aggregations to the filters, mappings and joins it
- reads, and checks the rows with an aggregate. A correct intermediate formula,
- a green build or a constant answer is not evidence that the delivered column
- uses it, a category outside a predicate is evidence to investigate rather than
- a mapping to assume (a resemblance of names never outranks a mapping that
- leaves the value out), and an investigation that did not settle is reported as
- unresolved. The metadata eval gains a `diagnose` task kind and a Diagnosis
- axis (localized, evidenced, qualified, unchanged), graded apart from the
- build, with two fixtures: `trial_events` (a dropped tier mapping, a declared
- exclusion, a missing subscription, an optional attribute and an unplaced
- code) and `adjusted_price` (an unused adjustment, swapped aliases, a correct
- model and an unsettled refund policy). ([#1048](https://github.com/exmergo/dex/pull/1048))
-- **A build says when an incremental model's next run went untested.** A
- `--for-plan` build now carries `data.completion.obligations.incremental_replay`
- for each required incremental model the plan edited (#1130): `satisfied` when a
- unit test overriding `is_incremental` to true passed in that build,
- `contradicted` (`incremental_test_failed`) when it failed, and otherwise
- `unchecked` with `full_refresh_only` (a `--full-refresh` runs only the full
- program) or `no_incremental_test`. A plan that edits no incremental model
- carries no such key. Obligations are listed and never change `outcome`. ([#1130](https://github.com/exmergo/dex/pull/1130))
-- **Compare a repair that is meant to change rows.** `transform compare` takes
- `--expect ''` (or `--expect-file`) stating the change a plan should make:
- which rows may be `added` and `removed` (`"none"`, `"any"`, or a row predicate
- over the output, with one `IN (SELECT ... FROM ref('') WHERE ...)` form
- for a column the model does not output), which `changed_columns` a kept key may
- change, and that the key holds (#1157). The verdict is `as_expected` or
- `unexpected`, with added, removed and changed keys split into matching and
- unexpected, the failed clauses (`unexpected_added`, `unexpected_removed`,
- `unexpected_changed_column`, `grain_not_held`) and up to five keys per failed
- class, read through the query firewall so a PII-flagged key is withheld. A
- `--for-plan` build carries `obligations.comparison`, holding each rewrite to
- its recorded verdict, so a change applied uncompared reads `not_compared`
- rather than passing unremarked. The procedure now routes an intended change to
- `--expect` instead of skipping the comparison. ([#1157](https://github.com/exmergo/dex/pull/1157))
-- **Ship `cube.js` to enforce the `dex_scopes` claim on Dex's token.**
- `scripts/cube/cube.js` defines `contextToApiScopes` restricting API endpoints to
- the token's `dex_scopes` claim (`meta` and `sql`), and `scripts/setup_cube_dev.sh`
- mounts it so `/v1/load` is refused to Dex's token. ([#1175](https://github.com/exmergo/dex/pull/1175))
-- **`transform references`, `rename` and `remove` know a versioned model.** A
- column of a versioned model is named `dim_teams.`, which selects every
- version, or `dim_teams.v2.`, which selects one. `transform references`
- follows it through each version file, the `versions:` entries and the consumers
- reaching it through `ref('dim_teams')` or `ref('dim_teams', v=N)`, and names the
- versions each occurrence belongs to. A rename or removal on the base name changes
- every version that has the column; on a label it changes that version and its
- consumers only, and a top-level column entry other versions still inherit is
- kept, with the renamed version excluding it and declaring its own. ([#1194](https://github.com/exmergo/dex/pull/1194))
-- **`maintain semantic` reports declaration drift on an Ossie, SLayer or Cube
- layer.** A changed population in `ai_context.dex` or `meta.dex` was a
- low-severity `definition_changed` naming no field (on Cube, nothing), and
- `data.declaration_drift` said there was no transformation project to read
- declarations from. `maintain snapshot` now fingerprints each definition's
- declaration per field, as a dbt model's is, from the `dex` block of its
- metadata and of its members' and from its primary key as the grain, storing
- hashes only. `maintain semantic` and `maintain check` report the existing
- `declaration_changed`, `declaration_added` and `declaration_removed` with the
- existing severities, so a changed population or primary key is `high`, and
- each finding carries `data.layer: semantic` and the vendor. Reformatting a
- block or reordering its keys is not drift. A baseline pinned before this is
- `checked: false` with a reason until `maintain snapshot --project-only`
- re-baselines it. Beside a dbt project, the layer's status is under
- `data.declaration_drift.semantic_layer`, and `checked` is true only when both
- were compared. ([#1196](https://github.com/exmergo/dex/pull/1196))
-- **`maintain verify` states a verdict for every declared key, not only the broken ones.**
- `data.grain_coverage` carries one record per declared grain key, from every
- source (a declaration, a `unique` test, a `unique_combination_of_columns` test,
- a primary entity): `proven`, `broken`, `not_applicable` for an empty relation,
- `unchecked` with a reason code (the reasons that reached a caller only as prose
- in `notes`), or `not_planned` for a key a higher-ranked source displaced. A key
- that held is now stated rather than read out of an absent finding, and every
- unique column on a model gets its own record. A model declaring two
- `unique_combination_of_columns` tests now has both checked; the second was
- dropped before (#1223). ([#1224](https://github.com/exmergo/dex/pull/1224))
-
-### Changed
-
-- **An INNER join the declaration names as its filter is no longer a failed
- check.** `--verify` judged every INNER join against the default orphan
- thresholds, so a join meant to drop rows (members with a handle) was
- `join_orphans` / `contradicted`, and `data.completion.assurance.failed_checks`
- listed the model as if a test had failed. When an `assumptions` entry's
- `column` names the join's driving key column, or a `population.filters` entry
- is on it, the `join_coverage` record is now `satisfied`, keeps its measured
- counts, and names that entry under `unmatched_accounted_for` with the finding
- the default would have raised. LEFT joins, joins the declaration requires and
- `join_no_match` are unchanged. `failed_checks` also gains `checks`, listing
- each failure with its kind (a `data_test` by name, or a contradicted record
- with its finding and join), so a join measurement is not read as a failed test. ([#1184](https://github.com/exmergo/dex/pull/1184))
-- **Identifier conversion counts on a join apply the converted side's own `ON`
- conjuncts and name cross-side filters.** Where the join drops the converted
- side's rows (an inner join, or the side a `LEFT` or `RIGHT` join does not keep),
- its `ON` conjuncts that read only that side now narrow the rows counted, as its
- `WHERE` conjuncts already did, so a row the model never keeps is no longer
- counted as a failure or a merge. `own_filters` lists them. A `WHERE` or `ON`
- conjunct reading both sides, another relation, or an unqualified column is named
- in `scope_filters_not_applied` with the reason, rather than left out silently. ([#1191](https://github.com/exmergo/dex/pull/1191))
-
-### Fixed
-
-- **A model driven off the time spine is no longer compared to it.**
- `maintain verify` and `transform build --verify` compared each model's row
- count with its driving parent, so a comparison mart that takes anchors from
- the time spine and range-joins a fact read as "392 rows against
- metricflow_time_spine's 120". A model whose driving parent is the project's
- time spine (a `time_spine:` config, or the `metricflow_time_spine` name) or a
- model generated in SQL is now skipped, and a note, not a warning, names the
- parent and why. A model that only joins a spine keeps its check, as does every
- model driven off an ordinary relation. Two spine shapes now read as generated
- in SQL rather than as a parent dex could not follow: `dbt_utils.date_spine`,
- whose nested `WITH` was followed as a physical table, and BigQuery's
- `unnest(generate_date_array(...))`. ([#988](https://github.com/exmergo/dex/pull/988))
-- **`transform remove` names a removal when the reference scan has limits.**
- When reference discovery cannot be finished, `transform remove` refuses with
- wording about a removal rather than talking about a rename the caller did not
- ask for. ([#1173](https://github.com/exmergo/dex/pull/1173))
-- **`transform plan` no longer refuses a model that lists a relation's columns while
- compiling.** `adapter.get_columns_in_relation`, which `dbt_utils.star`,
- `dbt_utils.get_filtered_columns_in_relation` and Fivetran's `fill_staging_columns`
- call, was refused as an unsupported `Describe` on DuckDB and as direct database
- access on BigQuery, so a control-flow model using them could not be planned. That
- includes the project override of a package staging model that the
- prerequisite-repair procedure recommends. Dex now answers it from the scoped
- inventory's column metadata (names and types, no rows), built by the adapter's own
- dbt column class so a nested BigQuery column keeps its `STRUCT<...>` type, counts
- each listing toward `query.max_statements` and names it in `warnings`. A raw `DESCRIBE`, `SUMMARIZE`,
- `SHOW`, `PRAGMA` or `information_schema` read stays refused, and the refusal now
- names `adapter.get_columns_in_relation` rather than `explore profile`. ([#1177](https://github.com/exmergo/dex/pull/1177))
-- **A declaration on a project override of a package model is refused in Dex's
- words when the package documents that model, and the override no longer owes
- one.** dbt gives a package's YAML entry for a model the project disables to the
- project's override of it, so any project entry for the same name failed dbt's
- parse as two entries for one resource, with a message cut before the file names.
- `transform plan` now refuses the declaration, or a hand-written entry, before dbt
- runs, naming the package's file and the project's, and says to declare the models
- that read the override instead. The override gets no "declares nothing" warning
- and no missing intent, and `data.declarations..package_documented` names
- the package's entry. `transform declare` skips it as `package_documented`.
- `data.prerequisites` names the package's file as `package_entry` on the
- `project_override` route. The prerequisite-repair recipe, the declaration
- guidance and the procedure now say the same thing. ([#1178](https://github.com/exmergo/dex/pull/1178))
-- `transform plan` reports a failed dbt parse whole: the lines that continue the cause, such as the files named by a duplicate schema.yml entry, now reach the envelope, and a message cut at the length cap says so instead of ending silently. ([#1180](https://github.com/exmergo/dex/pull/1180))
-- **`population.parent` and `references` can name an installed package's model,
- and a package parent is checked from plan to build.** A declaration naming a
- package's staging model (a Fivetran one, say) was refused because the project
- had "no model, seed or snapshot" of that name, so the population-parent checks
- were unusable exactly where marts are built on packages. The project is still
- looked up first, so a project override wins; otherwise an installed package's
- model, seed or snapshot is the parent. Its column is checked against the
- package's SQL or the compiled manifest, a column that cannot be read statically
- is a warning naming the package instead of a refusal, and a missing one is
- refused naming the package and its file. A source named as a parent is refused
- with that said. The plan-time `population_parent` check now walks the package's
- own `ref()` lineage, so a mart driven from a package's parts table under its
- conversations parent is `contradicted` rather than `unchecked`, and column-only
- macros such as `fill_staging_columns` and `dbt_utils.star` no longer hide a
- lineage. `transform declare` and drafting propose a `references` to a package
- model, and the native semantic routes resolve one. `transform build --verify`
- and `maintain verify --target dev` also read the namespaces dbt derives from the
- dev namespace (`_`, where a package sets `+schema`), so on a
- warehouse the package parent's population is measured instead of reported
- unbuilt. No package file is ever written. ([#1181](https://github.com/exmergo/dex/pull/1181))
-- **`transform plan` refuses a package its own edit declares, in Dex's words,
- before dbt runs.** Since #1060 a plan refused when the project's declared
- packages were not installed, but the check read the tree before the plan's
- edits, so a plan whose `packages_yml` edit added a package passed it and then
- failed with dbt's raw `Run "dbt deps"`. The check now reads the tree as the plan
- leaves it: a package the plan declares that is not installed is refused naming
- the package and `transform deps`, with the route (plan the `packages.yml` change
- on its own, apply it, run `transform deps`, then plan the rest), as the new
- `PlanDeclaresMissingPackagesError`; a package the plan stops declaring no longer
- refuses it. A model with Jinja control flow, whose dbt compile had no package
- check at all, gets the same refusal. A `packages_yml`-only plan needs no parse
- and is still stored, and a plan still installs nothing. ([#1182](https://github.com/exmergo/dex/pull/1182))
-- **`data.row_attribution` names a changed `UNION`, `INTERSECT` or `EXCEPT` instead
- of reporting nothing.** Row attribution compares a model's scopes SELECT with
- SELECT, so a CTE or final select that is a set operation was skipped: a `WHERE`
- added to one branch of a `UNION ALL` produced no entry, and
- `data.refactor_comparison_offer` could read `static_attribution: none` for the
- model, as if the edit moved no rows. A set-operation scope that changed,
- including one that became or stopped being a set operation, now reports an
- `unattributable` entry naming the scope and saying its branches were not
- compared, in the words `data.change_scope` already uses. The offer then reads
- `unattributed` and recommends `transform compare` before apply, and the
- whole-model net is still measured. An unchanged set operation still reports
- nothing, and neither does one whose only edit re-cases an unquoted name;
- re-casing a quoted name such as `"Status"`, or a string literal, is a change. ([#1183](https://github.com/exmergo/dex/pull/1183))
-- **GROUP BY comparison ignores qualifier and table alias changes when each reference resolves to an unambiguous source relation.** ([#1185](https://github.com/exmergo/dex/pull/1185))
-- **Join coverage no longer measures through a CTE that drops rows with a join.**
- A join whose key is read through a CTE or subquery that narrows its rows with
- an inner, comma or CROSS join (or a RIGHT or LEFT join on the side the key is
- not kept on) was probed against the whole table underneath, so a key the CTE
- drops counted as a match and the join could be reported `satisfied`. It is now
- `unchecked` with `filtered_cte`, and the reason names the scope and the join. A
- CTE whose LEFT join keeps every row of the key's relation is still measured. ([#1186](https://github.com/exmergo/dex/pull/1186))
-- **`explore query --target dev` reads a model `transform build` just wrote.**
- On a warehouse, a model whose only build is the dev one could be profiled with
- `explore profile --target dev`, but `explore query` had no `--target`. The
- aggregate that checks the build was refused as "not in the exploration cache",
- naming the `explore profile` the caller had already run. `explore query` now
- takes the same flag: for one command it reads the dev namespace and the
- namespaces dbt derives from it for the project's models, such as a package's
- `+schema`. The firewall, the PII gate, values-free mode and the cost handshake
- are unchanged, `--scope` still only narrows, nothing is written to
- `.dex/config.yml`, and a prod-looking target is refused. Without the flag, the
- refusal names the dev namespace and `--target dev`. The same flag on
- `explore profile` also reads the derived namespaces now, so a package's model can be
- profiled. If the connection cannot be opened (for example, a DuckDB file that
- another process holds locked), a refusal for an uncached relation says why,
- instead of pointing at `explore map`, which needs the same connection. ([#1187](https://github.com/exmergo/dex/pull/1187))
-- **`transform test --mutate` plants defects in an incremental model's
- `is_incremental()` branch.** Every mutant builds ephemeral, so the branch never
- reached the SQL dex mutated: a model whose only comparison was its watermark
- was refused, and elsewhere the branch silently left the score. The model is now
- compiled a second time with the branch taken, its own comparisons and filters
- are planted there, and they run only against the unit tests that override
- `is_incremental` to true, which no longer run against the full build's mutants.
- `data.incremental` reports the branch with its own counts, score, baseline and
- share of the one cap. With no such test, every branch mutant survives and names
- that test as the one to write. ([#1190](https://github.com/exmergo/dex/pull/1190))
-- **A retirement reads a `*` over an untouched model, a seed or a profiled
- source (#1170).** `transform remove var` resolves stars through the toggle
- check's compiled-relation catalog, now one shared implementation, instead of
- reporting them as `unreadable_select`. An unprofiled source stays `unchecked`
- and names the `dex explore profile` command that supplies its columns. The
- check compiles the judged models with their ancestors (and the proposal with
- their descendants too), and a model that does not compile is recorded as
- `compile_failed` without stopping the rest. Contributed by Bradley Joseph. ([#1192](https://github.com/exmergo/dex/pull/1192))
-- **The toggle check judges what dbt compiled, not the source it could not
- parse (#1156).** A select list and its `group by` count gated with
- `{% if var(...) %}` left text the reference scan could not parse once its Jinja
- was blanked, and `data.toggle` came back `unchecked` with "could not parse the
- SQL for columns" on exactly the files the check exists for. Those limits are
- gone, since every model is already judged from its compiled SQL at both values.
-
- - A flag read in a project macro is attributed to the models whose compiled SQL calls it (`macro_reads`), and a `var()` with no literal name is listed under `dynamic_reads` with its model, rather than limiting the verdict.
- - A disabled model that reads the flag is named under `not_compiled`, and the verdict is incomplete for it alone.
- - dbt stops a compile at the first model that fails and then writes no compiled SQL for any model. Dex now sets that model aside (`compile_failed` on its own record) and compiles the rest again, so one broken model no longer leaves the whole project unjudged.
- - `transform plan` accepts a Jinja edit to a disabled model. It used to refuse with "dbt returned no fresh compiled SQL". The model is now compiled enabled in the throwaway copy, so its SQL is still held to the read-only checks, and a warning says it is not built.
-
- ([#1192](https://github.com/exmergo/dex/pull/1192))
-- **A full retirement runs when the reference scan's only limits are column
- parses (#1172).** `transform remove var` with a retirement contract refused on
- any limit, including SQL the column scan could not parse, which cannot hide a
- `var()` read. It now plans the full contract there. `removed_column_still_read`
- reads those files from compiled SQL where it can, and
- `data.retirement.column_reads` names any file read neither way. That leaves the
- verdict `unchecked` and is carried to the build as an unchecked obligation.
- Unread YAML, an unreadable package and a dynamic `var()` read still refuse, and
- `transform rename` and every other `remove` kind still refuse on any limit. ([#1192](https://github.com/exmergo/dex/pull/1192))
-- **`maintain verify` row-population findings now label a join to a set-operation CTE with the CTE's name.**
- When a model cross joins a CTE whose body is a set operation such as `UNION ALL`, the `row_fanout` finding detail fell back to calling it "the cross join to a subquery". dex now preserves the CTE's name in the finding detail, and labels an anonymous set operation as "a set operation" rather than a subquery. ([#1216](https://github.com/exmergo/dex/pull/1216))
-- **`semantic define`, `update`, and `plan` now refuse declared but uninstalled packages before running dbt parse.**
- When dbt packages were declared but not installed, the semantic commands ran shadow dbt parse directly and failed with dbt's raw `Run "dbt deps"` message. dex now runs the same post-edit package check used by `transform plan`, refusing upfront with `reason: prerequisite` and naming `transform deps` without invoking dbt parse. ([#1218](https://github.com/exmergo/dex/pull/1218))
-- **bigquery dry-run pricing warnings report missing relations on one line
- without request urls or job ids (#1209).** upfront cost preflight on a cold dev
- target previously dumped multi-line notfound exceptions into warnings.
- notfound errors from dry runs are now translated through the adapter's error
- translation to a clean single line naming the missing relation with the estimate
- marked partial. ([#1219](https://github.com/exmergo/dex/pull/1219))
-- duckdb: carry catalog components on object metadata and quote each
- component rather than splitting the flat identifier, so relations with a
- dot in schema or table name resolve correctly (#1210). ([#1220](https://github.com/exmergo/dex/pull/1220))
-- **The values-free conformance suite no longer reads a cache timestamp as a leaked
- value.** `find_sentinels` searched a payload for each sentinel as a plain
- substring, and four sentinels are bare five-digit runs, so a timestamp the cache
- itself wrote, such as `00:34:22.731950`, read as a leaked balance and failed
- `test_a_profile_over_a_full_cache_carries_no_value` at random, in this
- repository's CI and in a host's that runs `ValuesFreeContract` against the release
- it pins. The fractional seconds of a time of day are now masked before matching.
- The fixture's own timestamps have none, so every seeded value, a leaked fixture
- timestamp included, is still caught. ([#1226](https://github.com/exmergo/dex/pull/1226))
-
-### Security
-
-- **A warehouse error no longer quotes the value it failed on.** A conversion,
- parse or range failure (`Could not convert string 'x' to INT32`, `Bad int64
- value: x`) quotes the input it could not handle, which is a row's value, and that
- text reached errors, warnings, notes, verification records, the cache and the
- query log. The warehouse's words are now kept and the value is masked
- (`Could not convert string to INT32`) on every connector and
- surface, including dbt build messages and the hosted semantic layer. In
- values-free mode, a join probe that `explore relationships --verify` or
- `explore map --verify` could not run now names the exception type only. ([#1176](https://github.com/exmergo/dex/pull/1176))
-
-
-
-
-
-### Added
-
-- **Join coverage is now measured through a filtered CTE over the rows the model actually joins.**
- A join whose side is read through a CTE or subquery that filters used to come back
- `unchecked` with `filtered_cte`, since probing the physical table underneath would count
- rows the model never joins. When every filtering hop reads one relation, its only reducing
- clause is a `WHERE`, and each conjunct is a row-by-row condition over columns and literals
- (comparisons, `IN` over a literal list, `BETWEEN`, `LIKE`, `IS`, boolean logic, `coalesce`,
- casts, `lower`/`upper`/`trim`, as in `where coalesce(_fivetran_active, true)`), the probe now
- reads that side through the same filter. Counts and denominators are the filtered
- population's, and a key that exists only in rows the filter drops is not a match. The
- record carries `effective_input`: per side, the relation, the scopes it was read through and
- the filters applied. Any other reducer (a `GROUP BY`, `DISTINCT`, `LIMIT`, `HAVING`,
- `QUALIFY`, a join beside the filter, a subquery or clock function, a filter on a computed or
- window column such as `rn = 1`) stays `filtered_cte`, now with a reason that names the scope
- and the shape at any depth. `maintain verify` and `transform build --verify` share the
- change, and the extra filters are priced in the same estimate (#1085). ([#1085](https://github.com/exmergo/dex/pull/1085))
-- **A feature retirement keeps its checks when Dex cannot finish scanning the project for the flag's readers.**
- `transform remove var` with a `retirement` contract refuses while the reference scan has a limit:
- SQL it cannot parse for columns (common in Jinja-heavy macros and in packages such as
- `dbt_utils`), unread YAML or packages, or a var read that names its variable at run time
- (`var('using_' ~ name)`). Agents then fell back to a plain `transform plan`, which refuses a
- `retirement` key, so no output was checked at all. The contract now takes `"scope": "authored"`
- for that case. It is admitted only where the full scan cannot finish, its `outputs` must be
- models this project defines, a removed metric must be one this project defines, and it must
- cover every model the payload rewrites, and literal and
- YAML reads of the flag are still refused until edited. The plan, `transform compare` and
- `transform build --verify --for-plan` check the named outputs and metrics exactly as before.
- Global discovery is reported apart as `data.retirement.discovery` (`status: unchecked`,
- `reason_code: discovery_incomplete`, the project `limits`, a count per package, unread files and
- dynamic reads), and the build adds a `reference_discovery` record that stays `unchecked` in
- `data.completion.obligations`, so passing output checks never reads as a feature retired
- everywhere. Without `scope`, the refusal is unchanged and now names this route. The scope and
- the discovery summary travel in the plan document and its digest; a complete retirement's
- stored form and digest are unchanged. (#1086) ([#1086](https://github.com/exmergo/dex/pull/1086))
-- **A plan now says what a repair changes beside its request, and which of those changes no assumption records.**
- A repair is meant to change some behavior and keep the rest. Two failures passed every plan-time
- check: a filter meant for the aggregates that also landed on a roster model, and a coverage fix
- that also changed what an empty window counts (`count(*)` over a left join counts one where it
- should count zero). `transform plan` now carries `data.change_scope` for each existing model it
- rewrites, read statically from both versions with no query on any connector. `population` is
- `changed`, `kept` or `unchecked`, and `changes` names each population change with the columns it
- reads, plus each output removed, added, retyped, re-aggregated or re-NULLed, in the final select
- and every CTE both versions share. A population change, a removed column and a changed type,
- aggregate or NULL treatment is `declared` where an existing assumption's `column` names a column
- it governs, and `undeclared` otherwise, with a warning: record it if the request asks for it,
- undo it if not. No new declaration field is involved. An added column and a rewritten formula are
- listed without a verdict. A `--for-plan` build carries the unsettled entries into
- `data.completion.obligations.change_scope`, and `data.decisions` now relays each assumption's
- `detail`. The shared procedure gains a short "settle the scope before the repair" step. The
- metadata eval adds `sandbox_scope` (a narrow, a broad and an ambiguous sandbox exclusion, graded
- by a new Scope axis that accepts either roster policy when it is recorded) and `visit_coverage`
- (filling missing days while keeping zero counts, NULL averages and column types). (#1115) ([#1115](https://github.com/exmergo/dex/pull/1115))
-- **version promotion checks that moved consumers read only columns in the new default.**
- when a model version promotion moves an unversioned consumer to a new default
- version, the plan now inspects the consumer's select list against columns present
- in the new default. if the consumer reads columns that the new default lacks, a
- warning is returned naming the consumer path, the model, the missing column(s),
- and the old and new version. consumers pinned with `ref('x', v=N)` are not checked
- because their target does not change. consumers whose select list cannot be read
- statically are warned as unchecked. the plan is not refused (#1124). ([#1124](https://github.com/exmergo/dex/pull/1124))
-- **`transform test --scaffold` now places boundary rows for day windows over whole-day expressions.**
- BigQuery has no interval `RANGE` frames, so day windows are commonly written as
- numeric `RANGE` frames over epoch-day expressions such as `unix_date(pickup_date)`
- or `date_diff(pickup_date, date '1970-01-01', day)`. The scaffold now recognizes an
- `ORDER BY` expression that is a whole-day function of one date column and treats
- the numeric bound as days, placing the same four boundary rows (anchor, last
- included day, first excluded day, and a gap in calendar dates) as an interval frame
- does. Any numeric `RANGE` over another expression keeps the `numeric_range_offset`
- warning note (#1135). ([#1145](https://github.com/exmergo/dex/pull/1145))
-- **Cube relative date ranges are recorded and documented.**
- An `inDateRange` filter with a relative value (such as `"last 7 days"`) is moved
- into the time dimension's `dateRange` when that dimension is grouped, and is
- resolved to timestamps by Cube at render time using the Cube server's clock.
- The resolved timestamps come back as bound parameters so Dex binds and prices
- exactly what runs. A recorded case in `tests/cube_vendor/cube_cases.py` now
- exercises this path, and `references/cube-compatibility.md` documents that a
- server in another time zone or with a skewed clock resolves it differently (#972). ([#1147](https://github.com/exmergo/dex/pull/1147))
-- **`explore --use-project` carries declared temporal history contracts.**
- when a dbt model declares a `history` contract block under `config.meta.dex`,
- `explore profile --use-project` and `explore map --use-project` now report it as
- `history` on the model's `declaration`. under `--values-free` or when profiling
- flags the status column as personal data, `status.target` is withheld as null
- and recorded in `withheld_fields`. ([#1149](https://github.com/exmergo/dex/pull/1149))
-- **A feature flag that stays live is checked in every model, on both values.**
- "Hide these columns when the flag is false" was easy to finish half-way: gate
- the models that feed one mart, and a ledger nothing in the marts reads, a model
- that inherits the column through `select *`, or a model whose table is empty
- still outputs it with the flag off. A green build and a row comparison cannot
- see either. `transform plan` now takes a `toggle` contract beside the edits:
- `variable`, `on_value`, `off_value` (both required, never read off a default),
- the governed `columns` and any `exempt_models`. `data.toggle` compiles every
- model of the project in a throwaway copy at each value, and the tree before the
- plan at the on value, probing no table's rows. It names each model that still outputs
- or reads a governed column with the flag off, loses one with it on, or loses or
- varies a column the toggle does not govern, with a `verdict`, `completeness`,
- `contract.producers` and the package readers it leaves out of scope.
- `transform compare` compiles both sides at the on value (`data.proposed_vars`),
- and `transform build --verify --for-plan` judges each built relation's columns
- from metadata at the value the build used. Findings are
- `toggle_column_present_when_off` and `toggle_column_missing_when_on`, and the
- other value is reported `unchecked` (`branch_not_built`). An off build no longer
- reports a governed column that `schema.yml` documents as `column_missing`. The
- contract travels in the plan document and its digest. Every other command
- refuses a `toggle` key rather than dropping it. New recipe:
- `skills/transform/references/feature-toggles.md`. (#1113)
-- **`transform test --scaffold` tests an incremental model's next run, not only its full build.**
- A full build and every `--full-refresh` run only an incremental model's full
- program, so a repair checked that way could leave the `is_incremental()` branch
- skipping rows on the watermark. On a model whose only jinja control flow is
- `{% if is_incremental() %}` (with an optional `{% else %}`), the scaffold now plans
- two dbt unit tests: `test_` with dbt's `is_incremental: false` override
- (which dbt requires on every unit test of an incremental model, so the scaffold
- previously could not be built there), and `test__incremental` with
- `is_incremental: true` and a `this` fixture written as typed SQL, so it runs
- before the model was ever built. Where the branch compares one column with a
- subquery over `{{ this }}`, a new `data.incremental.watermark` names the column,
- the comparison, the input and the `this` column, and the fixture puts rows
- before, on and after that watermark plus a NULL. A `this` column no input passes
- through is typed from the cached profile of the model's relation, or the scaffold
- refuses and names the profile to run. A failing unit test's build error now
- reads `actual differs from expected` instead of an empty `dbt build failed: `,
- and a node's message no longer carries dbt's color codes. The shared procedure
- says a full refresh does not show the next incremental run is right. New recipe:
- `skills/transform/references/incremental-repairs.md`.
-
-### Fixed
-
-- **Identifier-conversion counts now cover the rows the model keeps.**
- In `transform plan`'s `data.identifier_conversions`, a join conversion's `matched_entities`
- now counts only partner keys that pass the partner side's own `WHERE` and `ON` conjuncts,
- listed in `partner_filters`; it no longer overstates matches on a filtered inner join. A
- row-by-row `WHERE` in a later CTE on the chain that reads the conversion's scope is now
- carried back onto the rows counted (`later_filters_applied`), so identifiers the model
- removes anyway are no longer counted as failures. Anything else a later scope does to those
- rows is named in `later_filters_not_applied` with its reason: a filtering join, `HAVING`,
- `QUALIFY`, `LIMIT`, a filter on the conversion's own output or on the join's other side, or a
- scope that is read twice. A bare join key beside another `ON` conjunct is no longer
- misreported as an unsupported rewrite (#1073). ([#1073](https://github.com/exmergo/dex/pull/1073))
-- **An empty plan id is refused, and a missing one names the plan Dex picked.**
- `transform apply ""` read the empty id as no id and applied the latest unapplied
- plan, so `apply "$(dex transform plan ...)"` after a failed plan applied an
- earlier plan and said nothing about it. An explicitly empty or blank plan id is
- now refused with `reason: request` on `transform apply`, `export`, `ground`,
- `classify` and `compare`, before the plan store is read, and so are an empty
- `transform apply --plan-file` (which fell through to applying the latest stored
- plan) and an empty `transform build --for-plan` or `--for-plan-file` (which
- built with no plan coverage). With no id, `apply` still applies the latest
- unapplied plan and the other four still select it without applying anything,
- and each now names it in a new `data.resolved_plan`
- (`{plan_id, intent, created_at, resolved_from: "latest_unapplied"}`), placed
- beside `data.plan_id`, and in one `warnings` line, on the `needs_confirmation`
- apply and on a refusal raised after the pick (where an in-process host reads it
- as the exception's `resolved_plan`). An explicit id adds neither. ([#1103](https://github.com/exmergo/dex/pull/1103))
-- **`transform init --connector bigquery --project ` now honors the explicit
- project.** Init rendered its dev profile from configuration and credential
- discovery only, so a fresh repository with no `bigquery.project` and no gcloud
- default refused with "no GCP project to wire the dev target to" even though the
- command named one. The explicit project now wins over a configured or discovered
- one, and the generated profile and the saved `.dex/config.yml` both record it,
- so the initialized project needs no prior config edit. Without the flag, the
- existing configured and discovered resolution, and its actionable refusal when
- nothing resolves, are unchanged. A malformed `--project` (blank,
- whitespace-only, or not a BigQuery project id) is refused rather than written to
- the profile and the config; hyphenated ids and the legacy
- `example.com:my-project` form are accepted. ([#1107](https://github.com/exmergo/dex/pull/1107))
-- **`parent_population` now reports `parent_not_built` when a parent is missing.**
- before, a declared parent omitted from a build reported `not_measured` with
- `no single relation in the warehouse matched the parent`, confusing an unbuilt
- parent with ambiguous matching. when no warehouse relation matches, the record
- now reports `parent_not_built`. if a build selection is present, the message
- names the selection, suggests adding the parent to `--select`, and notes that
- a parent that is not an ancestor is never built by `+`. multiple matches
- continue to report `not_measured`. ([#1109](https://github.com/exmergo/dex/pull/1109))
-- **`transform test --mutate` now plants the boundary defects of a calendar window.**
- A frame bound written as an interval (`RANGE BETWEEN INTERVAL '6 day' PRECEDING`)
- had no mutation site, so a window's boundary could never show up as untested.
- Such a bound now gets two mutants, one unit wider and one unit narrower, with the
- unit kept as written. Each window mutant carries `frame`, naming the last day the
- window includes and the first it excludes. A numeric `ROWS` bound keeps its single
- mutant, and a numeric `RANGE` bound's defect now speaks of the ordering value
- rather than rows. A bound Dex cannot shift (a column, a fraction, a compound
- interval, or the frame's other bound) is listed under `data.unsupported_sites`
- with a reason code and a warning, rather than passing silently.
- `transform test --scaffold` places that boundary's fixture rows for a day or week
- interval over a date column: the current day, the last included day, the first
- excluded day, and a gap a row-count frame would cross. The new
- `skills/transform/references/test-strength.md` walks through the measure,
- strengthen and measure-again loop (#1112). ([#1112](https://github.com/exmergo/dex/pull/1112))
-- **`maintain reconcile` no longer stages a YAML edit for a source rename the staging model already absorbs, and no longer skips YAML cleanup when SQL could not absorb a drop.**
- when a model keeps its contract with an alias such as `page as page_path` over a
- renamed source column, the SQL splice is correctly a no-op, but the YAML half
- used to follow the source shape anyway and would break the model's column
- contract. YAML is staged only when the model's output actually changes; absorbed
- drift is reported as covered. a star model (or SQL already edited by hand) that
- no longer outputs a dropped column still gets its stale YAML entry removed, and
- downstream-reader warnings fire only when staging output actually changes. ([#1117](https://github.com/exmergo/dex/pull/1117))
-- **Verification no longer reports false `row_loss` for scalar aggregates.**
- a model that intentionally collapses every input row with `COUNT(*)`,
- `SUM(...)`, or another aggregate and no `GROUP BY` (including when that
- aggregate sits in a CTE the final select only projects) used to look like
- unexplained loss because nothing in the SQL named a reducer. those selects
- now count as a scalar aggregate, the same way a `GROUP BY` already did. a
- window such as `COUNT(*) OVER ()` still does not, so real join loss stays
- visible. ([#1119](https://github.com/exmergo/dex/pull/1119))
-- **`maintain grain` judges keys and joins on databricks tables with no `numrows`.**
- databricks tables whose `describe detail` reports no `numrows` have no catalog
- row count, and distinct probes previously did not select `count(*) as n_total`.
- as a result, `maintain grain` could not verify key uniqueness or join
- cardinality and produced warnings. the distinct-count and composite-key
- probes now select `count(*) as n_total` in the same priced scan, updating
- the cached row count so keys that lost uniqueness and join fanouts are
- verified without warnings. ([#1121](https://github.com/exmergo/dex/pull/1121))
-- **A governed Cube query now holds each cube to its own table.** Cube's `/v1/meta`
- carries no `sql_table`, so a plan was refused only when it read a table no cube in
- the repository sits on. A Cube server whose cubes swapped tables passed. Cube
- writes each cube's relation as `FROM
AS ""`, so the plan is now
- refused when a cube is read from another table than the `sql_table` its file
- declares. ([#1136](https://github.com/exmergo/dex/pull/1136))
-- **YAML-mode relationship tests keep the version on `ref(x, v=N)`.**
- without a manifest, a relationships test's `to: ref('dim_teams', v=2)` was
- read as `dim_teams`, so declared joins disagreed with the compiled project.
- the version label is kept, and a bare `ref()` to a versioned model resolves
- to `latest_version` the same way the manifest reader does. ([#1141](https://github.com/exmergo/dex/pull/1141))
-- **Generated dbt unit tests for incremental models without an `is_incremental()` branch now include the required `is_incremental: false` macro override.**
- dbt requires an `is_incremental` macro override for every unit test of an incremental model, even when the model SQL does not contain an explicit incremental branch. dex previously omitted this override when no incremental block was present in SQL, causing dbt unit test parsing to fail. dex now resolves model materialization and includes `is_incremental: false` in the generated full-build test. ([#1144](https://github.com/exmergo/dex/pull/1144))
-- **Build evidence no longer lists a skipped model's stale relation as generated, and an unrecognized node status can no longer read as `validated`.**
- `data.evidence.generated` now lists only the relations of models, seeds and snapshots that succeeded in the run, so a relation an earlier run left behind is not reported as fresh when this run skipped its model (#1104). Node statuses are now read against an allow-list: `success`, `pass` and `warn` succeeded, `error`, `runtime error`, `fail` and `failed` failed, and `skipped` was not attempted. Any other status, such as a microbatch model's `partial success` or `no-op`, is unrecognized: it never counts as built, never validates, and is not reported as a failure. The new outcome `indeterminate` says so, `data.completion.deliverables.unrecognized` names such a deliverable, and `transform compare` treats a parent on such a status as not rebuilt. A required node that is present without succeeding, beside passing nodes and with nothing failed, now makes the outcome `partial`, agreeing with `coverage.not_built` (#1105). Downstream-visible: hosts that store `generated`, or recompute and compare outcomes, will see the new values, and `verify_build_evidence` now refuses a document claiming `validated` over an unrecognized status. A new conformance vector covers `indeterminate`, a forged vector covers that refusal, and the `build-skipped` vector's `generated` is now empty. ([#1153](https://github.com/exmergo/dex/pull/1153))
-- **A Postgres table with a text column under a nondeterministic collation can be profiled.**
- Postgres refuses a regular expression and `replace()` under a nondeterministic
- collation (an ICU collation created with `deterministic = false`, such as a
- case-insensitive one), and the value-shape probes in `explore profile` use
- both, so one such column failed the profile statement for the whole table, and
- with it `explore map` and the on-demand profile behind `explore query`. The
- probes now read the column as `text` under the `C` collation. The patterns are
- ASCII, so matches on text columns are unchanged. Two string types were matched
- wrongly before and are now read as text: a `char(n)` value shorter than `n`
- no longer has its padding defeat the patterns' end anchors, and a `citext`
- column is matched case-sensitively, as on every other connector.
-- **A refactor blocked by a failing prerequisite can now be compared once the repair is built, including by a `--cold-deps` build.**
- `transform compare` judged a refactor's inputs by the ordinary build's
- `run_results.json` alone, while a `--cold-deps` build writes its own under
- `cold/`. A package prerequisite repaired and proven with `--cold-deps`, as the
- procedure asks, still compared `inputs_unsynchronized`, naming the failure that
- build had repaired. It now reads each upstream model's latest build attempt,
- ordinary or cold, with the manifest of the newest; a compile no longer counts as
- one. The `inputs_unsynchronized` detail names the order that clears it: the
- repair in a plan of its own, applied and built (`--cold-deps` for a package's
- model), then the refactor's plan compared while still unapplied. A recorded
- verdict includes `inputs_built_by` (`invocation_id`, `generated_at`, `cold`) when
- an upstream build exists: the latest build among the compared model's upstream
- models, recorded on the plan and reported by `transform apply` and a
- `--for-plan` build. It names one run; other inputs may come from earlier builds.
- It is absent where no build attempted those models, and on
- `awaiting_confirmation` and `plan_applied`, which are not recorded. `data.refactor_comparison_offer` on
- `transform plan` now says before any comparison whether the baseline builds:
- `baseline_ready`, and `per_model[].blocked_inputs` with each input's status and
- owner, with `data.next` leading with the repair. A plan that carries the repair
- beside the rewrite, whose comparison could only read the failed build, is named
- in `mixed_with_repair` with a warning. `transform deps` and the shared procedure
- say that installing a project's declared packages is not installing or upgrading
- a tool. New eval task `refactor_prerequisite/package_blocked_refactor`, and two
- procedure steps, `rebuilt_before_compare` and `cold_deps_after_repair` (#1114).
-
-### Security
-
-- **Concurrent commands no longer revert each other's exploration cache writes.**
- A command that writes the cache (`explore profile`, `explore relationships`,
- `explore map`, and `explore query` or `explore cluster` when they profile an
- object on demand) merged its profiles into the copy it loaded at its start and
- saved that, so a profile another command saved in the meantime was overwritten.
- That included a PII flag a refresh had just raised, which the query firewall then
- read at its old confidence until the next refresh. Only commands running at the
- same time against one `.dex/` were affected; one command at a time never was.
-
- - Every cache write now re-reads the stored cache under a new store-level cache
- lock, folds its own profiles into it, keeps any stored profile newer than the
- copy it carried, and saves before releasing the lock. No warehouse query runs
- under the lock.
- - The filesystem and SQLite backends hold the lock on `.dex/cache.lock`, apart
- from the spend lock. The in-memory backend holds it across threads.
- - A storage backend you wrote can offer the same lock through the new optional
- `CacheLock` protocol (`cache_lock(timeout=...)`). Without it, dex still re-reads
- the cache before merging, which narrows the window without closing it.
-
- Reported by [@catincloudlabs](https://github.com/catincloudlabs).
-
-
-
-
-
-### Added
-
-- **Declare one version of a versioned model.** A declaration naming `dim_teams.v2` renders into that version's item under `versions:`, and every other byte is kept. A fact about a column the version inherits is written as dbt's own override, and a model-level fact the shared entry also states is refused, because dbt concatenates the two lists. `transform declare dim_teams.v2` proposes for that version instead of skipping it. `explore --use-project`, `maintain snapshot` and declaration drift, `maintain verify` and drafting all read a version under its label.
-- **Plan and verify native dbt model versions.** A plan that touches a versioned model reports it under `data.model_versions`: each version's file and relation, the default an unversioned `ref()` resolves to before and after, and what every consumer's `ref` resolves to. dbt's own parse of the post-change project confirms it. A version no file builds (dbt only warns about it), two versions on one file, or a plain entry beside a version is refused with a typed code. A promotion and a warehouse relation that would move are warnings, and a new `_v` copy is named as an independent model, not a version. `transform build --verify --for-plan` holds the plan's versioned models to the manifest it built, with one record per version, default and consumer under `data.verification.model_versions`, each reaching the completion obligations. New recipe: `skills/transform/references/model-versions.md`.
-- **Show earlier prerequisite statuses.** Failed prerequisites include context from the last available build artifact, preserved across pricing and confirmation retries without another warehouse build. The evidence is historical and does not change `plan_relation`.
-
-### Changed
-
-- **stale-renderer check compares join sql and relationship.**
- the stale-renderer check in `cube/query.py` previously compared every member
- a query names and references, but skipped joins. queries against a cube whose
- join condition or relationship changed in the repository after the server
- started were rendered with outdated conditions. the stale check now compares
- the join sql and canonical relationship for every cube the query reaches,
- refusing when the server's `/v1/meta` disagrees. ([#969](https://github.com/exmergo/dex/pull/969))
-- `explore profile` now reports `mixed_identifier_shapes` for id-shaped columns that are not proven unique, so `transform plan` can cite that evidence on the common nullable-key repair case (#1072). ([#1072](https://github.com/exmergo/dex/pull/1072))
-- **A key cast to an integer is measured on Postgres.** Postgres has no cast that
- returns NULL on failure, so `transform plan` (`data.identifier_conversions`)
- and `maintain verify` (join coverage) reported every cast key there as
- `unchecked` with `reason_code: no_safe_cast_on_connector`. A cast to
- `smallint`, `integer` or `bigint` is now measured through a guarded cast: a
- value that is not an integer, or is out of range for the type, counts as
- failed instead of failing the probe. A cast to any other type still reports
- `no_safe_cast_on_connector`. ([#1087](https://github.com/exmergo/dex/pull/1087))
-- **The agent procedure repairs the layer the request names.** Before choosing a
- remedy for a failing prerequisite, the procedure now has the agent settle whether
- the request asks for a change to the input data or to the project. A project
- override no longer stands in for a request to modify the data, and a request to
- adapt the project never changes the input. A project-owned seed changes through
- its CSV or `+column_types` and a build. A source a loader owns cannot be changed
- from Dex, so any migration is a reviewable file marked as not run, and that part
- is reported incomplete. The agent checks the requested postcondition on the
- original relation, and `--cold-deps` evidence is no longer read as proof that
- data changed. The prerequisite-repair recipe gains a section on choosing the
- layer. No guard changes: Dex stays read-only against data.
-
-### Fixed
-
-- **snowflake uptime settlement applies resume minimum when warehouse resumes mid-run.**
- when another command suspended a shared snowflake warehouse between statements of a
- running command, the next statement resumed the warehouse, but settlement charged no
- resume floor because the warehouse was found running at the start. settlement now
- detects that `resumed_on` moved during the command and applies the 60-second floor
- from the statement that resumed it. ([#938](https://github.com/exmergo/dex/pull/938))
-- Identity comparison on an identifier conversion now follows a repair that casts and renames the key column, naming both the prior and authored outputs; two authored outputs from one source column still report `no_shared_key_column`. ([#1074](https://github.com/exmergo/dex/pull/1074))
-- **identifier conversion probe preserves quoted mixed-case cte names.**
- `conversion_probe` previously re-emitted cte names lowercased and unquoted
- in the probe's from clause, which failed to resolve on case-sensitive
- connectors like snowflake and postgres when a cte name was quoted and
- mixed-case. the probe now re-emits the cte's original identifier node,
- preserving quotes and casing as written. ([#1077](https://github.com/exmergo/dex/pull/1077))
-- Grain drafting no longer picks a PII-flagged column as the grain when a non-PII candidate exists, and when every candidate is flagged the draft evidence says so instead of staying silent. The PII preference also reads profiles stored under a model's configured alias, and the contradiction check matches a declared grain against every proven key, so an edit that strips the declared key of its proof still warns when another key remains. ([#1079](https://github.com/exmergo/dex/pull/1079))
-- ``macro_dispatch`` repair now walks through plain package macros that a model depends on, so models that depend on a macro which itself dispatches still get the prerequisite. ([#1081](https://github.com/exmergo/dex/pull/1081))
-- **`maintain grain` now checks a join declared after the baseline.** Before, `join_orphans_increased` covered only joins the baseline already held, so a relationship declared since the snapshot, or re-declared on other columns, was never checked. A join that was already wrong when the baseline was pinned was never reported either, because its orphan fraction became the "before". The grain axis now reads the joins declared today, the same way it reads declared grains. These come from the project (`relationships` tests, `references:` declarations, declared relationships) and from a native semantic layer (Ossie, Cube, SLayer); a dbt semantic layer's entity joins are not read here. A join the baseline measured under the bound is still compared with its earlier orphan fraction. Any other declared join is checked against a fixed bound and reported as `declared_join_orphans` at 20% orphaned or more (`high` from 50%). `data.baseline` (`absent`, `unmeasured` or `measured`) says why the bound applied, and a join that `join_orphans_increased` already reports is not reported twice. A declared join that does not resolve to the warehouse, or that names a missing column, is listed in `warnings`. `maintain check` runs the same probes. On a billed connector the new probes are priced in the same estimate, so a baseline mapped without `--verify` can now make `maintain grain` ask for confirmation, or `maintain check` make an offer, where it ran free before. ([#1097](https://github.com/exmergo/dex/pull/1097))
-- **A version's build no longer answers for another version.** A `--for-plan` build named a versioned model's deliverables by file stem, so a v2 that built could cover a v1 that failed. Deliverables are now each version's label (`dim_teams.v1`). A declared `population.parent` naming a versioned model now resolves to its default version, not to whichever version the manifest listed first.
-- **Agents preserve authorized protected columns when inspection is refused.** The
- shared procedure distinguishes a protected-value read refusal from a supported
- transformation: retain the requested or existing column contract, validate with
- metadata and permitted aggregates, and redact only when an applicable instruction
- or contract requires it. Privacy guards and human-only PII clearing are unchanged.
-- **Deleting a project override of a package model is no longer refused.** A plan
- that deletes a project model overriding a package model, and removes the
- `+enabled: false` that disabled the package's own copy, was refused because a
- surviving `ref()` still named the model. The package's model answers that `ref()`
- once it is enabled again, so the delete guard now accepts it. It is the step that
- undoes a project adaptation, for instance when the request turns out to be a repair
- to the data. A deletion that leaves the package model disabled is still refused.
-- **Honor repair and evaluation boundaries.** Removing a seed column type declaration rebuilds the selected dev seed using CSV inference, retaining applied declarations across pricing and narrow selections. Restored package models cannot satisfy references pinned to another package. Evaluation flags exclude shell comments, and incomplete-report scoring recognizes straight and curly apostrophes in contractions. Shared guidance hands repairs from read-only workflows to transform and profiles built seeds on dev.
-- **Nested `DESCRIBE` queries now return an actionable refusal.** Queries with
- unsupported nested statement shapes are rejected before warehouse access rather
- than raising an internal planning error. The refusal directs metadata requests
- to `explore inventory` or `explore profile`; ordinary SELECTs and existing
- privacy and read-only guards keep their behavior.
-- **Report which models actually built.** Verification scope excludes failed and skipped models and names them under `scope_not_built`. Build coverage preserves `covered` as presence in run results and adds `built` and `not_built` for successful execution.
-- **`transform build` applies a changed seed `+column_types` on DuckDB.** dbt
- reloads a seed into the table it already built, so a `column_types` entry added
- or changed after the first build was ignored and the column kept the type
- inferred from the CSV, with a green build. The pre-build seed check now also
- compares each selected seed's declared column types with its table in the dev
- target, through the connector's type aliases, and rebuilds a seed that differs
- with `dbt seed --full-refresh`. `data.full_refresh` names it and a warning says
- why.
-- Package readers (`installed_packages`, `needs_deps`, grounding and reference scans) honour `packages-install-path` instead of hardcoding `dbt_packages/`.
-
-
-
-
-
-### Added
-
-- **`transform remove var` records and verifies which behavior survives a flag.**
- "Retire this feature" and "make it permanent" both remove a variable's spelling,
- so a search for the name cannot tell them apart. A `retirement` key in the
- `--edits-file` payload now states the outcome: the flag value whose behavior
- survives, the columns each output then holds, and the metrics that remain.
- Dex never chooses the branch and never reads one off a default. The plan compiles
- the baseline at each value and holds the proposal to the contract under
- `data.retirement`, `transform compare` compiles its baseline at the retained value,
- and `transform build --verify --for-plan` checks the built relations' columns under
- `data.verification.retirement` and `data.completion.obligations`, which judges an
- empty table too. Package readers are reported and never edited, a read-only
- `var('x', true)` can be retired, and repeating a finished retirement is a no-op.
- Commands without a contract behave as before, and existing plan digests do not move. ([#858](https://github.com/exmergo/dex/pull/858))
-- **A rewritten model's plan now points to `transform compare` before apply, and apply reports what it found.**
- The plan's `data.refactor_comparison_offer` gives each rewritten model its own
- command and `static_attribution`, which says whether row attribution established
- anything (it cannot when the SQL calls a macro). `data.next` names the comparison
- ahead of `transform apply`. Each verdict is recorded on the plan, and
- `transform apply` and `transform build --for-plan` report it, or report
- `not_compared`, without refusing anything. `transform compare` now returns
- `inputs_unsynchronized` when the last build left a parent errored or skipped,
- because both sides would read that parent's outdated relation. The shared
- procedure tells agents to compare a change meant to keep results, and how to act
- on each verdict.
-- **Join coverage is measured through a cast key.** `maintain verify` and
- `transform build --verify` used to report a join such as
- `try_cast(a.k as int) = b.k` as an unchecked `non_equality_join`. They now probe
- it through the same conversion (a hard cast is measured as its safe form) and
- record it under `key_conversion`. Keys the conversion fails on stay unmatched and
- are counted as `conversion_failed_rows` and `conversion_failed_keys`. A key
- rewritten by any other function is `unsupported_key_expression`. `explore profile`
- also restates a candidate key mixing value shapes as the finding
- `mixed_identifier_shapes` (#861).
-- **`transform build` leads its payload with a bounded `data.completion` summary.**
- The summary comes first and stays under 4096 bytes, so a reader whose harness cuts
- the output after a few kilobytes still sees whether the change was done. With
- `--for-plan` it lists the required deliverables that were built, failed, skipped,
- missing or stale, and what blocked each one. A skipped model is never counted as
- built, even when dev still holds a relation from an earlier run. It also shows
- which deliverables anything checked (`asserted` or `build_only`), what
- verification ran, found and suppressed, and the declared obligations by status.
- Without a plan, coverage is `unknown` rather than empty. It appears on
- failed builds too, and Python callers get the same typed `BuildCompletion`.
- `success`, `outcome` and every existing field are unchanged.
-- **`transform build` says who owns a failed prerequisite, and `--cold-deps` proves a
- repair survives a reinstall.** `data.prerequisites` names each failed node's owner
- (project or package), its relation to the named plan, the required models behind
- it, and the repair routes dbt supports, including why an override does not apply
- (a reader pinned with `ref('pkg', 'model')`, a versioned or Python model).
- `--cold-deps` reinstalls packages into an isolated copy and builds from it, under
- the usual dev-only and cost gates. `data.cold_verification` lists the pins and every
- file the installed tree held that the reinstall did not reproduce, so an edit under
- `dbt_packages/` shows up as lost. An ordinary build never reinstalls. The recipe is in
- `skills/transform/references/prerequisite-repairs.md`.
-- **`transform plan` reports what an identifier conversion does to a model's
- entities.** Each `cast`, safe cast (`try_cast`, `safe_cast`, `try_to_number`),
- `lower`, `upper` or `trim` that a plan adds to an identifier column is listed under
- `data.identifier_conversions`. It covers filters, joins and projections, on new and
- edited models. Aggregate counts show how many distinct identifiers reach the
- conversion, how many fail it (NULL keys counted apart), how many merge into one key
- (`7` and `007`), how many change spelling, and how many still match across a join.
- On an edited model, the prior and authored identity sets are compared too, so an
- identity change shows even when the row count is unchanged. Each count states its
- denominator. An intentional filter elsewhere in the model is respected. Status is
- `lossless`, `declared`, `undeclared` (with a warning listing the
- contract-compatible options) or `unchecked` with a `reason_code`. Assumptions
- take an optional `column`, which is how a deliberate exclusion becomes
- `declared`. The counts are free on DuckDB and priced with row attribution
- elsewhere. No value is returned. An unsettled conversion on a required model
- appears under `data.completion.obligations.identifier_conversions` on a
- `--for-plan` build (#861).
- With `--attribute-rows`, a plan for a new model can now spend on these counts, and a
- cost-guard refusal is raised as it is for row attribution.
-- **`transform plan` warns when a model declaring `population.parent` is driven from
- an unrelated relation, on a new model as well as an edited one.** The warning names
- the driving relation, the parent and both fixes, under
- `data.declarations..contradictions` (`check: population_parent`). A relation
- in the parent's lineage, either direction, stays silent, as does a RIGHT, FULL or
- CROSS join that keeps the parent's rows. A driver Dex cannot read is `unchecked`.
- `population_contract` says whether a population is `prose` or `executable`, and
- `data.completion.obligations.prose_population` names required models nothing can
- check.
-
-### Changed
-
-- **`maintain reconcile` cuts a Cube view source whose includes all go.**
- when a dropped column removes every member in a view source's `includes` list,
- reconcile cuts that whole source entry from `cubes` rather than leaving
- `includes: []`. if that removal empties all sources for the view, the proposal
- is kept advisory with an explanation instead of writing a plan that would
- leave an empty view. ([#1051](https://github.com/exmergo/dex/pull/1051))
-
-### Fixed
-
-- **keep the model file on a case-only rename apply.**
- On a case-insensitive filesystem, `transform apply` treated the create half of a
- case-only rename as already applied (the delete path resolved to the same file)
- and then deleted that file, so the model disappeared. `write_edits` now detects
- a create+delete pair that differs only by case and applies them as one rename
- through a temporary sibling, so the create's spelling and content remain. ([#981](https://github.com/exmergo/dex/pull/981))
-- **`explore profile` no longer counts distinct values of a column whose type its
- connector skips.**
- A null-free `VARIANT`, `MAP`, `SUPER`, `GEOGRAPHY` or similar column reports no
- distinct count, which reads the same as a column the catalog has no statistics
- for, so dex sent it to the exact count. On a warehouse that cannot group the
- type, one such column could fail the profile of its table, and with it
- `explore map` and `explore relationships` (#925). Where the warehouse can count
- it, as DuckDB and ClickHouse do, the profile reported the count and could offer
- the column as a candidate key.
-
- Such a column now reports no `distinct_count`, and its null fraction where the
- connector measures one, and is no longer offered as a candidate key. A table
- whose aggregate scan read no rows or was refused gets no exact count either.
- Postgres views and unanalyzed tables are still measured, and a degraded column
- no longer uses up the columns measured there.
-
- This changes output you may store or compare. Once you profile again, a column
- that only held a `candidate_keys` place through this count leaves it, and after
- a new `maintain snapshot` `maintain check` stops watching it; declare the grain
- to keep it watched. ([#1052](https://github.com/exmergo/dex/pull/1052))
-- `transform compare` names `transform build --select …` when a compare input has not been built, instead of pointing agents at raw `dbt run`. ([#1067](https://github.com/exmergo/dex/pull/1067))
-- **`transform plan` names `transform deps` when declared packages are missing.** dbt refuses to parse a project whose declared packages are not installed, and its message points at raw `dbt deps`; plan now runs the declared-package check first and refuses with the verb dex has. Planning installs nothing, because deps can reach the network.
-- **`transform plan` row attribution no longer copies a warehouse error into
- `reason`.** A failed cast's error quotes the value it could not convert, so a
- value from the data could reach the envelope. The reason now keeps the context
- and the exception type (#861).
- On BigQuery, a prior model that did not compile also made its dry-run pricing raise
- out of the batch, so nothing was measured. Each statement is now priced on its own.
-- `semantic ossie|slayer|cube` refuse a `population.parent` that names nothing (or columns the layer does not expose), matching the dbt-route check (#1030).
-
-
-
-
-
-### Added
-
-- **Verification checks the temporal contract of a snapshot-backed status history.**
- A snapshot can build while a model over it disagrees about whether the first
- observation is a transition, whether an unrelated edit counts, or whether a
- timestamp is business or capture time. A model can now declare `history`: its
- snapshot, entity and status, and those policies. `maintain verify` and
- `transform build --verify` derive each entity's expected transition count, latest
- transition and first attainment from the snapshot's versions and the declared
- policy, and report disagreements as entity counts (`temporal_*`). Each contract
- gets a `temporal_contracts` record keeping the snapshot's execution, the assertions
- checked, and what stayed unchecked apart. A policy left out, late-arriving data
- whose business and capture order disagree, or a run in which no entity made a
- transition is never reported as clean. Supported today: one dbt snapshot, one status
- column, one output row per entity.
-- **Verification measures join coverage and checks a declared parent population.**
- A left join can keep every driving row and match nothing, so a model builds with
- plausible row counts and every joined field NULL. `maintain verify` and
- `transform build --verify` now measure every equality join a model writes, rows
- and distinct keys apart, and record each one under `join_coverage` as
- satisfied, contradicted, not applicable (an empty input, never reported as full
- coverage) or unchecked with a reason code. A join that matches nothing is
- `join_no_match`; a join the declaration requires is judged against the contract
- rather than a default threshold; and a column a join supplies that came back all
- NULL is reported against its declared NULL rule or the cached profile. A model
- can now declare `population.parent`, the entity it holds one row per, and
- verification counts the parents missing from it and the keys the parent does not
- have. The build path runs the join contract for the first time, priced into the
- build's estimate as `(join overlap probes)`.
-
-### Changed
-
-- **`transform plan` reads set operations from their first branch.**
- a model whose outermost query is a `UNION`, `UNION ALL`, `EXCEPT`, or
- `INTERSECT` previously skipped contract comparison because set operations were
- treated as unresolvable. `transform plan` now reads the model's output columns
- from its first branch (or from the union of branches for `UNION ALL BY NAME`).
- declarations pick this up, refusing a declared column absent from a union as
- they do for a direct SELECT list. ([#1042](https://github.com/exmergo/dex/pull/1042))
-- **A temporal contract no longer reads as `satisfied` for a model that does not
- descend from its declared snapshot.** Verification walks the manifest's dependencies, free and
- with no connection. A model that does not descend from `history.snapshot` is
- `unchecked` with `reason_code: snapshot_not_ancestor`, naming the snapshot and any
- other snapshot it descends from, and no mismatch is reported against a history it
- never read. A manifest that cannot answer is `lineage_unavailable`.
-- **The agent procedure separates what a request settles from an inferred default.**
- The procedure now names `request` or `contract` as an assumption's evidence only
- when that source actually settles the choice: "event rate per account" alone does
- not say whether accounts with no events belong, so a reasonable choice there is
- recorded as `default`, explained in a line, and the work continues. Observed counts
- describe the data and do not establish an intended population or NULL policy. The
- metadata-quality eval gains an attribution score, graded apart from the SQL, over
- four new tasks.
-- **`transform build --full-refresh --verify` checks the rows of the incremental
- models it rebuilt.** A rebuilt model holding materially fewer or more rows than its
- driving parent is now reported as `row_loss` or `row_fanout`, as a table is, and
- the parent's row count is priced in the build's one estimate. An incremental
- model this build did not rebuild, one whose `full_refresh: false` made dbt ignore
- the flag, and a microbatch model keep the skip, named in `warnings`. A microbatch
- model is no longer told to run `dbt compile`, which would not have helped.
- `maintain verify` compares no incremental model, as before.
-- **`transform plan` checks the column contract through `select *`.** The comparison
- with `schema.yml` was skipped for every model ending in `select * from final`. It now
- follows a star through CTEs, subqueries and joins, then to a referenced model's SQL,
- then to a cached profile, which the warning names. A skipped comparison says what
- stopped it. Existing projects may see new warnings. Two checks that read the same SELECT
- list also see through CTEs: a declaration naming a column absent from `final` is now
- refused, as it already was for a direct SELECT list, and the resolved-key convention
- warning can fire on more models.
-
-### Fixed
-
-- **Deriving an Ossie document at an already configured path produces a plan.**
- When the document did not exist yet, `transform plan` and `transform declare`
- only proposed its contents and incorrectly asked to add the same path to
- `semantic.ossie.files` again. The derived document is now validated with the
- configured layer and stored as a companion plan that `transform apply` can write.
- Unconfigured paths still require explicit adoption. ([#1024](https://github.com/exmergo/dex/pull/1024))
-- **A Snowflake estimate no longer recommends `snowflake.suspend_after_command`
- when it is already on.** With the setting on, dex still quotes a project's first
- command that resumes the warehouse the whole `AUTO_SUSPEND` tail, because it
- counts on a suspend only once it has seen one succeed. The note beside the
- estimate now says so, and says that later commands get the resume minimum. The
- advice next to it used to recommend turning the setting on and running
- `GRANT OPERATE` even when both were done. It now names the `dex config set` only
- while the setting is off and the grant only after a suspend was refused for
- lacking it, and dex drops it once a suspend keeps the tail out of the quote. ([#1025](https://github.com/exmergo/dex/pull/1025))
-- **dropped schemas are no longer carried forward as out-of-scope.** when a
- schema holding cached relations was dropped from the warehouse or left empty,
- `explore map` treated it as an unobserved namespace and carried its relations
- forward indefinitely, causing recurring `table_dropped` findings after every
- snapshot. observed namespaces are now derived from what the adapter examined,
- so relations in dropped schemas are dropped from the cache while namespaces
- outside a narrowed `--scope` continue to be carried forward untouched. ([#1032](https://github.com/exmergo/dex/pull/1032))
-- **A star's EXCLUDE/EXCEPT, REPLACE and RENAME now match columns the way the
- warehouse does.** A qualified modifier (`exclude (a.id)`, `rename (a.id as
- a_id)`) used to be read as its bare column name, so over a join it also hit the
- other table's same-named column: an exclusion dropped a column the warehouse
- keeps, and a rename swallowed it whole. A renamed column now also keeps its
- star's qualifier, so its lineage resolves in a join instead of being reported
- unreadable, and a REPLACE of a renamed column decides what the column produces
- under its new name (Snowflake runs both clauses), rather than the replacement
- being silently dropped. ([#1036](https://github.com/exmergo/dex/pull/1036))
-- **equivalent column data type aliases are no longer reported as mismatches.**
- the column contract in `maintain verify` and `transform build --verify`
- previously compared declared and actual types with a raw case-insensitive
- string match, reporting equivalent spellings like bigquery `int64` against
- reported `INTEGER` or duckdb `int` against `INTEGER` as `column_type_mismatch`.
- type comparison now normalizes connector-specific aliases across integer,
- string, float, boolean, and temporal families, treats parameterized types
- compatibly when metadata reflection omits parameters, and falls back to exact
- matching for unnormalizable types. ([#1037](https://github.com/exmergo/dex/pull/1037))
-- **The metadata eval now counts Dex commands invoked through a wrapper bound in
- the same command string.** A shell function (`R() { uv ... run.py "$@"; }`) or
- a variable (`R="uv ... run.py"`) wrapping a Dex invocation used to be invisible
- to the command tally; calls through the bound name now count like direct ones,
- while quoted mentions of the bound name (an `echo` inside the wrapper's own
- body) still stay uncounted. ([#1043](https://github.com/exmergo/dex/pull/1043))
-- **Trino profiling no longer counts distinct values of nested and sketch columns.**
- Since the exact-count pass began measuring columns with no distinct count,
- `explore profile` and `explore map` on Trino could run `COUNT(DISTINCT)` on columns
- such as `array(varchar)`, `json` or `hyperloglog`, which report only a non-null
- count. Those columns are now skipped, so they keep no distinct count and cannot
- fail the scan for the rest of the table.
-- **`transform build --verify` reports the column contract `maintain verify` does.**
- A verified build could return no findings while `maintain verify` reported
- `column_undeclared` on the same models. The build now reports `column_missing`,
- `column_undeclared` and `column_type_mismatch` for the models it built, from
- metadata, with no added statement or estimate. `data.verification.column_contract`
- names the models checked, those declaring no columns, and those not checked with a
- reason, such as a failed model whose older relation is still in place. Findings do
- not change the build's status. `maintain verify` now reports a relation whose
- metadata cannot be read and carries on, instead of stopping.
-
-
-
-Older releases are in the full [CHANGELOG.md](https://github.com/exmergo/dex/blob/main/CHANGELOG.md) and on [GitHub Releases](https://github.com/exmergo/dex/releases).
diff --git a/dex/cli/config.mdx b/dex/cli/config.mdx
deleted file mode 100644
index 812a56a..0000000
--- a/dex/cli/config.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: dex config
-sidebarTitle: config
-description: 'Reference for dex config: read every effective setting, validate .dex/config.yml by line, and set or unset keys as reviewable in-place edits that keep comments.'
-og:title: dex config · Exmergo Dex
-twitter:title: dex config · Exmergo Dex
----
-
-read, check and change .dex/config.yml, as reviewable diffs
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex config get`](#dex-config-get) | show effective settings and where each came from |
-| [`dex config validate`](#dex-config-validate) | list every problem in .dex/config.yml |
-| [`dex config set`](#dex-config-set) | change settings as a reviewable in-place edit |
-| [`dex config unset`](#dex-config-unset) | remove settings as a reviewable in-place edit |
-
-## dex config get
-
-Print every setting, or those under a key, with its value and source. Reads only the file: no connection, no extra needed.
-
-
-
-```text
-dex config get []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | show only the settings under this key | |
-
-
-
-## dex config validate
-
-Report syntax errors, refused values, unknown or duplicated keys and credential-like keys, by setting and line. Free.
-
-
-
-```text
-dex config validate
-```
-
-
-
-## dex config set
-
-Propose the change as a diff that keeps every comment, and write it with `--confirm`. Refuses credential-like keys and values. Free.
-
-
-
-```text
-dex config set [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | one or more key and YAML value pairs, applied as one change | |
-
-
-
-## dex config unset
-
-Propose removing keys, including ones dex does not read, as a diff, and write it with `--confirm`. Free.
-
-
-
-```text
-dex config unset [--duplicate] [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | setting or block to remove, including keys dex does not read | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--duplicate` | remove only ignored duplicate occurrences of key(s) | |
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/connect.mdx b/dex/cli/connect.mdx
deleted file mode 100644
index 9a2f218..0000000
--- a/dex/cli/connect.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: dex connect
-sidebarTitle: connect
-description: 'Reference for dex connect test: check that a connector can reach its warehouse with discovered credentials and report what it can do, before any real work.'
-og:title: dex connect · Exmergo Dex
-twitter:title: dex connect · Exmergo Dex
----
-
-check a connector's own credentials and capabilities
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex connect test`](#dex-connect-test) | check the connection, its capabilities and cost unit |
-
-## dex connect test
-
-Open the resolved connection read-only and report the dialect, the capabilities, and the cost paradigm. Free: it runs no billed query.
-
-
-
-```text
-dex connect test
-```
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/demo.mdx b/dex/cli/demo.mdx
deleted file mode 100644
index e19a057..0000000
--- a/dex/cli/demo.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: dex demo
-sidebarTitle: demo
-description: 'Reference for dex demo: create a seeded local DuckDB warehouse with realistic data quality problems, no credentials or network, to try every dex command on.'
-og:title: dex demo · Exmergo Dex
-twitter:title: dex demo · Exmergo Dex
----
-
-create a seeded local DuckDB warehouse to try dex against (no credentials, no network)
-
-```text
-dex demo []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | DuckDB file to create, refused if it exists (default: dex_demo.duckdb) | |
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/explore.mdx b/dex/cli/explore.mdx
deleted file mode 100644
index a3559f6..0000000
--- a/dex/cli/explore.mdx
+++ /dev/null
@@ -1,235 +0,0 @@
----
-title: dex explore
-sidebarTitle: explore
-description: 'Reference for dex explore: every read-only subcommand for inventory, profiling, joins, diagrams, guarded queries, clustering, and semantic layers, with flags.'
-og:title: dex explore · Exmergo Dex
-twitter:title: dex explore · Exmergo Dex
----
-
-make sense of a warehouse: rank objects, profile columns, infer joins
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex explore inventory`](#dex-explore-inventory) | list warehouse objects with counts and sizes, no rows |
-| [`dex explore profile`](#dex-explore-profile) | profile columns: grain, keys, PII flags, data quality |
-| [`dex explore relationships`](#dex-explore-relationships) | infer how tables join, optionally verified |
-| [`dex explore map`](#dex-explore-map) | rank, profile and relate a warehouse into .dex/ |
-| [`dex explore diagram`](#dex-explore-diagram) | draw the cached map as a Mermaid ER diagram |
-| [`dex explore query`](#dex-explore-query) | run guarded SELECTs through the query firewall |
-| [`dex explore cluster`](#dex-explore-cluster) | k-means over a sampled scan of numeric columns |
-| [`dex explore semantic`](#dex-explore-semantic) | list, read or query the semantic layer |
-
-## dex explore inventory
-
-Summarize the objects in scope from metadata. `--rank` orders them by what matters and caps the list. Free metadata on every connector.
-
-
-
-```text
-dex explore inventory [--rank] [--limit N] [--all]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--rank` | order objects by what matters, capped at 30 by default | |
-| `--limit N` | widen the ranked list to N objects (with `--rank`) | |
-| `--all` | lift the ranked list's cap (with `--rank`) | |
-
-
-
-## dex explore profile
-
-Profile the named objects from aggregates, never rows: candidate keys, grain, PII flags and data-quality findings. Billed on metered connectors, so it quotes the cost first.
-
-
-
-```text
-dex explore profile [--check-cumulative] [--target TARGET] [--columns {all}]
- [--refresh] [--use-project]
-
-## dex explore relationships
-
-Infer join edges with confidences. `--verify` measures each join with an overlap probe, which is billed on metered connectors.
-
-
-
-```text
-dex explore relationships [--verify] [--infer-by-overlap] [--refresh]
- [--use-project] [--use-hosted-semantic-layer]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--verify` | measure each join with an overlap probe (billed) | |
-| `--infer-by-overlap` | also find joins by value overlap of key-shaped columns (billed) | |
-| `--refresh` | re-profile even when the cached profile is fresh | |
-| `--use-project` | fold in the project's declared joins, grain and semantics | |
-| `--use-hosted-semantic-layer` | also read the configured hosted semantic layer's catalog | |
-
-
-
-## dex explore map
-
-Build or refresh the draft map in .dex/: the top-ranked objects with grain, keys and PII flags, plus the join edges. Billed on metered connectors, so it quotes the cost first.
-
-
-
-```text
-dex explore map [--full] [--detail] [--verify] [--infer-by-overlap]
- [--refresh] [--use-project] [--use-hosted-semantic-layer]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--full` | profile every object, not only the top-ranked (billed) | |
-| `--detail` | return every column and unprofiled object; scans nothing more | |
-| `--verify` | measure each join with an overlap probe (billed) | |
-| `--infer-by-overlap` | also find joins by value overlap of key-shaped columns (billed) | |
-| `--refresh` | re-profile even when the cached profile is fresh | |
-| `--use-project` | fold in the project's declared joins, grain and semantics | |
-| `--use-hosted-semantic-layer` | also read the configured hosted semantic layer's catalog | |
-
-
-
-## dex explore diagram
-
-Serialize the .dex/ map as a Mermaid erDiagram. Free and connectionless: it reads only the cache.
-
-
-
-```text
-dex explore diagram [--full]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--full` | draw every eligible object and column | |
-
-
-
-## dex explore query
-
-Run one or more SELECT statements through the query firewall, which returns values only from profiled columns cleared of PII. Billed on metered connectors.
-
-
-
-```text
-dex explore query [--sql-file FILE] [--across DATASETS] [--target TARGET]
- [--no-auto-profile] [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | one SELECT per argument; each is checked and run on its own | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--sql-file FILE` | read statements from a file, one per line or ;-separated | |
-| `--across DATASETS` | run each statement once per dataset, substituted for \{ds\} | |
-| `--target TARGET` | also read this dbt dev target's namespace; prod-looking targets are refused | |
-| `--no-auto-profile` | refuse unprofiled objects instead of profiling them first | |
-
-
-
-## dex explore cluster
-
-Cluster one object's numeric columns from a bounded sample and return sizes, centroids and silhouette, never rows. Needs the [cluster] extra; billed on metered connectors.
-
-
-
-```text
-dex explore cluster [--no-auto-profile] [--features COLUMNS] [--clusters N]
-
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `` | table or view to cluster | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--no-auto-profile` | refuse unprofiled objects instead of profiling them first | |
-| `--features COLUMNS` | numeric columns to cluster on, comma-separated | |
-| `-k`, `--clusters N` | number of clusters (chosen automatically when omitted) | |
-
-
-
-## dex explore semantic
-
-Discover the semantic layer's metrics, dimensions and entities (list), read one dimension's values (values), or run a governed metric query (query). Listing is free; values and query run SQL.
-
-
-
-```text
-dex explore semantic [--metric METRICS] [--for-dimension DIMENSIONS]
- [--search TERM] [--full] [--deployed] [--group-by DIMENSIONS]
- [--where FILTER] [--order-by COLUMNS] [--grain GRAIN] [--limit N]
- [--local] [--api] [{list,values,query}] [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{list,values,query}]` | list the catalog (default), read values, or run a query | `list` |
-| `[ ...]` | metrics, comma-separated; in values mode, the one dimension | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--metric METRICS` | metrics to query or scope to, comma-separated; repeatable | |
-| `--for-dimension DIMENSIONS` | list mode: metrics groupable by all these dimensions | |
-| `--search TERM` | list mode: match names, labels and descriptions | |
-| `--full` | list mode: lift the catalog's payload caps | |
-| `--deployed` | list mode: read the deployed definitions instead | |
-| `--group-by DIMENSIONS` | query mode: dimensions to group by, comma-separated | |
-| `--where FILTER` | query mode: a filter in the layer's own dialect | |
-| `--order-by COLUMNS` | query mode: columns to order by, comma-separated | |
-| `--grain GRAIN` | query mode: time grain, checked against the layer | |
-| `--limit N` | query mode: return at most N rows | |
-| `--local` | dex renders and runs the SQL, under the cost guard | |
-| `--api` | dbt Cloud runs the query; no cost guard applies | |
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/feedback.mdx b/dex/cli/feedback.mdx
deleted file mode 100644
index 847b59d..0000000
--- a/dex/cli/feedback.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: dex feedback
-sidebarTitle: feedback
-description: 'Reference for dex feedback: report a bug or suggest an improvement, with the environment to paste and issue links prefilled from it. Nothing is sent.'
-og:title: dex feedback · Exmergo Dex
-twitter:title: dex feedback · Exmergo Dex
----
-
-report a bug or suggest an improvement: the environment to paste and prefilled issue links (no connection, nothing sent)
-
-```text
-dex feedback [--command SUBCOMMAND]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--command SUBCOMMAND` | the command that misbehaved, named in the bug report link | |
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/init.mdx b/dex/cli/init.mdx
deleted file mode 100644
index 3d8d292..0000000
--- a/dex/cli/init.mdx
+++ /dev/null
@@ -1,40 +0,0 @@
----
-title: dex init
-sidebarTitle: init
-description: Set up a Dex project, try a local demo, adopt existing dbt, or explore without dbt. Managed docs, connection checks and readiness for agents and terminals.
-og:title: dex init · Exmergo Dex
-twitter:title: dex init · Exmergo Dex
----
-
-set up a Dex project, adopt dbt, or explore without dbt
-
-```text
-dex init [--mode {new,demo,adopt,explore}] [--project-dir PROJECT_DIR]
- [--target TARGET] [--dev-destination DEV_DESTINATION]
- [--agent-file {AGENTS.md,CLAUDE.md}] [--no-agent-instructions]
- [--no-interactive] [--layered-schemas] [--in-place] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | dbt project name; '.' is in-place; .dex stays at repo root | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--mode {new,demo,adopt,explore}` | new project, complete demo, adopt dbt, or explore without dbt | |
-| `--project-dir PROJECT_DIR` | existing dbt project to adopt (repository-relative) | |
-| `--target TARGET` | existing dev target to adopt | |
-| `--dev-destination DEV_DESTINATION` | dev namespace: dataset, schema, or database/catalog.schema | |
-| `--agent-file {AGENTS.md,CLAUDE.md}` | agent instruction file to update; repeat to select both | |
-| `--no-agent-instructions` | skip managed agent instructions | |
-| `--no-interactive` | return structured missing inputs without terminal questions | |
-| `--layered-schemas` | build each dbt layer into its own schema | |
-| `--in-place` | scaffold dbt in the current directory | |
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/maintain.mdx b/dex/cli/maintain.mdx
deleted file mode 100644
index 09340f9..0000000
--- a/dex/cli/maintain.mdx
+++ /dev/null
@@ -1,205 +0,0 @@
----
-title: dex maintain
-sidebarTitle: maintain
-description: 'Reference for dex maintain: snapshot a baseline, check schema, volume, grain, and semantic drift, verify a project, and reconcile with proposed diffs.'
-og:title: dex maintain · Exmergo Dex
-twitter:title: dex maintain · Exmergo Dex
----
-
-detect drift against the last snapshot and propose the fix
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex maintain snapshot`](#dex-maintain-snapshot) | capture the known-good baseline in .dex/snapshot.json |
-| [`dex maintain check`](#dex-maintain-check) | sweep every drift axis against the snapshot |
-| [`dex maintain schema`](#dex-maintain-schema) | detect added, dropped, retyped or renamed columns |
-| [`dex maintain volume`](#dex-maintain-volume) | detect row counts that collapsed, emptied or spiked |
-| [`dex maintain grain`](#dex-maintain-grain) | detect lost key uniqueness and changed grain |
-| [`dex maintain semantic`](#dex-maintain-semantic) | detect semantic definition drift and dangling references |
-| [`dex maintain reconcile`](#dex-maintain-reconcile) | propose the edits that reconcile detected drift |
-| [`dex maintain verify`](#dex-maintain-verify) | check the project is correct now, with no baseline |
-| [`dex maintain coverage`](#dex-maintain-coverage) | inventory the tests the dbt project declares |
-
-## dex maintain snapshot
-
-Pin the current map and fingerprint the project layers as the baseline drift is measured against. `--project-only` opens no connection.
-
-
-
-```text
-dex maintain snapshot [--project-only]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--project-only` | refingerprint only the project layers; opens no connection | |
-
-
-
-## dex maintain check
-
-Run every drift axis against the snapshot and rank the findings. The free axes always run; the scanning axes are offered with an estimate.
-
-
-
-```text
-dex maintain check [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | object to check (default: the whole project) | |
-
-
-
-## dex maintain schema
-
-Compare structure against the snapshot: columns, tables, nullability, dangling sources and changed models. Free metadata.
-
-
-
-```text
-dex maintain schema [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | object to check (default: the whole project) | |
-
-
-
-## dex maintain volume
-
-Compare row counts against the snapshot from free metadata. Objects with no maintained count, such as views, are named as not compared.
-
-
-
-```text
-dex maintain volume [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | object to check (default: the whole project) | |
-
-
-
-## dex maintain grain
-
-Re-measure key uniqueness, grain and join fanout, plus declared grains. Scans the data, so it is billed on metered connectors.
-
-
-
-```text
-dex maintain grain [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | object to check (default: the whole project) | |
-
-
-
-## dex maintain semantic
-
-Report changed, added and removed semantic definitions and references that no longer resolve, for free. Dimension cardinality change is a scan, offered with an estimate.
-
-
-
-```text
-dex maintain semantic [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | object to check (default: the whole project) | |
-
-
-
-## dex maintain reconcile
-
-Store the reconciling edits as a plan of diffs tagged mechanical or advisory. Never applied here; use transform apply. Repo-only.
-
-
-
-```text
-dex maintain reconcile [{schema,volume,grain,semantic}]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{schema,volume,grain,semantic}]` | reconcile only this drift class (default: all) | |
-
-
-
-## dex maintain verify
-
-Check build status, column contracts, row population, grain and join contracts against the built relations. Mostly free metadata; view row counts and join probes are offered with an estimate.
-
-
-
-```text
-dex maintain verify [--target TARGET] [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | model names: repeated, comma-separated or space-separated (default: all) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--target TARGET` | dbt dev target to verify against; prod-looking targets are refused | |
-
-
-
-## dex maintain coverage
-
-Count each model's, source's, snapshot's and seed's own tests by kind, its downstream tests, incremental branch tests and asserted columns, each against a stated denominator; each test's last run status, each model's recorded mutation score (fresh or stale), the columns singular tests read, and what checks each declared fact. Free; reads the manifest, run results and .dex/ only. `--mutate` refreshes stale and missing scores in one batch, behind one cost handshake.
-
-
-
-```text
-dex maintain coverage [--full] [--mutate] [--max-models N] [--target TARGET]
- [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | model, source.table, snapshot or seed names (default: all) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--full` | lift the caps on every listed section and name | |
-| `--mutate` | refresh stale and missing mutation scores | |
-| `--max-models N` | refresh at most N models (25, never more) | |
-| `--target TARGET` | dbt dev target `--mutate` runs against; prod-looking targets are refused | |
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/overview.mdx b/dex/cli/overview.mdx
deleted file mode 100644
index e96fc91..0000000
--- a/dex/cli/overview.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: dex CLI overview
-sidebarTitle: Overview
-description: 'Every dex CLI command at a glance: global options, connection flags shared by all subcommands, and where to start, generated from the released argparse tree.'
-og:title: dex CLI overview · Exmergo Dex
-twitter:title: dex CLI overview · Exmergo Dex
----
-
-Explore an unfamiliar warehouse, transform it with reviewable dbt edits, and maintain it as the world drifts.
-
-## Getting oriented
-
-Point it at data with `--connector`/`--path`, or commit a connector: block to .dex/config.yml (found by walking up from the working directory).
-
-DBT_PROFILES_DIR only locates dbt profiles.yml for dbt operations and the last-resort credential fallback; it does not select dex's connector or override `--connector`/`--path` or .dex/config.yml.
-
-No warehouse yet: `dex demo` seeds a local one, no credentials needed. Have one already: `dex explore map` is the command to run first. It ranks what matters, profiles it, and infers how the tables join.
-
-`dex --help` lists a group's own subcommands.
-
-## Command groups
-
-| Group | What it does |
-| --- | --- |
-| [`dex init`](/dex/cli/init) | set up a Dex project, adopt dbt, or explore without dbt |
-| [`dex connect`](/dex/cli/connect) | check a connector's own credentials and capabilities |
-| [`dex explore`](/dex/cli/explore) | make sense of a warehouse: rank objects, profile columns, infer joins |
-| [`dex transform`](/dex/cli/transform) | author and refactor dbt models, tests, and the semantic layer |
-| [`dex semantic`](/dex/cli/semantic) | define dbt or native semantic layers as reviewable diffs |
-| [`dex maintain`](/dex/cli/maintain) | detect drift against the last snapshot and propose the fix |
-| [`dex config`](/dex/cli/config) | read, check and change .dex/config.yml, as reviewable diffs |
-| [`dex demo`](/dex/cli/demo) | create a seeded local DuckDB warehouse to try dex against (no credentials, no network) |
-| [`dex procedure`](/dex/cli/procedure) | print the agent procedure, or the block to paste into CLAUDE.md / AGENTS.md (no connection) |
-| [`dex feedback`](/dex/cli/feedback) | report a bug or suggest an improvement: the environment to paste and prefilled issue links (no connection, nothing sent) |
-
-## Global options
-
-Every command accepts these. The last column says where on the command line each one may go.
-
-| Option | Description | Position |
-| --- | --- | --- |
-| `--connector NAME` | warehouse to use, overriding connector: in .dex/config.yml | before the group or after the subcommand |
-| `--path FILE` | DuckDB database file to read | before the group or after the subcommand |
-| `--scope NAMESPACE` | narrow the committed source allowlist to this namespace; repeatable | before the group or after the subcommand |
-| `--project PROJECT` | BigQuery project (the older spelling of `--scope`) | before the group or after the subcommand |
-| `--dataset DATASET` | BigQuery dataset, repeatable (the older spelling of `--scope`) | before the group or after the subcommand |
-| `--repo-root DIR` | directory to resolve .dex/config.yml from, walking up (default: .) | before the group or after the subcommand |
-| `--confirm` | run a billed command after its cost was quoted | before the group or after the subcommand |
-| `--budget AMOUNT` | spend this command may use, in the connector's cost unit | before the group or after the subcommand |
-| `--session-ceiling AMOUNT` | answer the one-time ask: commit a daily ceiling (DEX_SESSION_CEILING_CAP caps) | before the group or after the subcommand |
-| `--no-session-ceiling` | answer the one-time ask: record that no ceiling applies | before the group or after the subcommand |
-| `--values-free` | return no table value in any result (DEX_RESULT_MODE pins it) | before the group or after the subcommand |
-| `--cache-backend NAME` | where .dex/ state is kept for this run; must precede the group | before the group only |
-| `--project-format NAME` | transformation project format for this run; must precede the group | before the group only |
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/procedure.mdx b/dex/cli/procedure.mdx
deleted file mode 100644
index 18b3dd2..0000000
--- a/dex/cli/procedure.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: dex procedure
-sidebarTitle: procedure
-description: 'Reference for dex procedure: print the agent procedure every dex skill carries, the block to paste into CLAUDE.md or AGENTS.md, and a stale check.'
-og:title: dex procedure · Exmergo Dex
-twitter:title: dex procedure · Exmergo Dex
----
-
-print the agent procedure, or the block to paste into CLAUDE.md / AGENTS.md (no connection)
-
-```text
-dex procedure [--block] [--check FILE]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--block` | also return data.block, ready to paste into CLAUDE.md or AGENTS.md | |
-| `--check FILE` | report whether FILE carries the current procedure (repeatable) | |
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/semantic.mdx b/dex/cli/semantic.mdx
deleted file mode 100644
index 253f629..0000000
--- a/dex/cli/semantic.mdx
+++ /dev/null
@@ -1,242 +0,0 @@
----
-title: dex semantic
-sidebarTitle: semantic
-description: 'Reference for dex semantic: define, update, and plan dbt semantic models or native Apache Ossie documents as reviewable diffs, with every flag documented.'
-og:title: dex semantic · Exmergo Dex
-twitter:title: dex semantic · Exmergo Dex
----
-
-define dbt or native semantic layers as reviewable diffs
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex semantic define`](#dex-semantic-define) | plan new dbt semantic models or metrics |
-| [`dex semantic update`](#dex-semantic-update) | plan changes to existing semantic definitions |
-| [`dex semantic plan`](#dex-semantic-plan) | plan a mix of semantic additions, changes and removals |
-| [`dex semantic ossie`](#dex-semantic-ossie) | plan whole-document edits to a native Apache Ossie layer |
-| [`dex semantic slayer`](#dex-semantic-slayer) | plan whole-file edits to the configured SLayer model files |
-| [`dex semantic cube`](#dex-semantic-cube) | plan whole-file edits to the configured Cube model files |
-| [`dex semantic databricks`](#dex-semantic-databricks) | plan whole-file edits to the Metric View YAML files |
-| [`dex semantic snowflake`](#dex-semantic-snowflake) | plan whole-file edits to the Semantic View YAML files |
-
-## dex semantic define
-
-Validate new semantic models or metrics, including with dbt's own parser, and store them as a plan. Refuses a removal. Repo-only.
-
-
-
-```text
-dex semantic define [--edits-file FILE] [--definitions-file FILE] [--no-parse]
- []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-file edits payload as JSON; '-' reads stdin | |
-| `--definitions-file FILE` | definitions written in place, as JSON; '-' reads stdin | |
-| `--no-parse` | skip validation with dbt's own parser | |
-
-
-
-## dex semantic update
-
-Validate changed semantic definitions, removals included, and store them as a plan. Repo-only.
-
-
-
-```text
-dex semantic update [--edits-file FILE] [--definitions-file FILE] [--no-parse]
- []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-file edits payload as JSON; '-' reads stdin | |
-| `--definitions-file FILE` | definitions written in place, as JSON; '-' reads stdin | |
-| `--no-parse` | skip validation with dbt's own parser | |
-
-
-
-## dex semantic plan
-
-Validate a payload of semantic definitions and classify each as defined, updated, unchanged or removed, then store a plan. Repo-only.
-
-
-
-```text
-dex semantic plan [--edits-file FILE] [--definitions-file FILE] [--no-parse]
- []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-file edits payload as JSON; '-' reads stdin | |
-| `--definitions-file FILE` | definitions written in place, as JSON; '-' reads stdin | |
-| `--no-parse` | skip validation with dbt's own parser | |
-
-
-
-## dex semantic ossie
-
-Validate whole Ossie documents at the paths semantic.ossie.files configures, then store a plan. `--from-metric-view` proposes the document from a Metric View file through dex's port of apache/ossie-converters. Needs the [ossie] extra. Repo-only.
-
-
-
-```text
-dex semantic ossie [--edits-file FILE] [--from-metric-view FILE]
- [--name MODEL] [--dataset-metrics] [--into PATH] [{define,update,plan}]
- []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{define,update,plan}]` | define new documents, update existing ones, or plan a mix | |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-document edits payload as JSON; '-' reads stdin | |
-| `--from-metric-view FILE` | propose the Ossie documents from these Metric Views | |
-| `--name MODEL` | the model and fact dataset name | |
-| `--dataset-metrics` | write fact-only measures as dataset metrics | |
-| `--into PATH` | output path (default: beside the configured files) | |
-
-
-
-## dex semantic slayer
-
-Validate whole SLayer model files at the paths semantic.slayer.models configures, with SLayer's own model, then store a plan. Needs the [slayer] extra. Repo-only.
-
-
-
-```text
-dex semantic slayer [--edits-file FILE] [{define,update,plan}] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{define,update,plan}]` | define new documents, update existing ones, or plan a mix | |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-document edits payload as JSON; '-' reads stdin | |
-
-
-
-## dex semantic cube
-
-Validate whole plain-YAML Cube model files at the paths semantic.cube.files configures, with dex's port of Cube's model rules, then store a plan. Needs the [cube] extra. No Cube server, no warehouse. Repo-only.
-
-
-
-```text
-dex semantic cube [--edits-file FILE] [{define,update,plan}] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{define,update,plan}]` | define new documents, update existing ones, or plan a mix | |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-document edits payload as JSON; '-' reads stdin | |
-
-
-
-## dex semantic databricks
-
-Validate whole Metric View YAML files at the paths semantic.databricks.files configures, with dex's port of the Metric View YAML 1.1 rules, then store a plan. `--from-ossie` proposes the view from an Ossie document through dex's port of apache/ossie-converters. Needs the [metric-views] extra. Never deploys a view and opens no workspace connection. Repo-only.
-
-
-
-```text
-dex semantic databricks [--edits-file FILE] [--from-ossie FILE]
- [--fact DATASET] [--into PATH] [{define,update,plan}] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{define,update,plan}]` | define new documents, update existing ones, or plan a mix | |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-document edits payload as JSON; '-' reads stdin | |
-| `--from-ossie FILE` | propose the Metric View from these Ossie documents | |
-| `--fact DATASET` | the dataset the view is on (several roots) | |
-| `--into PATH` | output path (default: beside the configured files) | |
-
-
-
-## dex semantic snowflake
-
-Validate whole Snowflake Semantic View YAML files at the paths semantic.snowflake.files configures, with dex's port of Snowflake's specification and validation rules, then store a plan. Needs the [semantic-views] extra. Never deploys a view and opens no Snowflake connection. Repo-only.
-
-
-
-```text
-dex semantic snowflake [--edits-file FILE] [{define,update,plan}] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[{define,update,plan}]` | define new documents, update existing ones, or plan a mix | |
-| `[]` | one line saying what the change is for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | whole-document edits payload as JSON; '-' reads stdin | |
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/cli/transform.mdx b/dex/cli/transform.mdx
deleted file mode 100644
index 0bc0389..0000000
--- a/dex/cli/transform.mdx
+++ /dev/null
@@ -1,471 +0,0 @@
----
-title: dex transform
-sidebarTitle: transform
-description: 'Reference for dex transform: every subcommand that authors, plans, applies, builds, and tests dbt changes, with each flag, default, and positional argument.'
-og:title: dex transform · Exmergo Dex
-twitter:title: dex transform · Exmergo Dex
----
-
-author and refactor dbt models, tests, and the semantic layer
-
-Choose a command, then expand its usage and options. Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-| Command | What it does |
-| --- | --- |
-| [`dex transform init`](#dex-transform-init) | bootstrap a dbt project skeleton |
-| [`dex transform plan`](#dex-transform-plan) | validate authored dbt edits and store them as a plan |
-| [`dex transform apply`](#dex-transform-apply) | write a stored plan or plan document into the project |
-| [`dex transform build`](#dex-transform-build) | run dbt build against a dev target |
-| [`dex transform deps`](#dex-transform-deps) | install or refresh dbt packages |
-| [`dex transform plans`](#dex-transform-plans) | list stored plans, newest first |
-| [`dex transform macro`](#dex-transform-macro) | list shipped dbt macros, or plan one into the project |
-| [`dex transform references`](#dex-transform-references) | find where names are used across the project |
-| [`dex transform rename`](#dex-transform-rename) | plan every edit a rename needs |
-| [`dex transform remove`](#dex-transform-remove) | plan a definition's removal, refusing while reads remain |
-| [`dex transform place`](#dex-transform-place) | plan where a shared derived column should be defined |
-| [`dex transform declare`](#dex-transform-declare) | propose declarations for models that already exist |
-| [`dex transform repair`](#dex-transform-repair) | draft an override that repairs a failing package model |
-| [`dex transform test`](#dex-transform-test) | scaffold a unit test, or mutation-test existing tests |
-| [`dex transform compare`](#dex-transform-compare) | compare a model before and after a stored plan |
-| [`dex transform export`](#dex-transform-export) | export a stored plan as a portable, digested document |
-| [`dex transform ground`](#dex-transform-ground) | report what a plan depends on and how complete that is |
-| [`dex transform classify`](#dex-transform-classify) | classify what each edit's content actually contains |
-| [`dex transform preflight`](#dex-transform-preflight) | report what the warehouse will enforce on the next build |
-
-## dex transform init
-
-Propose a new dbt project as create diffs, for the connector named by `--connector` or .dex/config.yml. Refuses if a dbt project exists. Free.
-
-
-
-```text
-dex transform init [--layered-schemas] [--in-place] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | name of the dbt project to create | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--layered-schemas` | build each layer into its own schema | |
-| `--in-place` | scaffold into the current directory instead of <name>/ | |
-
-
-
-## dex transform plan
-
-Validate the edits in `--edits-file`, diff them against the project, and store a plan. Nothing is written until transform apply. Repo-only.
-
-
-
-```text
-dex transform plan [--edits-file FILE] [--scaffold TABLE]
- [--attribute-rows | --no-attribute-rows] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | one line saying what the edits are for | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | the edits payload as JSON; '-' reads stdin | |
-| `--scaffold TABLE` | add a staging model skeleton for a profiled table | |
-| `--attribute-rows` | measure the row-population delta of each change | |
-| `--no-attribute-rows` | name row-affecting changes without measuring them | |
-
-
-
-## dex transform apply
-
-Write a plan's diffs into the project. With no id, applies the latest unapplied plan. A file edited since planning is a conflict, never an overwrite. Repo-only.
-
-
-
-```text
-dex transform apply [--plan-file FILE] [--expect-digest HEX]
- [--accept-population-change REASON] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | plan to apply (default: latest unapplied, named in data.resolved_plan) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--plan-file FILE` | apply an exported plan document instead of a stored plan | |
-| `--expect-digest HEX` | refuse a plan document whose digest is not this one | |
-| `--accept-population-change REASON` | apply an undeclared population change, stating why | |
-
-
-
-## dex transform build
-
-Run dbt build on a dev target only, after a free preflight and a cost estimate. It runs only with `--confirm` and `--budget`.
-
-
-
-```text
-dex transform build [--target TARGET] [--select SELECTOR] [--verify]
- [--for-plan PLAN-ID] [--for-plan-file FILE] [--no-install-deps]
- [--cold-deps] [--full-refresh]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--target TARGET` | dbt target to build; prod-looking targets are refused | |
-| `--select SELECTOR` | dbt node selection (one or more selectors, or quoted), passed through to dbt | |
-| `--verify` | run the maintain verify sweep over the built nodes | |
-| `--for-plan PLAN-ID` | report whether the build covered this stored plan | |
-| `--for-plan-file FILE` | report coverage of an exported plan document | |
-| `--no-install-deps` | refuse missing dbt packages instead of installing them | |
-| `--cold-deps` | reinstall packages in an isolated copy and build from it | |
-| `--full-refresh` | rebuild selected incremental models after their logic changed | |
-
-
-
-## dex transform deps
-
-Run dbt deps inside the project. It installs the packages the project already declares in packages.yml, at the versions package-lock.yml pins where the lockfile matches that file (dbt resolves them again where it does not); it does not install or upgrade a tool. Repo-confined, with no warehouse spend.
-
-
-
-```text
-dex transform deps
-```
-
-
-
-## dex transform plans
-
-List the plans in .dex/plans, pending and applied, newest first. Free.
-
-
-
-```text
-dex transform plans
-```
-
-
-
-## dex transform macro
-
-With no name, list the dbt macros dex ships. With a name, plan scaffolding that macro into the project's macro directory. Repo-only.
-
-
-
-```text
-dex transform macro []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | shipped macro to scaffold (omit to list them) | |
-
-
-
-## dex transform references
-
-Report every use of each name across model SQL, YAML, macros, seeds and installed packages, and say how complete the answer is. With `--usage`, also how other models filter, branch on or aggregate each model.column. Repo-only and free.
-
-
-
-```text
-dex transform references [--kind KIND] [--full] [--usage] [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| ` [ ...]` | name to look up; model.column resolves through ref() | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--kind KIND` | narrow to one kind, such as model, column, var or metric | |
-| `--full` | lift the cap of 200 occurrences across 50 files | |
-| `--usage` | also report how other models use each model.column | |
-
-
-
-## dex transform rename
-
-Generate one plan renaming a column, var, model, seed, snapshot, macro or source everywhere it is used. Refuses rather than partially applying. Repo-only and free.
-
-
-
-```text
-dex transform rename [--edits-file FILE]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `` | column, var, model, seed, snapshot, macro or source | |
-| `` | current name; a column is named model.column | |
-| `` | new name | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | hand-authored edits to store in the same plan | |
-
-
-
-## dex transform remove
-
-Plan the removal of a definition and refuse while any read survives, naming each one. Pass the read edits with `--edits-file`. Repo-only.
-
-
-
-```text
-dex transform remove [--edits-file FILE]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `` | column, var, model, seed, snapshot, macro or source | |
-| `` | name to remove; a column is named model.column | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | hand-authored edits to store in the same plan | |
-
-
-
-## dex transform place
-
-Find the lowest common model that can define the column for every target, define it there, and thread it down. `--explain` stores no plan. Repo-only and free.
-
-
-
-```text
-dex transform place [--targets MODELS] [--expr SQL] [--explain] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | name of the derived column to define | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--targets MODELS` | models that need the column, comma-separated | |
-| `--expr SQL` | SQL expression that computes the column | |
-| `--explain` | return the reasoning without storing a plan | |
-
-
-
-## dex transform declare
-
-Store one plan proposing the measured facts (grain, keys, joins, running totals) each selected model does not yet declare, plus any intent the `--edits-file` declarations supply. Capped at 25 models; every skipped model is named. Repo-only and free.
-
-
-
-```text
-dex transform declare [--edits-file FILE] [--limit N] [--intent INTENT]
- [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | model to declare (default: every model in the project) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | payload whose `declarations` supply intent for the plan | |
-| `--limit N` | propose at most N models (can only lower the cap of 25) | |
-| `--intent INTENT` | one line saying what the plan is for | |
-
-
-
-## dex transform repair
-
-Read the latest build's failure of a package model, restate its SQL as a project override (package macros qualified, vars resolved, the package node disabled), convert the columns the error names where the cached profile settles what they hold, compile it, and store it as a plan. Nothing is applied.
-
-
-
-```text
-dex transform repair [ ...]
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[ ...]` | a failing package model (`model` or `pkg.model`) | |
-
-
-
-## dex transform test
-
-`--scaffold` plans a unit_tests skeleton for a model. `--mutate` plants one defect at a time and reports which ones no test caught; `--downstream` also counts the tests of the models that read it. Mutation runs dbt on the dev target and is billed on metered connectors.
-
-
-
-```text
-dex transform test [--scaffold MODEL | --mutate MODEL] [--max-mutants N]
- [--target TARGET] [--check-equivalence | --no-check-equivalence]
- [--downstream | --no-downstream]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--scaffold MODEL` | plan a unit test skeleton for this model | |
-| `--mutate MODEL` | measure which planted defects this model's tests miss | |
-| `--max-mutants N` | run at most N mutants (can only lower the cap of 20) | |
-| `--target TARGET` | dbt dev target to mutate against | |
-| `--check-equivalence` | compare each survivor with the model on the dev data | |
-| `--no-check-equivalence` | report survivors without comparing them | |
-| `--downstream` | also run the tests of the models downstream of it | |
-| `--no-downstream` | run only the model's own tests | |
-
-
-
-## dex transform compare
-
-Compile the model with and without the plan, then compare output columns and the exact row multiset on the same dev inputs. Returns counts, never rows. equivalent holds for the compared inputs only. Scans go through `--confirm` `--budget` on metered connectors.
-
-
-
-```text
-dex transform compare [--model MODEL] [--map OLD=NEW] [--key COLUMN]
- [--accept-type COLUMN] [--expect JSON | --expect-file PATH]
- [--target TARGET] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | stored plan id (default: latest unapplied, named in data.resolved_plan) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--model MODEL` | the model whose results should not change | |
-| `--map OLD=NEW` | a baseline output column the plan renames (repeatable) | |
-| `--key COLUMN` | baseline key column, repeatable; default: declared grain | |
-| `--accept-type COLUMN` | baseline column whose type may change in its family | |
-| `--expect JSON` | JSON: the rows the plan may add, remove and change | |
-| `--expect-file PATH` | read `--expect`'s JSON from a file ("-" reads stdin) | |
-| `--target TARGET` | dbt dev target to read; prod-looking targets are refused | |
-
-
-
-## dex transform export
-
-Print one stored plan as a document another checkout can verify and apply, with a digest over the whole plan. Repo-only and free.
-
-
-
-```text
-dex transform export []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | plan to export (default: latest unapplied, named in data.resolved_plan) | |
-
-
-
-## dex transform ground
-
-List the models, sources, columns and relations a plan reads, what could not be resolved, and a fingerprint of the inputs. Repo-only and free.
-
-
-
-```text
-dex transform ground []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | plan to ground (default: latest unapplied, named in data.resolved_plan) | |
-
-
-
-## dex transform classify
-
-Read each edit's content and label it declarative, executable, authority-bearing, data or unknown, naming the signal. Repo-only and free.
-
-
-
-```text
-dex transform classify [--edits-file FILE] []
-```
-
-**Arguments**
-
-| Argument | Description | Default |
-| --- | --- | --- |
-| `[]` | plan to classify (default: latest unapplied, named in data.resolved_plan) | |
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--edits-file FILE` | classify an edits payload as JSON; '-' reads stdin | |
-
-
-
-## dex transform preflight
-
-Read the rendered profiles.yml for provider-side controls on the dev target and say whether any of them binds. Free and connectionless.
-
-
-
-```text
-dex transform preflight [--target TARGET]
-```
-
-**Options**
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--target TARGET` | profiles.yml target to read (default: the configured dev target) | |
-
-
-
-Every command here also accepts the [global options](/dex/cli/overview#global-options).
-
-Source: [`packages/dex-core/src/exmergo_dex_core/cli.py`](https://github.com/exmergo/dex/blob/v1.18.0/packages/dex-core/src/exmergo_dex_core/cli.py) ([edit on main](https://github.com/exmergo/dex/edit/main/packages/dex-core/src/exmergo_dex_core/cli.py)). This page is generated; change the source, not the site.
diff --git a/dex/concepts/dbt-project.mdx b/dex/concepts/dbt-project.mdx
deleted file mode 100644
index 62b14c4..0000000
--- a/dex/concepts/dbt-project.mdx
+++ /dev/null
@@ -1,225 +0,0 @@
----
-title: 'dbt projects: what dex reads and writes'
-sidebarTitle: dbt projects
-description: What dex reads from a dbt project, how it writes changes back as reviewable diffs, and how it runs dbt build, deps, and parse against a dev target only.
-og:title: 'dbt projects: what dex reads and writes · Exmergo Dex'
-twitter:title: 'dbt projects: what dex reads and writes · Exmergo Dex'
----
-
-Start with [Transform a dbt project](https://docs.exmergo.com/dex/guides/transform) for the workflow.
-This reference describes the files Dex reads and writes, and how it runs dbt.
-
-The dbt project is the source of truth for the transformation model. dex
-maintains no parallel model: it loads the project, reasons over it together with
-warehouse introspection and the `.dex/` cache, and writes changes back into the
-source files as reviewable diffs.
-
-It is not dex's only write surface. A semantic layer can own its own definitions
-on the semantic axis, and `semantic ossie define|update|plan` followed by
-`transform apply` writes the exact documents named in `semantic.ossie.files`,
-confined to the repository and byte for byte. That surface shares this one's plan
-and apply spine and none of the path families below, which is why it is described
-in [`semantic-layer.md`](/dex/semantic-layers/overview) rather than here.
-
-## Compiling authored control flow
-
-A model edit using Jinja `for` or `if` is checked against fresh dbt-compiled SQL
-in a throwaway copy containing the whole edit set. The compiled query must pass
-the SELECT-only guard; the stored edit keeps the authored Jinja. Compilation
-requires dbt and a dev profile that passes the usual build coherence and
-existence preflight, and never reuses a prior manifest as proof.
-Missing or failed compilation stores no plan.
-
-Compile-time `run_query`, statement blocks and `adapter.execute` SELECTs run
-through Dex's scoped read-only connector, query firewall, PII gate and result
-limits. `get_relation()` and `is_incremental()` use Dex's scoped, scan-free inventory.
-`adapter.get_columns_in_relation()` (what `dbt_utils.star`,
-`get_filtered_columns_in_relation` and Fivetran's `fill_staging_columns` call) is
-answered from the same inventory's column metadata: names and types, never a row,
-free on every connector. The columns are built by the adapter's own dbt column
-class, so a macro reads the `data_type` a real build would give it; on BigQuery a
-nested column keeps its `STRUCT<...>` or `ARRAY<...>` type, built from the table's
-field tree. Each listing counts toward `query.max_statements` and is
-named once in the plan's warnings, and a relation the inventory does not hold
-(outside the source scope, or not built yet) is answered with no columns, as dbt
-answers a missing relation, with a warning naming it. The SQL spellings of the
-same read stay refused: a top-level or nested `DESCRIBE`, `SUMMARIZE`, `SHOW`,
-`PRAGMA` or an `information_schema` read, including the one the dispatched
-`get_columns_in_relation` macro issues when called directly, and the refusal names
-`adapter.get_columns_in_relation` as the supported route. Direct database handles
-and other unsupported adapter introspection refuse; truncated macro results refuse
-too. The first discovered query is priced before
-spend and later queries share its command and daily ceilings. See
-[cost controls](/dex/guardrails/cost-controls#queries-discovered-during-model-compilation).
-No model materialization runs during planning.
-
-## What dex reads
-
-- `dbt_project.yml`: the project name, profile name, and the six authored path
- families (`model-paths`, `macro-paths`, `snapshot-paths`, `seed-paths`,
- `test-paths`, `analysis-paths`), each defaulted the way dbt defaults it when
- the key is absent.
-- The source files under those families, scanned for the suffixes each one can
- hold: `*.sql` / `*.yml` / `*.yaml` under the model, macro, snapshot, test and
- analysis paths, and `*.csv` / `*.yml` / `*.yaml` under the seed paths. Together
- they are the editing surface (model SQL, `schema.yml`, dbt semantic models,
- macros, snapshots, seeds, singular and generic tests, analyses). A file dex can
- author but does not load would hash as absent, so a later edit to it would
- register as a create and the apply after it would conflict on a file nobody
- touched; the scan covers every family for that reason, not for completeness.
-- The newer available `manifest.json` from Dex's isolated artifact directory
- or the project's own target path when the project has been compiled; a fresh
- project loads fine without one.
-- `profiles.yml` (searched the way dbt searches: `$DBT_PROFILES_DIR`, the project
- directory, `~/.dbt`), but only to resolve a target's **name and adapter type**.
- Connection fields, credentials included, never leave the engine.
-- `dbt_packages/` when packages are installed, each package loaded as the dbt
- project it is, so a package that configures its own path families is read the
- way dbt reads it.
-
-### The reference index
-
-One projection over all of the above answers "where is this name used", and
-`transform references` returns it. Three things about it are worth knowing before
-relying on it.
-
-**It reads calls, not text.** Jinja is scanned for the calls it contains, so a
-`var()` read inside a macro body is a use of that var, a `{% if %}` block is not a
-blind spot, and the two-argument `ref('package', 'model')` form resolves to the
-model rather than to the package.
-
-**An argument dex did not read is `indeterminate`, never absent.** A
-`{{ ref(var('x')) }}` names a model only dbt can know, and a dimension whose
-`expr` is a computed expression names a column dex will not guess at. Both are
-reported by file and line with no name attached, because the fact is about the
-call site and not about any one target. Collapsing "dex could not resolve this"
-into "there is nothing here" is how a use goes missing, so the two stay apart.
-
-**It states whether it believes itself complete.** `completeness` is `complete`
-only when every reason to doubt the answer has been ruled out, and `limits` names
-each remaining one: an unresolved reference, packages declared but not installed,
-`sqlglot` absent on a column query, a file that would not parse. A completeness
-claim that is not complete is worse than no claim, because it is the one a caller
-acts on without checking.
-
-Names are matched at the grain the question allows. A model, macro, var, source,
-metric, entity, dimension or measure name is exact. A bare column name is matched
-across the project and labelled `name_matched`; a qualified `model.column` is
-resolved through the `ref()` graph, with occurrences outside that lineage still
-listed and labelled `same_name_elsewhere` rather than dropped. A dotted name reads
-as a source before it reads as a qualified column, since `raw.orders` is the more
-common thing to ask about.
-
-A seed contributes its header row and never a data row: the header names columns,
-which is what an index is for, and the rows are project data, which never enters
-agent context.
-
-The project is discovered automatically (the repo root, or a unique child
-directory holding a `dbt_project.yml`); `dbt_project_dir` in `.dex/config.yml`
-pins it when discovery would be ambiguous. Absent a dbt project, explore still
-works, writing only to the `.dex/` cache. dbt authoring and `maintain
-reconcile`'s mechanical edits do need one, since dbt is what they edit and diff.
-The semantic axis does not: a repository whose only declarations are native
-semantic documents authors them through `semantic ossie`, and `maintain` still
-fingerprints that layer and runs its free drift axes against it.
-
-dbt is the format dex ships, not the only one it can read. `maintain`'s four
-detection commands read whichever format `project.format` names, so a host whose
-models are not a dbt project can still be a drift baseline; `transform` and
-`maintain reconcile`'s mechanical edits are dbt throughout. See
-[`project.md`](/dex/reference/project-formats) for the seam and how to name another format.
-
-## How dex writes
-
-Every proposed change is a **plan**: the agent-authored file contents, validated
-by the engine, pinned to the sha256 of each file they would change, and stored
-under `.dex/plans/`. Applying a plan re-hashes every file first:
-
-- Hash matches (or the file is a clean create): apply, all-or-nothing.
-- File already carries the proposed content: a no-op, not a conflict.
-- Anything else means a human edited the file after the plan was made. That is a
- **conflict**: nothing is written, the divergence is surfaced as a diff, and the
- caller either re-plans against current state or overrides with an explicit
- `--confirm`.
-
-Each edit carries an `op`: `upsert` (create or update, the default) or `delete`.
-A delete removes a file as a first-class reviewable diff, pinned to the file's
-hash like any other edit, so it obeys the same conflict rule: a file a human
-touched after planning is never silently removed. Deletes are guarded as a unit:
-a plan is refused if any file that survives it still `ref()`s a deleted model, so
-the post-change project is proven to have no dangling reference before the plan
-is stored (and, when dbt is available, the same post-deletion tree is confirmed
-by dbt's own parser). The guard reads the reference index described under
-[What dex reads](#what-dex-reads), not a text search, so it resolves a
-two-argument `ref()`, does not mistake a seed's data row for source, and warns
-rather than refusing on a reference it could not resolve. A rename is expressed as one plan: delete the old model,
-create the new one, and update every referrer, validated together.
-
-Human edits to dbt are authoritative by construction; dex holds no competing copy
-to overwrite them from. Writes are confined to the six authored path families
-plus the project-root manifests dbt keeps there (`dbt_project.yml`,
-`profiles.yml`, `packages.yml`, `dependencies.yml`); path escapes are refused. A
-native semantic document is not in this surface and is never reached through it:
-it carries its own confinement rule, the exact paths the semantic axis declares.
-Within the surface, an edit's kind and its location have to agree: a snapshot
-belongs under the snapshot paths and nowhere else, a seed under the seed paths, a
-macro under the macro paths, a singular or generic test under the test paths, an
-analysis under the analysis paths, and model SQL and semantic YAML under the
-model paths. `schema.yml` is the one kind several families admit, because dbt
-expects a seed's column types, a snapshot's tests, a singular test's severity and
-an analysis's description declared beside the thing they describe. Filing a kind
-in the wrong family is refused at plan time naming both fixes (move the file, or
-relabel the kind), since dbt would otherwise parse a snapshot or a test as a
-model, or never load a seed or an analysis at all.
-
-A model, a snapshot and a seed each build a relation dbt names after the file and
-each is `ref()`-able, so all three count as nodes: deleting one is guarded
-against surviving references exactly like deleting a model, and all three are
-what `maintain` fingerprints as the transformation layer. A macro is not a node
-and never was one.
-
-**Neither a singular test nor an analysis is a node here, and the word is worth
-being careful with.** dbt calls a singular test a node (`test..`)
-and it is one in dbt's graph, but it builds no relation and nothing can `ref()`
-it, so it is not one of "the things this project builds": counting it would put a
-name into the drift baseline that no warehouse table will ever back. An analysis
-is further out still, compiled by `dbt compile` into `target/compiled/`, never
-built, and absent from a `dbt build` entirely. Both are loaded so they can be
-authored and hashed like anything else; neither enters the transform-layer model
-list, and deleting either raises no dangling-reference guard because there is
-nothing that could dangle.
-
-dex never builds to a non-dev target, and a delete only ever removes a file from
-the repo, never a relation from the warehouse.
-
-## Running dbt (build, deps, parse)
-
-By default, Dex writes artifacts under `/dex//`, and
-`data.artifact_directory` reports the directory used. This keeps artifacts from
-different dbt runtimes apart. `transform.artifacts: shared` selects the project's
-normal target path, with compatibility checks before anything writes. The
-[command contract](/dex/reference/command-contract) describes the artifact policy and the
-`transform build --full-refresh` option for rebuilding selected incremental
-models on dev.
-
-Every dbt subprocess runs with its working directory pinned to the project dir, so
-relative paths in `profiles.yml` and anywhere else resolve against the project, not
-the caller's shell cwd. Its environment is the caller's minus the credentials dbt
-never reads (`GITHUB_TOKEN`, `GH_TOKEN`, `DBT_SL_TOKEN`, the ClickHouse Cloud API
-key and secret, AI provider API keys), because any macro, a package's included,
-can read any variable through `env_var()`; warehouse credentials a profile reads
-still reach it. When the project declares packages (`packages.yml`, or a
-`dependencies.yml` with a `packages:` key) and `dbt_packages/` is missing or empty,
-`transform build` runs `dbt deps` automatically before building; `transform deps`
-is the explicit install/refresh. `transform build --cold-deps` reinstalls into an
-isolated copy instead, leaving this project's `dbt_packages/` alone. Package
-installation writes only `dbt_packages/` and the lockfile inside the project and spends nothing against the warehouse, so it
-runs without the cost gate.
-
-Semantic plans are validated up to and including dbt's own parser before they are
-stored: dex copies the project (minus warehouse files, target, and logs) into a
-throwaway directory, overlays the proposed YAML, and runs `dbt parse` there, so
-nothing the parser writes touches the real project. When dbt is unavailable the
-parse degrades to a warning rather than a hard failure.
-
-Source: [`references/dbt-project.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/dbt-project.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/dbt-project.md)). This page is generated; change the source, not the site.
diff --git a/dex/concepts/methodology.mdx b/dex/concepts/methodology.mdx
deleted file mode 100644
index 7b3281d..0000000
--- a/dex/concepts/methodology.mdx
+++ /dev/null
@@ -1,395 +0,0 @@
----
-title: Exploration methodology
-sidebarTitle: Methodology
-description: 'How dex makes sense of a warehouse without enumerating it: one-pass inventory, ranking, aggregate-only profiling, join inference, and the persisted draft map.'
-og:title: Exploration methodology · Exmergo Dex
-twitter:title: Exploration methodology · Exmergo Dex
----
-
-Start with [Explore a warehouse](https://docs.exmergo.com/dex/guides/explore) for the workflow.
-This reference explains how Dex selects tables and measures their structure.
-
-dex explores the way an analytics engineer does: it ranks what matters, drills in
-selectively, builds understanding from aggregates rather than rows, infers how
-tables relate, and persists a draft map. The guiding constraint is sense-making,
-not enumeration: dex never dumps a full schema into context. Everything below is
-read-only against the data, and on DuckDB it is free and resource-bounded rather
-than cost-bounded.
-
-## Inventory: one cheap pass
-
-Inventory is a single catalog round-trip with no table scans. For each object it
-records the cheap facts the catalog already knows: object type (table or view),
-an estimated row count, and a column count. Byte size is left unknown rather than
-fabricated, because there is no cheap per-object byte size to read; the row
-estimate is the size signal that feeds ranking. This pass is what makes selective
-drill-down possible: you cannot rank what you have not listed, and you should not
-scan what you have not yet decided is worth scanning.
-
-The row count is an estimate where the catalog keeps one and unknown where it does
-not, and the two are never collapsed into each other. A warehouse maintains no
-count for a view, and BigQuery maintains none for an external table either;
-several report that as a zero, which is why the count is decided from the object's
-kind rather than taken at face value. Unknown means the size signal cannot
-participate, so an uncounted object ranks as if it were small until something
-counts it. Empty means the object holds nothing, which is a finding. Reading the
-first as the second was how an external table over object storage came to be
-reported as an empty table with correct column statistics beside the claim.
-
-## Ranking: turn a list into a shortlist
-
-Ranking scores every object in [0, 1] from cheap signals so attention goes to the
-objects that matter first. The score blends four normalized signals:
-
-- **Size** (log-damped row estimate): bigger tables matter more, but the log keeps
- one giant log table from crushing everything else.
-- **Connectivity** (degree in the inferred-join graph): a hub table that many
- tables reference is central to the model.
-- **Naming**: a boost for analytics-engineering conventions (fact, dimension,
- staging, mart prefixes) and entity-shaped names; a penalty for scratch, backup,
- temp, and test names. Configured `ranking_hints` add explicit boosts.
-- **Shape**: a moderate column count reads as a real modeled entity; extremely
- wide or single-column tables are damped.
-
-Ranking is a pure function over metadata, so it costs nothing to run and re-run as
-relationships are discovered.
-
-## Profiling: understanding from aggregates, never rows
-
-Profiling builds a column-level picture from SQL aggregates only. For each object
-it issues one batched aggregate query (a non-null count, an approximate distinct
-count, and conditionally a min and max), batching wide tables so a single
-statement never balloons. From those it derives null fraction, distinct count, and
-a uniqueness signal. The distinct count is approximate for scale, so uniqueness
-starts as a candidate signal, never a proven key.
-
-Because an approximate count can overshoot a genuinely unique column and turn a
-real key into a false "grain unknown", profiling then escalates: any column whose
-approximate distinct count sits near its non-null count (within a bounded band) is
-re-counted with an exact `COUNT(DISTINCT)` in one batched, read-only statement,
-capped to the few closest candidates per table so the escalation stays cheap. An
-escalated count is marked exact, and only an exact count is allowed to confirm a
-key or a table's grain; downstream consumers (relationship fan-out notes included)
-never draw a hard conclusion from an approximation.
-
-When no single column proves unique (the shape of a fact table, whose grain is
-exactly what a profile must answer), profiling probes 2-column composite keys. A
-pair can only be a key if the product of its members' distinct counts reaches the
-row count, so pairs are pruned on that necessary condition using the counts
-already in hand, then ranked (id-shaped members first, smallest product next) and
-capped to a few probes issued as one exact distinct-combination statement. A pair
-that reuses a column from a better-ranked pair at a similar product is the same
-hypothesis with different filler, so it ranks behind every pair that is not, but
-it is never removed from the running: the cap is the spend guard, and while it
-has room a discarded candidate costs a grain and saves nothing. A pair whose
-combination count equals the row count is unique, which is necessary for a key and
-not sufficient to be one. On metered connectors the probe spends only inside the
-already-confirmed budget, narrowing to the best-ranked pairs the budget covers, and
-skipping with an explanatory note only when it cannot cover one.
-
-Two shapes of pair are unique for reasons that have nothing to do with the table's
-identity, and both are excluded from the pool before anything is priced. A pair
-whose member is a **continuous measure** is one: a measurement's cardinality grows
-with the table, so it completes a partner by arithmetic rather than by meaning, and
-a key made of money is almost never the grain anybody intended. The other is a pair
-**anchored on a column that is already unique on almost every row**. At that ratio
-the handful of rows the column fails to separate get separated by accident by any
-partner carrying more than a value or two, so the pair restates the column's
-near-uniqueness instead of discovering a grain. The exception, and the reason this
-is a test on the pair rather than on the column, is a partner whose domain is
-bounded by the fanout rather than by the table: when a few duplicate order ids are
-separated by a three-value line number, the data really does have that grain. A
-near-unique *timestamp* gets no such exception, because a per-row event time is not
-an entity whose rows a position column enumerates.
-
-Excluding before probing is deliberate on three counts: the exact answer could not
-move a decision either way, the pair would have to be reported and immediately
-disclaimed, and dropping it frees a capped slot for a pair that might be the real
-grain. None of it applies to a table too small for cardinality-versus-rows
-reasoning to mean anything, where every column looks near-unique and every measure
-looks continuous: below a fixed row floor everything is asked and the exact count
-decides.
-
-What survives enters the candidate keys, smallest proven cardinality first, so the
-tightest proven key is the first entry and, absent any single-column key, the
-reported grain. Where nothing survives, the grain is reported unknown and the
-near-unique column is named with its counts, because the finding there is
-duplicates in the source rather than an absent key.
-
-Suppression is never silent. Every combination the probe considered comes back in
-`key_evidence`, one entry per combination, carrying its columns, whether it was
-reported or suppressed, and the reason in the profile's own words. The reported
-entries appear in the same order as the candidate keys, so the ranking is readable
-rather than implied, and the suppressed ones follow. That is also what makes a
-probe that ran and found only artifacts distinguishable from one that never ran,
-which the probe's own budget notes say instead.
-
-A candidate key held as a string is also checked for **mixed value shapes**, the
-trace a partial migration or a merged upstream leaves in an id column. The
-profiling scan sorts every non-null value into one of four groups, numeric, dashed
-UUID, hexadecimal, or other, and returns only the fraction in each. When two or
-more groups each hold at least 5% of the values, the profile names them in a
-data-quality note. A value counts as hexadecimal only at 8 characters or more:
-below that, ordinary codes such as two-letter country codes or airline seats like
-`12A` are spelt in the letters A to F by chance often enough to clear 5% on their
-own. A shorter hex value counts as other instead, so a population of short hashes
-mixed into a numeric key is still reported, under that name. The note ends with
-the consequence that fits the groups it names: with a numeric group, a cast or
-numeric comparison silently drops the rest; without one, a join or filter written
-for one shape silently misses the others. Only the fractions and a label derived
-from the hex lengths (`32-character hexadecimal (md5-shaped)`) leave the engine,
-never a value.
-
-Two safety rules are enforced at the source, in the SQL that is generated:
-
-- **min and max are surfaced only where the extreme value is not itself
- sensitive**: numeric and temporal columns that carry no PII flag. For any string
- column, or any column flagged as PII, min and max are never even computed, so a
- raw or sensitive value never leaves the engine.
-- **All generated SQL is read-only.** Beyond the read-only connection, every
- statement is parsed and refused if it is not a single read-only SELECT.
-
-### PII: flagged, never surfaced
-
-PII is detected from column names and aggregate shape, never by inspecting values.
-A name-pattern table maps a column to a category (email, phone, name, address,
-government_id, financial, credential, location, date_of_birth) with a base
-confidence, which aggregate signals then nudge (a near-unique text column on an
-email-like name strengthens the flag; very low cardinality on a location-like name
-weakens it). The result is recorded strictly as (column, category, confidence)
-with no example value, and that flag is what propagates downstream into emitted
-dbt.
-
-For the weakest signal, a generic `*_name` string column, the profiling scan also
-computes three **value-shape statistics** as in-engine SQL aggregates: the
-fraction of values that are all-caps tokens, the fraction shaped like a given
-name plus surname, and the average token count. These are regex predicates
-inside measuring aggregates, so only numeric fractions leave the engine, never a
-value. The evidence moves confidence in both directions: a person-shaped
-distribution corroborates the flag up to the exact-token level, while a tiny
-closed all-caps vocabulary (a region or nation dimension) or long multi-token
-labels (part and product descriptions) de-rate it to reference-data confidence.
-When the evidence is missing or ambiguous, the name-derived confidence stands:
-absence of evidence never weakens a flag.
-
-The flag itself is never removed by evidence. What a weak flag means is the
-consumer's decision, and the consumers differ: some gate on a flag's presence at
-any confidence, others compare it against a blocking threshold. That split, the
-threshold, and the only way a human clears a flag are in
-[`pii-policy.md`](/dex/guardrails/pii-policy).
-
-## Relationships: joins from metadata, not scans
-
-Relationship inference reads the profiles already gathered and never scans data to
-verify referential integrity, so it stays free and read-only at the cost of
-certainty, which is why every inferred join carries a confidence. The opt-in
-verification pass is the one place joins are measured, and it batches: the joins
-sharing a child relation are answered by one read of it, so what verification
-costs follows the relations it touches rather than the number of joins between
-them.
-
-A join is proposed when a foreign-key-shaped column name matches a parent object whose
-corresponding column is a candidate key and the types are compatible; confidence
-reflects how strong the name and key signals are. Candidate keys and the most
-likely grain come from the uniqueness signals: single columns proven unique, plus
-the composite keys proven at profile time that survived the artifact exclusions
-above; a single-column key is always preferred as the grain, and a member of a
-composite key is never treated as unique on its own. Where the strongest signal is
-a column unique on almost every row but not all of them, that is what the profile
-says, naming the ratio, the counts, and how many rows would have to be removed for
-the column to be unique. It reports no key at all rather than a combination built
-on the shortfall, because a caller who cannot tell a real key from filler is worse
-served by several candidates than by one named defect and none. Declared joins come
-from whichever channels declare one: the dbt project when one is present, and the
-semantic layer when one is configured, which need not be dbt's. Absent both,
-declared joins are simply empty, which is expected because explore is designed to
-work without either. A declared join carries every column pair it was written
-with, so a composite is one declaration measured as one complete tuple rather
-than a first-column proxy that would report a healthy join three times over while
-no tuple matched. Where two channels declare a join between the same pair of
-relations on different columns, both are kept and the disagreement is reported;
-dex does not pick a winner between two things the repository asserts.
-
-Declarations refine those verdicts without entering them. A declared
-grain fills in where measurement found none, and is noted where it disagrees, but
-a measurement-proven single column still wins the reported grain and the candidate
-keys stay measurement-only: an unmeasured declared key is a claim, and the cache is
-a drift baseline rather than a record of what the project asserts. The consequence
-is that a declared grain needs verifying somewhere else, which is what `maintain
-grain` does with it, and why that axis reports two different things about
-uniqueness. A key measurement proved unique that no longer is has a before and an
-after, so it lapsed. A declared combination that does not hold has neither: nothing
-changed, the project is asserting a grain the data never had, and the fix is to the
-declaration rather than to the data.
-
-## Row population: a model against the relation it is built from
-
-Everything above measures a relation on its own terms. A transformation project
-raises a question none of it answers: not what this relation looks like, but
-whether it holds the rows it should, given the relation it was built from. That
-is where the expensive errors live, because they raise nothing. An inner join
-written where a left join was meant, a filter that quietly excludes NULLs, a
-de-duplication keyed on the wrong column: each drops rows, none is an error, and
-uniqueness and not-null tests all still pass over the smaller result.
-
-The comparison needs one thing the warehouse cannot supply, which is the model's
-**driving parent**: the relation in its FROM clause, as distinct from the ones it
-joins. Those are different roles. The driving relation sets how many rows the
-model starts with, and a join can only reduce that number or multiply it. So the
-parent is read out of the compiled SQL rather than out of the dependency graph,
-which knows a model's parents but not which of them drives it, and it is followed
-through the chain of CTEs a dbt model compiles to, since the FROM of a compiled
-model's final select names an internal CTE almost every time.
-
-A parent can drive a model without being its population. A comparison mart that
-takes Monday anchors from the time spine and range-joins a daily fact holds one
-row per anchor, window and day, and the spine's row count is not a number it is
-expected to preserve. So a model driven off the project's time spine, or off a
-model generated in SQL, is not compared, and a note says so (#988). A model that
-only joins a spine still is, because then the spine is not what sets its count.
-
-**What the SQL says about itself decides whether the numbers mean anything.** A
-model carrying a filter, an aggregate, a de-duplication, or a set operation was
-written to hold fewer rows than its parent, and no amount of arithmetic
-distinguishes a filter that removed the rows it should from one that removed too
-many. There is no principled bound to compute, so those models are not reported
-at all rather than reported with a caveat. The cost of that choice is real: a
-filtered model that also lost rows to a bad join says nothing. The cost of the
-other choice is worse, because a detector that fires on every aggregate in a
-project is one nobody reads twice. The same logic runs the other way for growth,
-where an `UNNEST` or a lateral is a construct whose entire purpose is turning one
-row into several.
-
-Row counts themselves come from the cheapest source that can answer, and which
-one answered changes what the finding claims. A stored catalog count is free but
-is treated as an estimate, so the finding is not marked exact; an actual count is
-a proof. Where counting bills nothing, everything is counted, because a verdict
-about a ten percent difference has no business resting on an estimate. Where it
-bills something, it is priced and offered rather than taken, and the models it
-would have covered are named as uncompared. That last part matters more than it
-looks: a warehouse keeps no row count for a view, and a view is dbt's default
-materialization, so on a metered connector the models this can judge for free and
-the ones it cannot are split down exactly that line.
-
-## Test strength: measuring the tests rather than the data
-
-Everything above measures data. A dbt project also carries assertions about that
-data, and those assertions are themselves unmeasured: a suite of twenty tests
-that all pass proves the tests ran, not that any of them would object if the
-model were wrong. The two are routinely confused, because the only number the
-ecosystem reports is a count, and a count cannot distinguish a `not_null` on a
-surrogate key from a unit test pinning the arithmetic.
-
-The measurement that does distinguish them is to break the model deliberately and
-see whether anything complains. `transform test --mutate` plants one defect at a
-time, drawn from the same taxonomy the rest of this document is organised around:
-a boundary comparison that now includes or excludes its edge, a filter dropped or
-inverted, an inner join where a left join was meant, a missing `CASE` branch, an
-inverted ratio, a window frame off by one (a calendar window both one day
-wider and one day narrower), a `sum` reporting a `max`. Each is
-built and the model's own tests are run against it. A defect nothing catches is
-reported as a gap in the suite, described as the defect rather than as a diff,
-because the reader's next step is to write a test and not to reread SQL they
-already know.
-
-Three properties keep the result honest. Every verdict is relative to the tests
-that passed against the *unmutated* model, so a suite measured against its own
-already-failing tests cannot come back looking clean. A mutant the warehouse
-refuses outright is reported separately from one the tests caught, since a build
-would have failed on it anyway and counting it would flatter the suite. And a
-mutant that survives is a statement about detection, not about correctness: some
-survivors are defects the current data cannot distinguish at all, such as an
-inner join where every key happens to match, which is exactly why the finding
-names the test that would catch it rather than claiming the model is wrong.
-
-A defect has to get past every test in the project to ship, not only the tests on
-the model it was planted in. A mart test that pins every published count is often
-the strongest test an intermediate model has, and a measurement that ignored it
-would push the same coverage one hop upstream for no gain. So the tests on the
-models downstream run too, with the mutant routed through them, and a defect only
-they caught is reported apart from one the model's own tests caught: the first
-says the project would have stopped it, the second says this model's suite would
-have. The per-model score keeps the second meaning, because it is the one a
-reader acts on when deciding where a test belongs.
-
-dex measures which survivors those are. Each one is compared with the unmutated
-model on the dev target, and the two kinds need different tests: a survivor the
-data cannot tell apart needs a fixture that reaches the case, since no assertion
-over today's rows can see it, and one the data already tells apart needs an
-assertion over those rows. The comparison fingerprints every row of each side,
-counts the fingerprints, and reports how many rows each side has that the other
-does not. It counts a multiset rather than a set, so a mutant that only
-duplicates rows still differs, and it returns four integers and never a row.
-
-Two limits are worth knowing. The fingerprint is a 64-bit hash, so two
-different rows could in principle collide and read as the same; across the row
-counts a dev target holds that is vanishingly rare, but it is not impossible.
-And a model has to reproduce its own output for the comparison to mean
-anything, so the unmutated model is compared with itself first. A `random()`,
-a uuid or a `row_number()` over ties fails that self-check and no survivor is
-labelled. A floating-point aggregate can differ in its last digits between
-evaluations, and the self-check only catches that when it happens to show, so
-a `distinguishable` label on a model that sums floats deserves a second look.
-
-## The draft map: composing and persisting
-
-`explore map` composes the above into the `.dex/` cache (never the source of
-truth; see `canonical-model.md`). It ranks first on cheap signals, profiles a
-selective top set by default (with a `--full` option to profile everything, and an
-automatic profile-all on small warehouses), infers relationships among the
-profiled set, then re-ranks with connectivity for the final scores. The selective
-pass never caps silently: the summary states how many objects were profiled versus
-skipped and the rule that drew the line. On a re-map, an object that falls outside
-this run's top set keeps its prior profile (carried forward, each dataset stamped
-with its own `profiled_at`) rather than dropping to inventory-only, so coverage
-accumulates across runs. The cache is re-derived and replaced on each run so
-dropped objects disappear, while the original creation timestamp is preserved. What
-is printed back is a counts-level summary, never the cache contents, keeping the
-output sense-making rather than a dump.
-
-## Diagrams: serializing structure, never drawing values
-
-`explore diagram` renders the cached map as a Mermaid `erDiagram`. It is a pure
-function of the cache: it opens no connection, needs no credential, spends
-nothing, and can be re-run freely while a diagram is being shaped.
-
-**The rule that bounds it, and every renderer after it: dex may serialize
-structure it has already computed into a text format, and dex never renders data
-values into a visual encoding.** An entity-relationship diagram of the objects,
-keys, and joins is structure. A chart of null fractions or value distributions is
-a picture of the data itself, which is a different product's job. In practice
-that admits `erDiagram`, `flowchart`, and `classDiagram`, and rules out `pie`,
-`xychart`, `sankey`, and `quadrantChart`. No column value reaches a diagram: the
-cached min and max are never read, and a PII flag renders as its category and
-confidence, because flagged-not-hidden is the posture everywhere else too.
-
-A diagram is trusted more readily than the JSON it came from, so the cardinality
-rules are strict. Mermaid requires a glyph on every edge and dex's relationship
-record carries no cardinality, so the renderer derives one only from what was
-proven. It claims "exactly one" on the parent side only when the parent key is a
-proven key **and** the join was declared in the repository or measured with no
-orphans; it degrades to "zero or one" when uniqueness is proven but nothing
-measured the overlap; and it degrades to "zero or many" when uniqueness was never
-established at all. Declared joins are drawn solid and inferred joins dotted, and
-the edge label carries the kind, the confidence, and the orphan fraction, so an
-unverified guess says so on its face.
-
-Selection follows the same rule as the rest of explore: a fully attributed
-diagram of a large warehouse is a schema dump, so the default draws objects that
-were profiled and participate in a join, carrying their grain, key, join, and
-PII-flagged columns. `--full` widens to every eligible object and column, an
-entity cap binds in both modes, and everything left out is counted in the notes.
-
-Rendering is deterministic, so the same cache produces byte-identical output and
-a regenerated file diffs cleanly. dex writes no diagram file: the text comes back
-in the envelope and choosing where it lands is the caller's decision.
-
-## What the agent sees
-
-Every command prints exactly one sanitized JSON envelope (see
-`command-contract.md`); credentials and raw rows can never cross that boundary,
-and a leak is a hard failure rather than a silent scrub. The agent reads the
-envelope and decides the next step, so multi-step exploration is the agent
-orchestrating stateless subcommands over the repository and the `.dex/` cache.
-
-Source: [`references/methodology.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/methodology.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/methodology.md)). This page is generated; change the source, not the site.
diff --git a/dex/concepts/source-of-truth.mdx b/dex/concepts/source-of-truth.mdx
deleted file mode 100644
index 690071c..0000000
--- a/dex/concepts/source-of-truth.mdx
+++ /dev/null
@@ -1,162 +0,0 @@
----
-title: The source of truth and the .dex/ cache
-sidebarTitle: Source of truth
-description: 'Why the repository is the source of truth for dex: dbt models and the semantic layer stay canonical, and the .dex/ directory is only a disposable cache.'
-og:title: The source of truth and the .dex/ cache · Exmergo Dex
-twitter:title: The source of truth and the .dex/ cache · Exmergo Dex
----
-
-dex maintains no canonical model of its own. **The repository is the source of
-truth**, on two axes: the transformation project, which is dbt, and the semantic
-layer, which is dbt's own or a native format that owns its definitions in files
-beside it. dex reads whichever are present, reasons over them together with
-warehouse introspection, and writes changes back as reviewable diffs. The only
-state dex keeps of its own is a non-canonical cache under `.dex/`.
-
-## Why dbt, not a dex-native model
-
-An earlier design made the source of truth a dex-invented semantic model, with
-every other format a projection of it. That was an over-correction. The reasoning
-was "the interchange formats are immature, so build our own," but the right
-response to an immature standard is to anchor on the mature thing, not to invent
-a third one: a representation dex invents has no spec, no tooling, and no users,
-so it is the least mature option, not the most stable. And the premise was
-largely wrong on the facts: **dbt's MetricFlow already expresses nearly all of
-the richness** in question (entities; categorical and time dimensions with
-granularity; measures; and metrics of kind simple, ratio, derived, and
-cumulative, with time spines). The dex-native model was, in effect, a plan to
-re-implement MetricFlow, worse. dbt is mature, versioned, adopted, and where AEs
-already live, so it is the correct anchor for the transformation model.
-
-The decisive practical win: with the repository as the source of truth there is
-no parallel copy to reconcile, so the round-trip fidelity problem, the
-per-element provenance and identity machinery, and "the human's file wins"
-conflict resolution all disappear. Human edits are authoritative by construction.
-
-That reasoning is about not inventing a model, and it does not argue against
-reading a format somebody else specifies. A semantic layer that owns its own
-definitions is read where it lives, on its own axis, with no translation into
-dbt's vocabulary and no dbt project required. Those definitions are source of
-truth in exactly the same sense the dbt project is: they are files in git, dex
-holds no competing copy of them, and every change dex makes to them is a diff.
-See [`semantic-layer.md`](/dex/semantic-layers/overview).
-
-## How dex reads and writes the dbt project
-
-- **Read:** load the project primarily from the compiled `manifest.json` (dbt's
- own documented, versioned serialization of nodes, sources, tests, semantic
- models, metrics, and lineage), supplemented by the raw SQL and YAML for editing.
- This lives in `dbt_project.py`.
-- **Reason:** over that view plus warehouse introspection and the `.dex/` cache.
-- **Write:** edits go back into the dbt source files as reviewable diffs. dex
- never holds a competing copy.
-
-## The `.dex/` cache (not canonical)
-
-`.dex/` holds only what the repository has no home for, and it is a cache that
-informs proposals, never the source of truth:
-
-```
-.dex/
- config.yml non-secret config: connector + dbt target, budgets, ranking hints
- cache.json exploration artifacts (DexCache): profiles, PII flags, relationships,
- ranked candidate keys with the evidence behind each (key_evidence,
- including the combinations suppressed as artifacts and why), grain,
- rankings, data-quality observations. A column profile records whether
- its distinct count is exact or approximate (distinct_count_exact); each
- dataset carries the time it was profiled (profiled_at) so
- carried-forward profiles stay attributable, and the file carries a
- schema version, so a profile written before the artifact exclusions
- existed is re-profiled rather than read as if they had applied.
- provenance.tool_version is the engine release that last wrote it
- (null where unknown), so a cache two releases share says which
- one it came from
- snapshot.json the maintain baseline: a frozen fingerprint of the warehouse schema, the
- transformation project's state, the semantic layer's definitions with the
- relationships and keys they declare, and declared grain assumptions. The
- two project layers are fingerprinted independently, so a repository with a
- semantic layer and no transformation project still gets a baseline. Written
- by `maintain snapshot`; the drift detectors diff current reality against it,
- and warn when the tool_version it records is another engine release.
- queries.jsonl the `explore query` audit log: one line per firewall decision (allowed,
- refused, or failed) with the SQL text and result counts, never result
- values. A decision that profiled an object on demand first names it
- under profiled_on_demand (profile_planned where the decision was
- needs_confirmation), so a scan run on the caller's behalf is as
- findable as a spend. A call carrying several statements writes one
- line each, sharing a timestamp and carrying batch_index and
- batch_size, so six statements read as one authorization event
- rather than six. Doubles as product signal: probe shapes that
- recur here are candidates for promotion to named commands.
-```
-
-Delete `.dex/` and nothing canonical is lost: dex re-derives the cache from the
-repository and the warehouse. The cache types live in `cache.py`; secrets never live
-here. PII is recorded as `(column, category, confidence)` with no example values.
-
-The layout above is the CLI's choice, not the engine's. Where this state lands is
-a backend behind the `Store` protocol, injected at the entry point: the CLI picks
-the filesystem so subcommands stay stateless across processes and the session
-budget carries from one command to the next, while an in-process library caller
-gets an in-memory store by default and writes nothing at all. A host can
-implement the protocol over its own session store or database. The repository is
-unaffected by any of this: it is the source of truth and stays a git-reviewable
-filesystem artifact, which is why `repo_root` remains separate from the store.
-
-Credentials are in neither place. dex discovers them at connection time and never
-stores, caches, or refreshes one, in any backend. A host serving more than one end
-user can supply them itself, the warehouse connection and a hosted semantic layer
-token alike, so each request reaches its target as its own principal instead of as
-the process; that moves who the caller is, and nothing else. The cost gate is still
-built by the engine from the store, the source allowlist still only narrows, and no
-credential becomes persistent state.
-
-## The extension seam (more formats later)
-
-Supporting more model formats over time does not require a neutral internal model.
-It requires a seam thin enough that a class with the right methods is a project,
-with no base class to inherit and no registration step. That seam is three nested
-protocols in `adapters/project.py`, and a format implements the tiers it can serve:
-
-| tier | protocol | adds |
-|---|---|---|
-| 1 | `ExploreProject` | `definitions()` |
-| 2 | `MaintainProject` | `transform_layer()`, `semantic_layer()` |
-| 3 | `EditableProject` | `write_edits()` |
-
-`DbtProject` is the one implementation dex ships. Future sources (SQLMesh, Cube, an
-orchestrated asset graph) become new implementations of the same protocols without
-touching the engine that reasons over a project. A semantic layer that builds
-nothing is not one of them: it owns no model graph, no compilation, and no
-targets, so it sits on a separate seam described in
-[`semantic-layer.md`](/dex/semantic-layers/overview) and satisfies none of the tiers above. Nothing behind the seam is a rich
-neutral model: `definitions()` returns the engine's existing `ProjectDefinitions`
-rather than a parallel vocabulary that would have to be mapped at every call site,
-and dex does not project the dbt model back out into other formats. dex reasons
-over the project and authors into it directly; there is no one-way exporter path.
-
-Tiers rather than a capability flag, because a flag is a claim the engine has to
-trust while `isinstance(project, EditableProject)` is checkable. A format that
-cannot receive an edit declines tier 3 and cannot accidentally claim otherwise.
-
-[`project.md`](/dex/reference/project-formats) is the contract itself: what each tier owes its callers,
-the one rule that is not visible in the signatures, how a format is named in
-configuration, and the conformance suite that proves an implementation works.
-Read that before writing a format; this section only says where the seam sits.
-
-> An earlier version of this section named a single `ProjectAdapter` protocol with
-> `load()` and `write_edits()`. That protocol still exists, unreferenced, because it
-> has been public since v1, but it is superseded and satisfies no tier. Anything
-> written against it would be refused as "not a project".
-
-## The round-trip rule (reconcile, simplified)
-
-1. Re-read the dbt project and warehouse on every transform or maintain run.
-2. Human edits are already authoritative (the repository is canonical); there is
- no internal copy to reconcile against, only the `.dex/` snapshot used to
- detect change.
-3. Diff the current dbt project and warehouse against the snapshot; propose edits.
-4. On any ambiguous or overwriting change, surface a diff and ask. Never silently
- overwrite.
-
-Source: [`references/canonical-model.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/canonical-model.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/canonical-model.md)). This page is generated; change the source, not the site.
diff --git a/dex/connect.mdx b/dex/connect.mdx
deleted file mode 100644
index b69c49e..0000000
--- a/dex/connect.mdx
+++ /dev/null
@@ -1,83 +0,0 @@
----
-title: Connect your data
-sidebarTitle: Connect your data
-description: Choose a warehouse connector, verify access, and narrow the data Dex can read. Set spending limits before profiling or building on a metered warehouse.
-og:title: Connect your data · Exmergo Dex
-twitter:title: Connect your data · Exmergo Dex
----
-
-
-Use this path when you already have a warehouse or DuckDB file. If you want to
-learn the commands first, the [quickstart](/dex/quickstart) creates a local demo.
-
-## 1. Choose the connector
-
-The skill wrapper selects the connector extra from your project's configuration.
-For a standalone CLI, install the matching extra as described in
-[Installation](/dex/installation).
-
-| Your data | Setup and configuration | CLI extra |
-| --- | --- | --- |
-| Local DuckDB file | [DuckDB](/dex/connectors/duckdb) | `duckdb` |
-| Google BigQuery | [BigQuery](/dex/connectors/bigquery) | `bigquery` |
-| Snowflake | [Snowflake](/dex/connectors/snowflake) | `snowflake` |
-| Databricks SQL | [Databricks](/dex/connectors/databricks) | `databricks` |
-| Amazon Redshift | [Redshift](/dex/connectors/redshift) | `redshift` |
-| PostgreSQL | [PostgreSQL](/dex/connectors/postgres) | `postgres` |
-| ClickHouse | [ClickHouse](/dex/connectors/clickhouse) | `clickhouse` |
-| Trino or Starburst | [Trino](/dex/connectors/trino) | `trino` |
-
-Each connector page names its authentication sources and configuration keys.
-Keep credentials in the connector's credential store or environment, rather than
-pasting them into a chat or committing them to `.dex/config.yml`.
-
-## 2. Verify the connection
-
-For an existing DuckDB file, pass its path directly:
-
-```bash
-dex connect test --path /absolute/path/to/warehouse.duckdb
-```
-
-For a configured project:
-
-```bash
-dex config validate
-dex connect test
-```
-
-Check the reported connector, target, and capabilities before profiling. A working
-dbt profile alone does not always select Dex's connector; use the configuration
-and discovery rules on your connector's page.
-
-
-
-`dex config get` shows effective settings and where they came from.
-`dex config set` first returns a diff; reissue it with `--confirm` only after
-reviewing that diff. See the [configuration commands](/dex/cli/config).
-
-
-
-## 3. Decide scope and spending limits
-
-Start with the databases or datasets relevant to your task. Connector settings
-establish the source allowlist; `--scope` can narrow it for an individual command.
-A dev build destination is separate from the source scope.
-
-On a metered warehouse, read the estimate before approving work. Budget units
-vary by connector. The person running the session chooses the per-command and
-daily limits; an agent must not invent them.
-
-See [cost controls](/dex/guardrails/cost-controls) for the confirmation flow and
-what belongs in each ceiling. Hosted dbt Cloud semantic queries have a different
-boundary and are outside Dex's cost guard.
-
-## 4. Start with an inventory
-
-```bash
-dex explore inventory --rank
-```
-
-Use that shortlist to decide what to profile, or ask your agent to
-[explore the warehouse](/dex/guides/explore). A successful connection proves
-access; it does not prove the tables' grain or the joins between them.
diff --git a/dex/connectors/bigquery.mdx b/dex/connectors/bigquery.mdx
deleted file mode 100644
index 3931b08..0000000
--- a/dex/connectors/bigquery.mdx
+++ /dev/null
@@ -1,305 +0,0 @@
----
-title: BigQuery connector
-sidebarTitle: BigQuery
-description: Connect dex to BigQuery with Application Default Credentials. Every scan is priced by a free dry run, capped with maximum_bytes_billed, and read-only.
-og:title: BigQuery connector · Exmergo Dex
-twitter:title: BigQuery connector · Exmergo Dex
----
-
-The first billed cloud connector. Namespace: `project.dataset.table`. Cost
-paradigm: **bytes scanned**. Read-only against data, enforced in depth.
-
-## Authentication: discover, don't ask
-
-Auth is Application Default Credentials (ADC), never a prompted or pasted key.
-The engine discovers credentials at runtime; if none exist it tells you the
-fix:
-
-```
-gcloud auth application-default login
-```
-
-Service accounts work through `GOOGLE_APPLICATION_CREDENTIALS`, Workload
-Identity Federation, impersonation (`--impersonate-service-account`), or the
-metadata server; whatever `google.auth.default()` resolves. The GCP project
-resolves in this order:
-
-1. `bigquery.project` in `.dex/config.yml`
-2. `GOOGLE_CLOUD_PROJECT` / `GCLOUD_PROJECT`
-3. the ADC default project
-4. the `project` of a `type: bigquery` target in a discovered dbt `profiles.yml`
-
-Only the principal's coarse type (user, service account, impersonated,
-federated) is ever surfaced; its identity and any key material never cross the
-envelope.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: bigquery
-bigquery:
- project: my-project # billing/quota project jobs run in
- datasets: # source allowlist; empty means every dataset
- - raw # bare names resolve against `project`
- - bigquery-public-data.samples # qualified names read another project
- location: EU # optional job-location override
- dev_dataset: dbt_dev # where dbt dev builds write (never a source)
- max_full_profile_bytes: null # opt-in TABLESAMPLE threshold for huge tables
-budget:
- ceiling: 1000000000 # per-command bytes (1 GB); --budget overrides
- session_ceiling: 10000000000 # cumulative bytes per UTC day
-```
-
-## Cost model: preflight before spend, capped at the server
-
-- **Free:** `connect test`, `explore inventory`, all schema and row/byte-count
- metadata (API calls, never `INFORMATION_SCHEMA`, which bills a 10 MB minimum
- per query), and every dry-run.
-- **Billed:** profiling aggregates, `explore query`, relationship verification
- probes, and `transform build`.
-
-`explore query` and `explore cluster` bill an auto-profile of an object this connection has that the `.dex/` cache cannot adjudicate, priced into the same handshake as the statements: see [`cost-controls.md`](/dex/guardrails/cost-controls). Pass `--no-auto-profile` (or set `auto_profile: false` in `.dex/config.yml`) to be refused instead.
-
-Every billed command is estimated first with free dry-runs, which is why the
-estimate here is `exact` rather than modelled. Budgets are bytes; the handshake
-itself is in [`cost-controls.md`](/dex/guardrails/cost-controls).
-
-On the confirmed run, every statement is dry-run again and charged against the
-budget, and every job carries a server-side `maximum_bytes_billed` cap, so a
-drifting estimate cannot overrun the budget. Where the billed bytes land
-afterwards, and when a ledger that cannot be read refuses a command, are in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-BigQuery bills a 10 MB minimum per query; a remaining budget below that is
-refused with the math rather than letting the job fail server-side. Query-cache
-hits bill zero and are recorded as such.
-
-### What a profile estimate is made of
-
-A profile's cost is not one query per table. After the aggregate scan, a
-profile may issue up to three more queries against the same table: an exact
-distinct count for a near-unique column, a value-domain probe for a
-low-cardinality one, and a composite-key probe. Which of them run depends on
-the aggregate scan's own approximate results, so none can be dry-run before it,
-and the estimate holds one 10 MB floor apiece instead. A reserve is dropped only
-where an object's metadata already rules the query out: a table known to hold no
-rows, a table of nested or repeated columns only (no approximate distinct, which
-every probe starts from), a table too small for a value domain, or one with too
-few countable columns to form a composite pair.
-
-The reserve cannot mirror every reason a composite probe ends up issuing nothing.
-A pair built on a continuous measure, or one that merely completes a column
-already unique on almost every row, is excluded before the probe runs, and both
-verdicts come from distinct counts that do not exist at estimate time. So a table
-whose every candidate pair is excluded that way still carries its reserve and
-then spends nothing. That is the loose direction and it is the safe one:
-reserving for a query that does not run costs a caller headroom, while failing to
-reserve for one that does is an overrun.
-
-An object BigQuery keeps no row count for, meaning every view and every external
-table, reserves all three. Unknown is not empty: the count arrives inside the
-aggregate scan, so every probe can run, and at estimate time there is no number
-yet to narrow the hold with. That makes an external table's estimate four 10 MB
-floors rather than one, which is worth knowing before pointing a profile at a
-lakehouse of them. The reserve is released rather than spent when a probe does not
-run, so it costs headroom for the length of the command, not money.
-
-The reserve scales with object count rather than data size, so on a warehouse of
-many small tables it can be most of the number. Both the `needs_confirmation`
-payload and the over-ceiling refusal split it out, in prose and in
-`reserved_bytes` / `reserved_queries`, so a raised budget is a decision rather
-than a guess:
-
-```
-220,200,960 bytes of this estimate is escalation reserve: 21 queries at
-BigQuery's 10,485,760-byte per-query minimum, held for probes a profile may add
-after its aggregate scan and may never issue. The remaining 533,991,980 bytes
-is dry-run scan
-```
-
-A mid-command verify checkpoint prices overlap probes, which carry no reserve,
-so it reports none rather than repeating the profile's.
-
-### What a join overlap probe costs
-
-The 10 MB minimum is charged per table a query references, so a probe that reads
-a child and a parent floors at two of them. Issued one per join, a graph's probes
-therefore cost twice its edge count in floors, and a dimension five facts join
-pays its own floor five times. That is a bill set by how many joins exist rather
-than by how much data they cover, and it recurs on every run that verifies.
-
-So the probes are batched: the joins that share a child relation are measured
-against one read of it, and the batch's children are combined into a single
-statement. Each statement then names each of its tables once, and a graph of M
-tables floors at M times 10 MB however many joins connect them. On a nine-edge
-star schema over seven tables the estimate falls from 180 MiB to 70 MiB, against
-32 MiB of scan that both shapes pay: what the batching removes is floor, not
-measurement. The per-join results are identical, and `--infer-by-overlap`'s sweep
-is batched the same way, which matters more there because it runs up to fifty
-probes.
-
-### What a drift sweep costs
-
-`maintain grain` and the scanning half of `maintain check` ask each table several
-things: an exact distinct count over its proven keys, a distinct count per
-composite or declared grain, one per join whose declared arity makes that side a
-key, a null-fraction survey, and, under `check`, a distinct count for the
-categorical dimensions the semantic layer reads from it. Issued separately, each
-of those paid its own 10 MB floor on the same table, so a sweep's bill tracked how
-many questions it asked rather than what they read.
-
-So a table's probes run as one statement, and the sweep floors once per table it
-scans. The statement reads no column the separate probes would not have, and the
-findings are identical. A table that owes only one probe runs it exactly as
-before. A table large enough to be profiled from a block sample keeps its null
-survey as a statement of its own, since the survey reads the sample and the
-distinct counts must read every row. Where the remaining budget cannot cover the
-combined statement, each probe runs on its own and skips or narrows with its own
-note, as it always has.
-
-Folding several *tables* into one statement would save nothing: the floor is
-charged per table a statement references, not only per statement. `maintain
-volume` runs no query at all; it reads the row counts BigQuery keeps in table
-metadata.
-
-## Profiling behavior
-
-- Aggregates only (`COUNT`, `APPROX_COUNT_DISTINCT`, `MIN`/`MAX` on safe
- columns), batched to keep statements bounded.
-- `RECORD`/`STRUCT` columns get a non-null count only; `REPEATED` (ARRAY)
- columns get no aggregates (they cannot be NULL and distinct counts are
- invalid on them); `JSON`/`GEOGRAPHY` are treated as nested.
-- Tables that require a partition filter are never scanned: they get a
- metadata-only profile plus a data-quality note.
-- A row count is read from the metadata only for a base table, which is the only
- kind BigQuery maintains one for. A view, a materialized view, an external table
- and a snapshot all report `num_rows` as `0` whatever they hold, so that zero is
- read as unknown rather than as empty, and the real count comes from the
- aggregate scan's own `COUNT(*)`, which is already paid for. Until an object is
- profiled its count and byte size are therefore `null`, which ranks it as if it
- were small: profile it to rank it on its size. `empty table (no rows)` is
- reported from the aggregate's zero, so it means the object is empty rather than
- uncounted, and `maintain volume` names the objects it could not compare instead
- of returning no finding for them.
-- With `bigquery.max_full_profile_bytes` set, larger tables are profiled from
- a `TABLESAMPLE SYSTEM` block sample, flagged as approximate, and uniqueness
- is not judged.
-- Exact distinct-count escalation (the uniqueness proof), the composite-key
- probe, and the value-domain probe each spend only within the
- already-confirmed budget, and degrade (to an approximate verdict, no
- composite key, or no reported domain) plus a table note when the remaining
- budget cannot cover them. The composite-key probe degrades in two steps: it
- first narrows to the best-ranked candidate pairs the budget can cover, and
- only skips outright when it cannot cover one. Either way the note says which
- it was, because a missing composite key otherwise reads as a warehouse that
- answered and had none.
-- The reserve holds one query minimum for the composite-key probe however many
- pairs it carries, so on a wide table the probe's dry run can price above what
- the estimate held for it. The per-statement gate, not the reserve, is what
- bounds that: the probe is priced against the live remaining budget before it
- runs, and narrows or skips rather than exceeding it.
-
-## Read-only, in depth
-
-BigQuery has no read-only connection mode, so the layers are: every statement
-passes the SELECT-only guard in the BigQuery dialect (scripting, DML, DDL,
-`EXPORT DATA`, `CALL`, and multi-statement input are refused); the adapter
-calls no mutating client API; and the recommended grants are read-only:
-
-- `roles/bigquery.dataViewer` on the datasets dex explores
-- `roles/bigquery.jobUser` on the billing project
-- `roles/bigquery.dataEditor` on the dedicated dev dataset only (for
- `transform build`)
-
-## dbt
-
-The `[bigquery]` extra carries `dbt-bigquery`. Running
-`transform init --connector bigquery`
-renders a single `dev` target with `method: oauth` (ADC; no secret
-is ever written), pointed at `bigquery.dev_dataset` (default `dbt_dev`), and
-refuses a dev dataset that is also a source. Passing `--project ` picks the
-project explicitly: it wins over a configured or discovered one, and init
-records the same value as `bigquery.project`, so a fresh repository needs no
-prior config edit and no gcloud default project. When `budget.ceiling` is set, the
-profile carries `maximum_bytes_billed` so every statement dbt runs is capped
-server-side. `transform build` surfaces an upfront byte estimate: it runs a free
-`dbt compile`, dry-runs each compiled node the same way `explore` prices a query,
-and sums the result (downstream nodes whose dev inputs are not built yet cannot
-be dry-run, so on a cold target the total is a partial floor). It still requires
-`--confirm` and a `--budget`, and its billed bytes land in the spend ledger.
-
-`transform build --verify` costs only where the warehouse keeps no row
-count, so a table's count is free metadata; how the counts are priced into
-the build's own estimate is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-`--verify` also reads `bigquery.dev_dataset` for the length of that one command,
-because dbt writes the relations it is judging there and that dataset is refused
-as a source everywhere else. The dataset need not exist yet: dbt creates it on a
-first build. A build that writes every model into a custom schema never creates
-it, and row population is then suppressed with a reason that names the gap. How
-that read is bounded is under **Read scope** in
-[`command-contract.md`](/dex/reference/command-contract).
-
-`transform test --mutate` prices the whole batch upfront and confirms it once.
-Each mutant is spliced into each of the model's compiled data tests and dry-run
-priced as the statement the warehouse will actually run, which matters here more
-than on any other connector: dropping or flipping a predicate on a partitioned
-table changes what the scan prunes, so a mutant can legitimately cost more than
-the model it came from and pricing the batch at the baseline's cost would
-under-report it. The breakdown names `(baseline)` and each mutant by id, so one
-`--budget` covers the run and the caller sees where it goes. Unit tests read
-fixtures rather than the warehouse and are not priced. If the confirmed budget
-runs out partway, the run stops and the remaining mutants come back `not_run`.
-Nothing is materialized: mutants build as ephemeral models, so no table or view
-is created in `bigquery.dev_dataset` and none of the run needs cleaning up.
-
-Comparing each survivor with the unmutated model on the dev data is opt-in here,
-with `--check-equivalence`, and goes into the same estimate rather than a second
-ask. The comparison is dry-run priced once as the self-check and once per mutant
-with the mutant spliced in, since a mutant that widens a partition scan widens
-its comparison too. It is priced as if every mutant survives, as
-`(equivalence checks, if every mutant survives)`, and only survivors run one,
-so the settled spend is at most that line. Each comparison is one statement, and
-the 10 MB per-query minimum applies to each. A comparison the dry run refuses
-turns the check off with a reason, before anything is spent. Without the flag,
-survivors report `equivalence.status: not_checked`.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-Each downstream test is dry-run priced with the mutant spliced in beneath the
-models it reads, so the estimate is exact, and the 10 MB per-query minimum
-applies to each.
-
-
-
-With `--layered-schemas`, the scaffolded `generate_schema_name` override makes
-each layer build into its own sibling dataset in the profile's project
-(`staging_dev`, `intermediate_dev`, `marts_dev` on the `dev` target);
-dbt-bigquery creates them on first build. Init's content preflight lists each
-target dataset through the free `tables.list` metadata API (never
-`INFORMATION_SCHEMA`, which bills a minimum per query) and warns when one
-already holds tables or views.
-
-## JSON quirks
-
-Two BigQuery behaviors cost real debugging time when modeling JSON with
-dynamic (data-dependent) keys, the shape NoSQL-sourced CDC exports land in:
-
-- A JSON function's path argument must be a compile-time literal; building it
- per row (string concatenation into `JSON_QUERY`) is rejected at compile
- time. The subscript operator on the JSON value (`doc[key_expr]`) accepts a
- computed key.
-- `JSON_KEYS` recurses into nested objects by default, silently returning
- nested field names alongside the real top-level keys; pass an explicit
- depth (`JSON_KEYS(doc, 1)`) to stop it. The symptom of the default is
- quiet: extra rows that orphan a downstream join.
-
-The shipped `unpivot_json_object` macro (`transform macro unpivot_json_object`)
-bakes both fixes in; prefer it to hand-rolling this pattern.
-
-Source: [`references/bigquery.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/bigquery.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/bigquery.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/clickhouse.mdx b/dex/connectors/clickhouse.mdx
deleted file mode 100644
index ef880e8..0000000
--- a/dex/connectors/clickhouse.mdx
+++ /dev/null
@@ -1,428 +0,0 @@
----
-title: ClickHouse connector
-sidebarTitle: ClickHouse
-description: 'Connect dex to self-hosted ClickHouse or ClickHouse Cloud: two-part namespaces, database-seconds or compute-seconds pricing, and read-only server caps.'
-og:title: ClickHouse connector · Exmergo Dex
-twitter:title: ClickHouse connector · Exmergo Dex
----
-
-The analytical database, self-hosted or ClickHouse Cloud. Namespace:
-`database.table`, **two parts**, because ClickHouse has no catalog level above
-the database. The cost paradigm is deployment-dependent: self-hosted uses
-**database load** in database-seconds; Cloud uses **compute time** in
-compute-seconds with compute-unit-hours alongside. Read-only against data,
-enforced in depth.
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime and never prompts for or persists a
-password. Discovery order:
-
-1. `CLICKHOUSE_URL` (or `CLICKHOUSE_DSN`), the connection URL most stacks
- already export
-2. the `CLICKHOUSE_*` environment (`CLICKHOUSE_HOST`, `_PORT`, `_USER`,
- `_PASSWORD`, `_DATABASE`, `_SECURE`)
-3. the committed non-secret `clickhouse.host`/`port`/`database`/`user` config
- target, with the password still supplied by `CLICKHOUSE_PASSWORD`
-4. the `host` of a `type: clickhouse` target in a discovered dbt `profiles.yml`,
- with `{{ env_var(...) }}` references expanded
-
-There is no `pg_service.conf` analogue to pin, which is why this chain is one
-shorter than the Postgres one.
-
-Only a coarse method (for example `environment:dsn` or `config_target:password`)
-is ever surfaced. DSNs, identities, and passwords never cross the envelope; the
-sanitizer additionally strips `user:pass@host` URL fragments. Every discovery
-failure names all the fixes.
-
-**Splitting dex's identity from dbt's.** dex reads and dbt writes, and they are
-usually different users. The shape that keeps them apart is `CLICKHOUSE_URL` for
-dex (carrying the read-only user) and `CLICKHOUSE_PASSWORD` for dbt (which is
-what the rendered profile's `env_var` reference resolves at dbt runtime). This
-mirrors Postgres's `DATABASE_URL` plus `PGPASSWORD`.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: clickhouse
-clickhouse:
- host: clickhouse.internal
- port: 8123
- database: app # the database bare table references resolve in
- user: dex_ro
- databases: # source allowlist; empty means all visible
- - app
- dev_database: dbt_dev # where dbt dev builds write (never a source)
- deployment: self_hosted # `cloud` selects compute-time guarding
- compute_unit_price_usd: null # Cloud only; actual regional/contract CU price
- max_full_profile_bytes: null # opt-in SAMPLE threshold; see Profiling
-budget:
- ceiling: 60 # per-command seconds; --budget overrides
- session_ceiling: 600 # cumulative seconds per UTC day
-```
-
-Point dex at a **read-only user** rather than `default`. The documented grant
-shape is SELECT on the source databases plus SELECT on `system.tables`,
-`system.columns` and `system.databases`, with write access only on the dedicated
-dev database for the dbt user. `scripts/clickhouse_seed.sql` is the shared,
-parameterized data fixture; `scripts/clickhouse_local_users.sql` shows the local
-`dex_ro` and `dbt_dev` grant shape.
-
-Granting `system.grants` and `system.role_grants` as well is optional and only
-affects the dev-target preflight: without them dex cannot read the dbt user's
-privileges and says so rather than guessing (see [dbt builds](#dbt-builds)).
-
-## Scoping a command
-
-A ClickHouse scope is a bare database, because there is no catalog above it to
-qualify with and a dotted entry would name a table:
-
-```
-dex --scope app explore inventory
-```
-
-`--scope` narrows the committed `clickhouse.databases` allowlist and can never
-widen it. Resolution is free (one `system.databases` read) and happens before
-anything is estimated, so a typo is refused for nothing with the databases that
-do exist listed.
-
-## Identifiers are two parts
-
-`app.customers`, not `something.app.customers`. ClickHouse has no catalog level,
-and dbt-clickhouse's `schema:` **is** the ClickHouse database (there is no
-`database:` key in its profile at all). dex keeps the engine's own shape rather
-than synthesizing a third component, so every identifier in the inventory, the
-cache, and every drift finding is one you can paste into `clickhouse-client`.
-
-## Cost model
-
-Self-hosted ClickHouse bills nothing, but a scan is real load on a server that is
-usually shared and usually serving something latency-sensitive. So the guarded
-quantity is **database-seconds**, gated through the same strict handshake as
-every metered connector.
-
-- **Free:** `connect test`, `explore inventory`, all schema and size facts
- (`system.tables` and `system.columns`, no scans), `EXPLAIN ESTIMATE`,
- `maintain schema`, `maintain volume`, every dev-target preflight, and
- `dbt compile`-based build pricing.
-- **Metered:** profiling, relationship verification, `explore query`,
- `explore cluster`, `maintain grain`, the cardinality half of
- `maintain semantic`, and `transform build`.
-
-Three things make this connector's lifecycle unusually good, and they are worth
-knowing because they are what the estimate quality label does *not* say.
-
-**The estimate is free and executes nothing.** `EXPLAIN ESTIMATE` reports the
-rows and marks a statement would read after primary-key and partition pruning,
-so a filtered probe on a huge table is not quoted as a full scan. It covers the
-MergeTree family only, so Log, Memory, Distributed and view relations fall back
-to `system.tables` sizes. The handshake payload carries `estimate_basis`
-(`explain_estimate`, `system_tables`, or `floor`) so you can tell which priced a
-given command. A statement answered entirely from part metadata (a bare
-`count()`) legitimately estimates nothing and takes the fallback.
-
-`estimate_quality` is **heuristic**, deliberately, even though the row count is
-exact: the number you confirm is seconds, and seconds come from a throughput
-constant. The exact part rides one field down rather than inflating the label.
-
-**The cap is layered, because time alone does not bind.**
-`max_execution_time` is checked at block boundaries and a single fast block can
-overshoot it, so every billed statement also carries `max_bytes_to_read`, derived
-by inverting the same throughput constant the estimate used. Both overflow modes
-are set to `throw` explicitly, so a server default of `break` could never turn a
-cap into a silently truncated result: a refusal is recoverable, a wrong answer is
-not.
-
-`max_result_rows` is deliberately **not** set. With `throw` it refuses the
-one-extra-row fetch that detects truncation, and with `break` it was measured not
-to bind at all; a setting that either breaks a legitimate query or does nothing is
-worse than no setting. The result is already bounded twice: the query firewall
-clamps `LIMIT` into the statement, and the adapter slices client-side.
-
-**Settlement is free and exact.** Every response carries the
-`X-ClickHouse-Summary` header, so elapsed nanoseconds, rows read and bytes read
-come back with the result. No second query, and no `system.query_log` poll (which
-flushes on a delay). The seconds in the ledger are what the *server* spent, not
-what the client waited, which is a genuine accuracy improvement over the other
-db-load connector.
-
-For self-hosted there is no currency translation, because nothing is billed in
-one. Rows and bytes actually read are reported as table notes rather than in the
-spend summary, so nothing there carries a magnitude in a unit the ceiling is not
-in.
-
-Cloud uses the same free estimates, caps, and exact statement-seconds
-settlement. Before any billed work, dex reads `CGroupMemoryTotal` from every
-replica through `clusterAllReplicas('default', system.asynchronous_metrics)` and
-cross-checks the number of answers against `system.clusters`. It derives:
-
-```
-compute_units_per_hour = total_memory_gib / 8
-compute_unit_hours = seconds * compute_units_per_hour / 3600
-```
-
-The capacity read is cached for one command and fails closed when it is denied,
-empty, malformed, partial, or inconsistent. A service resuming from idle answers
-on one replica before the others join, so an unproved read is retried for about
-15 seconds before the refusal, which then names the server's reason; a denied
-grant refuses at once. dex never substitutes a configured replica count, a
-guessed tier, or a public price. When
-`compute_unit_price_usd` is present, estimates and settled spend also carry a USD
-translation using that supplied rate.
-
-These fields are explicitly approximate, not an invoice. dex attributes the
-server-reported time of each statement at the capacity observed for that
-command; Cloud bills active capacity per minute and can include wake and idle
-time outside the statement.
-
-The dedicated AWS us-east-1 Scale test service is configured with the actual
-compute rate of \$0.29846 per 8-GiB compute unit-hour. Its \$25.30/TB-month storage
-rate is documented operational context only: storage persists independently of
-a statement, so dex does not mislabel it as query spend or fold it into the
-per-command confirmation.
-
-## Deployment
-
-`clickhouse.deployment` declares which ClickHouse this is, and it is a cost
-decision rather than a connection one:
-
-- `self_hosted` (default) bills no currency, so dex guards it in
- database-seconds.
-- `cloud` is guarded in compute-seconds. Live allocated memory translates the
- same binding seconds into approximate compute-unit-hours and, when configured,
- USD.
-
-`compute_unit_price_usd` is refused under `self_hosted`, where it would be
-accepted and ignored.
-
-Deployment is a **declaration, never a sniff**. At connect dex additionally
-checks the server's own `cloud_mode` setting in both directions and refuses when
-the declaration does not match reality. A declared Cloud endpoint proceeds only
-after that corroboration and the live capacity proof.
-
-For Cloud, `connect test` adds `compute.replica_count`, `total_memory_gib`,
-`compute_units_per_hour`, the metadata source, and `approximate: true`. Its
-budget adds `ceiling_compute_unit_hours`; confirmation adds
-`estimated_compute_unit_hours`, `compute_unit_rate`, and optionally
-`estimated_usd`; settlement adds `compute_unit_hours_billed` and optionally
-`usd_billed`. The binding ceiling and ledger remain seconds.
-
-## Read-only, enforced in depth
-
-- `readonly = 2` and `allow_ddl = 0` sent as settings on **every statement**,
- free or billed, so a host that supplies its own client cannot lose them.
- `2` rather than `1` because `1` also forbids changing settings, which would
- block dex from sending its own per-statement caps.
-- SELECT-only generation through one execution door, with SQLGlot-parsed refusal
- of DDL, DML, `OPTIMIZE`, multi-statement, and scripting in the ClickHouse
- dialect.
-- An adapter that issues no mutating statement of any kind.
-- A documented least-privilege user (SELECT only on the source databases).
-
-**The honest limit.** `readonly = 2` by definition permits a session to change
-its own settings, so dex's cap is self-imposed exactly as Postgres's
-`SET statement_timeout` is. The unraisable form is a server-side settings
-constraint on the dex user:
-
-```xml
-
- 300
-
-```
-
-`readonly = 2` also permits `CREATE TEMPORARY TABLE`. That is session-local and
-cannot touch source data, the SELECT-only guard refuses it as DDL anyway, and a
-least-privilege user has no grant for it.
-
-`connect test` reports `session_read_only` from the server's own `readonly`
-setting rather than assuming it.
-
-## Profiling behavior
-
-- Nullability comes from the **type**, not a column flag: ClickHouse has no
- `is_nullable`, so `Nullable(...)` and `LowCardinality(...)` are unwrapped in
- either nesting order before any type reasoning happens.
-- **That has a consequence for drift.** Because nullability is part of the type
- string, a column that starts or stops accepting nulls is reported by
- `maintain schema` as `column_retyped` rather than `nullability_changed`, and
- `maintain reconcile` answers a retype with advice rather than an edit on every
- connector. So a nullability change here is surfaced with both type spellings
- named and the declaration is yours to update, where the same warehouse change on
- BigQuery or Snowflake would arrive as a proposed edit.
-- Distinct counts come from `uniq` (a HyperLogLog sketch) in the same pass as the
- null counts, and are never a uniqueness verdict on their own. Near-unique
- columns escalate to an exact `uniqExact` inside the confirmed budget.
-- `Array`, `Map`, `Tuple`, `Nested`, `JSON` and the geo types degrade to a
- non-null count: distinct counts and extremes are not meaningful on them.
-- **`ORDER BY` is a sort key, not a uniqueness constraint.**
- `system.columns.is_in_primary_key` is free and raises the prior on a candidate
- key, but it never declares one. ClickHouse has no foreign keys at all, so every
- relationship dex reports here is name-and-shape inference.
-- Tables on `ReplacingMergeTree`, `CollapsingMergeTree` and friends carry a note
- saying so, because rows sharing the sorting key are kept until a background
- merge collapses them: a duplicate count there describes the stored parts rather
- than the modeled grain, and querying with `FINAL` shows the collapsed view.
-- `max_full_profile_bytes` is honored only where the table declared a sampling
- expression in its MergeTree key, which most do not. Where it cannot be honored
- it is **refused out loud** with a note, rather than silently producing a full
- scan you believed was sampled, or an `ORDER BY rand()` that reads everything
- and then sorts it.
-- `explore cluster` samples with `ORDER BY rand() LIMIT n` for the same reason,
- and the note says so: it is a full scan bounded by the budget.
-
-## dbt builds
-
-The dbt adapter is `dbt-clickhouse`, which ships with the `[clickhouse]` extra.
-Its `schema:` is the ClickHouse database and it has no `database:` key, so
-`transform init` renders `schema: ` and nothing else.
-
-**The dev-target preflight asks a privilege question, not an existence one.**
-dbt-clickhouse issues `CREATE DATABASE IF NOT EXISTS` in its own `create_schema`
-macro, so a missing dev database is not fatal; the privilege to create it is.
-This lands with Postgres rather than with Snowflake and Databricks, where the
-missing object is the whole problem.
-
-Where it differs from Postgres is what happens when the answer is unknown.
-Postgres will answer a privilege question about any role; ClickHouse shows
-another user's grants only to a caller holding the right access. So the preflight
-has three outcomes rather than two:
-
-| What dex could read | What it does |
-|---|---|
-| nothing | says so, and does not preflight grants |
-| direct grants, but not role membership | may **clear** a target, never refuses one, since a privilege held through an invisible role looks identical to a missing one |
-| grants and role membership | may clear or refuse |
-
-A refusal names the statement that fixes it:
-
-```
-GRANT CREATE DATABASE, CREATE TABLE, INSERT, SELECT ON dbt_dev.* TO dbt_dev;
-```
-
-**The build cap rides the profile.** `transform init` renders a `custom_settings`
-block whose values are `env_var` references, and `transform build` sets those
-variables to the confirmed budget, so the ceiling becomes a per-statement
-server-side cap:
-
-```yaml
-custom_settings:
- max_execution_time: "{{ env_var('DEX_CLICKHOUSE_MAX_EXECUTION_TIME', '300') }}"
- timeout_overflow_mode: throw
- max_bytes_to_read: "{{ env_var('DEX_CLICKHOUSE_MAX_BYTES_TO_READ', '100000000000') }}"
- read_overflow_mode: throw
-```
-
-The literal defaults are real caps rather than `0`, because in ClickHouse `0`
-means *no limit*: a zero default would render a profile that silently removes the
-backstop the moment anyone runs dbt by hand.
-
-A hand-written profile without those references is perfectly valid and builds
-fine; what it cannot do is be capped. dex **warns** in that case rather than
-refusing, and the build result says the run was uncapped rather than claiming a
-cap it never injected.
-
-`transform build --verify` costs only where the warehouse keeps no row count, so a
-table's count is free `system.tables` metadata; how the counts are priced into the
-build's own estimate is in [`cost-controls.md`](/dex/guardrails/cost-controls).
-
-`transform test --mutate` prices its whole batch as one number and confirms it
-once, then runs one dbt invocation per mutant. Nothing is materialized: a mutant
-builds as an ephemeral model, so the dev namespace holds exactly the relations it
-held before. A budget that runs out partway stops the run, and the remaining
-mutants are reported `not_run` rather than the budget being exceeded. Survivors
-are not yet compared with the model on the dev data on this connector, so each
-reports `equivalence.status: not_checked` with the reason, and nothing is
-priced or run for it.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-
-
-`--verify` also reads `clickhouse.dev_database` for the length of that one
-command, because dbt writes the relations it is judging there and that database
-is refused as a source everywhere else. The database need not exist yet:
-dbt-clickhouse creates it on a first build, and dex lists it after dbt has run.
-How that read is bounded is under **Read scope** in
-[`command-contract.md`](/dex/reference/command-contract).
-
-The shipped `unpivot_json_object` macro has a ClickHouse implementation built on
-`ARRAY JOIN` over `JSONExtractKeysAndValuesRaw`, since ClickHouse has no lateral
-join. It is top-level-only and keeps each value as raw JSON text, matching the
-other adapters.
-
-## Semantic layer
-
-`explore semantic query --local` does not work on ClickHouse: MetricFlow ships no
-ClickHouse renderer. This is declared as an inert capability with a named refusal
-listing the connectors that do work, rather than degrading to another dialect's
-renderer, which would produce SQL that runs and returns wrong numbers.
-
-A native Apache Ossie layer behaves differently here than on a three-part
-connector, and both differences are worth knowing before writing a document
-against ClickHouse. Ossie's dialect enum has no ClickHouse token, so expressions
-are read in the portable `ANSI_SQL` dialect rather than in something close, which
-is the correct answer and not a fallback to guess about. And a dataset source
-links to a relation only when this connector accepts the whole source as one
-identifier, which here means two parts (`database.table`) rather than three: a
-document written as `database.schema.table` reads cleanly and links to nothing on
-ClickHouse while linking on DuckDB. See
-[Apache Ossie compatibility](/dex/semantic-layers/ossie).
-
-## Statement refusals
-
-A server-side statement error raises `WarehouseQueryError`, with the server's
-numeric error code when available and `stage: run` for the query execution door.
-The diagnostic is limited to the first non-empty line and capped, as on the other
-connectors. `maintain verify` can therefore report a refused grain measurement
-against its model and continue checking the others. In values-free mode the
-server's message is withheld and the envelope reports `warehouse_refused`.
-
-The existing named errors for missing tables, insufficient grants, unreachable
-servers, timeouts and budget/read limits keep their behavior. An unexpected
-client-side programming error is not classified as a server refusal.
-
-## Testing
-
-Offline, deterministic, and free: `tests/fakes/clickhouse.py` is a stateful fake
-of the client surface, driving `tests/adapters/test_connect_clickhouse.py` and
-the ClickHouse block of the safety spine.
-
-The live suite runs against a container you start yourself, so there is nothing
-to provision and nothing to spend. The same script CI runs stands it up locally:
-
-```bash
-scripts/setup_clickhouse_dev.sh
-DEX_TEST_CH_DSN=clickhouse://dex_ro:dex_ro@127.0.0.1:8124/app \
- DEX_TEST_CH_DEV_PASSWORD=dbt_dev \
- uv run pytest tests/integration -q -m clickhouse
-scripts/setup_clickhouse_dev.sh --down
-```
-
-The narrow Cloud suite is repository-gated and serialized with the other live
-cloud jobs. Its protected `clickhouse-cloud-integration` environment is created
-by `scripts/setup_clickhouse_cloud_ci.sh`. Before opening SQL, both CI and the
-local runner call the same read-only usage preflight; it refuses once the exact
-service reaches 2 compute CHC in the current UTC day. The post-run report marks
-unlocked usage records provisional because Cloud metering can lag.
-
-Setup, rotation, local execution, troubleshooting, and bounded teardown are in
-`scripts/clickhouse_cloud/README.md`. To run locally, with the protected
-non-secret values and the two database credentials in the environment and the
-scoped API key's two files in `DEX_SECRETS_DIR` (the README shows how to write
-them; the key is never read from the environment):
-
-```bash
-scripts/clickhouse_cloud/run_integration.sh
-```
-
-The seed is deliberately flawed in ways that make two silent hazards observable:
-40 of 5,000 `order_items` rows point at products that do not exist (so an orphan
-probe that reports zero has lost `join_use_nulls`), and `events.occurred_at` has
-exactly three consecutive days missing from a 90-day span (so a continuity check
-that reports no gap has the window function wrong).
-
-Source: [`references/clickhouse.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/clickhouse.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/clickhouse.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/databricks.mdx b/dex/connectors/databricks.mdx
deleted file mode 100644
index 4c26fbc..0000000
--- a/dex/connectors/databricks.mdx
+++ /dev/null
@@ -1,184 +0,0 @@
----
-title: Databricks connector
-sidebarTitle: Databricks
-description: 'Connect dex to Databricks SQL warehouses over Unity Catalog: unified SDK auth, warehouse-seconds pricing with DBUs alongside, and read-only enforcement.'
-og:title: Databricks connector · Exmergo Dex
-twitter:title: Databricks connector · Exmergo Dex
----
-
-The lakehouse connector, compute-time billed over Unity Catalog. Namespace:
-`catalog.schema.table` (three-level). Cost paradigm: **warehouse-seconds**
-(DBUs shown alongside). Read-only against data, enforced in depth.
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime through the Databricks SDK's
-unified auth chain and never prompts for or persists a token. Discovery order:
-
-1. `databricks.profile` in `.dex/config.yml`, naming a `~/.databrickscfg`
- entry (the store `databricks auth login` writes)
-2. `DATABRICKS_*` environment variables (`DATABRICKS_HOST` plus a credential:
- `DATABRICKS_TOKEN`, OAuth M2M client variables, or the GitHub OIDC
- federation CI exchanges into a token)
-3. the default `~/.databrickscfg` profile (a `[DEFAULT]` section, or the
- newer CLI's `default_profile` pointer)
-4. the `host` of a `type: databricks` target in a discovered dbt
- `profiles.yml`
-
-The CLI's OAuth cache, PATs, OAuth M2M, and workload identity federation all
-arrive through the same SDK door; only the coarse method (for example
-`default_profile:oauth_user`) is ever surfaced. Identities and token values
-never cross the envelope. Every discovery failure names the fix.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: databricks
-databricks:
- profile: null # a ~/.databrickscfg entry; optional
- warehouse: abc123def456 # REQUIRED for anything billed; ID or http_path
- catalogs: # source allowlist; empty means all visible
- - samples.tpch # catalog or catalog.schema entries
- dev_catalog: dex_ci # where dbt dev builds write (never a source)
- dev_schema: dbt_dev # default dbt_dev
- max_full_profile_bytes: null # opt-in TABLESAMPLE threshold for huge tables
- dbu_price_usd: null # your contract price; set it to see dollars
-budget:
- ceiling: 300 # per-command warehouse-seconds; --budget overrides
- session_ceiling: 3600 # cumulative seconds per UTC day
-```
-
-**The warehouse pin is strict.** Billed statements run only on
-`databricks.warehouse` (a SQL warehouse ID or its
-`/sql/1.0/warehouses/...` HTTP path); an unpinned or unresolvable warehouse
-refuses with the fix named. Pin the smallest warehouse that works (a 2X-Small
-serverless with the minimum auto-stop is the intended shape;
-`scripts/setup_databricks_ci.sh` provisions exactly that).
-
-`transform init` content-checks every schema the new project would build into
-through Unity Catalog REST only, so the pinned warehouse is never woken: the
-base `dev_catalog.dev_schema`, plus the sibling layer schemas (`staging_dev`,
-`intermediate_dev`, `marts_dev` on the `dev` target) when `--layered-schemas`
-is on. A schema that already holds tables or views is warned about, never
-refused.
-
-## Cost model: two clients, one guarded quantity
-
-Metadata is free and scans cost warehouse runtime, so dex guards
-**warehouse-seconds**, not bytes, and splits its clients to keep the free
-paths provably free:
-
-- **Free (SDK REST, no SQL session):** `connect test`, `explore inventory`,
- all catalog/schema/table/column metadata, warehouse facts, estimation, and
- `maintain check` (drift detection reads metadata only). The SQL session is
- opened lazily by the first billed statement, because opening one lands on
- the warehouse and can wake it; free commands leave a STOPPED warehouse
- stopped.
-- **Billed (SQL session on the pinned warehouse):** profiling aggregates,
- `explore query`, relationship verification probes, DESCRIBE DETAIL size
- probes, and `transform build`.
-
-`explore query` and `explore cluster` bill an auto-profile of an object this connection has that the `.dex/` cache cannot adjudicate, priced into the same handshake as the statements: see [`cost-controls.md`](/dex/guardrails/cost-controls). Pass `--no-auto-profile` (or set `auto_profile: false` in `.dex/config.yml`) to be refused instead.
-
-Budgets (`budget.ceiling`, `--budget`, `budget.session_ceiling`) are
-warehouse-seconds: the number you budget is the number the server enforces.
-Every cost surface also carries the translation to **DBUs**
-(`seconds x dbu_per_hour / 3600`, rate from the warehouse size, marked
-approximate: published rates move and differ by type and cloud), and to
-dollars when `databricks.dbu_price_usd` is set. dex never guesses a dollar
-price: it varies by cloud, tier, and contract.
-
-**Estimates start as an honest floor and refine in-budget.** Databricks has
-no dry-run and Unity Catalog exposes no free row or byte counts, so the first
-handshake quotes a conservative per-statement floor, labeled
-`estimate_quality: "low"`, plus a startup floor when the pinned warehouse is
-not running (seconds for serverless, minutes for classic). Once you confirm a
-budget, the adapter runs an engine-built `DESCRIBE DETAIL` per table, charged
-inside the confirmed budget, never before it, to learn `sizeInBytes`: that
-sharpens later estimates, drives the sampling decision, and is noted per
-table when unavailable (some shared tables refuse it). The same estimator
-prices `transform build`: each compiled model, snapshot, and test is estimated
-and summed into the build's upfront cost, labeled `estimate_quality: "low"`
-like any other Databricks estimate.
-
-`transform build --verify` costs only where the warehouse keeps no row
-count, so a table's count is free metadata; how the counts are priced into
-the build's own estimate is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-`transform test --mutate` prices its whole batch as one number and confirms it
-once, then runs one dbt invocation per mutant. Nothing is materialized: a mutant
-builds as an ephemeral model, so the dev namespace holds exactly the relations it
-held before. A budget that runs out partway stops the run, and the remaining
-mutants are reported `not_run` rather than the budget being exceeded. Survivors
-are not yet compared with the model on the dev data on this connector, so each
-reports `equivalence.status: not_checked` with the reason, and nothing is
-priced or run for it.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-
-
-`--verify` also reads the dev schema (`databricks.dev_catalog` /
-`databricks.dev_schema`) for the length of that one command, because dbt writes
-the relations it is judging there and that schema is refused as a source
-everywhere else. The schema need not exist yet: dbt creates it on a first
-build, and dex lists it after dbt has run. How that read is bounded is under
-**Read scope** in [`command-contract.md`](/dex/reference/command-contract).
-
-
-**The budget is hard-enforced regardless of estimate quality.** Before every
-billed statement the session's `STATEMENT_TIMEOUT` is set to the remaining
-budget, so a weak floor cannot overrun the ceiling: Databricks kills the
-statement and dex reports the over-ceiling refusal. Actual spend is
-wall-clock seconds per statement (including any wake the statement caused),
-recorded as `billed_seconds` in the ledger. Connections identify themselves with a `dex` user-agent for
-attribution.
-
-The estimate carries its DBU translation; the handshake itself is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-## Read-only, enforced in depth
-
-- Every data statement passes the SELECT-only guard parsed in the databricks
- dialect through one execution door (DML, DDL, `MERGE`, `COPY INTO`,
- `OPTIMIZE`, `VACUUM`, and multi-statement forms all refuse).
-- The adapter issues no mutating calls: Unity Catalog REST reads, `SET
- STATEMENT_TIMEOUT`, `DESCRIBE DETAIL`, and guarded SELECTs only.
-- The documented grant shape is least-privilege: `CAN USE` on the pinned
- warehouse, `USE CATALOG` + `USE SCHEMA` + `SELECT` on source catalogs, and
- write only on the dedicated dev catalog
- (`scripts/setup_databricks_ci.sh` creates this shape).
-- dbt dev builds write to `dev_catalog.dev_schema`, which is refused as a
- source, and the generated profile pins the warehouse's HTTP path and one
- thread. A user OAuth connection renders dbt's own OAuth flow; a token
- connection renders a `DATABRICKS_TOKEN` env reference, never a value.
-
-## Profiling behavior
-
-Profiling is batched aggregates (COUNT, APPROX_COUNT_DISTINCT, min/max only
-for engine-cleared safe columns), never row values. Nested and
-semi-structured columns (ARRAY, MAP, STRUCT, VARIANT, BINARY, GEOGRAPHY,
-GEOMETRY) degrade to non-null counts. Tables above
-`databricks.max_full_profile_bytes` are profiled from a sample
-(`TABLESAMPLE`), noted, with uniqueness not judged; the threshold binds once
-DESCRIBE DETAIL has learned a size. Exact distinct-count escalation spends
-only inside the confirmed budget and degrades to approximate verdicts with a
-note when the remainder cannot cover it.
-
-## Testing
-
-Offline: a stateful fake pair (`tests/fakes/databricks.py`): a Unity Catalog
-workspace client serving metadata and a DBAPI connection that records
-statement ordering, simulates timing on an injected clock, and enforces
-STATEMENT_TIMEOUT with the connector's real error types, behind a counting
-factory that proves free paths never open a SQL session. Live: an env-gated
-integration suite (`DEX_TEST_DATABRICKS_*`) reading the samples catalog and
-writing only to the scratch catalog, run in CI on a schedule via an OIDC
-federation policy (no stored keys), never as a merge or release gate.
-
-Source: [`references/databricks.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/databricks.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/databricks.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/duckdb.mdx b/dex/connectors/duckdb.mdx
deleted file mode 100644
index 56bde0f..0000000
--- a/dex/connectors/duckdb.mdx
+++ /dev/null
@@ -1,171 +0,0 @@
----
-title: DuckDB connector
-sidebarTitle: DuckDB
-description: 'Run dex on DuckDB with no credentials: the zero-setup on-ramp, the demo warehouse, the dev and CI engine, and the read-only, resource-bounded defaults.'
-og:title: DuckDB connector · Exmergo Dex
-twitter:title: DuckDB connector · Exmergo Dex
----
-
-DuckDB is a first-class product connector and, at the same time, the engine behind
-dex's evals and benchmarks. One adapter, three uses: the zero-credential
-on-ramp, the dev and CI engine, and the eval and benchmark engine. `dex demo`
-supplies the on-ramp's content, so that first use needs no warehouse of your own.
-
-## Auth and target
-
-No credentials. The target is a local DuckDB file (or a directory of Parquet/CSV).
-Set it in `.dex/config.yml`:
-
-```yaml
-connector: duckdb
-duckdb:
- path: ./warehouse.duckdb
-```
-
-or pass `--path ./warehouse.duckdb` on any command.
-
-A relative `path:` in `.dex/config.yml` resolves against the project root the
-config lives in, not the shell cwd, so the same file opens whether you run from the
-project root or a subdirectory (config is found by walking up to the git root). A
-live `--path` is typed in your shell, so it stays relative to the current directory.
-
-## Read-only and resource bounds
-
-DuckDB is always opened **read-only** (`read_only=True`). A read-only open of a
-nonexistent file fails by design: the adapter attaches to an existing analytical
-store, it never creates one, and there is no writable fallback to relax. Because the
-work is free and local, there is no cost ceiling, only resource bounds: a memory
-limit and a thread cap (defaults: 2GB, 4 threads), overridable from config. The
-adapter (`adapters/duckdb.py`) owns all of this.
-
-`dex demo` is the one place a DuckDB file is created, and it is deliberately not the
-adapter (see the next section).
-
-## The demo warehouse
-
-```bash
-dex demo # -> ./dex_demo.duckdb and ./.dex/config.yml
-dex explore map # no flags: the config demo wrote points at the file it made
-```
-
-`dex demo` generates a small e-commerce warehouse locally: 7 tables and 29,512 rows
-(`customers` 1,200, `products` 300, `orders` 5,000, `order_items` 14,000,
-`web_events` 9,000, `warehouse_locations` 12, and `returns`, which an interrupted
-load left empty). No credentials, no cloud account, no network. The path is
-positional and resolves against `--repo-root`, which defaults to the working
-directory, so `dex --repo-root R demo` writes both files into `R` and the commands
-it prints carry the same `--repo-root`. `--path` is refused there, because
-everywhere else it names the warehouse dex reads.
-
-**Generated, not committed.** DuckDB's storage format has broken backward
-compatibility across releases before, so a committed file could stop opening for a
-user on a newer duckdb, and that failure would land on the first command a stranger
-ever runs. A generator builds against whatever duckdb resolved and cannot rot; it
-also weighs a few KB in the wheel rather than a binary that does not
-delta-compress.
-
-**Deterministic.** One pinned seed, a random stream restricted to primitives that
-are stable across CPython releases, and no wall-clock anywhere: every date is
-measured back from a fixed anchor. A test pins a sha256 over every generated cell,
-so a change that would silently move a count quoted in the READMEs fails CI instead.
-
-**Create-only, and off the connector path.** The generator writes a new file and
-refuses rather than replace one, with no `--confirm` that can talk past that, and it
-never creates a parent directory; it will not write a `.dex/config.yml` where a
-project at or above the target already has one, so it cannot shadow a real config
-with its own. It lives in `demo/warehouse.py`, imports `duckdb` directly, and
-reaches neither the adapter nor the SQL guard, so the read-only rule above keeps no
-branch that could be relaxed. The safety spine asserts that mechanically: one test
-scans the package for every `duckdb.connect(` and requires `read_only=True`
-everywhere except the generator, another opens a freshly generated file through the
-adapter and confirms a write is still refused.
-
-**Seeded to be realistically broken**, because a first run that reports a clean bill
-of health teaches nothing. `order_item_id` lost its uniqueness to a double-loaded
-batch; `sku` mixes numeric and md5-shaped ids from a merged catalogue;
-`web_events.customer_id` shares the CRM's column name and none of its values, so
-`--verify` collapses the inferred join at 100% orphans; `orders.placed_at` is a
-VARCHAR holding timestamps and `web_events.occurred_at` a BIGINT holding epoch
-milliseconds; `customers.email` and `full_name` are personal data, while
-`warehouse_locations.city` and its coordinates are PII false positives on a
-building, and `site_name` is de-rated below the block threshold by its own values.
-
-`generate_demo_warehouse` is exported from the package, so the Python API and
-`examples/quickstart.py` build the same fixture.
-
-## Exact distinct counts
-
-Profiling reads distinct counts approximately (`approx_count_distinct`) for scale,
-but the adapter also exposes `exact_distinct_counts(identifier, columns)`: one
-batched, read-only `COUNT(DISTINCT ...)` that the engine calls to escalate the few
-columns sitting near unique, so a real key is never lost to approximation error.
-The escalation policy lives in the engine, not the adapter; the adapter only
-answers the exact query it is asked for (an empty column list runs nothing).
-
-## Dev-target seeding convention
-
-`transform build` runs against the `dev` target with cwd pinned to the project dir,
-so a relative `path:` in `profiles.yml` resolves to a database inside the project,
-never a stray file at the caller's shell cwd. If that dev DuckDB file does not yet
-exist and the project reads from `sources`, build refuses with an actionable
-message rather than letting dbt create an empty database: seed the dev target first
-(copy the shared source warehouse, or point the dev `path:` at an existing file). A
-source-less project is allowed to create its dev database on first build, with a
-warning.
-
-`transform build --verify` is free here. A relation whose row count the catalog
-does not keep gets a real `COUNT(*)` instead of an estimate, because counting
-bills nothing and a verdict about a ten percent difference has no business
-resting on a catalog figure, so every finding comes back `exact: true`. That
-matters more than it sounds: dbt-duckdb materializes as a view by default and
-DuckDB keeps no row count for a view, so a sweep that trusted metadata alone
-would judge nothing in a default project. There is no dev-namespace fold to make
-either, since the dev target is a database file and the dev-target preflight
-already refuses a build whose profile and config disagree about which one.
-
-`transform test --mutate` is free here too, and it is the connector to learn the
-command on: every mutant is a full dbt run, so twenty of them against a local
-file cost nothing but a few seconds, and no handshake stands between the caller
-and the answer. Nothing is materialized either way, because a mutant builds as
-an ephemeral model, so the dev database holds exactly the relations it held
-before.
-
-Each survivor is also compared with the unmutated model on the dev data, free
-and unasked here: one aggregate `dbt show` per survivor, plus one self-check of
-the unmutated model against itself, labels it `equivalent` or
-`distinguishable`. `--no-check-equivalence` turns that off.
-
-The tests of the models downstream of the mutated one run against each mutant
-too, unasked here because it is free: each downstream model is made ephemeral in
-the same copy, so dbt inlines the chain, mutant at the bottom, into each of its
-tests. A defect only those tests caught is `caught_downstream`, and `score`
-still counts it as a miss for the model's own suite. `--no-downstream` turns
-that off.
-
-
-
-The dev target being the source file is also why `transform init`'s content
-preflight skips DuckDB's base namespace: "the file already holds objects" is
-true of every working setup, so warning on it would only teach users to skim.
-With `--layered-schemas` the layer schemas inside the file (`staging_dev`,
-`intermediate_dev`, `marts_dev` on the `dev` target) are genuinely dbt-owned,
-and those are checked and warned about when populated.
-
-## Capabilities probe
-
-```bash
-uv run python -m exmergo_dex_core --path ./warehouse.duckdb connect test
-```
-
-returns an envelope whose `data` reports `connector`, `dialect`, `read_only:
-true`, `paradigm: free_local`, the engine version, and the resource bounds.
-
-## Why it anchors v0.1
-
-The full Explore, Transform, Maintain loop is built and proven on DuckDB first, with
-no cloud accounts, fully deterministic in CI. The cloud connectors and their cost
-paradigms layer onto the proven loop at v0.2. It also matches ADE-bench's
-DuckDB mode and Spider2.0-DBT's dbt engine, so the test engine and the benchmark
-engine are the same engine.
-
-Source: [`references/duckdb.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/duckdb.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/duckdb.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/postgres.mdx b/dex/connectors/postgres.mdx
deleted file mode 100644
index 7d6f7b2..0000000
--- a/dex/connectors/postgres.mdx
+++ /dev/null
@@ -1,258 +0,0 @@
----
-title: PostgreSQL connector
-sidebarTitle: PostgreSQL
-description: 'Connect dex to PostgreSQL: credential discovery from pg_service.conf or the environment, database-seconds cost gating, and per-statement timeouts.'
-og:title: PostgreSQL connector · Exmergo Dex
-twitter:title: PostgreSQL connector · Exmergo Dex
----
-
-The operational database AEs pull from. Namespace: `database.schema.table`
-(one connection, one database; the first component is always the connected
-database). Cost paradigm: **database load**, expressed as database-seconds.
-Read-only against data, enforced in depth.
-
-## Managed Postgres platforms
-
-Use the same `postgres` connector with these platforms' PostgreSQL services:
-
-- [Supabase](https://supabase.com/docs/guides/database/connecting-to-postgres)
-- [Neon](https://neon.com/docs/connect/connect-from-any-app)
-- [PlanetScale Postgres](https://planetscale.com/docs/postgres/connecting)
-- [Amazon RDS for PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_PostgreSQL.html)
-- [Amazon Aurora PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Aurora.AuroraPostgreSQL.html)
-- [Google Cloud SQL for PostgreSQL](https://docs.cloud.google.com/sql/docs/postgres/introduction)
-- [Google AlloyDB for PostgreSQL](https://docs.cloud.google.com/alloydb/docs/overview)
-- [Azure Database for PostgreSQL](https://learn.microsoft.com/en-us/azure/postgresql/overview)
-- [Render Postgres](https://render.com/docs/postgresql-creating-connecting)
-- [Railway PostgreSQL](https://docs.railway.com/databases/postgresql)
-- [Heroku Postgres](https://devcenter.heroku.com/articles/connecting-heroku-postgres)
-- [DigitalOcean Managed PostgreSQL](https://docs.digitalocean.com/products/databases/postgresql/how-to/connect/)
-- [Aiven for PostgreSQL](https://aiven.io/docs/products/postgresql/howto/list-code-samples)
-
-Set `connector: postgres` and supply the service's PostgreSQL connection details
-through the credential sources under Authentication below, such as
-`DATABASE_URL`. The endpoint must be reachable from the machine running Dex;
-keep the provider's required TLS settings in the connection details. Use a direct
-connection or a session pool that preserves session settings across statements,
-since Dex sets read-only mode and statement timeouts on the connection.
-
-The service names above refer to their PostgreSQL offerings. PlanetScale's
-Vitess offering, for example, uses MySQL. A PostgreSQL-compatible protocol alone
-does not establish compatibility with the catalogs, statistics, and session
-settings Dex uses. The [integration suite](#testing) exercises PostgreSQL; the
-list above describes hosted services using that connection path.
-
-Hosted services can charge for compute, storage, and other resources. Dex's
-database-seconds budget controls query load; it does not estimate the provider's
-hosting bill.
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime and never prompts for or
-persists a password. Discovery order:
-
-1. `postgres.service` in `.dex/config.yml`, naming a `pg_service.conf` entry
- (`PGSERVICEFILE`, else `~/.pg_service.conf`)
-2. `DATABASE_URL` (the twelve-factor URL most app stacks already export)
-3. the `PG*` environment (`PGHOST`/`PGDATABASE`/`PGSERVICE` and friends),
- resolved natively by libpq, including `~/.pgpass`
-4. the committed non-secret `postgres.host`/`port`/`dbname`/`user` config
- target (password still supplied by `PGPASSWORD` or `~/.pgpass`)
-5. the `host` of a `type: postgres` target in a discovered dbt `profiles.yml`
-
-Only a coarse method (for example `database_url:password` or
-`environment:external`) is ever surfaced; the credential kind is `password`
-when one is inline and `external` for everything else (`.pgpass`, peer or
-trust auth, SSL client certificates), deliberately coarse. DSNs, identities,
-and passwords never cross the envelope (the sanitizer additionally strips
-`user:pass@host` URL fragments). Every discovery failure names all the fixes.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: postgres
-postgres:
- service: analytics # a pg_service.conf entry; optional
- schemas: # source allowlist; empty means all visible
- - app
- dev_schema: dbt_dev # where dbt dev builds write (never a source)
- max_full_profile_bytes: null # opt-in TABLESAMPLE threshold for huge tables
-budget:
- ceiling: 60 # per-command database-seconds; --budget overrides
- session_ceiling: 600 # cumulative seconds per UTC day
-```
-
-Point dex at a **read-only role** (or better, a read replica) rather than a
-superuser on the primary; the documented grant shape is USAGE on source
-schemas plus SELECT on their tables, with write access only on the dedicated
-dev schema for the dbt role. `scripts/postgres_seed.sql` shows the shape
-(`dex_ro` and `dbt_dev` roles).
-
-## Cost model: load, not dollars
-
-Postgres bills nothing, but dex is usually pointed at a production OLTP
-primary, and an unbounded scan there is a real cost: it evicts cache, holds
-back vacuum, and steals cycles from the application. So the guarded quantity
-is **database-seconds**, gated through the same strict handshake as every
-metered connector.
-
-- **Free:** `connect test`, `explore inventory`, all schema facts
- (`pg_catalog` lookups, no table scans), `pg_stats` reads, `EXPLAIN`
- estimation, and the free axes of `maintain check` (schema and volume read
- catalog metadata only).
-- **Metered:** profiling aggregates, `explore query`, relationship
- verification probes, distinct-count escalations, and `transform build`.
-
-`explore query` and `explore cluster` bill an auto-profile of an object this connection has that the `.dex/` cache cannot adjudicate, priced into the same handshake as the statements: see [`cost-controls.md`](/dex/guardrails/cost-controls). Pass `--no-auto-profile` (or set `auto_profile: false` in `.dex/config.yml`) to be refused instead.
-
-Budgets (`budget.ceiling`, `--budget`, `budget.session_ceiling`) are
-database-seconds: the number you budget is the number the server enforces.
-
-**Estimates are a heuristic, honestly labeled.** Query estimates come from
-the genuinely free planner preflight (`EXPLAIN (FORMAT JSON)`), so an
-index-served lookup is not quoted as a full scan; plan cost translates to
-seconds through a deliberately conservative scan rate, and profile estimates
-come from relation sizes over the same rate. Every handshake payload carries
-`estimate_quality: "heuristic"`.
-
-**The budget is hard-enforced regardless of estimate quality.** Before every
-metered statement the session's `statement_timeout` is set to the remaining
-budget, so a wrong heuristic cannot overrun the ceiling: Postgres kills the
-statement and dex reports the over-ceiling refusal. Actual spend is
-wall-clock seconds per statement (a killed statement still bills what ran),
-recorded as `billed_seconds` in the ledger. Every session connects as `application_name = 'dex'` for
-attribution in `pg_stat_activity`.
-
-Budgets here are database-seconds; the handshake itself is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-## Read-only, enforced in depth
-
-- The session sets `default_transaction_read_only = on` before any statement,
- so the server itself refuses writes (SQLSTATE 25006) even if every other
- guard were bypassed. Connections are autocommit, so no idle-in-transaction
- session ever holds back vacuum on the primary.
-- Every data statement passes the SELECT-only guard parsed in the postgres
- dialect through one execution door (DML, DDL, `COPY`, and multi-statement
- forms all refuse).
-- The adapter issues no mutating statements: catalog SELECTs, `EXPLAIN`, and
- session `SET`s only.
-- The documented grant shape is a least-privilege read-only role; dbt dev
- builds write to `dev_schema` (default `dbt_dev`), which is refused as a
- source, and the generated profile renders one thread and an `env_var`
- password reference, never a value.
-
-## Profiling behavior
-
-Profiling is deliberately light on the primary. The metered batch is one
-cheap single-pass scan per 50 columns: `COUNT(*)`, per-column non-null
-counts, and min/max only for engine-cleared safe columns. **Distinct counts
-come free from the planner's own statistics** (`pg_stats.n_distinct`, scaled
-by the exact row count when negative); the value-carrying statistics columns
-(`most_common_vals`, `histogram_bounds`) are never read. A statistics
-estimate is never a uniqueness verdict: near-unique keys escalate to an exact
-`COUNT(DISTINCT)` inside the confirmed budget through the standard escalation
-flow, and that scan also upgrades the row count from the `reltuples` estimate
-to an exact figure, so uniqueness proofs and grain verdicts compare against
-real rows.
-
-Freshness caveats, surfaced as data-quality notes rather than silently
-thinner numbers: a never-analyzed table has no row estimate and no distinct
-estimates (the note names `ANALYZE` as the fix), and `maintain volume` on
-unprofiled tables compares planner estimates whose accuracy tracks
-autovacuum's ANALYZE cadence. `json`, `jsonb`, arrays, `bytea`, `xml`,
-`tsvector`, and the geometric and PostGIS types degrade to non-null counts.
-Tables above `postgres.max_full_profile_bytes` are profiled from a block
-sample (`TABLESAMPLE SYSTEM`), noted, with uniqueness not judged.
-
-**The value-shape probes read a string column as text under the `C`
-collation.** The probes behind the type-contradiction, mixed-key-shape and
-generic-name findings use a regular expression and `replace()`, and Postgres
-refuses both under a nondeterministic collation (an ICU collation created with
-`deterministic = false`, such as a case-insensitive one). Each probe therefore
-reads `column::text COLLATE "C"`, so a table with such a column profiles like
-any other. The patterns are ASCII with explicit ranges, so `C` matches a text
-value exactly as its own collation would. The cast to `text` also means a
-`char(n)` column is matched without its padding, as `length()` already
-measures it, and a `citext` column is matched case-sensitively, as every other
-connector matches a string. Counts and min/max still read the column itself,
-in its own collation. Grouping, distinct counts and equality joins on a
-nondeterministic column follow that collation, so on a case-insensitive
-column `'A'` and `'a'` are one value to a uniqueness check or a join probe,
-as they are to a unique index on that column.
-
-**A cast key is measured through a guarded cast.** Postgres has no cast that
-returns NULL on failure, so where `transform plan` (identifier conversions) or
-`maintain verify` (join coverage) measures a key cast to `smallint`, `integer`
-or `bigint`, the probe casts the value only where its text is an integer in
-the type's range, and counts every other value as failed. The guard keeps
-every cast total, like the profiling probes, so it does not depend on the
-order Postgres evaluates a `CASE` in. A cast to any other type is reported
-`unchecked` with `reason_code: no_safe_cast_on_connector`.
-The guard reads the value as text, so a numeric, float or boolean source
-that Postgres would cast (`2.00`, `1e15`, `true`) also counts as failed.
-
-## dbt builds
-
-`transform init` renders a `type: postgres` dev profile from the discovered
-connection: host, port, user, and dbname from whichever source won discovery,
-`schema` pinned to the dedicated dev schema, one thread, and
-`password: "{{ env_var('PGPASSWORD', '') }}"` (the empty default keeps
-`~/.pgpass` and peer auth working when no variable is set). dbt has no
-dry-run, so `transform build` cannot be estimated upfront; the ceiling and
-confirmation still bind, and the ceiling is injected into the dbt subprocess
-as `PGOPTIONS="-c statement_timeout=s"`, the per-statement
-server-side cap (the `maximum_bytes_billed` analogue). Actual per-node
-execution time is summed into `billed_seconds` and recorded to the ledger.
-
-`transform build --verify` inherits that: its row counts cannot be priced
-upfront either, so they are gated after the build as a phase drawn against the
-reservation the build already holds, and their execution time is billed into the
-same settlement. Only a relation the warehouse keeps no row count for is counted
-at all, which is any view (dbt's default materialization); a table's count is
-free catalog metadata, and a verdict resting on it is reported `exact: false` to
-say so.
-
-`transform test --mutate` prices its whole batch as one number and confirms it
-once, then runs one dbt invocation per mutant. Nothing is materialized: a mutant
-builds as an ephemeral model, so the dev namespace holds exactly the relations it
-held before. A budget that runs out partway stops the run, and the remaining
-mutants are reported `not_run` rather than the budget being exceeded. Survivors
-are not yet compared with the model on the dev data on this connector, so each
-reports `equivalence.status: not_checked` with the reason, and nothing is
-priced or run for it.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-
-
-`--verify` also reads `postgres.dev_schema` for the length of that one command,
-because dbt writes the relations it is judging there and that schema is refused
-as a source everywhere else. The schema need not exist yet: dbt creates it on a
-first build, and dex lists it after dbt has run. How that read is bounded is
-under **Read scope** in [`command-contract.md`](/dex/reference/command-contract).
-
-
-`transform init` content-checks the dev schema (and, with `--layered-schemas`,
-the sibling `staging_dev` / `intermediate_dev` / `marts_dev` layer schemas)
-with one `pg_class` catalog lookup per schema, warning when one already holds
-tables or views; a missing schema stays silent, since dbt creates it.
-
-## Testing
-
-Offline: a stateful fake connection (`tests/fakes/postgres.py`) that records
-statement ordering, serves catalog and `pg_stats` lookups from a table
-registry, answers `EXPLAIN` with size-derived plan costs, simulates timing on
-an injected clock, and enforces `statement_timeout` with psycopg's real
-`QueryCanceled`. Live: an env-gated integration suite (`DEX_TEST_PG_DSN`,
-plus `DEX_TEST_PG_DEV_PASSWORD` for builds) against the seeded database from
-`scripts/postgres_seed.sql`; `scripts/setup_postgres_dev.sh` stands up the
-same thing locally in Docker, and CI runs the suite against a free, keyless,
-digest-pinned `postgres:16` service container with its capabilities dropped
-(kept in the integration workflow for pattern parity, never a merge gate).
-
-Source: [`references/postgres.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/postgres.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/postgres.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/redshift.mdx b/dex/connectors/redshift.mdx
deleted file mode 100644
index 9108e0f..0000000
--- a/dex/connectors/redshift.mdx
+++ /dev/null
@@ -1,260 +0,0 @@
----
-title: Amazon Redshift connector
-sidebarTitle: Redshift
-description: 'Connect dex to Amazon Redshift Serverless or provisioned clusters: IAM temporary credentials, compute-seconds priced as RPU-hours, read-only access.'
-og:title: Amazon Redshift connector · Exmergo Dex
-twitter:title: Amazon Redshift connector · Exmergo Dex
----
-
-The AWS warehouse, Serverless-first. Namespace: `database.schema.table` (one
-connection, one database; the first component is always the connected
-database). Cost paradigm: **compute-seconds**, translated to RPU-hours on
-Serverless. Read-only against data, enforced in depth. Provisioned clusters
-ride the same SQL and metadata paths with seconds-only accounting (node-hours
-bill flat, so there is nothing to translate); the cost gate is designed for
-Serverless.
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime and never prompts for or
-persists a password. Discovery order:
-
-1. `redshift.workgroup` in `.dex/config.yml`: the Serverless pin. The AWS
- default credential chain (`aws configure`, `AWS_*` env, SSO, an assumed
- role, instance metadata; `redshift.aws_profile` pins a named profile)
- resolves the endpoint, port, and database from the control plane, and the
- driver mints IAM **temporary database credentials** (`GetCredentials`) at
- connect time. Nothing durable exists to leak.
-2. `redshift.cluster_identifier` plus `dbname`/`user`: the provisioned IAM
- analogue (`GetClusterCredentials`).
-3. the `REDSHIFT_*` environment (`REDSHIFT_HOST`, `REDSHIFT_DATABASE`,
- `REDSHIFT_USER`, password via `REDSHIFT_PASSWORD`)
-4. the committed non-secret `redshift.host`/`port`/`dbname`/`user` config
- target (password still supplied by `REDSHIFT_PASSWORD`)
-5. the `host` of a `type: redshift` target in a discovered dbt `profiles.yml`
-
-Only a coarse method is ever surfaced (for example `iam_serverless:profile`
-or `config_target:password`); identities, keys, and passwords never cross the
-envelope. Every discovery failure names all the fixes, including the IAM
-permissions the workgroup path needs (`redshift-serverless:GetWorkgroup`,
-`GetCredentials`, and `GetNamespace` for database discovery).
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: redshift
-redshift:
- workgroup: dex-wg # the Serverless pin; IAM auth + RPU facts
- aws_profile: null # a named ~/.aws profile; default chain if unset
- region: null # when the chain's default region is wrong
- schemas: # source allowlist; empty means all visible
- - shop
- dev_schema: dbt_dev # where dbt dev builds write (never a source)
- rpu_price_usd: null # your region's RPU-hour price; set it to see dollars
-budget:
- ceiling: 300 # per-command compute-seconds; --budget overrides
- session_ceiling: 3600 # cumulative seconds per UTC day
-```
-
-Point dex at a read-only database user (or let IAM mint one); the documented
-grant shape is USAGE on source schemas plus SELECT on their tables and on
-`svv_table_info` (an IAM-minted user starts without it, and without it table
-sizes are unknown and estimates degrade to minimums), with write access only
-on the dedicated dev schema for the dbt user.
-
-## Scoping a command
-
-`redshift.schemas` is the committed source allowlist. `--scope` narrows it
-for one command and is repeatable; a Redshift scope is a bare `` in
-the connected database (dbt refuses cross-database references, so there is
-nothing to qualify). Resolution is a catalog lookup and happens before
-anything is estimated: a scope that names no schema is refused with the
-schemas that do exist listed, never quietly dropped, and `--scope` narrows
-the committed allowlist, never widens it. `--project` and `--dataset` are
-BigQuery vocabulary and error here.
-
-## Cost model: compute-seconds, honestly floored
-
-Redshift Serverless charges RPU-hours whenever compute is active, with a
-**60-second minimum** each time an idle workgroup wakes, and AWS treats every
-incoming query as billable activity. Two consequences dex states plainly
-rather than hides:
-
-- **Metadata is cheap, not free.** Inventory, `connect test`, estimation,
- and the free axes of `maintain check` read only catalogs
- (`pg_catalog`, `SVV_TABLE_INFO`, `SVV_COLUMNS`) and are not gated, but
- touching an idle workgroup can incur the wake minimum; `connect test`
- carries that warning on Serverless.
-- **Estimates carry the wake floor once per command.** There is no API that
- says whether compute is warm (and probing would itself bill), so every
- estimate on Serverless includes the 60-second minimum exactly once,
- labeled an upper bound that actuals waive when compute was already active.
-
-**Metered:** profiling aggregates, `explore query`, relationship
-verification probes, distinct-count escalations, and `transform build`.
-
-`explore query` and `explore cluster` bill an auto-profile of an object this connection has that the `.dex/` cache cannot adjudicate, priced into the same handshake as the statements: see [`cost-controls.md`](/dex/guardrails/cost-controls). Pass `--no-auto-profile` (or set `auto_profile: false` in `.dex/config.yml`) to be refused instead.
-
-Budgets (`budget.ceiling`, `--budget`, `budget.session_ceiling`) are
-compute-seconds: the number you budget is the number the server enforces.
-Every cost surface also carries the translation to **RPU-hours**
-(`seconds x base_capacity / 3600`, base capacity from the workgroup via the
-control plane, labeled approximate because Serverless can scale above it)
-and to dollars when `redshift.rpu_price_usd` is set. dex never guesses a
-dollar price: the RPU-hour rate varies by region and agreement.
-
-**Estimates are a heuristic, honestly labeled.** Redshift has no dry-run,
-and its EXPLAIN costs are relative units with no honest translation to
-seconds, so estimates come from table bytes (`SVV_TABLE_INFO`) over a
-conservative capacity-scaled scan rate; every handshake payload carries
-`estimate_quality: "heuristic"`. The same estimator prices `transform build`:
-each compiled model, snapshot, and test is estimated and summed into the
-build's upfront cost.
-
-`transform build --verify` costs only where the warehouse keeps no row
-count, so a table's count is free metadata; how the counts are priced into
-the build's own estimate is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-`transform test --mutate` prices its whole batch as one number and confirms it
-once, then runs one dbt invocation per mutant. Nothing is materialized: a mutant
-builds as an ephemeral model, so the dev namespace holds exactly the relations it
-held before. A budget that runs out partway stops the run, and the remaining
-mutants are reported `not_run` rather than the budget being exceeded. Survivors
-are not yet compared with the model on the dev data on this connector, so each
-reports `equivalence.status: not_checked` with the reason, and nothing is
-priced or run for it.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-
-
-`--verify` also reads `redshift.dev_schema` for the length of that one command,
-because dbt writes the relations it is judging there and that schema is refused
-as a source everywhere else. The schema need not exist yet: dbt creates it on a
-first build, and dex lists it after dbt has run. How that read is bounded is
-under **Read scope** in [`command-contract.md`](/dex/reference/command-contract).
-
-
-**The budget is hard-enforced regardless of estimate quality.** Before every
-metered statement the session's `statement_timeout` is set to the remaining
-budget, so a wrong heuristic cannot overrun the ceiling: Redshift kills the
-statement and dex reports the over-ceiling refusal. Actual spend is
-wall-clock seconds per statement (a killed statement still bills what ran),
-recorded as `billed_seconds` in the ledger. Every session connects as `application_name = 'dex'`
-(`SYS_CONNECTION_LOG`) and sets `query_group = 'dex'` for attribution.
-
-The estimate carries its RPU translation; the handshake itself is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-## Read-only, enforced in depth
-
-- Every data statement passes the SELECT-only guard parsed in the redshift
- dialect through one execution door (DML, DDL, `COPY`, `UNLOAD`, and
- multi-statement forms all refuse).
-- The adapter issues no mutating statements: catalog SELECTs and session
- `SET`s only.
-- The session attempts `default_transaction_read_only = on`; whether Redshift
- honors it is probed rather than assumed, and `connect test` reports the
- truth as `session_read_only` (the guard and grants hold either way).
-- The documented grant shape is a least-privilege read-only user; dbt dev
- builds write to `dev_schema` (default `dbt_dev`), which is refused as a
- source, and the generated profile renders one thread and IAM or an
- `env_var` password reference, never a value.
-
-## Profiling behavior
-
-Profiling is batched aggregates in single passes: `COUNT(*)`, per-column
-non-null counts, `HLL(...)` approximate distincts (Redshift refuses more
-than three `APPROXIMATE COUNT(DISTINCT)` expressions per statement, so the
-equivalent HLL aggregate keeps a wide batch a single pass), and min/max only
-for engine-cleared safe columns; never row values. Redshift keeps no usable
-planner distincts, so approximate distincts ride the billed batch, and an
-approximation is never a uniqueness verdict: near-unique keys escalate to an
-exact `COUNT(DISTINCT)` inside the confirmed budget, and that scan also
-upgrades the `SVV_TABLE_INFO` row estimate to an exact figure. When no single
-column proves unique, the composite-key probe (a bounded batch of exact
-distinct-combination counts) spends inside the same confirmed budget, and
-like the escalation it carries the pending Serverless wake minimum when it
-bills first; when the remaining budget cannot cover every pair, the probe
-narrows to the best-ranked pairs it can afford, and skips with a note only
-when it cannot afford one, in which case the grain stays unknown. `SUPER`,
-`VARBYTE`, `GEOMETRY`, `GEOGRAPHY`, and `HLLSKETCH` columns degrade to
-non-null counts. There is **no sampled-profiling threshold**: Redshift has
-no TABLESAMPLE, so a sampling knob would be a lie; the budget is the only
-bound. Empty tables are inventoried from `pg_class` even though
-`SVV_TABLE_INFO` omits them.
-
-**Every `CAST` in a generated aggregate is total, and has to stay that way.**
-Redshift evaluates a `CASE` branch's cast for rows the `WHEN` never selects,
-so guarding a cast behind a shape predicate inside a `CASE` does not protect
-it: the declared-type-vs-content probe did exactly that and died on any table
-with one non-numeric string in a profiled column (`Invalid digit, Value 'p',
-Pos 0, Type: Long`). There is no `TRY_CAST` here and the Python UDF escape
-hatch is end-of-support after 2026-06-30, so the discipline is in the
-expression shape: a cast's argument is itself a `CASE` yielding a digit-only
-string on every row, with a sentinel every predicate built on the cast
-rejects. It is enforced offline for all six adapters (see
-`assert_every_cast_is_total`), because no unit test can catch a dialect that
-disagrees with the standard about evaluation order.
-
-**Two more spellings the server refuses outright, both verified live.**
-`DATEDIFF` resolves to `pg_catalog.date_diff`, which is declared over
-`DATE`/`TIME`/`TIMETZ`/`TIMESTAMP` and has no `TIMESTAMPTZ` overload, while
-`DATE_TRUNC` over a `TIMESTAMPTZ` column returns `TIMESTAMPTZ`: the periods
-the temporal-continuity probe diffs are exactly the shape it rejects
-(`function pg_catalog.date_diff("unknown", timestamp with time zone,
-timestamp with time zone) does not exist`), which failed the whole profiling
-statement for any table carrying a `TIMESTAMPTZ` column. Both operands are
-therefore cast to `TIMESTAMP`, a conversion that is total for every type
-reaching that path and shifts nothing, since it applies to both sides by the
-same rule. And `SUBSTR`, the spelling the shared expressions use, is refused
-by name (`SUBSTR() function is not supported (Hint: use SUBSTRING instead)`)
-at execution over a real table, not only in a leader-node-only query, so this
-adapter emits `SUBSTRING` for the slash-date component extraction. Neither
-spelling is universal in the other direction: BigQuery has `SUBSTR` and no
-`SUBSTRING`, which is why the idiom is per-connector rather than swapped in
-the shared builder.
-
-## dbt builds
-
-`transform init` renders a `type: redshift` dev profile from whichever
-source won discovery: IAM discovery renders `method: iam` (temporary
-credentials minted by dbt-redshift at runtime, nothing persisted), password
-discovery renders `password: "{{ env_var('REDSHIFT_PASSWORD') }}"` (a Jinja
-reference, not a value), both with `schema` pinned to the dedicated dev
-schema and one thread. Before the cost gate, and for free, `transform build`
-refuses config that has drifted from the rendered profile, and a dev schema
-the profile's user lacks the privilege to create or write (the Postgres
-question: dbt creates the schema, but only if the user may). `transform init`
-additionally content-checks the dev schema (and, with `--layered-schemas`,
-the `staging_dev` / `intermediate_dev` / `marts_dev` layer schemas) with one
-catalog lookup per schema, warning when one already holds tables or views;
-this works on IAM profiles too, since content, unlike privilege, is not a
-per-user question. dbt has no
-dry-run and dex cannot inject a per-build server cap through dbt-redshift,
-so the honest layering is: per-node execution time summed into
-`billed_seconds` on the ledger, a durable `ALTER USER dbt_dev SET
-statement_timeout` applied by the setup script, and a workgroup usage limit
-(RPU-hours per day) as the account-level backstop. Keep one dev schema per
-building user: dbt swaps a rebuilt relation in place, and a relation another
-user owns breaks the swap with a bare `relation already exists` (verified
-live), so two identities sharing `dbt_dev` will trip over each other's
-views.
-
-## Testing
-
-Offline: a stateful fake connection (`tests/fakes/redshift.py`) that records
-statement ordering, serves the catalog census (including SVV_TABLE_INFO's
-empty-table omission), simulates timing on an injected clock, and enforces
-`statement_timeout` with redshift_connector's real error shape. Live: an
-env-gated integration suite (`DEX_TEST_REDSHIFT_*`) against a seeded
-Serverless workgroup, run in CI on a schedule via GitHub OIDC role assumption
-(no stored keys), never as a merge gate; `scripts/setup_redshift_ci.sh`
-provisions the workgroup, users, and the usage-limit backstop.
-
-Source: [`references/redshift.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/redshift.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/redshift.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/snowflake.mdx b/dex/connectors/snowflake.mdx
deleted file mode 100644
index f9603e1..0000000
--- a/dex/connectors/snowflake.mdx
+++ /dev/null
@@ -1,392 +0,0 @@
----
-title: Snowflake connector
-sidebarTitle: Snowflake
-description: Connect dex to Snowflake through connections.toml, environment variables, or a dbt profile. Warehouse-seconds pricing, credits shown, read-only by design.
-og:title: Snowflake connector · Exmergo Dex
-twitter:title: Snowflake connector · Exmergo Dex
----
-
-The first compute-time billed connector. Namespace: `database.schema.table`.
-Cost paradigm: **warehouse-seconds** (credits shown alongside). Read-only
-against data, enforced in depth.
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime and never prompts for or persists
-a password. Discovery order:
-
-1. `snowflake.connection_name` in `.dex/config.yml`, naming a
- `~/.snowflake/connections.toml` entry (the store the `snow` CLI writes)
-2. the default connection (`default_connection_name` in `config.toml`, or
- `SNOWFLAKE_DEFAULT_CONNECTION_NAME`)
-3. `SNOWFLAKE_*` environment variables (`SNOWFLAKE_ACCOUNT` +
- `SNOWFLAKE_USER` plus a credential; this is also how CI's
- workload-identity token arrives: `SNOWFLAKE_AUTHENTICATOR=WORKLOAD_IDENTITY`,
- `SNOWFLAKE_WORKLOAD_IDENTITY_PROVIDER=OIDC`, `SNOWFLAKE_TOKEN=`)
-4. the `account` of a `type: snowflake` target in a discovered dbt
- `profiles.yml`
-
-Key-pair, SSO (`externalbrowser`), password, token, and workload-identity
-credentials all work; only the coarse method (for example
-`named_connection:key_pair`) is ever surfaced. Identities, passwords, and key
-material never cross the envelope. Every discovery failure names the fix.
-
-A key-pair connection's private key file must be readable by its owner alone,
-the rule `ssh` applies to its keys: a file with any group or other permission
-bit is refused, with its path and the `chmod 600` that fixes it, before any
-connection is attempted. Windows is not checked, because its mode bits are
-synthesized and its ACLs, which govern access there, are not visible to this
-check.
-
-One caveat: workload identity covers the engine (explore, maintain, query)
-but not dbt builds, because stable dbt-snowflake does not support it yet.
-`transform init` refuses a workload-identity connection and names the
-alternatives (key-pair or SSO); the refusal lifts once dbt-snowflake ships
-support.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: snowflake
-snowflake:
- connection_name: dex-ci # a connections.toml entry; optional
- warehouse: DEX_CI_WH # REQUIRED for anything billed; the pin is strict
- databases: # source allowlist; empty means all visible
- - SNOWFLAKE_SAMPLE_DATA.TPCH_SF1 # db or db.schema entries
- dev_database: DEX_CI # where dbt dev builds write (never a source)
- dev_schema: DBT_DEV # default DBT_DEV
- max_full_profile_bytes: null # opt-in SAMPLE threshold for huge tables
- credit_price_usd: null # your contract price; set it to see dollars
- suspend_after_command: false # suspend the warehouse after a command that woke it (needs OPERATE)
-budget:
- ceiling: 300 # per-command warehouse-seconds; --budget overrides
- session_ceiling: 3600 # cumulative seconds per UTC day
-```
-
-**The warehouse pin is strict.** Billed statements run only on
-`snowflake.warehouse`; a connection-level default warehouse is never spent on,
-and a missing or unpinned warehouse refuses with the fix named. Pin the
-smallest warehouse that works (X-Small with 60s auto-suspend is the intended
-shape; `scripts/setup_snowflake_ci.sh` provisions exactly that plus a resource
-monitor as the hard monthly backstop). Auto-suspend matters as much as size:
-every billed command that leaves the warehouse idle is charged the idle time
-until it suspends (see **Warehouse uptime** below), and Snowflake's default
-for a new warehouse is 600 seconds, which bills a two-second query for ten
-minutes. Where the warehouse is shared and its `AUTO_SUSPEND` cannot be
-lowered, `suspend_after_command: true` gets the same effect per command (see
-**Suspending after a command** below). `connect test` recommends one or the
-other whenever `AUTO_SUSPEND` is longer than 60 seconds and neither is in
-place; dex never changes `AUTO_SUSPEND` itself.
-
-## Scoping a command
-
-`snowflake.databases` is the committed source allowlist, and a single database
-can span four orders of magnitude in table size, so prefer `db.schema` entries
-over bare `db` when the difference matters for cost.
-
-`--scope` narrows that allowlist for one command, and is repeatable. It accepts
-a bare schema (`--scope TPCH_SF1`, qualified against the databases already in
-scope), a database, or a qualified `database.schema`. Resolution is free (SHOW
-metadata, no warehouse) and happens before anything is estimated:
-
-- A scope that names no database and no schema is **refused**, and the error
- lists the schemas that do exist. It is never quietly dropped, because an
- estimate that silently spans the whole allowlist is one a user could confirm
- believing it bounded a handful of tables.
-- A bare schema that exists in more than one in-scope database is refused as
- ambiguous, asking for `database.schema`.
-- A scope outside the committed allowlist is refused. `--scope` narrows; it
- never widens.
-
-`--project` and `--dataset` are BigQuery vocabulary and error here.
-
-## Preflight before a dbt build
-
-`transform build` refuses, for free, before the cost gate:
-
-- when `.dex/config.yml` and the rendered `profiles.yml` disagree about the dev
- database, schema, or warehouse (the profile is what dbt reads, so a config
- edit that never reached it would otherwise build against the old target), and
-- when `snowflake.dev_database` does not exist. dbt creates schemas but never
- databases, so the first build would fail inside dbt's `list_schemas` macro
- with `002043: Object does not exist`. dex names the database and the
- statement that fixes it:
-
-```sql
-CREATE DATABASE IF NOT EXISTS DBT_DEV;
-```
-
-dex never creates it for you, and never rewrites your `profiles.yml`: its only
-writes are reviewable diffs inside the repo.
-
-`transform init` runs its own free preflight in the other direction: a
-SHOW-only content check (cloud-services layer, no warehouse) of every schema
-the new project would build into, warning when one already holds tables or
-views. With `--layered-schemas` the layers build into sibling schemas of
-`snowflake.dev_database` (`STAGING_DEV`, `INTERMEDIATE_DEV`, `MARTS_DEV` on
-the `dev` target), and those are checked too.
-
-## Cost model: the inversion from BigQuery
-
-On BigQuery, metadata is free and scans bill by bytes. On Snowflake the rule
-flips: metadata is cheap (SHOW commands run on the cloud-services layer with
-no warehouse), while any data scan costs warehouse runtime. So dex guards
-**warehouse-seconds**, not bytes.
-
-- **Free:** `connect test`, `explore inventory`, all schema and row/byte
- metadata (SHOW commands, no `INFORMATION_SCHEMA` scans), estimation, and
- `maintain check` (drift detection reads metadata only).
-- **Billed:** profiling aggregates, `explore query`, relationship verification
- probes, and `transform build`.
-
-`explore query` and `explore cluster` bill an auto-profile of an object this connection has that the `.dex/` cache cannot adjudicate, priced into the same handshake as the statements: see [`cost-controls.md`](/dex/guardrails/cost-controls). Pass `--no-auto-profile` (or set `auto_profile: false` in `.dex/config.yml`) to be refused instead.
-
-Budgets (`budget.ceiling`, `--budget`, `budget.session_ceiling`) are
-warehouse-seconds: the number you budget is the number the server enforces.
-Every cost surface also carries the translation to **credits**
-(`seconds x credits_per_hour / 3600`, rate from the warehouse's size and
-generation via `SHOW WAREHOUSES`; Gen2 rates are marked approximate), and to
-dollars when `snowflake.credit_price_usd` is set. dex never guesses a dollar
-price: no API exposes your contract rate.
-
-**Estimates are a heuristic, honestly labeled.** Snowflake has no dry-run, so
-the estimate is derived from table bytes over a conservative scan rate, and
-every handshake payload carries `estimate_quality: "heuristic"`. The estimate
-also quotes, once per command, the **warehouse uptime** no statement will
-report: the 60-second resume minimum when the pinned warehouse is suspended,
-and the idle tail until auto-suspend either way, with a note saying which. So
-a two-second probe against a cold warehouse is quoted at what the account will
-actually see. The same estimator prices `transform build`: each compiled
-model, snapshot, and test is estimated and summed into the build's upfront
-cost, with the uptime as a line of its own, `(warehouse uptime)`.
-
-`transform build --verify` costs only where the warehouse keeps no row
-count, so a table's count is free metadata; how the counts are priced into
-the build's own estimate is in
-[`cost-controls.md`](/dex/guardrails/cost-controls).
-
-`transform test --mutate` prices the batch in warehouse-seconds, from the same
-heuristic the rest of this connector uses rather than from a dry run, so the
-estimate carries `estimate_quality: heuristic` and the resume minimum floors it
-like any other billed command here. One estimate and one confirmation cover
-every mutant; a budget that runs out partway stops the run and reports the rest
-as `not_run`. Each run settles at the per-node execution seconds it reports,
-ledgered under `command: "transform test"`, and the batch's warehouse uptime
-settles once at the end as one more row under the same command. The stop rule
-counts that uptime before admitting the next run, and it includes the time
-between runs, while dbt starts and parses with the warehouse up, which no
-estimate prices: a batch confirmed at exactly its estimate can stop a run
-early. Nothing is materialized,
-because a mutant builds as an ephemeral model, so `snowflake.dev_database` holds
-exactly the objects it held before the run.
-
-Comparing each survivor with the unmutated model on the dev data is opt-in here,
-with `--check-equivalence`, and is priced in seconds into the same estimate from
-the same heuristic: one line for the self-check, and one for the comparisons,
-priced as if every mutant survives. Only survivors run one, so the settled
-seconds are at most that line, ledgered under the same command. Without the
-flag, survivors report `equivalence.status: not_checked`.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-The heuristic prices a statement by the bytes it scans, and a downstream test
-recomputes the whole chain beneath it (joins and aggregates included), so on a
-large source it can settle above its line; the stop rule counts settled
-seconds, so the confirmed budget still binds.
-
-
-`--verify` also reads the dev schema (`snowflake.dev_database` /
-`snowflake.dev_schema`) for the length of that one command, because dbt writes
-the relations it is judging there and that schema is refused as a source
-everywhere else. The schema need not exist yet: dbt creates it on a first
-build, and dex lists it after dbt has run. How that read is bounded is under
-**Read scope** in [`command-contract.md`](/dex/reference/command-contract).
-
-
-**The budget is hard-enforced regardless of estimate quality.** Before every
-billed statement the session's `STATEMENT_TIMEOUT_IN_SECONDS` is set to the
-remaining budget, less the uptime the command will still owe once its
-statements are done, so a wrong heuristic cannot overrun the ceiling: Snowflake
-kills the statement and dex reports the over-ceiling refusal. Every session is
-tagged `QUERY_TAG = 'dex'` for attribution.
-
-## Warehouse uptime
-
-Snowflake bills a warehouse for being up, not for running statements: at least
-60 seconds each time a suspended warehouse resumes, then per second until it has
-idled for its `AUTO_SUSPEND`. Statement time alone under-reports exactly the
-small commands an agent runs most (a three-second build on a warehouse with a
-60-second auto-suspend bills over a minute), so a command's actual spend has two
-parts, both recorded as `billed_seconds` in the ledger:
-
-- **Statement time.** Wall-clock seconds per statement dex runs, and dbt's
- per-node execution seconds for a build.
-- **Uptime no statement reported**, settled once the command's last statement
- is done, from a free `SHOW WAREHOUSES`: the time between the command's own
- statements, floored at 60 seconds when it found the warehouse suspended, plus
- the `AUTO_SUSPEND` tail when it left the warehouse idle. A build folds this
- into its own settlement row; other commands record it as one more row in
- their `reservation_id` group, with no statement hash. A warning names what
- was added and why.
-
-The rules that decide the figure:
-
-- **The last user pays the tail.** A command that finishes while other queries
- are still running or queued on the warehouse is charged no tail; one that
- leaves it idle is charged all of it.
-- **A tail is paid once per resume cycle.** Each command records what it
- claimed of the warehouse's current resume cycle (the warehouse, its
- `resumed_on`, when its last statement ended, its `AUTO_SUSPEND`) as a
- zero-amount settlement row carrying `warehouse_claim` in the spend ledger. A
- command that then finds the warehouse still running in the same cycle is
- charged only what it adds to that claim: the gap since the previous
- command's last statement plus its own span, rather than a second tail. Ten
- commands half a minute apart settle about one tail between them, as the
- warehouse bills, instead of ten. The rule only lowers a charge, never past
- the command's own statement time, and never raises one past statement time
- plus one tail, so a warehouse other users keep running cannot make dex claim
- their uptime. The estimate quotes by the same rule. A store without readable
- ledger history charges the full tail, the safe direction.
-- **A command that never woke the warehouse owes no uptime.** Snowflake answers
- a result-cache hit or a count served from metadata without resuming it.
-- **`AUTO_SUSPEND` off means unbounded.** The warehouse bills until someone
- suspends it, so no tail is charged, the warning says the figure is a lower
- bound, and `connect test` warns.
-- **It is a model of Snowflake's billing rules, not a meter.** Snowflake's
- suspend check runs about every 30 seconds, so a tail can run up to that much
- longer than `AUTO_SUSPEND`, most likely when the setting is not a multiple of
- 30; multi-cluster scale-out and resizes are not modeled.
- `SNOWFLAKE.ACCOUNT_USAGE.WAREHOUSE_METERING_HISTORY` is the authority, and the
- resource monitor the backstop. dex cannot settle from that view instead: it
- reports hourly buckets that mix in other users, lags up to three hours, and is
- readable only with ACCOUNTADMIN or MONITOR USAGE.
-
-The overhead belongs to the command, not to any statement, so it is quoted once
-per command as its own `(warehouse uptime)` line, by whichever handshake shows
-the caller an estimate first, and a phase whose budget cannot cover it asks
-rather than running. Where the idle tail is most of the estimate, a note states
-the command's own work, what `AUTO_SUSPEND` makes it bill, and what a 60-second
-`AUTO_SUSPEND` or a suspend would bring it to. The estimate carries its credit
-translation; the handshake itself is in [`cost-controls.md`](/dex/guardrails/cost-controls).
-
-### Suspending after a command
-
-`snowflake.suspend_after_command: true` (off by default) has dex suspend the
-pinned warehouse at the end of a command, so the command bills its statement
-time floored at Snowflake's 60-second resume minimum instead of the whole
-`AUTO_SUSPEND` tail. On a warehouse at the 600-second default that is roughly a
-tenth of the per-command bill. It is opt-in because, unlike the session
-parameters dex sets, it acts on a warehouse other workloads may share, and dex
-only suspends one it can show was its own to suspend:
-
-- **The command woke it.** It found the warehouse suspended, and the
- warehouse's `resumed_on` moved during the command's first statement, so the
- resume was this command's and not another session's.
-- **Nothing else is using it.** `SHOW WAREHOUSES` shows nothing running or
- queued once the command's last statement is done. A warehouse that was
- already running when the command started is never suspended, whoever was
- using it.
-- **It wakes on its own.** `AUTO_RESUME` is on, so the next query anyone sends
- resumes it. A warehouse with `AUTO_RESUME = FALSE` is never suspended, since
- every query after the suspend would fail until someone resumed it by hand.
-- **It is the pinned warehouse.** The statement is rendered by one typed
- adapter method that can only produce `ALTER WAREHOUSE ""
- SUSPEND`, refusing when `SHOW WAREHOUSES` spells the warehouse differently
- from the pin. No agent-authored SQL reaches it, and the query firewall goes
- on refusing every `ALTER`. Suspending stops compute and touches no data,
- schema or file, and Snowflake lets running statements finish first.
-
-It needs `OPERATE` on the warehouse:
-
-```sql
-GRANT OPERATE ON WAREHOUSE DEX_WH TO ROLE DEX_ROLE;
-```
-
-Without the grant the suspend is refused, the command completes and warns with
-the grant to add, and it settles the tail as before. The warnings about the
-tail print their commands ready to copy, with the warehouse and the session's
-own role filled in (the role comes from the login response, so reading it runs
-no statement). While the setting is off, `connect test` prints the `dex config
-set` that turns it on and the grant, so adopting it is two copied commands. An
-estimate's note names only what is missing: the `dex config set` while the
-setting is off, and the grant once a suspend has been refused for lacking it.
-dex cannot test the grant without suspending something, so the quote counts on
-a suspend only once one has worked: the first command after the setting is
-turned on is quoted the tail, with a note saying why, and is settled at what
-the suspend did; later ones are quoted the resume minimum, until a refusal is
-recorded. `connect test` reports
-`budget.warehouse.suspend_after_command` (`enabled`, `last_outcome`) and lists
-`OPERATE` under `required_grants` while the setting is on. If the grant is
-revoked after a suspend has worked, one command is quoted the resume minimum
-and settled at the tail before the refusal it records puts the tail back in
-the quote.
-
-## Read-only, enforced in depth
-
-- Every data statement passes the SELECT-only guard parsed in the snowflake
- dialect through one execution door (DML, DDL, `COPY INTO`, `CALL`,
- `ALTER`, and multi-statement forms all refuse).
-- The adapter issues no mutating statements: SHOW commands, SELECTs, and
- session parameters only, plus `ALTER WAREHOUSE ""
- SUSPEND` where `snowflake.suspend_after_command` opts in, which stops compute
- and changes no data. The safety spine pins that set.
-- The documented grant shape is a least-privilege role: USAGE on the pinned
- warehouse, read (or `IMPORTED PRIVILEGES`) on source databases, and write
- only on the dedicated dev database (`scripts/setup_snowflake_ci.sh` creates
- this shape).
-- dbt dev builds write to `dev_database.dev_schema`, which is refused as a
- source, and the generated profile pins the warehouse and one thread.
-
-## Profiling behavior
-
-Profiling is batched aggregates (COUNT, APPROX_COUNT_DISTINCT, min/max only
-for engine-cleared safe columns), never row values. Semi-structured and
-spatial columns (VARIANT, OBJECT, ARRAY, GEOGRAPHY, GEOMETRY, VECTOR) degrade
-to non-null counts. Tables above `snowflake.max_full_profile_bytes` are
-profiled from a block sample (`SAMPLE SYSTEM`), noted, with uniqueness not
-judged. Exact distinct-count escalation spends only inside the confirmed
-budget and degrades to approximate verdicts with a note when the remainder
-cannot cover it.
-
-`SHOW COLUMNS` reports a type token rather than a full type. `NUMBER(38,0)` and
-`NUMBER(10,2)` both arrive as `FIXED`, and `VARCHAR(50)` as `TEXT`, so precision,
-scale and length are not recorded anywhere dex can compare. Two things follow:
-`maintain schema` reports no `column_retyped` for a precision, scale or length
-change, and `is_integer_type` treats `FIXED` as a known, accepted false negative
-rather than guessing at the scale behind it.
-
-## Semantic Views
-
-`semantic.vendor: snowflake` reads Snowflake Semantic View YAML files from the
-repository with no connection (see
-[Snowflake Semantic View compatibility](/dex/semantic-layers/snowflake-semantic-views)).
-On the warehouse side, a deployed semantic view is never inventoried: `SHOW
-VIEWS` does not list one, `SHOW COLUMNS` lists its members with a `kind` other
-than `COLUMN` and the inventory skips them, and a plain `SELECT` on one fails.
-The dev-namespace existence check lists them with `SHOW SEMANTIC VIEWS`, so a
-schema holding one is not read as empty.
-
-Dogfooding against deployed views is a maintainer's setup, outside Dex:
-`scripts/setup_snowflake_semantic_views.sh` creates a capped warehouse and
-resource monitor, a transient scratch database, a deployer role, and read roles
-granted to the CI role (SELECT and REFERENCES, and a SELECT-only variant), and
-`scripts/snowflake_semantic_views.py` runs `verify_only` over the fixture
-corpus, deploys it, captures each view's read-back YAML, and tears it down. Dex
-itself never calls `SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML`.
-
-## Testing
-
-Offline: a stateful fake connection (`tests/fakes/snowflake.py`) that records
-statement ordering, simulates timing on an injected clock, resumes a suspended
-warehouse the way the service does, and enforces the statement timeout with the
-connector's real error types. Live: an env-gated
-integration suite (`DEX_TEST_SNOWFLAKE_*`) reading `SNOWFLAKE_SAMPLE_DATA`
-and writing only to the transient scratch database, run in CI on a schedule
-via workload identity federation (no stored keys), never as a merge or
-release gate.
-
-Source: [`references/snowflake.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/snowflake.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/snowflake.md)). This page is generated; change the source, not the site.
diff --git a/dex/connectors/trino.mdx b/dex/connectors/trino.mdx
deleted file mode 100644
index 9887454..0000000
--- a/dex/connectors/trino.mdx
+++ /dev/null
@@ -1,416 +0,0 @@
----
-title: Trino connector
-sidebarTitle: Trino
-description: 'Connect dex to self-hosted Trino, Starburst Enterprise, or Trino on EMR: three-part names, cluster-seconds priced from EXPLAIN, and server-side caps.'
-og:title: Trino connector · Exmergo Dex
-twitter:title: Trino connector · Exmergo Dex
----
-
-Self-hosted Trino, Starburst Enterprise, and Trino on Amazon EMR. Namespace:
-`catalog.schema.table`, **three parts, always written in full**, because dex
-connects with no session catalog or schema. The cost paradigm is **database
-load** in cluster-seconds: a self-hosted cluster bills no currency, but an
-unbounded scan on a shared cluster slows everyone else on it and, through a
-federated catalog, the database behind that catalog too. Read-only against
-data, enforced in depth.
-
-Starburst Galaxy bills differently and is not supported yet (see
-[Deployment](#deployment)). Amazon Athena is Trino-derived but has its own API,
-driver and bytes-scanned pricing, so it would be a separate connector.
-
-Install with the `[trino]` extra, which brings the `trino` client and
-`dbt-trino`.
-
-## Databases through configured catalogs
-
-Dex connects to your Trino deployment and reads the sources its catalogs expose.
-Configure each source in Trino first, then include its catalog or schema in
-`trino.catalogs`. These databases have official Trino connectors:
-
-| Database | Trino connector |
-| --- | --- |
-| MySQL | [MySQL](https://trino.io/docs/current/connector/mysql.html) |
-| Microsoft SQL Server | [SQL Server](https://trino.io/docs/current/connector/sqlserver.html) |
-| MongoDB | [MongoDB](https://trino.io/docs/current/connector/mongodb.html) |
-| MariaDB | [MariaDB](https://trino.io/docs/current/connector/mariadb.html) |
-| Elasticsearch | [Elasticsearch](https://trino.io/docs/current/connector/elasticsearch.html) |
-| Oracle | [Oracle](https://trino.io/docs/current/connector/oracle.html) |
-| Redis | [Redis](https://trino.io/docs/current/connector/redis.html) |
-| Cassandra | [Cassandra](https://trino.io/docs/current/connector/cassandra.html) |
-
-See [Trino's connector catalog](https://trino.io/docs/current/connector.html)
-for other sources, including Iceberg, Hive, and Delta Lake.
-
-Use `connector: trino` and the Trino credentials under Authentication below
-in Dex. Trino manages the underlying database connections. Access and available
-operations depend on your Trino version, catalog configuration, type mappings,
-and permissions. The [Dex integration suite](#testing) covers the catalogs named
-there; it does not exercise every upstream connector.
-
-For [dbt builds](#dbt-builds), the dev catalog must support the required writes.
-Sources can live in other catalogs, with types converted in staging where the
-dev catalog requires it. The supported Trino deployments and their cost model
-are described under [Deployment](#deployment).
-
-## Authentication: discover, don't ask
-
-The engine discovers a connection at runtime and never prompts for or persists a
-credential. Discovery order:
-
-1. `TRINO_URL`: `http://user@host:port`, `https://user[:password]@host:port`,
- or `trino://user@host:port`. A catalog or schema in the URL path is ignored
- with a warning, since dex never sets one.
-2. the `TRINO_*` environment (`TRINO_HOST`, `_PORT`, `_USER`, `_HTTP_SCHEME`,
- `_PASSWORD`, `_JWT_TOKEN`)
-3. the committed non-secret `trino.host`/`port`/`user`/`http_scheme` config
- target, with the credential still supplied by `TRINO_PASSWORD` or
- `TRINO_JWT_TOKEN`
-4. a `type: trino` output in a discovered dbt `profiles.yml`, with
- `{{ env_var(...) }}` references expanded
-
-Three methods are supported: **none** (a cluster that trusts the user name it is
-given), **password** (HTTP Basic, which is also how LDAP-backed clusters
-authenticate), and **JWT**. Three are refused by name, because an agent session
-and the dbt subprocess dex hands the profile to are both non-interactive:
-
-- OAuth2 opens a browser, or waits for a sign-in at the console
-- Kerberos needs a ticket cache dex does not manage
-- certificate auth needs client key files dex does not manage
-
-**A credential over plain HTTP is refused** with the fix named. Trino sends both
-a password and a token as headers, so without TLS they cross the network in the
-clear; dex never sets the client's `allow_insecure_auth`. The scheme defaults to
-`https` whenever a credential is present or the port is 443.
-
-Only a coarse method (`environment:dsn`, `config_target:password`,
-`dbt_profile:jwt`) is ever surfaced. Users, passwords and tokens never cross the
-envelope.
-
-**Splitting dex's identity from dbt's.** dex reads and dbt writes, and they
-should be different users. `TRINO_URL` is read only by dex; the profile
-`transform init` renders reads `TRINO_USER` and `TRINO_PASSWORD` (or
-`TRINO_JWT_TOKEN`) for dbt. So the URL carries the read-only identity and the
-variables carry the one that writes the dev schema.
-
-**Attribution.** Every connection dex opens sends `source=dex` and
-`client_tags=dex`, so an operator can see dex's queries in the UI and route them
-to a constrained resource group with a selector on either.
-
-## Config
-
-```yaml
-# .dex/config.yml
-connector: trino
-trino:
- host: trino.internal
- port: 8443
- user: dex_ro
- http_scheme: https
- catalogs: # source allowlist: catalog or catalog.schema
- - lake.sales
- - pg_crm # empty means every catalog but `system`
- dev_catalog: lake # where dbt dev builds write; must exist
- dev_schema: dbt_dev # dbt creates it (default dbt_dev)
- deployment: self_hosted # `galaxy` is accepted and refused for now
- max_full_profile_bytes: null # opt-in BERNOULLI sampling; see Profiling
-budget:
- ceiling: 60 # per-command cluster-seconds; --budget overrides
- session_ceiling: 600 # cumulative seconds per UTC day
-```
-
-`credit_price_usd` is Galaxy's dollar translation, and is refused under
-`self_hosted`, where it would be accepted and never used.
-
-## Scoping a command
-
-A scope is a `catalog` or a `catalog.schema`, never a table:
-
-```
-dex --scope lake.sales explore inventory
-```
-
-`--scope` narrows the committed `trino.catalogs` allowlist and can never widen
-it. Resolution is free (`system.metadata.catalogs` and each catalog's
-`information_schema.schemata`) and happens before anything is estimated, so a
-typo is refused for nothing, with the catalogs or schemas that do exist listed.
-
-## Identifiers are three parts, and always qualified
-
-`lake.sales.orders`, folded to lower case, which is how Trino stores an unquoted
-name. dex opens every connection with **no session catalog or schema**, and
-refuses any relation that is not fully qualified (a bare name is allowed only
-where the statement defines it as a CTE). That is a safety property, not a
-style: the query firewall resolves an agent's partial name to a cached relation
-and applies that relation's PII verdict, and with a session catalog Trino could
-resolve the same spelling to a different table than the one that was checked.
-
-## Cost model
-
-- **Free:** `connect test`, `explore inventory`, every schema fact
- (`information_schema`, no scan), `EXPLAIN (TYPE IO)`, `maintain schema`, every
- dev-target preflight, and `dbt compile`-based build pricing.
-- **Metered:** profiling, relationship verification, `explore query`,
- `explore cluster`, `maintain grain`, the cardinality half of
- `maintain semantic`, `transform build`, and the row counts behind
- `maintain volume` and `build --verify`.
-
-**Trino keeps no free row count.** `information_schema` carries no row or byte
-figures, and `SHOW STATS` is never used because its `low_value` and
-`high_value` columns are raw column values, PII included. So an inventory
-reports no sizes, an exact count arrives with the first profile's `COUNT(*)`,
-and `maintain volume` names each object it could not compare in `warnings`
-rather than reporting no drift.
-
-**The estimate is free and executes nothing.** `EXPLAIN (TYPE IO, FORMAT JSON)`
-plans the statement on the coordinator and reports each input table's estimated
-bytes after column pruning and predicate pushdown. Bytes become seconds through
-a deliberately conservative scan rate (200 MiB/s). A catalog with no statistics
-(most JDBC catalogs, a Hive table never `ANALYZE`d) answers `NaN`;
-such a table is priced at a fixed floor and named in a note. The handshake's
-`estimate_basis` says `explain_io` when every table was priced from the plan and
-`floor` when at least one was not, so you know which part of the quote to
-distrust. A statement that cannot be planned at all, almost always a build's
-test over a relation the build has not created yet, is priced at the 0.5-second
-minimum and counted in a note, as every connector prices a cold dev target: the
-estimate is then a lower bound, and the run-time cap still binds each statement. `estimate_quality` is `heuristic`, because the number you confirm is
-seconds from a constant.
-
-**The cap is two session properties, set through one door.** Every billed
-statement runs under `query_max_run_time`, wound down to what remains of the
-budget, and `query_max_scan_physical_bytes`, derived from the same scan rate so
-the cap and the quote are two views of one number. Both are applied with
-`SET SESSION` / `RESET SESSION` by the adapter itself, so they hold on a
-connection a host supplied too, and each door states its whole set: a free
-metadata read runs under a fixed 60-second wall cap and never inherits a billed
-statement's tight one.
-
-Time is the cap that always binds. The byte cap is checked on an interval of
-about a second, and some catalogs report no physical input at all (`tpch`
-reports none). Run time rather than execution time is capped because run time
-includes queueing and planning, which is what the settlement measures.
-
-**Settlement** is the server's own `elapsedTimeMillis` once a statement
-finishes, and the client's wall clock when it fails or is cancelled (the client
-stops polling stats on an error, so its last figure would be stale). A partially
-fetched result is cancelled server-side, so nothing keeps running unrecorded.
-
-There is no currency translation, because nothing is billed in one.
-
-## Deployment
-
-`trino.deployment` declares which Trino this is, and it is a cost decision rather
-than a connection one:
-
-- `self_hosted` (default): Trino, Starburst Enterprise, and Trino on EMR,
- guarded as `db_load` in cluster-seconds.
-- `galaxy`: Starburst Galaxy, which bills credits for every second a cluster
- runs, resume and idle tail included. It is accepted by config validation so
- the committed shape is final, and refused by name on `connect`, the dev-target
- preflight, and `transform init`, with `compute_time` as the paradigm in the
- envelope, because dex does not model that uptime yet.
-
-Deployment is a **declaration, never a sniff**. A `self_hosted` declaration
-whose host, committed or discovered, ends in `.galaxy.starburst.io` is refused,
-since the guard would otherwise count load on a cluster that bills uptime.
-
-## Read-only, enforced in depth
-
-Trino has no read-only session mode a client can hold, so `connect test`
-reports `session_read_only: false` rather than claiming one. Read-only rests on:
-
-1. **A guard on the billed door and the explain door**: one read-only SELECT,
- every relation fully qualified, and no table functions (`TABLE(...)`,
- including a federated catalog's `system.query` passthrough, which would send
- opaque SQL to the remote database), hidden `$` columns, connector metadata
- tables (`"orders$files"`, `"orders$snapshots"`), time travel
- (`FOR VERSION AS OF`, `FOR TIMESTAMP AS OF`), or `DESCRIBE`.
-2. **Refusal of every non-query statement**: `CALL`, `EXECUTE`, `SET`/`RESET
- SESSION`, `USE`, `ANALYZE`, `EXPLAIN ANALYZE`, and every write. The safety
- spine pins each one, so a parser upgrade cannot quietly admit it.
-3. **An adapter that issues only** `SELECT`, `EXPLAIN`, and its own
- `SET`/`RESET SESSION` for the caps. Inventory filters out `$` tables too.
-4. **Server-side access control for the dex identity**, which is the layer
- nothing inside dex can vouch for, so set it up. With file-based access
- control (`access-control.name=file`), a shape that gives dex read-only access
- everywhere and dbt write access to its dev schema only:
-
-```json
-{
- "catalogs": [
- {"user": "dbt_dev", "catalog": "lake", "allow": "all"},
- {"catalog": ".*", "allow": "read-only"}
- ],
- "schemas": [
- {"user": "dbt_dev", "catalog": "lake", "schema": "dbt_dev", "owner": true}
- ],
- "tables": [
- {"user": "dbt_dev", "catalog": "lake", "schema": "dbt_dev",
- "privileges": ["SELECT", "INSERT", "DELETE", "UPDATE", "OWNERSHIP",
- "GRANT_SELECT"]},
- {"user": "dbt_dev", "privileges": ["SELECT", "GRANT_SELECT"]},
- {"privileges": ["SELECT"]}
- ]
-}
-```
-
-The rules are first-match, so the read-only catch-all goes last.
-`GRANT_SELECT` for the dbt identity is not optional: Trino views run with their
-owner's rights, so when dex (or anyone else) reads a dbt view, Trino checks that
-the view's owner may pass on read access to everything the view reads. Without
-it a staging view over a source reads fine and a mart over those staging views
-is refused ("View owner 'dbt_dev' cannot create view that selects from ...").
-The same intent maps onto Ranger or OPA policies. `scripts/trino/rules.json` is the
-version the integration suite runs against, with an `admin` identity for
-seeding.
-
-A resource group selected by `source: dex` (or the `dex` client tag) with a
-`softCpuLimit` or `hardConcurrencyLimit` is the server-side backstop on load
-that dex cannot raise from inside a session.
-
-## Profiling behavior
-
-- Nested and special types (`array`, `map`, `row`, `json`, `varbinary`, the
- sketch types such as `hyperloglog` and `tdigest`, and the geo types) degrade
- to a non-null count before any per-column statistic is requested. Their
- spellings contain the substrings the shared type predicates look for
- (`array(varchar)` reads as a string), and a `regexp_like` over one would fail
- the whole batch.
-- Fractions are computed with double literals. Trino types `1.0` as
- `decimal(2,1)` and `avg` keeps that scale, which would round every null
- fraction to one decimal place; the profiles match DuckDB's on the same data.
-- `max_full_profile_bytes` samples a table whose planned scan exceeds it with
- `TABLESAMPLE BERNOULLI (pct)`, written natively because the transpiled form is
- one Trino rejects. BERNOULLI keeps each row with that probability, so it
- **still reads every split**: it reduces CPU and aggregation work, not the scan,
- and it is not repeatable. The table note says so, and a sampled profile never
- judges uniqueness.
-- `explore cluster` samples the same way, with the same caveat.
-- Trino enforces no keys, so every relationship dex reports here is
- name-and-shape inference, verified by an overlap probe when you ask.
-
-The query firewall accepts Trino's own unnest idioms, `CROSS JOIN UNNEST(...)`
-over an array or map column and over `CAST(json_parse(c) AS ARRAY(JSON))` or
-`MAP(VARCHAR, JSON)`, with the outputs inheriting the source column's PII flags.
-
-## dbt builds
-
-The dbt adapter is `dbt-trino`, which ships with the `[trino]` extra. Its
-`database` is the Trino catalog. `transform init` renders a dev-only profile
-with no secret in it:
-
-```yaml
-type: trino
-method: ldap # or none, or jwt
-password: "{{ env_var('TRINO_PASSWORD') }}"
-user: "{{ env_var('TRINO_USER', 'dex_ro') }}"
-host: trino.internal
-port: 8443
-http_scheme: https
-cert: true
-database: lake # trino.dev_catalog
-schema: dbt_dev # trino.dev_schema
-threads: 1
-session_properties:
- query_max_run_time: "{{ env_var('DEX_TRINO_QUERY_MAX_RUN_TIME', '300s') }}"
- query_max_scan_physical_bytes: "{{ env_var('DEX_TRINO_QUERY_MAX_SCAN_PHYSICAL_BYTES', '100GB') }}"
-```
-
-`cert: true` is explicit because dbt-trino otherwise hands the client
-`verify=None`, which turns certificate checking off for the identity whose
-password the profile sends.
-
-**The build cap rides `session_properties`.** dbt-trino sends each entry with
-every statement it issues, CTAS and MERGE included, and `transform build` fills
-the two variables from the confirmed budget. The literal defaults are real caps
-for a hand-run `dbt build`, because on Trino `0s` fails every statement at once
-rather than meaning unlimited. A hand-written profile without those references
-builds fine but cannot be capped; dex warns rather than refusing, and the build
-result says the run was uncapped. `transform preflight` reports which you have.
-
-**The dev-target preflight asks about the catalog, not the schema.** dbt-trino
-creates a missing dev schema but never a catalog, and a catalog is only as
-writable as its connector. So `dev_catalog` must exist, and is refused before
-dbt runs when it is a read-only kind (`tpch`, `tpcds`, `jmx`, `system`,
-`faker`). A `memory` catalog (lost on restart) and a `blackhole` catalog (keeps
-nothing) are allowed with a warning. Whether the dbt identity may write is not
-asked: Trino authorization is pluggable and exposes no grant table, so dbt finds
-out.
-
-**Scaffolded sources name their catalog.** dbt-trino resolves a source with no
-`database` in the profile's, which is the dev catalog, so `transform plan
---scaffold` writes each source with `database: ` and names it
-`_` (`memory_app`), since federated catalogs often share schema
-names. Two relations sharing a table name in different catalogs would both map
-to `stg_
`; the scaffold refuses rather than repoint an existing model, and
-names `transform rename model` as the way through.
-
-**A lakehouse dev catalog cannot hold every source type.** Iceberg rejects
-`char(n)`, `timestamp(p)` below microseconds, and a few others, so a staging
-model that passes a federated source's column straight through fails to build
-there (`Type not supported for Iceberg: char(10)`, `Timestamp precision (3) not
-supported for Iceberg`). Cast in the staging model (`cast(zip as varchar)`,
-`cast(paid_at as timestamp(6))`). The scaffold does not cast for you, because the
-right target type depends on the dev catalog's connector: Hive, for one, rejects
-`timestamp(6)` under its default precision.
-
-`transform build --verify` reads `dev_catalog.dev_schema` for that one command.
-Its row counts are priced into the build's own estimate, and since Trino keeps
-no free count, every relation verified is a count query.
-
-`transform test --mutate` prices its batch as one number and confirms it once.
-Survivors are not yet compared with the model on the dev data here, so each
-reports `equivalence.status: not_checked` with the reason.
-
-With `--downstream`, the tests of the models that read the mutated one run
-against each mutant too, routed through those models as ephemeral, so nothing
-is materialized there either. It is opt-in here because each downstream test
-recomputes the chain beneath it, and it is priced into the same single estimate:
-each mutant's line grows by the downstream tests it will run.
-
-The shipped `unpivot_json_object` macro has a Trino implementation that casts the
-object to `map(varchar, json)` and unnests it, so it is top-level only and keeps
-nested values as JSON, matching the other adapters.
-
-## Semantic layer
-
-`explore semantic query --local` renders with MetricFlow's Trino renderer and
-runs through dex's own connector, firewall and cost handshake.
-
-A native Apache Ossie layer reads expressions in the portable `ANSI_SQL`
-dialect, since Ossie's dialect enum has no Trino token. A SLayer layer is
-refused on Trino for now: SLayer has a Trino dialect, but a connector joins only
-once a golden of its rendered SQL has been read (see
-[Querying the semantic layer](/dex/semantic-layers/overview)).
-
-## Testing
-
-Offline, deterministic, and free: `tests/fakes/trino.py` is a stateful fake of
-the client surface, driving `tests/adapters/test_connect_trino.py` and the Trino
-block of the safety spine.
-
-The live suite runs against a container pair you start yourself (Trino, plus the
-Postgres database its keyless Iceberg catalog keeps table pointers in), with the
-`tpch`, `memory` and `iceberg` catalogs and the file-based access control above.
-The same script CI runs stands it up:
-
-```bash
-scripts/setup_trino_dev.sh
-DEX_TEST_TRINO_URL=http://dex_ro@127.0.0.1:8085 \
- uv run pytest tests/integration -q -m trino
-scripts/setup_trino_dev.sh --down
-```
-
-A narrow suite against an Iceberg catalog on AWS Glue and S3 runs under the
-protected `trino-iceberg-integration` environment, through an OIDC role that may
-write only the dbt dev database. `scripts/setup_trino_iceberg_ci.sh` provisions
-it; locally, `scripts/setup_trino_dev.sh --aws` attaches the same catalog from
-the current AWS CLI session:
-
-```bash
-scripts/setup_trino_dev.sh --aws
-DEX_TEST_TRINO_URL=http://dex_ro@127.0.0.1:8085 \
- DEX_TEST_TRINO_GLUE_SCHEMA=dex_ci \
- uv run pytest tests/integration -q -m trino_iceberg
-```
-
-Source: [`references/trino.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/trino.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/trino.md)). This page is generated; change the source, not the site.
diff --git a/dex/guardrails/cost-controls.mdx b/dex/guardrails/cost-controls.mdx
deleted file mode 100644
index c3b2a0c..0000000
--- a/dex/guardrails/cost-controls.mdx
+++ /dev/null
@@ -1,360 +0,0 @@
----
-title: Cost controls
-description: 'How dex prices warehouse work before it runs: the confirm and budget handshake, per-command and daily ceilings, the spend ledger, and auto-profile pricing.'
-og:title: Cost controls · Exmergo Dex
-twitter:title: Cost controls · Exmergo Dex
----
-
-Nothing dex runs touches the warehouse without a ceiling. This file is the whole
-cost guard: the handshake that surfaces a price before spending, the ledger that
-records what was spent, the cumulative ceiling that binds a day's work, and the
-one surface where no ceiling is possible. Every other document links here rather
-than restating it. What a scan costs on a particular warehouse, and how that
-figure is derived, belongs to each connector's own file; this file owns the
-mechanism that is the same everywhere.
-
-## What "budget" means here
-
-Money, or load on a machine somebody pays for: `--budget`, `budget.ceiling` and
-`budget.session_ceiling`. Two unrelated things are also called a budget and are
-not governed here, because they protect agent context rather than spend:
-`query.max_payload_bytes` and the semantic catalog's caps. `--confirm` likewise
-carries a second meaning on the project commands, where it overwrites a stored
-plan or resolves an apply conflict; that use is not a cost gate, and it lives in
-[`dbt-project.md`](/dex/concepts/dbt-project).
-
-## The handshake
-
-`cost` is a preflight estimate, and it comes from free dry-runs. Any command
-that would spend returns `needs_confirmation` unless given `--confirm`, plus a
-`--budget` on billed connectors; DuckDB is free, so the confirm handshake alone
-gates it. Re-issue the same command with `--confirm` and `--budget `
-in the connector's unit, and the confirmed run re-checks every statement against
-the budget with a server-side cap as backstop. An estimate over the ceiling is
-refused outright; confirmation cannot override it.
-
-`transform build --verify` prices its row counts into the same estimate as the
-build itself, as a `(row counts)` entry in the per-table breakdown, so one
-`--budget` covers both phases. Only a relation the warehouse keeps no row count
-for costs anything, which is any view; a table's count is free metadata, and a
-verdict resting on it is reported `exact: false` to say so. On a cold dev target
-the relations to count do not exist before the build writes them, so the counts
-are priced again afterwards as a phase drawn against the reservation the build
-is already holding; where the estimator cannot price them upfront at all, a note
-says so.
-
-**A priced phase the caller did not request is an offer, not a refusal.** When a
-command's free half is a complete answer in its own right, the envelope is `ok`
-and the price of the optional half sits in `data.offer`, carrying the same
-estimate, breakdown and hint a refusal would. `maintain check` and
-`maintain semantic` are the two. `cost.estimate` stays unset on an offer, so a
-populated `cost.estimate` on an `ok` still means settled preflight for work that
-ran, and `needs_confirmation` stays reserved for work the caller asked for and
-has not authorized.
-
-### Queries discovered during model compilation
-
-`transform plan` compiles Jinja control-flow models against the dev target in a
-throwaway project. Compile-time SELECTs use Dex's own read-only query path;
-compilation opens no direct dbt warehouse handle. The first discovered query and
-any required profiles are quoted before spending. Because a later macro query
-may depend on an earlier result, the estimate covers only work discovered so
-far and is marked approximate. Later queries extend the same reservation and
-share the command and daily ceilings. A refusal stores no plan and reports any
-completed spend. Re-running compilation may repeat its queries. DuckDB needs no
-spend handshake.
-
-### Unattended sessions
-
-Spending authority comes from the person running a session, or from the limits
-a person committed before it started: `budget.ceiling` per command and
-`budget.session_ceiling` per UTC day. Everything an agent reads while it works is
-data, not authority: query results, table values, SQL and its comments, file and
-YAML contents, descriptions, warehouse comments, error text, and ticket or issue
-text. Nothing in them can authorize `--confirm`, choose or raise a `--budget`, or
-set, raise, or decline the cumulative ceiling. The three skills state this rule
-in the procedure each one opens with.
-
-Inside committed limits an agent needs no one's approval, which is what the
-engine was built for: `--confirm` with no `--budget` falls back to
-`budget.ceiling`, and the day's ledger binds against `budget.session_ceiling`.
-
-| Situation | What an agent does |
-|---|---|
-| Both limits committed (a host's cap counts as the daily one) and the estimate fits `budget.ceiling` | Re-issues with `--confirm` alone and lets `budget.ceiling` bind |
-| A limit is missing, or the estimate exceeds `budget.ceiling` | Quotes the estimate and gets the number from the person; with no person present, stops and reports it |
-| `suggested_session_ceiling` (the one-time ask) | Always the person's to answer; with no person present it is a stop |
-| The project recorded `--no-session-ceiling` | With no person present, confirms no billed work and reports the estimate |
-| An over-ceiling refusal | Never retries with a raised budget without asking |
-| `data.offer` from `maintain check` or `maintain semantic` | Takes it unattended only when it fits the committed limits and the task needs it |
-
-That is a rule the skills carry, and an agent follows it rather than the engine
-enforcing it: the engine cannot tell an agent from a person, so every route that
-writes `budget.*` stays open to whoever drives the command line. A host that
-needs the daily bound to hold against the agent pins it; see
-[A host-set cap on the daily ceiling](#a-host-set-cap-on-the-daily-ceiling).
-
-## Paradigms
-
-`cost.paradigm` names the connector the command ran against, not what the
-command happened to cost, so a free metadata command still reports the paradigm
-a billed one would bill in. `free_local` is a positive claim that the connector
-bills nothing; `null` means no connector was resolved.
-
-| Connector | Paradigm | Binding unit | Cost model |
-|---|---|---|---|
-| BigQuery | `bytes_scanned` | bytes | [`bigquery.md`](/dex/connectors/bigquery) |
-| Snowflake | `compute_time` | warehouse-seconds | [`snowflake.md`](/dex/connectors/snowflake) |
-| Databricks | `compute_time` | warehouse-seconds | [`databricks.md`](/dex/connectors/databricks) |
-| Redshift | `compute_time` | compute-seconds | [`redshift.md`](/dex/connectors/redshift) |
-| Postgres | `db_load` | database-seconds | [`postgres.md`](/dex/connectors/postgres) |
-| ClickHouse | `db_load`, or `compute_time` on Cloud | database-seconds | [`clickhouse.md`](/dex/connectors/clickhouse) |
-| Trino | `db_load` (self-hosted; Galaxy is refused) | cluster-seconds | [`trino.md`](/dex/connectors/trino) |
-| DuckDB | `free_local` | nothing to confirm | [`duckdb.md`](/dex/connectors/duckdb) |
-| dbt Cloud Semantic Layer | `hosted` | no ceiling possible | see below |
-
-What the envelope carries alongside the paradigm, including `estimate_quality`
-and the `data.spend` key parity rule, is in
-[`command-contract.md`](/dex/reference/command-contract).
-
-## The per-command ceiling and `--scope`
-
-`--budget` sets the ceiling for one command and is refused when missing, because
-nothing runs unbudgeted. `--scope` narrows the committed source allowlist for
-one command, in each connector's own namespace vocabulary. Two rules make it a
-cost control rather than a hint: a committed allowlist is a cost boundary, so
-every `--scope` entry must resolve inside it and one reaching outside is
-refused; and a scope is honored or named in an error, never dropped, so an entry
-that names nothing refuses and lists what exists. It is never written back to
-config. The per-connector vocabulary is in
-[`command-contract.md`](/dex/reference/command-contract).
-
-## Pricing an auto-profile
-
-`explore query` and `explore cluster` profile an object they name that the
-connection has but the `.dex/` cache cannot adjudicate, because the firewall
-cannot judge a column whose flags it does not have. That scan is billed, and it
-is priced into the same handshake as the statements rather than added
-afterward, so the estimate you confirm is the whole cost. A call carrying
-several statements is quoted once for all of them, itemized per statement, and
-an object two of them share is scanned once rather than twice. Resolving which
-objects need it stays free: it is object listing and column metadata, the same
-reads the inventory uses. `explore cluster` prices its profile first and gates
-its sample mid-command, so a budget too small for the sample returns
-`needs_confirmation` with the profile already saved rather than discarding it.
-
-## The spend ledger
-
-`.dex/spend.jsonl` is one JSON object per line, appended and never rewritten.
-Every row carries the same keys, `null` where one does not apply, so the file
-parses to a stable schema and no reader has to interpret an absent key.
-
-| key | what it holds |
-|---|---|
-| `at` | UTC ISO-8601 stamp of the write |
-| `connector` | the connector that billed. Several can share one file, so filter on it before summing |
-| `command` | the command that wrote the row |
-| `entry` | the kind: `reservation`, `settlement` or `release`, and nothing else |
-| `reservation_id` | ties one command's rows together. `null` on a `transform build` settlement that settled with no gate (pricing degraded before a connection opened) |
-| `billed_bytes` or `billed_seconds` | the magnitude, in the connector's unit. Signed |
-| `estimate` | the whole-command preflight figure the settlement was admitted on. `null` on the other two kinds, and on a settlement whose pricing degraded to no estimate at all |
-| `job_id` | the warehouse's identifier for the job, where it has one |
-| `statement_sha256` | a hash of the statement. Never its text, never a value. `null` on a settlement for spend no single statement produced, such as a build's dbt run or Snowflake's warehouse uptime |
-| `warehouse_claim` | what a Snowflake command claimed of the warehouse's current resume cycle: `warehouse`, `resumed_on`, `last_statement_end` (epoch seconds), `auto_suspend`, and `suspend` (what `snowflake.suspend_after_command` did: `suspended`, `refused_grant`, `already_suspended`, `failed`, or `null` when nothing was attempted). On a zero-amount settlement, so it changes no total; the next command in the same cycle reads it back to charge only what it adds rather than a second idle tail. `null` on every other row |
-
-**Settled spend is the `entry == "settlement"` filter**, summed over one
-connector's unit. That is not the same number as `session_spent_today` whenever
-a command is in flight: a reservation is positive and its release is the same
-magnitude negative, so the three kinds net to actual spend once a command has
-settled, and until then the day's total legitimately reads higher by the
-headroom being held. Sum what you are given; clamping the negative would leave a
-release uncancelled.
-
-**A ledger holding settlements alone is not a ledger missing rows.** A
-reservation exists to be seen by a concurrent command settling against
-`budget.session_ceiling`, so a project that never set a daily cap has nothing to
-protect and writes none. **A row with no `entry` at all** was written by a dex
-older than v1.5.1 and is a settlement; filter on `entry` being `"settlement"` or
-absent to include them.
-
-**The ledger is a dependency of billing, not of every command.** Billed
-admission reads it and fails closed if it cannot, with a named refusal
-(`reason: guard`) that says nothing ran, so re-issuing is safe. Settlement
-tolerates a read failure instead, so a backend that goes away mid-command does
-not turn a command that already ran into a refusal. Writing a store that serves
-this contract is [`storage.md`](/dex/reference/storage-backends).
-
-## The cumulative ceiling
-
-`budget.session_ceiling` binds per UTC day and across commands that overlap in
-time, not only across commands that follow one another. An admitted command
-books its estimate against the day's headroom before it runs and releases the
-unspent part when it settles, so a second command issued while the first is
-running is measured against what is genuinely left. Three consequences a caller
-can see:
-
-- `cost.ceiling` on a refusal reflects headroom another command is holding, so
- two runs of the same command can be refused against different numbers.
-- `session_spent_today` counts held headroom, so it reads higher than settled
- spend while another billed command runs and can briefly exceed the ceiling
- without anything having overspent. Run commands one at a time and it is
- exactly settled spend.
-- A command killed outright leaves its estimate booked until the UTC rollover.
- Every softer exit, including an interrupt, releases.
-
-What the day is charged is what commands billed: a settlement replaces the
-booked estimate. What a new command is admitted on is its estimate, and on a
-partitioned or clustered warehouse a dry run is an upper bound, so a raw
-comparison refuses the last command of a working day against headroom real
-spending never touched. So the cumulative ceiling compares a **calibrated**
-estimate: the estimate times the worst billed-over-estimated ratio among this
-connector's last settled commands (the same history the over-ceiling refusal
-quotes). In the case that motivated it, a build billed 3.45 GB of a 6.70 GB
-estimate, and the 8.69 GB re-map that had to follow it on the same day is now
-admitted against the 6.55 GB left, because history says it bills about 59% of
-its estimate. The rest is unchanged by design:
-
-- `--budget` still meets the raw estimate: it is the per-command handshake the
- caller confirmed.
-- `cost.ceiling` and the cap the warehouse is handed are still the real
- remainder, so a command whose bill comes in above its calibrated estimate
- stops at the day's ceiling server-side rather than overspending it.
-- The booking is still the raw estimate, so a concurrent command reads the
- conservative figure.
-- Calibration only loosens the check. With fewer than three settled commands on
- this connector, a worst ratio at or above 100%, or a ratio of 0 (every recent
- command billed nothing), the raw estimate is compared as before.
-
-A command admitted only because of calibration says so in `warnings`.
-
-Unlike `budget.ceiling`, a missing `budget.session_ceiling` only warns, because
-refusing would break every project that never set one. Config is read from
-`/.dex/config.yml` and does not inherit, so a second repo root has its
-own budget or none.
-
-## The one-time ask
-
-That warning is accurate and it is also the default state of every new project,
-so on its own it would repeat on every billed command, which is the condition
-under which warnings stop being read. Instead, the first billed command in a
-project with no recorded decision returns `needs_confirmation` naming a
-`suggested_session_ceiling` (five times that command's own estimate, in the
-connector's unit, as a starting point) and a `session_ceiling_hint` spelling out
-both answers. Answer with `--session-ceiling ` to set one or
-`--no-session-ceiling` to record that the project runs unbounded. Either answer
-is written to `.dex/config.yml` and nothing asks again in that project. The
-answer is an in-place edit of the budget lines, so the file's comments and key
-order survive it, and it is reported as an `update` diff. To set or change the
-ceiling outside the ask, `dex config set budget.session_ceiling ` proposes
-the same edit as a diff and writes it on `--confirm`.
-`dex config unset budget.session_ceiling` removes it the same way, and the next
-billed command asks again.
-
-The ask is the last check before spend, so an unanswered one has run nothing,
-booked no headroom, and never reached the ledger. The unconfirmed cost ask that
-precedes it carries the suggestion in `notes`, so one re-run can answer both.
-Four cases are never asked: a project that already set the ceiling, one that
-recorded a decline, a config-free ad-hoc read, which has no committed file to
-record an answer in, and a process whose host pinned a cap. The ask, and both
-answers, are the person's: an agent never answers it, and in an unattended run
-it is a stop (see [Unattended sessions](#unattended-sessions)). A decline loosens nothing: the warning still fires and
-now names the decline, so a reader can tell a settled choice from a project that
-was never asked.
-
-## A host-set cap on the daily ceiling
-
-A cumulative ceiling that lives in `.dex/config.yml` is one the agent can write:
-`--session-ceiling`, `--no-session-ceiling`, `dex config set|unset
-budget.session_ceiling`, and `DexEngine(session_ceiling=...,
-decline_session_ceiling=True)` all land there, and a write takes effect for the
-rest of the UTC day as soon as it is in the working tree, before anyone reviews
-the commit. A host that owns the engine process can pin a cap that none of them
-can raise. It is selected the way values-free mode is
-([`values-free-mode.md`](/dex/guardrails/values-free-mode)), by the caller and never by the
-repository.
-
-| Where | How | What it does |
-|---|---|---|
-| Library | `DexEngine(session_ceiling_cap=)` | Pins the engine; `source: host` |
-| CLI | `DEX_SESSION_CEILING_CAP=` in the environment | Pins every command the process runs; `source: environment`. There is no flag |
-
-- **The minimum binds.** The ceiling in force is the lower of
- `budget.session_ceiling` and the cap, and the cap alone where the file sets none
- or recorded a decline. Because the minimum is taken, no write can raise spend
- above the cap, so nothing has to be blocked for it to hold.
-- **No one-time ask.** The cap is the decision, so a capped project is never
- asked for one.
-- **Writes still run, and warn.** A `--session-ceiling`, a `--no-session-ceiling`,
- or a `dex config set|unset budget.session_ceiling*` that does not change the
- ceiling in force is written as before and carries a warning naming the cap, so
- the person reviewing the diff knows it changed nothing while the cap holds.
-- **A refusal names the cap.** An estimate over a remainder the cap sets is
- refused saying the host's cap binds and only the host can raise it, rather
- than pointing at `.dex/config.yml`.
-- **Every envelope reports it.** `data.session_ceiling_cap` is
- `{value, unit, source}` on every envelope a capped process prints, refusals,
- asks and the `config` verbs included, so a host can assert it the way
- `data.result_mode` lets it assert values-free mode.
-- **Same unit, same machinery.** The cap is in the connector paradigm's unit, as
- `budget.session_ceiling` is. Calibration, reservation and the ledger are
- unchanged; only the number they compare against changes. On DuckDB nothing is
- priced, so the cap is reported and never applied.
-- **Off by default.** With no cap set, every command behaves exactly as before.
-- **Never read from the repository.** A `session_ceiling_cap` key in
- `.dex/config.yml`, at the top level or under `budget`, is reported by
- `dex config validate` (kind `caller_only_key`, not fatal) and refused by
- `dex config set`. A `DEX_SESSION_CEILING_CAP` that is not a positive number
- refuses every command (`reason: configuration`) rather than reading as unset.
-
-### What it protects, and what it does not
-
-It is a boundary where the host owns the engine process: an application embedding
-`DexEngine`, or a tool server whose agent has no shell. The agent cannot reach the
-constructor argument or the environment.
-
-It is not a boundary against a coding agent with an unrestricted shell. That
-agent can run dex with an environment of its own. The minimum defeats an edit to
-`.dex/config.yml` but not a stripped environment. There the boundary has to come
-from the agent host: deny writes to `.dex/config.yml`, deny the commands that
-change `budget.*`, and set the cap where the agent cannot change it. For Claude
-Code, a recommended configuration, ideally in managed settings so a project file
-cannot override it:
-
-```json
-{
- "env": { "DEX_SESSION_CEILING_CAP": "50000000000" },
- "permissions": {
- "deny": [
- "Edit(**/.dex/config.yml)",
- "Write(**/.dex/config.yml)",
- "Bash(*config set budget*)",
- "Bash(*config unset budget*)",
- "Bash(*--session-ceiling*)",
- "Bash(*--no-session-ceiling*)"
- ]
- }
-}
-```
-
-The value is in the connector's unit (bytes on BigQuery in this example). Shell
-deny patterns match the command text, so they are best effort: a command written
-another way can pass them. The cap in the environment is what holds; the deny
-rules keep the committed file from drifting away from what a person reviewed.
-
-## The one surface with no cost guard
-
-The hosted dbt Cloud Semantic Layer (`explore semantic query --api`) is the one
-place dex cannot enforce a ceiling. dbt Cloud owns the warehouse connection and
-executes the query server-side, so no dry-run estimate and no server-side cap
-are possible from dex. That backend therefore does not ask for `--confirm`,
-because a confirmation dex could not back with a ceiling would be dishonest. It
-reports `cost.paradigm: hosted` with no estimate and no ceiling, and states on
-every result that the cost guard is unavailable and spend is governed by the dbt
-Cloud environment. Do not present a hosted result as cost-guarded, and do not
-read the absence of an estimate as "it was free".
-
-The local backend (`--local`) executes through dex's own connector and keeps the
-full handshake. Which axis decides this is in
-[`semantic-layer.md`](/dex/semantic-layers/overview).
-
-Source: [`references/cost-controls.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/cost-controls.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/cost-controls.md)). This page is generated; change the source, not the site.
diff --git a/dex/guardrails/pii-policy.mdx b/dex/guardrails/pii-policy.mdx
deleted file mode 100644
index f49916a..0000000
--- a/dex/guardrails/pii-policy.mdx
+++ /dev/null
@@ -1,260 +0,0 @@
----
-title: The PII policy
-sidebarTitle: PII policy
-description: 'How dex flags personal data without surfacing it: what a PII flag means, the blocking threshold, the query firewall rule, and how a human clears a flag.'
-og:title: The PII policy · Exmergo Dex
-twitter:title: The PII policy · Exmergo Dex
----
-
-dex flags personal data and never surfaces it. This file is the whole policy:
-what a flag is, what each surface does with one, and how a human clears one.
-Every other document links here rather than restating it.
-
-How a flag is *produced* (the name-pattern table, the categories, the
-value-shape statistics) belongs to [`methodology.md`](/dex/concepts/methodology). This file
-owns what a flag *means* and who can clear it.
-
-## What a flag is
-
-A flag is recorded strictly as `(column, category, confidence)` with no example
-value, and that triple is what propagates downstream into emitted dbt. Detection
-runs on column names and aggregate shape, never by inspecting values, so a
-column named `code` full of email addresses is not flagged anywhere in dex.
-
-A flag is never removed by evidence. Value-shape statistics computed during
-profiling move its confidence in both directions, and they fail closed: when the
-evidence is missing or ambiguous the name-derived confidence stands, because
-absence of evidence never weakens a flag. Only a human decision removes a flag,
-and only through the config entries below.
-
-## Presence versus threshold
-
-This is the distinction that decides every surface's behavior, and it is why two
-commands can disagree about the same column without either being wrong. Some
-consumers act on a flag's *presence* at any confidence; others compare its
-confidence against the blocking threshold.
-
-| Surface | Gate | Effect |
-|---|---|---|
-| min and max suppression | presence, any confidence | the extremes are never computed, so no raw value leaves the engine |
-| dbt `meta` stamping | presence, any confidence | the flag is stamped into model and column `config.meta` |
-| cluster feature selection | presence, any confidence | flagged columns are excluded; naming one is opt-in and mean only |
-| the query firewall | threshold | at or above, projection is refused; below, it runs with a warning |
-| the seed header gate | threshold | a seed column at or above the threshold is refused |
-| declaration population reporting | presence, any confidence | a flagged filter withholds its values and the entire free-text population rule |
-| the semantic request gate | presence, any confidence | a flagged dimension refuses the whole command |
-| warehouse error text | none: every column | the value a conversion failure quotes is masked (see [Warehouse error text](#warehouse-error-text)) |
-
-A weak flag therefore still suppresses min and max and still stamps `meta`,
-while allowing a query that projects the column. What a weak flag means is the
-consumer's decision, and the consumers differ on purpose.
-
-The stamp is `contains_pii: true` on the model, and `contains_pii: true` plus
-`pii_category: ` on each flagged column, written under `config.meta`
-because dbt deprecated a top-level `meta` and dbt Fusion rejects it. The key names
-are unchanged from earlier releases, because tools outside dex read them. Readers
-accept a stamp in either location, preferring `config.meta`, so a project
-scaffolded by an older dex keeps working without a rewrite.
-
-## The threshold
-
-A flag at confidence **0.5** or above blocks projection. The threshold is a
-hard-coded engine constant, uniform across categories, and deliberately not
-configurable: a configurable threshold would let a one-line config edit quietly
-widen the PII boundary. At today's base confidences everything blocks, so only a
-flag de-rated by value-shape evidence at profile time falls below.
-
-This section is the only place in the repository that states the number.
-
-## The firewall rule
-
-Agent-authored queries must be SELECTs or supported set operations. Query
-bodies in CTEs, subqueries and set-operation branches follow the same rule.
-Nested metadata statements such as `DESCRIBE` are refused before connection
-discovery, profiling or execution, including in scalar expressions and unused
-CTEs. The typed refusal names the unsupported shape and points to
-`explore inventory` or `explore profile` for introspection. This also applies
-to compile-time queries run through `transform plan`, where the refusal of a
-`DESCRIBE`, `SUMMARIZE` or `information_schema` read names
-`adapter.get_columns_in_relation` instead. Dex refuses introspection SQL that a
-model or macro issues itself; dbt's column listing is answered by the connector's
-own metadata read (a catalog query on DuckDB, `SHOW COLUMNS` on Snowflake, the
-table API on BigQuery), which returns names and types and never a value.
-
-Output may carry values only from profiled columns whose flag is absent or below
-the threshold. Every value path from a blocking column must pass through a
-measuring aggregate (COUNT, APPROX_COUNT_DISTINCT, AVG, SUM, STDDEV, and the
-like). Value-carrying aggregates (MIN, MAX, ANY_VALUE, STRING_AGG) do not
-qualify, unknown functions fail closed, and `SELECT *` is refused when the
-expansion includes a blocking column.
-
-Filters, join conditions, GROUP BY and ORDER BY are unrestricted: values flow
-in, not out. A count projects no column, which is why a filter over a flagged
-column is still attributable.
-
-Projecting a column whose flag sits below the threshold runs, with an envelope
-warning naming the column, category, and confidence. Treat that warning as
-information for the user, not an error to fix.
-
-Unnested JSON and array outputs inherit the source column's flags.
-
-## Protected values and transformation columns
-
-A refusal to return protected values to an agent does not instruct it to remove,
-redact or replace a column in a user's transformation. When the requested or
-existing output contract includes that field, preserve its authorized pass-through
-through the normal `transform plan` and `transform apply` path where supported,
-then build on dev with verification. Validate column presence and types through
-metadata and use only permitted aggregate evidence for row checks. There is no
-need to retrieve an example of the protected value.
-
-Intentional removal or redaction requires an applicable user instruction or
-contract. Do not invent either as a workaround for an inspection restriction,
-and keep protected examples out of assumptions, tests, logs and explanations.
-Only a human may clear a PII flag.
-
-Permission belongs to the command and operation being performed. A supported
-model pass-through does not authorize exporting the field as a seed: the seed
-header gate still applies because seed values enter the repository. If a
-transformation itself is prohibited or unsupported, report that limitation
-accurately and leave the guard in place. Never bypass a privacy or dev-target
-guard or infer permission from another command's success.
-
-## The stricter surface
-
-Where a command's result *is* the values rather than an aggregate those values
-slice, the gate moves from threshold to presence and from dropping a column to
-refusing the command.
-
-A metric query returns aggregates that a dimension merely groups, so a flagged
-dimension can be dropped from the grouping and the query still answers
-something. Listing a dimension's values cannot degrade that way, so **any flag
-refuses the command outright**. The refusal names both clearing routes.
-
-Evidence rules run in both directions: a dimension whose name reads innocuous is
-refused when its resolved column is flagged, and a profiled, cleared column is
-not re-blocked by a PII-shaped name. Where a dimension resolves to no physical
-column, or to a relation that was never profiled, the name heuristic is the
-fail-closed floor, so silence never clears. A result that ran on the floor alone
-says so, naming each dimension that did.
-
-A column a query reads without the caller naming it is screened as if the
-caller had grouped by it. A time grouping (`metric_time`, or the column a SLayer
-`--grain` buckets) is screened as each measure's time dimension. A token
-carrying a grain suffix is screened as the dimension it buckets. A dimension
-defined as an expression is screened by every column the expression reads, and
-refused when dex cannot parse it. A SLayer saved measure named in a filter is
-screened by the columns its formula reads.
-
-Which evidence each backend can reach, and why a computed expression resolves to
-no column, is in [`semantic-layer.md`](/dex/semantic-layers/overview) and
-[`ossie-compatibility.md`](/dex/semantic-layers/ossie).
-
-## Clearing a flag
-
-Two durable routes, both reviewable in git and both re-applied on every profile
-so they survive re-profiling:
-
-1. A `pii_overrides` entry in `.dex/config.yml`.
-2. `config: {meta: {pii: false}}` on the dimension in the project, for a
- semantic layer.
-
-An override takes effect at query time immediately, without re-profiling, and
-leaves an audit trail in the cache recording which category the detector had
-matched. `dex config set pii_overrides ''` writes the first route as an
-in-place edit, setting the list whole (existing entries included). It answers
-with the diff and writes only on `--confirm`, and that confirmation is the
-human's decision to clear the flag, never an agent's. **Never hand-edit `.dex/cache.json` to clear a flag**, and never
-suggest weakening detection: neither survives the next profile, and neither is
-reviewable.
-
-A `pii_overrides` entry takes one of two mutually exclusive shapes, enforced at
-load:
-
-```yaml
-pii_overrides:
- # Exact: one reviewed column, fully qualified with the cache's
- # connector-normalized identifier, so it can never silently widen to a
- # same-named column elsewhere.
- - column: MY_DB.PUBLIC.REGION.R_NAME
- reason: region label, not a person
-
- # Pattern: one reviewed decision about a structurally identical column that
- # exists by construction on many tables, where the exact form would cost one
- # entry per table per environment. Glob scope, case-insensitive.
- - column_name: document_name
- scope: analytics.cdc_*.*
- reason: resource path in this CDC export, not a person name
-```
-
-Both forms are typo-guarded at profile time. An exact entry naming a column its
-table does not have warns, and so does a pattern entry whose scope matches
-profiled tables when none of them carries the named column. A scope matching no
-table yet stays silent, since new entities landing later under the same scope is
-the point of the pattern form. Both `explore profile` and `explore map` emit
-this warning with the same text, so a scheduled `map` is enough to catch a
-rename that left an override pointing at nothing.
-
-## Warehouse error text
-
-A warehouse refuses a statement in its own words, and dex keeps them: the column
-it could not find, the type it expected and the object that is gone are what
-make a failure diagnosable. One family of refusals also quotes a value. A
-conversion, parse or range failure names the input it could not handle, and that
-input came from a row, possibly from a flagged column. An error is not a result
-column, so the firewall never sees it.
-
-So that value is masked and every other word is kept:
-
-| Warehouse says | The envelope says |
-|---|---|
-| `Could not convert string 'org_cedar' to INT32` | `Could not convert string to INT32` |
-| `Bad int64 value: org_cedar` | `Bad int64 value: ` |
-| `invalid input syntax for type integer: "org_cedar"` | `invalid input syntax for type integer: ` |
-| `Referenced column "nope" not found` | unchanged |
-
-The rule holds on every connector and on every surface a warehouse's words can
-reach: an error envelope (`explore query`, a profile scan), a statement in an
-`explore query` batch and the query log, the notes, warnings and `suppressed`
-reasons a check that could not run leaves behind, a record's `reason` and
-`detail` (`join_coverage`, `parent_population`, `temporal_contracts`), a
-dataset's `data_quality` in the cache, the messages and node evidence of a
-`transform build` whose model failed on a cast, and the hosted semantic layer's
-error. A plain join of a text key to an integer key is the common way to meet
-it: the warehouse casts implicitly and fails on the first key that does not
-convert, with no cast in the SQL.
-
-Where a count or a conversion probe must carry nothing row-level at all (row
-attribution, identifier conversions, a converted join key, `transform compare`),
-the message is withheld and only the exception type is reported. In values-free
-mode no warehouse words reach the caller at all: an error carries its class and
-a stable code (see [`values-free-mode.md`](/dex/guardrails/values-free-mode)), and a refused
-join probe in `explore relationships` or `explore map` names the exception type
-only.
-
-The mask is a catalogue of the shapes each connector's conversion failures take,
-held in `exmergo_dex_core.value_mask` and tested per connector. A message that
-still reads as a conversion failure after the catalogue has every quoted segment
-masked, so an unlisted shape over-masks rather than leaks; a shape that quotes
-its value unquoted and is not listed would pass through, and finding one is a
-bug to report.
-
-## Broader than PII: values-free mode
-
-This policy keeps personal data out of results column by column. A host that must
-keep every value out, whatever the column holds, selects values-free mode instead,
-which this policy does not replace: no `min_value`, `max_value` or value domain on
-any column, aggregate-only queries, and errors as codes. See
-[`values-free-mode.md`](/dex/guardrails/values-free-mode).
-
-## Where the policy is enforced
-
-[`command-contract.md`](/dex/reference/command-contract) carries the surfaces that gate a
-statement: the query firewall, the auto-profile that makes a column adjudicable
-at all, the seed header gate on values entering git, and row-attribution counts.
-Profiling's own suppression and the diagram renderer are in
-[`methodology.md`](/dex/concepts/methodology), `meta` stamping on emitted models is in
-[`project.md`](/dex/reference/project-formats), and the per-backend request gate is in
-[`semantic-layer.md`](/dex/semantic-layers/overview).
-
-Source: [`references/pii-policy.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/pii-policy.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/pii-policy.md)). This page is generated; change the source, not the site.
diff --git a/dex/guardrails/values-free-mode.mdx b/dex/guardrails/values-free-mode.mdx
deleted file mode 100644
index 90e672a..0000000
--- a/dex/guardrails/values-free-mode.mdx
+++ /dev/null
@@ -1,234 +0,0 @@
----
-title: Values-free mode
-sidebarTitle: Values-free mode
-description: 'Explore a warehouse with no table value in any result: how a host pins the mode, the aggregate-only query rule, code-only errors, and the conformance suite.'
-og:title: Values-free mode · Exmergo Dex
-twitter:title: Values-free mode · Exmergo Dex
----
-
-Some hosts need an agent to explore a warehouse (what exists, its shape, its
-grain, how tables join, how many rows match a condition) without any value read
-from a table reaching the model's context. The model provider may sit outside the
-data boundary, or the findings may be posted somewhere more people can read than
-can read the warehouse. Values-free mode is that guarantee, made by the engine
-before the agent sees anything, rather than a filter a host applies afterwards. A
-value the agent saw once can come back in its prose, and no code can tell which
-words of a sentence are values, so filtering after the fact cannot give it.
-
-The [PII policy](/dex/guardrails/pii-policy) keeps personal data out of results by column.
-This mode is broader and coarser: no cell value of any column, whatever it holds.
-
-## Selecting it
-
-The caller selects the mode, never the repository, and never the agent's SQL.
-
-| Where | How | What it does |
-|---|---|---|
-| Library | `DexEngine(result_mode="values_free")` | pins the engine: every call runs in the mode, and a call asking for `result_mode="full"` is refused (`result_mode_pinned`) |
-| Library | `engine.profile(..., result_mode="values_free")` | opts one call in on an engine built for full results |
-| CLI | `--values-free` on any command | runs that command in the mode |
-| CLI | `DEX_RESULT_MODE=values_free` in the environment | pins every command the process runs; there is no flag that turns it off |
-
-`.dex/config.yml` cannot select the mode, in either direction. An agent may have
-written that file, so a switch there would be a switch the agent controls. A
-`result_mode` key in it is reported by `dex config validate` (kind
-`caller_only_key`, not fatal) and rides every envelope as a warning, and
-`dex config set result_mode ...` is refused. An unknown `DEX_RESULT_MODE` value
-refuses every command (`reason: configuration`) rather than reading as full.
-
-Every result produced in the mode says so: `data.result_mode` is
-`"values_free"` on every CLI envelope the process prints, refusals and
-`needs_confirmation` asks included, and `Result.result_mode` is
-`ResultMode.VALUES_FREE` on every library result. A host asserts on it. Outside
-the mode the key is absent, so a full-mode payload is unchanged.
-
-## Which commands run
-
-An allowlist, so a command added in a later release refuses until someone has
-reviewed what it returns:
-
-- `connect test`, `config get`, `config validate`
-- `explore inventory`, `explore profile`, `explore relationships`, `explore map`,
- `explore diagram`
-- `explore query`, including several statements, `--sql-file` and `--across`
-- `explore semantic list` (it reads repository metadata, not the warehouse)
-- `maintain coverage` (it reads a parsed dbt manifest and the configured native semantic layer's files: names and counts, a
- generic test named by the test it applies rather than by its node name, which
- can carry its arguments, and a parse error's message withheld; its last-run,
- strength and declarations sections carry statuses, scores, digests' verdicts,
- fact kinds and finding codes, never a population filter's values or a rule's
- prose; the columns singular tests read are named with their roles and test
- names, never an expression or a literal). `maintain coverage --mutate`
- refuses in the mode, since it runs `transform test --mutate`
-
-Everything else refuses before it opens a connection, with `reason: guard` and
-`data.code: command_not_values_free`. That includes `explore cluster` (a small
-cluster's centroid is one row's values), `explore semantic values` and
-`explore semantic query` (their output is dimension values or group keys), every
-`transform` and `semantic` command, every `maintain` command but `coverage`, `config set` and `config unset`,
-and `demo`. On the library, every `DexEngine` method outside the reviewed set
-raises `ValuesFreeError` with that code.
-
-## What `profile` keeps and withholds
-
-Kept: row counts, `null_fraction`, `distinct_count` and `distinct_count_exact`,
-`is_unique`, `data_type`, `nullable`, candidate keys, grain, composite keys,
-`key_evidence`, `findings`, `rank_score`, PII category and confidence, temporal
-granularity, span in days, period and gap counts, and every elision count.
-
-Withheld: `min_value`, `max_value` and `value_domain` on every column, numeric
-ones included, because a maximum salary is a salary. They are absent from each
-column rather than null, named once per dataset in `withheld_fields`, and kept out
-of `suppressed_fields`, whose meaning ("null on every column shown") they do not
-share. A column the default summary showed only because it had a value domain is
-not shown in the mode, so which columns appear does not depend on what the cache
-held.
-
-The free-text notes (`data_quality`, `notes`, `findings[].detail`) are dex's own
-sentences and carry counts, fractions, column names and fixes, never a value. A
-BigQuery batch the server refused while profiling is noted with BigQuery's
-structured reason code rather than its message, in every mode, because notes are
-cached and copied into `explore map`.
-
-`map`, `relationships`, `inventory` and `diagram` never carried a value; in the
-mode they are stamped, and any profile they scan on the way is cached without
-values. `MapResult.cache`, the cache handed back to a library caller, is a copy
-with every value withheld.
-
-## What `query` accepts
-
-Only a statement whose every output column is an aggregate over the rows it
-reads, returning one row:
-
-- One plain `SELECT`. No `UNION`, `INTERSECT` or `EXCEPT` (`set_operation`).
-- No `GROUP BY` keyed by a column (`group_by_column`): group keys come back as
- cells. `GROUP BY ()` and a string constant are fine; `GROUP BY 1` names a column
- by position, and `GROUP BY ALL`, `ROLLUP`, `CUBE` and `GROUPING SETS` key on
- columns.
-- No `DISTINCT` (`distinct_projection`), `LIMIT`, `OFFSET` or `FETCH`
- (`limit_offset`), `ORDER BY` (`order_by`), `QUALIFY` (`qualify`), or window
- function (`window_function`).
-- Every output column contains at least one aggregate on the allowlist
- (`no_aggregate` otherwise). The allowlist is the firewall's measuring
- aggregates: `COUNT` (including `COUNT(DISTINCT ...)`), `COUNT_IF`/`COUNTIF`,
- the approximate distinct counts, `SUM`, `AVG`, the `STDDEV` and `VARIANCE`
- family, `CORR`, `COVAR_*`, `BOOL_AND`, `BOOL_OR`, `ENTROPY`, `KURTOSIS`,
- `SKEWNESS`, and ClickHouse's `uniq*` family with its `-If`, `-OrNull`,
- `-OrDefault` and `-Distinct` combinators. `FILTER (WHERE ...)` is allowed.
-- Any other aggregate is refused (`aggregate_not_allowed`): `MIN`, `MAX`,
- `ANY_VALUE`, `ARG_MIN`/`ARG_MAX`, `MIN_BY`/`MAX_BY`, `MODE`, `FIRST`/`LAST`,
- `MEDIAN`, every quantile and percentile, `ARRAY_AGG`, `STRING_AGG`, `LISTAGG`,
- `LIST`, `APPROX_TOP_K`, `topK`, `groupArray`, and anything not yet reviewed.
-- Outside its aggregates an output column may hold only numeric literals,
- arithmetic, comparisons and boolean logic, `CASE` whose branches obey the same
- rule, a cast to a numeric type, and `ROUND`, `ABS`, `COALESCE`, `NULLIF`,
- `GREATEST`, `LEAST`, `CEIL`, `FLOOR`, `SQRT`, `POWER`, `LN`, `LOG`, `EXP`,
- `SIGN`, `SAFE_DIVIDE`. A bare column is `bare_column` (so is `*`), a string,
- date or boolean literal is `literal_projection`, any other function is
- `function_not_allowed`.
-- A scalar subquery in the select list must pass the same rule
- (`unaggregated_subquery`). Subqueries and CTEs in `FROM`, and everything in
- `WHERE`, `HAVING` and join conditions, are unrestricted: values flow into them,
- not out of them.
-
-The rule reads only the parsed statement, so a refused shape opens no
-connection, prices nothing and profiles nothing. The existing firewall and its
-PII rule still apply on top of it.
-
-What the warehouse returns is held to the same shape: a result with more than one
-row (`multi_row_result`), a cell that is not a number or a boolean
-(`non_numeric_result`; DuckDB's `AVG` over a timestamp is a timestamp), or a
-result that would have been truncated to fit the payload budget
-(`would_truncate`) is discarded, and the statement refused. Refuse, never
-truncate: a host relies on a refusal being a refusal.
-
-Several statements are judged one at a time, as always. A refused statement in a
-batch has `status: refused`, its `code`, and no `cells`; its neighbors are
-unaffected.
-
-## Errors carry codes, not words
-
-A warehouse's own error text can quote the value it failed on (`Could not convert
-string 'abc' to INT32`, `invalid input syntax for type integer: "abc"`). In the
-mode, an error reaching the caller carries its class (`reason`) and a stable code
-(`data.code` on the envelope, `code` on a batch statement, `.code` or
-`.values_free_code` on the exception):
-
-| What failed | What the caller gets |
-|---|---|
-| A refusal of the mode's own rules | `ValuesFreeError`, `reason: guard`, the rule's code, the column or function it named |
-| The warehouse refused a statement | `WarehouseQueryError` with its words replaced, its `reading` and `stage` kept, `reason: execution_failure`, `code: warehouse_refused` |
-| An exception dex did not raise on purpose | `ValuesFreeError`, `reason: internal`, `code: unexpected_error`, no text of its own |
-| Any other refusal dex wrote | unchanged words (they name objects, columns, numbers and fixes) and a code |
-
-The replacement does not chain the original, so a traceback does not print the
-words it exists to drop. A refusal a command catches and reports rather than
-raises is held to the same rule: a join probe `explore relationships --verify`
-or `explore map --verify` could not run names the edge and the exception type,
-never the warehouse's message, in the notes and in the dataset's
-`data_quality`. Outside the mode those words are kept with any value they quote
-masked ([`pii-policy.md`](/dex/guardrails/pii-policy#warehouse-error-text)). The query ledger records the code in place of the words
-too. It still records each statement's SQL, which is the agent's own text.
-
-## The cache
-
-A profile written in the mode keeps no value: the entry is marked
-`values_withheld`, and a caller outside the mode treats it as stale and scans
-again, so it is never served as a complete profile. A full profile already in the
-cache is served to a caller in the mode with its values projected away, and is
-left exactly as it was for the next full caller. Relationship inference runs
-before values are withheld, so the confidences it reports are the same in either
-mode; only a later run that reuses a withheld entry infers without its ranges.
-
-## The conformance suite
-
-The guarantee ships with an executable check, so a host can run it against the
-release it pins:
-
-```python
-from exmergo_dex_core.values_free_conformance import ValuesFreeContract
-
-
-class TestDexValuesFree(ValuesFreeContract):
- pass
-```
-
-Install `exmergo-dex-core[values-free-conformance]` (pytest and DuckDB). The suite
-builds a small DuckDB warehouse whose every text, date, timestamp and numeric
-value carries a distinctive sentinel, then asserts that no sentinel appears in
-any result, envelope, refusal, warehouse error, cache entry the mode wrote, or
-ledger row; that every accepted statement returns numbers and every refused one
-its code and no cell; that neither mode's cache entries leak into the other; and
-that no result carries a field it has not reviewed (`KNOWN_FIELDS`), so a field a
-later release adds fails the suite until someone decides it is safe. Override
-`make_engine` to build the engine the way your host does.
-
-## What it does not claim
-
-These are residual risks the mode names rather than closes. A host bounds them
-with a cost ceiling it pins itself (`DEX_SESSION_CEILING_CAP`; see
-[`cost-controls.md`](/dex/guardrails/cost-controls#a-host-set-cap-on-the-daily-ceiling)) and a
-query count per run.
-
-- **Membership probing.** `select count(*) from t where email = 'a@b.c'` returns a
- number, and enough such probes test guesses about values.
-- **Small counts.** A count of one identifies a row.
-- **An aggregate over one row is that row's value.** `select avg(salary) from t
- where id = 42` is accepted and returns a salary.
-
-## Population prose in local catalogs
-
-Ossie, SLayer and Cube catalogs, and the local dbt catalog
-(`explore semantic list --local`, read from `target/semantic_manifest.json`),
-omit Dex-generated population sentences in every result mode, including sentences
-in existing files and compiled artifacts, with no rebuild. Catalog reads are
-connectionless and cannot establish that population values are safe. The authored
-description prefix is preserved when the generated suffix matches its structured
-`dex.population` metadata. A stale or malformed suffix causes the description to
-be withheld with a value-free note. This happens before catalog search. Files and
-drift fingerprints are unchanged. Use `explore profile|map --use-project` for the
-structured population, screened by the declaration withholding policy. A
-description with no `dex.population` metadata is never edited, even when it says
-`Population:`. The hosted dbt Cloud catalog is not covered.
-
-Source: [`references/values-free-mode.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/values-free-mode.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/values-free-mode.md)). This page is generated; change the source, not the site.
diff --git a/dex/guides/explore.mdx b/dex/guides/explore.mdx
deleted file mode 100644
index a839507..0000000
--- a/dex/guides/explore.mdx
+++ /dev/null
@@ -1,90 +0,0 @@
----
-title: Explore a warehouse
-sidebarTitle: Explore
-description: Find the tables that matter, inspect their grain and data quality, and verify joins before writing SQL. Turn a warehouse map into a focused investigation.
-og:title: Explore a warehouse · Exmergo Dex
-twitter:title: Explore a warehouse · Exmergo Dex
----
-
-
-**Outcome:** a map of the relevant tables, evidence for their grain, and measured
-join behavior. Start from a [connected project](/dex/connect), or use the
-[demo warehouse](/dex/quickstart).
-
-## Start with a question
-
-Give your agent a purpose for the exploration:
-
-```text
-Use Dex to investigate how orders relate to customers. Profile the tables
-we need, verify their joins, and report duplicate keys or missing parents.
-```
-
-On a large warehouse, scope the request to a business area before widening it.
-
-## Map, then inspect
-
-```bash
-dex explore inventory --rank
-dex explore map
-```
-
-Inventory identifies the important objects; the map adds profiles and inferred
-relationships. Read the map's skipped objects and elision counts before treating
-it as a complete inventory of the warehouse.
-
-Then profile the relations your question actually reads. On the demo:
-
-```bash
-dex explore profile orders customers
-dex explore relationships --verify
-```
-
-Check whether a proposed key is unique, whether it contains NULLs, and whether
-the join has unmatched rows or multiplies the parent. A declared relationship
-states the project's intent; verification measures the data behind that claim.
-
-## Ask the data question
-
-```bash
-dex explore query "select status, count(*) as order_count from orders group by status"
-```
-
-Use `explore query` for SQL questions so profiling, scope, cost, and PII checks
-apply. Read the reported truncation and warnings along with the answer.
-
-## Keep the evidence useful
-
-A useful exploration report names the grain, joins that were verified, findings
-that affect the question, and anything left unmeasured. It distinguishes what
-the project declares from what the data proves.
-
-
-
-```bash
-dex explore map --use-project
-dex explore relationships --verify --use-project
-```
-
-These commands include local project declarations and semantic relationships.
-A declaration can inform a map without proving its assertion against the data.
-
-
-
-
-
-```bash
-dex explore diagram
-```
-
-The result contains Mermaid text under `data.mermaid`. Your agent can render it.
-The diagram reads the cached map and does not query the warehouse. Use `--full`
-when you need more of the cached objects and columns.
-
-
-
-## Continue
-
-Use the evidence to [transform a model](/dex/guides/transform). For selection
-rules and measurement detail, read the [exploration methodology](/dex/concepts/methodology).
-For every option, use [`dex explore`](/dex/cli/explore).
diff --git a/dex/guides/maintain.mdx b/dex/guides/maintain.mdx
deleted file mode 100644
index 107ebad..0000000
--- a/dex/guides/maintain.mdx
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: Maintain a project
-sidebarTitle: Maintain
-description: Check the project as it stands, capture a known-good baseline, and compare later changes against it. Review reconciliation plans and verify repairs on dev.
-og:title: Maintain a project · Exmergo Dex
-twitter:title: Maintain a project · Exmergo Dex
----
-
-
-**Outcome:** a clear account of what changed, what is wrong now, and which edits
-would fix it. You need a connected project. Drift comparisons also need a saved
-baseline; correctness checks do not.
-
-## Choose the question
-
-| You want to know | Command | Needs a previous snapshot? |
-| --- | --- | --- |
-| Is the project correct now? | `dex maintain verify` | No |
-| Which models, columns and sources have tests? Did they pass last run? How strong are they? What checks each declared fact? | `dex maintain coverage` | No |
-| Which mutation scores are out of date, and refresh them | `dex maintain coverage --mutate` | No |
-| What changed since the baseline? | `dex maintain check` | Yes |
-| What edits would reconcile the drift? | `dex maintain reconcile` | Yes |
-
-Ask your agent:
-
-```text
-Use Dex to check this project against its last snapshot. Separate measured
-problems from checks that did not run, and show me the proposed fixes.
-```
-
-## 1. Check the current project
-
-```bash
-dex maintain verify
-```
-
-For relations built only on dev, use `--target dev`. Review both findings and
-suppressed checks. A missing baseline does not prevent this check, but missing
-build evidence or unmeasured relations can limit what it proves.
-
-## 2. Save a baseline you trust
-
-After reviewing and fixing the current state:
-
-```bash
-dex maintain snapshot
-```
-
-A snapshot records the state future drift checks compare against. It is not a
-backup of your warehouse, and saving one does not establish correctness.
-
-## 3. Compare later changes
-
-```bash
-dex maintain check
-```
-
-Read schema, volume, grain, and semantic findings in context. On a metered
-connector, a free result may include an offer for additional measured checks.
-An offered check has not run; decide whether to approve it before drawing a
-conclusion from its absence.
-
-## 4. Review and verify a repair
-
-```bash
-dex maintain reconcile
-```
-
-Reconciliation proposes edits. It does not apply them. Review the mechanical
-changes and advisory findings, then apply the returned plan ID and build on dev:
-
-```bash
-dex transform apply PLAN_ID
-dex transform build --target dev --verify --for-plan PLAN_ID
-```
-
-Read `data.outcome` and `data.evidence.coverage`: only `validated` means the
-build ran every node the repair changed.
-
-Only refresh the baseline after the result is accepted. Taking a new snapshot
-before investigating drift makes the changed state the new comparison point.
-
-
-
-`dex maintain snapshot --project-only` refreshes the project layers of the
-baseline without opening a warehouse connection. Use it when that is the state
-you intend to record. It does not prove row counts or data quality, and it is
-not a substitute for checking warehouse drift.
-
-
-
-See [`dex maintain`](/dex/cli/maintain) for individual drift commands and
-[cost controls](/dex/guardrails/cost-controls) for optional measurement offers.
diff --git a/dex/guides/ossie-semantic-layer.mdx b/dex/guides/ossie-semantic-layer.mdx
deleted file mode 100644
index 5cfee18..0000000
--- a/dex/guides/ossie-semantic-layer.mdx
+++ /dev/null
@@ -1,680 +0,0 @@
----
-title: 'Apache Ossie tutorial: a semantic layer end to end'
-sidebarTitle: Ossie tutorial
-description: 'Walk one Apache Ossie semantic document through every dex command on a local DuckDB warehouse: configure, read, query, detect drift, and author changes.'
-og:title: 'Apache Ossie tutorial: a semantic layer end to end · Exmergo Dex'
-twitter:title: 'Apache Ossie tutorial: a semantic layer end to end · Exmergo Dex'
----
-
-One [Apache Ossie](https://github.com/apache/ossie) (incubating) document, one
-local warehouse, and every command dex has for a native semantic layer, in the
-order you would actually run them. Nothing here needs a dbt project, a
-credential, a cloud account, or a network connection, which is the point: a
-semantic layer is a thing a repository can have on its own.
-
-Read [Querying the semantic layer](/dex/semantic-layers/overview) for the reference
-treatment of the commands and [Apache Ossie
-compatibility](/dex/semantic-layers/ossie) for the row-by-row statement of what dex
-accepts and what it declines to claim. This page is the sequence.
-
-```
-pip install "exmergo-dex-core[duckdb,ossie]"
-```
-
-`[duckdb]` is the warehouse and `[ossie]` is the document validator. They are
-independent: reading, validating, fingerprinting, and authoring a native layer
-all happen without a warehouse, and a warehouse install carries no Ossie
-support unless you ask for it.
-
-## 1. A warehouse to point at
-
-```
-dex demo
-dex explore inventory
-```
-
-`dex demo` writes `dex_demo.duckdb` (7 tables, 29,512 rows) and a
-`.dex/config.yml` beside it, refusing rather than overwriting anything that is
-already there. The data is generated from a pinned seed and is deliberately
-flawed, which is what makes the rest of this page interesting.
-
-Run `explore inventory` before writing a line of the document. On DuckDB the
-catalog name comes from the filename, so the identifiers are
-`dex_demo.main.orders` and not `demo.main.orders`, and a document written
-against a guess will parse cleanly and link to nothing. The identifiers it
-reports are:
-
-```
-dex_demo.main.customers
-dex_demo.main.order_items
-dex_demo.main.orders
-dex_demo.main.products
-dex_demo.main.returns
-dex_demo.main.warehouse_locations
-dex_demo.main.web_events
-```
-
-## 2. The document
-
-Save this as `semantics/commerce.ossie.yaml`. It is written to exercise every
-branch of the read path at once, so it is denser than a real first document
-would be.
-
-```yaml
-version: "0.2.0.dev0"
-name: commerce
-description: Orders, the customers who place them, and the products they buy.
-ai_context:
- instructions: >-
- Revenue is gross and excludes returns. Do not present it as net.
- synonyms: [sales, retail]
-datasets:
- - name: orders
- source: dex_demo.main.orders
- description: One row per placed order.
- primary_key: [order_id]
- fields:
- - name: order_id
- datatype: Integer
- label: Order ID
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_id
- - name: customer_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: customer_id
- - name: status
- datatype: String
- description: Order lifecycle state.
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: status
- - dialect: SNOWFLAKE
- expression: status
- - dialect: MDX
- expression: "[Order].[Status]"
- - name: order_total_eur
- datatype: Decimal
- description: Order total converted at a fixed rate.
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_total * 0.92
- - name: quoted_status
- datatype: String
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: '"status"'
-
- - name: customers
- source: dex_demo.main.customers
- description: One row per registered customer.
- primary_key: [customer_id]
- ai_context: Contains personal data; treat email and full_name carefully.
- fields:
- - name: customer_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: customer_id
- - name: email
- datatype: String
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: email
- - name: country_code
- datatype: String
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: country_code
- - name: signup_date
- datatype: Date
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: signup_date
-
- - name: order_items
- source: dex_demo.main.order_items
- description: One row per line on an order.
- primary_key: [order_id, product_id]
- fields:
- - name: order_item_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_item_id
- - name: order_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_id
- - name: product_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: product_id
- - name: quantity
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: quantity
-
- - name: returns
- source: dex_demo.main.returns
- description: One row per returned order line.
- primary_key: [return_id]
- fields:
- - name: return_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: return_id
- - name: order_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_id
-
- - name: web_events
- source: dex_demo.main.web_events
- description: One row per page view.
- fields:
- - name: customer_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: customer_id
- - name: page_path
- datatype: String
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: page_path
-
- - name: recent_orders
- source: "SELECT * FROM dex_demo.main.orders WHERE status = 'paid'"
- description: A rolling window, expressed as a query rather than a table.
- fields:
- - name: order_id
- datatype: Integer
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: order_id
-
-relationships:
- - name: orders_to_customers
- from: orders
- to: customers
- from_columns: [customer_id]
- to_columns: [customer_id]
- - name: web_events_to_customers
- from: web_events
- to: customers
- from_columns: [customer_id]
- to_columns: [customer_id]
- - name: returns_to_order_items
- from: returns
- to: order_items
- from_columns: [order_id, return_id]
- to_columns: [order_id, order_item_id]
-
-metrics:
- - name: revenue
- datatype: Decimal
- description: Sum of gross order totals.
- ai_context:
- instructions: Gross of returns. Pair with order_count for an average.
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: SUM(orders.order_total_eur)
- - dialect: SNOWFLAKE
- expression: SUM(orders.order_total_eur)::NUMBER(38,2)
- - dialect: MAQL
- expression: "SELECT SUM({fact/order_total})"
- - name: order_count
- datatype: Integer
- description: How many orders were placed.
- expression:
- dialects:
- - dialect: ANSI_SQL
- expression: COUNT(*)
-```
-
-What each part is there to demonstrate:
-
-| in the document | what it exercises |
-|---|---|
-| `orders.status` in `ANSI_SQL`, `SNOWFLAKE`, and `MDX` | one field, several dialects, one of them not SQL |
-| `orders.order_total_eur` | a computed field, which carries no physical column |
-| `orders.quoted_status` | a quoted identifier, which also carries none |
-| `order_items.primary_key` | a composite grain that reaches exploration |
-| `recent_orders.source` | a query-backed dataset, which is opaque |
-| `returns_to_order_items` | a composite relationship, two ordered column pairs |
-| `web_events_to_customers` | a declaration the warehouse will contradict |
-| `revenue` and `order_count` | metric lineage that resolves, and lineage that does not |
-
-The document is one semantic model, flat at its root: `version`, `name`, then the
-model's own `datasets`, `relationships` and `metrics`. A configured file holds one
-such document; a layer of several models is several files. The keys and the
-relationships' `from_columns` and `to_columns` name **fields** of their datasets,
-not warehouse columns: here every field is named after the column it exposes, so
-the two read the same, but a field `customer_ref` defined as `customer_id` would be
-named `customer_ref` in a key and still reach the column `customer_id` when dex
-verifies it. An expression may also be written as a top-level `sql:` (Ossie's
-portable `OSSIE_SQL_2026`) instead of, or beside, its `dialects`.
-
-## 3. Configuring it
-
-Ossie is selected on the semantic axis. It is never the transformation project,
-so there is no `project:` block here at all:
-
-```yaml
-connector: duckdb
-duckdb:
- path: dex_demo.duckdb
-semantic:
- vendor: ossie
- ossie:
- files:
- - semantics/commerce.ossie.yaml
-```
-
-Beside a dbt project the only difference is that the project axis is also
-populated, and the two do not interact:
-
-```yaml
-connector: duckdb
-project:
- format: dbt
-semantic:
- vendor: ossie
- ossie:
- files:
- - semantics/commerce.ossie.yaml
-```
-
-`semantic.ossie.files` is the whole of the layer's coordinates. There is no
-discovery step and no glob, because a document dex was not told to read is a
-document nobody reviewed. Paths are relative to the repository root and confined
-to it: an absolute path, a `..` that walks out, and a symlink resolving out are
-each refused.
-
-## 4. Reading the layer
-
-```
-dex explore semantic list
-```
-
-Four fields say which layer answered, and they are worth reading before
-anything else in the payload:
-
-```json
-"backend": "local", "vendor": "ossie", "deployment": "local", "execution": "dex"
-```
-
-`dimension_scope` is `declarations`, meaning one row per dimension the document
-declares rather than one row per token a query could group by. The layer comes
-back as six semantic models (one per dataset, namespaced
-`.`), eighteen dimensions, two metrics, and:
-
-```json
-"entities": [], "measures": []
-```
-
-Those two are empty because the format has nowhere to put them, and the
-`unavailable` block says so rather than leaving you to infer it:
-
-```json
-"unavailable": {
- "metrics": ["dimensions", "input_measures", "composition", "filter",
- "time_axis", "queryable_granularities", "label"],
- "entities": ["name", "type", "label", "description", "roles"],
- "measures": ["name", "agg", "expr", "agg_time_dimension", "label",
- "description", "semantic_model", "column"]
-}
-```
-
-Read that before concluding anything from an empty list. A metric here reports
-no groupable dimensions because Ossie states no metric-to-dimension
-relationship at all, which is a different fact from a metric that can be
-grouped by nothing.
-
-Two more things the catalog is careful about. `commerce.revenue` carries
-`semantic_models: ["commerce.orders"]`, because its expression names
-`orders.order_total_eur` and that reference resolves. `commerce.order_count` is
-`SUM`-free and names nothing, so its lineage is empty rather than every dataset
-in the model:
-
-> metric 'order_count' names no dataset field dex could resolve, so its lineage
-> is empty. Ossie states no metric-to-dataset reference, and naming every
-> dataset in the semantic model would be a claim the document does not make.
-
-## 5. What did not link, and why
-
-Every dimension carries the physical `column` behind it, and four of them carry
-none. That is a decision, not a failure, and each one says which decision:
-
-> field 'orders.order_total_eur' is computed rather than a bare column
-> (ANSI_SQL: order_total * 0.92), so it carries no physical column. A column
-> guessed out of an expression makes the PII gate screen the wrong one and
-> report it as evidence
-
-> field 'orders.quoted_status' is a quoted identifier ("status"), so it carries
-> no physical column. An unquoted identifier is folded the way the warehouse
-> folds it while a quoted one is exact, so the two need not name the same column
-> and dex cannot tell which was meant
-
-> dataset 'commerce.recent_orders' has a source dex cannot read as one relation
-> on duckdb, so it carries no physical link. Ossie documents a source as a table
-> reference or a query without a portable way to tell them apart, and a query
-> read as a relation would reach the PII gate as false evidence
-
-The fourth is the one to notice, because it is a check dex ran and reported
-rather than a check it passed:
-
-> MAQL, MDX expressions are preserved as written and were not checked: they are
-> not SQL, so dex neither parses them nor reads a physical column out of one
-
-Both non-SQL expressions are still in the payload, verbatim, under the element's
-`vendor_params.dialects`. Nothing the document says is dropped. What changes is
-that dex will not read a column out of them, and says so instead of staying
-quiet.
-
-The document also warns, and a warning is not a partial refusal. The layer is
-read in full and the warning rides along:
-
-> relationship 'returns_to_order_items' joins to_columns ['order_id',
-> 'order_item_id'] on dataset 'order_items', which do not cover its primary key
-> or any of its unique keys. The join may fan out
-
-## 6. The governed route when `query` and `values` refuse
-
-Ossie is catalog-first. `list` answers; `query`, `values`, and
-`--for-dimension` refuse, and `--api` refuses too:
-
-```
-dex explore semantic query revenue
-dex explore semantic values customers__country_code
-```
-
-> Apache Ossie specifies interchange metadata, not a portable query runtime: it
-> defines no filter grammar, no join planning, and no execution semantics, so
-> dex has nothing to render a governed statement from.
-
-That is a property of the format rather than a gap in this implementation, and
-the refusal names the alternative rather than leaving you stuck. A dimension
-carries its `semantic_model`, that model carries its `relation`, and the
-relation is an ordinary warehouse object:
-
-```
-dex explore profile dex_demo.main.customers
-dex explore query "select country_code, count(*) as customers
- from dex_demo.main.customers
- group by country_code order by customers desc limit 5"
-```
-
-```json
-"shape": "columnar",
-"columns": ["country_code", "customers"],
-"cells": [["IT", 173], ["BE", 163], ["DE", 152], ["ES", 149], ["SE", 145]]
-```
-
-This route is governed, not a way around the guards. It runs through the query
-firewall ([`pii-policy.md`](/dex/guardrails/pii-policy)) and, on a metered warehouse, through
-the cost handshake ([`cost-controls.md`](/dex/guardrails/cost-controls)). Profiling flagged
-`customers.email` at confidence 0.95, so:
-
-```
-dex explore query "select email from dex_demo.main.customers limit 5"
-```
-
-> query refused: the projection would carry values from PII-flagged column(s):
-> customers.email (email). Use a measuring aggregate over them (COUNT, COUNTIF,
-> APPROX_COUNT_DISTINCT, AVG(LENGTH(...))), or drop them from the output.
-
-The flag reached that column because the field `customers.email` is a bare
-identifier on a relation dex can address. A field that carries no column is
-screened by the name heuristic instead, and the payload says which happened.
-
-## 7. What the declarations reach in exploration
-
-```
-dex explore map --use-project
-dex explore relationships --use-project --verify
-dex explore diagram
-```
-
-Three things arrive from the document, and a fourth with `explore profile
---use-project` or the map's objects: a `declaration` on each dataset's relation,
-with its `primary_key` as the grain, `grain_status` comparing it with what
-profiling measured, and anything annotated under `ai_context.dex`.
-
-**Source annotations.** Each relation is marked with the semantic models sitting
-on it, and empty is an answer: `dex_demo.main.products` and
-`dex_demo.main.warehouse_locations` come back with `semantic_models: []`,
-which is what separates a load-bearing table from a merely large one.
-
-**The declared grain.** `order_items` has a composite `primary_key` in the
-document, and it supplies a grain measurement could not prove, saying where the
-grain came from rather than leaving that silent:
-
-> grain order_id, product_id comes from the project's declared composite key
-> (measurement found no key of its own)
-
-That is the case the declaration earns its keep in. Nothing keys this table:
-`order_item_id` is unique on 13,000 of its 14,000 rows because a batch was
-loaded twice, and the column pairs that are unique here are unique only because
-of that shortfall, so profiling reports none of them and says so in
-`key_evidence`. A declaration cannot fix duplicates, and it does not claim to.
-It states what the grain is meant to be, `maintain grain` is where that gets
-verified against the data, and the measurement keeps the finding.
-
-**The declared joins**, at confidence 1.0, with the composite kept whole:
-
-```json
-{"from_dataset": "dex_demo.main.returns", "from_columns": ["order_id", "return_id"],
- "to_dataset": "dex_demo.main.order_items", "to_columns": ["order_id", "order_item_id"],
- "kind": "declared", "confidence": 1.0,
- "declared_by": "ossie relationship 'returns_to_order_items'"}
-```
-
-Both pairs survive into `explore diagram`, which labels the edge
-`order_id = order_id, return_id = order_item_id`. No first-column proxy is ever
-emitted or measured, because a composite measured one column at a time can
-report a healthy join three times over while no complete tuple matches.
-
-`--verify` is where the document meets the data. `orders_to_customers` verifies
-with no orphans. `web_events_to_customers` does not:
-
-> dex_demo.main.web_events.customer_id -> dex_demo.main.customers.customer_id is
-> declared as a foreign key but 100% of values have no match in the parent; the
-> project and the warehouse disagree
-
-Its confidence stays at the 1.0 the document asserts. A measurement never
-revises a declaration; it reports the disagreement and leaves the decision to
-you. The composite edge is measured as a complete tuple and comes back with no
-orphan fraction at all, because `returns` is the demo's half-failed load and has
-no rows: an honest absence of evidence rather than a clean bill of health.
-
-## 8. A baseline, and drift against it
-
-```
-dex maintain snapshot
-```
-
-```json
-"transform_layer": null,
-"semantic_layer": {"semantic_model_count": 6, "metric_count": 2}
-```
-
-`transform_layer` is null because there is no transformation project here and
-Ossie declares no build step, so a transform baseline over it would be a
-baseline of nothing. The two layers are fingerprinted independently, which is
-exactly why a repository with a semantic layer and nothing else still gets one.
-
-The semantic side records each dataset and metric with a content hash, the
-relation behind it, the column each field resolves to, the declared keys in the
-arity they were written, and every relationship with its ordered column pairs.
-It also records that it captured them, so a baseline written before that was
-possible reports the relationship axis as unchecked rather than as clean.
-
-Now break something. Point `web_events.page_path` at a column that does not
-exist, and change one side of the composite relationship:
-
-```
-dex maintain semantic
-```
-
-> [high] broken_relationship: relationship 'returns_to_order_items' from
-> 'commerce.returns' to 'commerce.order_items' names column pair(s) that no
-> longer resolve: [['return_id', 'line_item_id']]
-
-> [high] dangling_reference: dimension 'page_path' on semantic model
-> 'commerce.web_events' references column 'page_url', which is gone from
-> dex_demo.main.web_events
-
-Two more findings at `low` record that the definitions themselves changed. All
-of it is free: this axis reads the documents and the cache and opens no
-warehouse connection. The command's paid half, dimension cardinality, needs a
-semantic model that records which of its dimensions are categorical, and an
-Ossie dataset records none, so `data.offer` is null and there is nothing to
-confirm.
-
-`maintain grain` is where the declaration is measured:
-
-```
-dex maintain grain
-```
-
-> [high] (order_id, product_id) on dex_demo.main.order_items is no longer
-> unique: 13952 distinct combinations over 14000 rows (~48 duplicate rows);
-> no known join uses it
-
-The declared composite reached the grain channel, was measured as a composite,
-and the warehouse disagreed with it. No join uses this key: the declared join
-into `order_items` matches on `(order_id, order_item_id)`. When a join does use
-the key, the finding says joins on it will fan out and lists them in
-`data.joins`. It is a finding, never an automatic
-rewrite. On DuckDB this is free; on a metered warehouse it goes through the same
-`--confirm --budget` handshake every scanning command does.
-
-`maintain reconcile` has nothing to author here. A native semantic layer is not
-an editable transformation project, so its proposals are advisory and no plan is
-stored. Authoring is the next section, and it is a different command.
-
-## 9. Authoring into the layer
-
-```
-dex semantic ossie update "add customer lifetime value" --edits-file edits.json
-```
-
-The payload is the ordinary dex edits shape, and `kind` may be omitted because
-this command implies `semantic_document`:
-
-```json
-{"edits": [{"path": "semantics/commerce.ossie.yaml", "content": ""}]}
-```
-
-Edits are whole documents. dex overlays what you supplied onto the other
-configured files, validates the complete prospective layer, and only then stores
-a plan. It also checks the references against the exploration cache without
-opening a connection, and it distinguishes what it verified from what it
-declined to:
-
-> cache validation skipped 1 query-backed, quoted, or otherwise opaque dataset
-> source(s); dex does not guess a physical relation
-
-> cache validation skipped 2 computed or non-SQL field expression(s); dex
-> validates only a direct physical column reference
-
-> cache validation checked 5 direct relation(s) and 29 physical column
-> reference(s) using stored evidence only; no warehouse connection was opened
-
-Those are notes. A reference the cache can positively contradict is a refusal,
-and no plan is stored:
-
-> the prospective Ossie semantic layer has references contradicted by the
-> exploration cache, so no plan was stored: dataset[5] 'suppliers' names source
-> 'dex_demo.main.suppliers', but the cached inventory for namespace
-> 'dex_demo.main' does not contain it
-
-The namespace guards are the difference between the three modes. `define`
-refuses a semantic-model name the layer already has, `update` refuses one it
-does not, and `plan` accepts both and reports each under `defined` or `updated`:
-
-> semantic ossie define found names already defined: commerce; use
-> `semantic ossie update` or `semantic ossie plan`
-
-Nothing is written until you apply:
-
-```
-dex transform apply p1cd6a7ce57
-```
-
-If the file changed after the plan was made, the whole apply refuses rather than
-writing part of it:
-
-```json
-"conflicts": [{"path": "semantics/commerce.ossie.yaml",
- "expected_sha256": "0c5a833d...", "found_sha256": "789230894..."}]
-```
-
-> these files changed after the plan was made (human edits are authoritative);
-> re-plan against current state, or re-run with `--confirm` to overwrite
-> deliberately
-
-On a clean apply the accepted bytes are written exactly as authored. dex does
-not parse and re-serialize the document, so comments, key order, quoting, and
-whitespace all survive, and configured documents the payload did not mention are
-untouched. The comment above the new field is still there afterwards, and
-`explore semantic list` now reports `customers__lifetime_value` beside the
-others.
-
-## 10. What this page did not prove
-
-**Catalog-first is not a roadmap item.** Ossie specifies interchange metadata
-and no portable query runtime. The refusals in section 6 are the format's shape.
-Upstream has an active working group on a query language and a reference engine;
-when that lands it becomes a declared runtime with its own governed contract,
-not a loosening of these commands.
-
-**Validation is not an execution guarantee.** There is no external validator
-here the way `dbt parse` is for dbt: there is no published Ossie package and no
-runtime to load a document into. A document that passes is schema-valid and
-internally consistent. Whether any engine can execute it is a separate question
-dex has no basis to answer, and no dex surface says otherwise.
-
-**dbt was never involved.** No dbt project, no MetricFlow, no manifest, at any
-step above. The two axes are independent in both directions: dbt does not depend
-on Ossie, Ossie does not depend on MetricFlow, and a repository may have either,
-both, or one of each.
-
-**dex reads Ossie; it does not convert it.** There is no exporter to or from
-another semantic format, and dex says nothing about what another tool would make
-of a document it read.
-
-The schema dex validates against is pinned by content rather than by version
-string, and upgrading it is a reviewed procedure rather than a version bump. The
-pin, the upstream commit, the known deltas, and the upgrade steps are in
-[Apache Ossie compatibility](/dex/semantic-layers/ossie).
-
-Source: [`references/ossie-walkthrough.md`](https://github.com/exmergo/dex/blob/v1.18.0/references/ossie-walkthrough.md) ([edit on main](https://github.com/exmergo/dex/edit/main/references/ossie-walkthrough.md)). This page is generated; change the source, not the site.
diff --git a/dex/guides/semantic-layer.mdx b/dex/guides/semantic-layer.mdx
deleted file mode 100644
index 508e044..0000000
--- a/dex/guides/semantic-layer.mdx
+++ /dev/null
@@ -1,77 +0,0 @@
----
-title: Use a semantic layer
-sidebarTitle: Semantic layers
-description: Find the metrics your project defines, choose the right semantic backend, and author changes through reviewable plans. Check query support before running them.
-og:title: Use a semantic layer · Exmergo Dex
-twitter:title: Use a semantic layer · Exmergo Dex
----
-
-
-**Outcome:** find the definitions your project already owns, then choose whether
-to query them or change them. A catalog that can be read is not necessarily a
-backend that can execute queries.
-
-## 1. Identify the layer
-
-| Your project uses | Where definitions live | Read next |
-| --- | --- | --- |
-| dbt semantic models | MetricFlow YAML in the dbt project | [Semantic layer reference](/dex/semantic-layers/overview) |
-| dbt Cloud Semantic Layer | Hosted catalog and query API | [Hosted backend](/dex/semantic-layers/overview#hosted-backend-api-dbt-cloud-semantic-layer) |
-| Apache Ossie | Native YAML documents in the repository | [Ossie walkthrough](/dex/guides/ossie-semantic-layer) |
-| SLayer | Native model files in the repository | [SLayer support](/dex/semantic-layers/overview#slayer-models-vendor-slayer) |
-| Cube | Cube YAML model files in the repository | [Cube compatibility](/dex/semantic-layers/cube) |
-| Databricks Metric Views | Metric View YAML files in the repository | [Metric View compatibility](/dex/semantic-layers/databricks-metric-views) |
-| Snowflake Semantic Views | Semantic View YAML files in the repository, deployed by you; or the views deployed on the account, read alone (`deployment: snowflake_account`) | [Semantic View compatibility](/dex/semantic-layers/snowflake-semantic-views) |
-
-Use the configuration and extras for that backend. Keep the existing format as
-the source of truth; choosing Dex does not require converting it to another one.
-
-## 2. Inspect the catalog first
-
-```bash
-dex explore semantic list
-```
-
-Read the available metrics, dimensions, entities, and physical mappings. The
-mapping to warehouse columns matters: it connects semantic queries to profiling
-and PII checks.
-
-Ask your agent:
-
-```text
-Use Dex to list the revenue metrics in this project's semantic layer.
-Explain their dimensions and physical sources before running a query.
-```
-
-## 3. Query or author
-
-**To answer a metric question**, use `explore semantic query` or
-`explore semantic values` on a backend that supports it. Start with the names
-returned by the catalog and the [semantic query reference](/dex/semantic-layers/overview).
-
-**To change definitions**, ask the agent to prepare a plan using `semantic
-define|update|plan` for dbt semantic models, or the matching `semantic ossie`,
-`semantic slayer`, `semantic cube`, `semantic databricks` or `semantic snowflake`
-command for native documents. Dex never deploys a Metric View or a Semantic
-View: applying the plan writes the file, and you deploy it. Review the
-plan and apply it through `transform apply`.
-
-
-Hosted dbt Cloud semantic queries are outside Dex's cost guard. Understand that
-boundary before running them. Other backends have different query capabilities;
-reading a native document does not authorize a hosted catalog or query request.
-
-
-## A complete local example
-
-The [Apache Ossie walkthrough](/dex/guides/ossie-semantic-layer) takes a native
-layer from local files through catalog inspection, exploration, a drift baseline,
-and authoring. It also explains the cases where metric queries are refused and
-how to ask a governed warehouse question instead.
-
-For exact schemas and validation limits, use the
-[semantic layer reference](/dex/semantic-layers/overview),
-[Ossie compatibility](/dex/semantic-layers/ossie),
-[Cube compatibility](/dex/semantic-layers/cube),
-[Metric View compatibility](/dex/semantic-layers/databricks-metric-views), or
-[Semantic View compatibility](/dex/semantic-layers/snowflake-semantic-views).
diff --git a/dex/guides/transform.mdx b/dex/guides/transform.mdx
deleted file mode 100644
index e0bbe50..0000000
--- a/dex/guides/transform.mdx
+++ /dev/null
@@ -1,267 +0,0 @@
----
-title: Transform a dbt project
-sidebarTitle: Transform
-description: Take a model change from verified source data through a reviewable plan, apply it, and build on dev. Check the resulting rows before calling the change done.
-og:title: Transform a dbt project · Exmergo Dex
-twitter:title: Transform a dbt project · Exmergo Dex
----
-
-
-**Outcome:** a reviewed project change, built on dev, with evidence that its
-rows match the request. You need a connected warehouse and a dbt project with a
-dev target. Start with [Connect your data](/dex/connect) if either is missing.
-
-## 1. State what the model should mean
-
-Tell the agent the grain and population you want, not just the model name:
-
-```text
-Use Dex to create a customer summary with one row per customer, including
-customers who have no orders. Include an order count of zero for those
-customers. Show me the plan and verify the resulting rows on dev.
-```
-
-The agent should profile the source relations and verify the joins before
-writing the SQL. It records the model's meaning in a declaration: grain,
-population, column roles, units, and any assumptions it had to make.
-
-
-
-After connecting and exploring, use `dex transform init analytics` to create a
-project named `analytics`. This command creates the project files and records
-the connection in configuration, returning the changes as diffs. It refuses to
-overwrite an existing project. Existing projects are discovered from the
-repository; `dbt_project_dir` can select one when the repository holds several.
-
-The generated dev profile still needs a valid target. For DuckDB, a new dev file
-that reads sources must be populated before the build can succeed. Follow the
-[DuckDB dev-target guidance](/dex/connectors/duckdb#dev-target-seeding-convention).
-
-
-
-## 2. Review the plan
-
-The agent submits the edits and declarations together:
-
-```bash
-dex transform plan "Create a customer summary" --edits-file edits.json
-```
-
-`edits.json` is the agent's prepared change, not a file Dex creates from this
-command alone. The result includes a plan ID, diffs, warnings, and declaration
-feedback. Resolve missing intent and contradictions, then plan again before
-applying. For an existing model, also review row attribution: a refactor should
-preserve its results.
-
-When the plan rewrites a model that already exists, it carries
-`data.refactor_comparison_offer`. If the change is meant to keep that model's
-results (a refactor, an extracted intermediate, a cleanup), compare before
-applying, because applying discards the baseline:
-
-```bash
-dex transform compare PLAN_ID --model account_summary
-```
-
-`equivalent` holds for the relations named in `input_scope` at `compared_at`.
-`different` means the rewrite changed the rows or the schema: fix it, or state an
-intended rename with `--map` or type change with `--accept-type`. `not_checked`
-is not a pass: its `reason_code` names what to repair, such as a parent whose last
-build failed. The offer says so before you compare: `baseline_ready: false`
-names each blocked input and its owner. Repair it in a plan of its own, apply
-and build that plan (with `--cold-deps` where a package owns the failing model),
-then compare the refactor's plan, which you have not applied yet:
-
-```bash
-dex transform plan "override the package model" --edits-file repair.json
-dex transform apply REPAIR_PLAN_ID
-dex transform build --target dev --verify --cold-deps --for-plan REPAIR_PLAN_ID
-dex transform compare PLAN_ID --model account_summary
-```
-
-Putting the repair in the refactor's own plan leaves the comparison nothing
-built to read, so Dex warns and names the split (`mixed_with_repair`). The
-verdict's `inputs_built_by` names the latest build among its upstream models;
-other inputs may come from earlier builds. `transform deps` installs the packages
-the project already declares, at the versions `package-lock.yml` pins where it
-matches `packages.yml`; that is not installing or upgrading a tool. The offer's `static_attribution` says when this comparison is the
-only evidence a refactor kept its results, for example when the model's SQL
-calls a macro. A change meant to alter results needs no comparison. The verdict
-is recorded on the plan, and `transform apply` reports it.
-
-When the plan adds a cast or a `lower`, `upper` or `trim` to an identifier, such
-as a `try_cast(product_id as integer) is not null` that makes a broken join
-compile, it reports the conversion under `data.identifier_conversions`, with
-counts and their denominator. The counts show how many identifiers do not
-convert, how many collapse into one key (`7` and `007`), and how many the prior
-model held that the authored one does not, even when the row count is unchanged.
-A text identifier may be a second legitimate scheme rather than bad data, and
-Dex does not decide which. An `undeclared` conversion needs a decision: keep
-the other scheme (compare as text, normalize, use a bridge or a namespace), or
-record the exclusion as an assumption naming its `column`. On DuckDB the counts
-are free. Elsewhere they need `--attribute-rows` and are priced with row
-attribution.
-
-A repair is meant to change some behavior and keep the rest, and
-`data.change_scope` shows where those lines fall. For each existing model the
-plan rewrites, it says whether the row population is `changed`, `kept` or
-`unchecked`, and it names each output the plan removes, retypes, re-aggregates or
-re-NULLs. Re-aggregating covers `count(*)` becoming `count(visit_id)`, and
-re-NULLing covers a `coalesce` added to an average. The report is free and reads
-no data.
-
-A change no assumption records is `undeclared` and raises a warning. If the
-request asked for it, record it as an assumption naming its `column`. If not,
-undo it.
-
-For a request such as "exclude sandbox accounts from our metrics", the
-`population` lists show which edited models now filter and which ones the edit
-leaves alone. They read each model's own SQL, so check a roster's rows on the
-build as well. Whether the account directory filters too is a decision to record
-rather than a side effect, and when the request leaves it open it is a `default`.
-
-Read the [command contract](/dex/reference/command-contract#how-authored-content-reaches-the-engine)
-when you need to construct the edits payload yourself.
-
-## 3. Apply the reviewed plan
-
-Replace `PLAN_ID` with the ID returned by planning:
-
-```bash
-dex transform apply PLAN_ID
-```
-
-This writes project files. If a file changed after planning, re-plan against its
-current content so the diff you review is the one you apply.
-
-## 4. Build and verify on dev
-
-```bash
-dex transform build --target dev --verify --for-plan PLAN_ID
-```
-
-On a metered connector, review the estimate and follow the
-[cost confirmation flow](/dex/guardrails/cost-controls). A successful dbt build
-is only part of the result. Read `data.completion` first. It is the first key
-of the payload and is held to 4 KiB, so it survives a cut-off read even when
-hundreds of nodes follow it. With `--for-plan`, its `deliverables` say which of
-the nodes the plan changed were built, failed, skipped, missing or stale (and,
-when dbt reports a status Dex does not recognize, such as a microbatch model's
-`partial success`, `unrecognized`), and `blocked` names what stopped each one. A skipped report is not done, even if dev
-still holds a table from an earlier run. `assurance.build_only` lists what built
-with nothing checking its rows, and `assurance.failed_checks.checks` says which
-kind of check failed on each model: a data test by name, or a verification
-record such as `join_coverage` with its finding and join. An INNER join used as
-a filter is not a failure when the declaration says so: name the driving key in
-an assumption's `column` or a `population.filters` entry. Without `--for-plan`, `coverage` is `unknown`.
-
-`data.verification.scope` lists the models this run built successfully;
-`scope_not_built` names the other reported models. In the evidence block,
-`coverage.covered` includes failed and skipped nodes present in run results.
-Use `coverage.built` and `coverage.not_built` to distinguish successful execution.
-`generated` lists only the relations this run's successful nodes produced, and
-an unrecognized node status makes the outcome `indeterminate`, never `validated`.
-
-When something upstream stopped the build, `data.prerequisites` names the failed
-node's owner (your project or an installed package), whether the plan could have
-caused it, and the repairs dbt supports for it. An edit under `dbt_packages/` is
-not one of them, because the next `dbt deps` replaces it. Add `--cold-deps` to
-reinstall packages into an isolated copy and build from there, which proves the
-repair survives and lists anything your installed tree held that a reinstall does
-not reproduce. It may reach the network, so a normal build never does it.
-
-Each prerequisite's `previous_run` gives its earlier status and run context when
-available. This history survives pricing and confirmation retries without an
-extra build. It may describe a different selection or source tree, so it does
-not establish whether the plan caused the failure or change `plan_relation`.
-
-The [command contract](/dex/reference/command-contract) gives every
-field. Then read `data.outcome` (only `validated` means every required node ran
-and passed) and `data.verification.ran`, its findings,
-and `suppressed` checks. Missing parents, multiplied rows, or an entirely NULL column
-need investigation before the change is finished. `data.verification.column_contract`
-says which built models had their columns compared with `schema.yml`, which declare
-none, and which could not be checked and why.
-
-
-
-Use `--full-refresh` when the requested change requires rebuilding the selected
-incremental relation, rather than processing its next batch:
-
-```bash
-dex transform build --target dev --select fct_orders --full-refresh --verify
-```
-
-A full refresh drops and rebuilds selected incremental relations on dev. It can
-scan substantially more data. Review the full-rebuild estimate before approving
-it; this flag is not a routine fix for a failed build.
-
-A model configured with `full_refresh: false` is not rebuilt: check
-`data.full_refresh.not_refreshed` before treating a selected relation as
-rebuilt. With `--verify`, a rebuilt incremental model's row count is compared
-with its driving parent, as a table's is, but not every model gets the comparison:
-a microbatch model, and one whose compiled SQL or driving parent Dex cannot
-resolve, are skipped and named in `warnings`, and a check that did not run is
-listed under `data.verification.suppressed`. Read both before relying on it. Even
-where it ran, these are counts: a green verification does not show the rebuilt
-values are right, so check them before accepting the change, for example with
-`dex explore profile --target dev --refresh`.
-
-A full refresh runs only the model's full build, never its
-`{% if is_incremental() %}` branch. If the problem is rows the next incremental
-run skips or loads twice, prove that branch with the unit test
-`dex transform test --scaffold ` writes for an incremental model, which
-overrides `is_incremental` and puts rows before, on and after the watermark.
-Then build again without `--full-refresh`.
-
-
-
-
-
-A flag that stays live, as in "hide the fee columns when `enable_fees` is
-false", has to hold on both values in every model of the project. That includes
-models that do not feed the mart you changed, such as a ledger nothing else
-reads, a model that inherits a column through `select *`, or a model whose
-table is empty. State it with a `toggle` key beside the edits in the
-`transform plan` payload:
-
-```json
-{"edits": [...],
- "toggle": {"variable": "enable_fees", "on_value": true, "off_value": false,
- "columns": ["fee_amount"], "exempt_models": ["stg_orders"]}}
-```
-
-Dex compiles every model at each value without probing any table's rows (a
-compile-time macro such as `run_query` can still query the warehouse), and
-`data.toggle`
-names each model that still outputs a governed column with the flag off or loses
-one with it on. `transform compare` checks the on value against today's results.
-After `transform build --verify --for-plan `,
-`data.verification.toggle` judges each built relation's columns at the value
-that build used, so an empty table is checked too. The other value is reported
-as not built.
-
-Removing a flag is a different change: use a `retirement` contract on
-`dex transform remove var`, which states which behavior survives. Where Dex
-cannot finish scanning the project for the flag's readers (Jinja-heavy macros,
-packages such as `dbt_utils`), add `"scope": "authored"` to that contract: the
-outputs it names are still checked, and reference discovery is reported as
-unchecked rather than complete.
-
-
-
-
-
-By default, Dex writes dbt artifacts under `target/dex//` rather
-than mixing them with another runtime's artifacts. The build result's
-`data.artifact_directory` names the directory used. Follow that path when
-investigating a failure instead of assuming the project's previous manifest
-describes this run. See the
-[build command contract](/dex/reference/command-contract).
-
-
-
-## Keep it correct
-
-Once the change is verified, [establish a maintenance baseline](/dex/guides/maintain).
-For refactoring tools, test scaffolding, mutation testing, and every build flag,
-see [`dex transform`](/dex/cli/transform).
diff --git a/dex/guides/troubleshooting.mdx b/dex/guides/troubleshooting.mdx
deleted file mode 100644
index 9ebc097..0000000
--- a/dex/guides/troubleshooting.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: Understand a refusal or incomplete result
-sidebarTitle: Troubleshooting
-description: Find the next step when Dex needs confirmation, lacks a dependency, refuses a query, or cannot verify a build. Resolve the cause without bypassing the guards.
-og:title: Understand a refusal or incomplete result · Exmergo Dex
-twitter:title: Understand a refusal or incomplete result · Exmergo Dex
----
-
-
-Start with the JSON envelope's `status`, `reason`, `errors`, and `warnings`.
-A refusal explains a boundary; a successful result may still contain findings
-or checks that did not run.
-
-## Choose the symptom
-
-
-
-
-Read what it is asking you to approve. A cost estimate, configuration diff, and
-file changed since planning require different decisions.
-
-For spend, follow [cost controls](/dex/guardrails/cost-controls). For a config
-change, review the diff in [`dex config`](/dex/cli/config). If a planned file has
-changed, plan again against the current file before applying.
-
-Do not treat `--confirm` as a universal retry flag.
-
-
-
-
-Check `uv --version` in the terminal your agent uses. Follow
-[Installation](/dex/installation) if it is missing. A `reason: prerequisite`
-response names the extra the command needs; install that extra or use the skill
-wrapper that selects it. Do not replace the command with a raw warehouse client.
-
-
-
-
-Run from your project directory, inspect `dex config get`, and run
-`dex config validate`. Then use `dex connect test` to check the selected target.
-See [Connect your data](/dex/connect) for connector discovery and scope.
-
-For dbt, check that Dex can discover one project or that `dbt_project_dir`
-selects the intended one. `DBT_PROFILES_DIR` locates dbt profiles; it does not by
-itself select Dex's connector.
-
-
-
-
-Read the [PII policy](/dex/guardrails/pii-policy). Only a human clears a flag.
-If an aggregate answers the question, ask for the aggregate instead of returning
-individual values. Do not alter flags to make a query pass.
-
-
-
-
-The warehouse refused a statement on a conversion, parse or range failure, and
-its message quoted the value it could not handle. Dex keeps the message and
-masks that value, because it comes from a row. The rest of the message still
-says what failed: often a text key compared to an integer key, which the
-warehouse casts implicitly. Profile the column to see its shapes, then fix the
-cast or the join. See the [PII policy](/dex/guardrails/pii-policy).
-
-
-
-
-Use a fresh directory outside an existing Dex project. The demo is create-only
-and will not replace an existing warehouse file. A configuration above the
-directory can also keep it from creating the demo configuration. See the
-[quickstart](/dex/quickstart).
-
-
-
-
-Read `data.verification`, including findings and suppressed checks. A successful
-dbt run does not prove the population, joins, or grain are right. Investigate
-row loss, fan-out, and NULL columns, fix the plan, then rebuild with `--verify`.
-A `column_missing`, `column_undeclared`, or `column_type_mismatch` finding means
-the built relation and `schema.yml` disagree: fix whichever is out of date.
-See [Transform a dbt project](/dex/guides/transform).
-
-
-
-
-Read the elision counts, skipped objects, suppressed checks, and any optional
-measurement offer. Narrow the question or request the missing evidence.
-A check that did not run is not a clean result. See
-[Explore](/dex/guides/explore) or [Maintain](/dex/guides/maintain).
-
-
-
-
-For the exact response fields, use the
-[command contract](/dex/reference/command-contract#the-envelope).
diff --git a/dex/index.mdx b/dex/index.mdx
deleted file mode 100644
index 44fa8ae..0000000
--- a/dex/index.mdx
+++ /dev/null
@@ -1,62 +0,0 @@
----
-title: Dex
-sidebarTitle: Introduction
-description: Explore a warehouse, change dbt models with reviewable plans, and check for drift. Start with a local demo, then bring Dex to your agent and data.
-og:title: Exmergo Dex
-twitter:title: Exmergo Dex
----
-
-
-Dex gives your coding agent a repeatable way to understand a warehouse, change
-its dbt project, and check that the results are right. You keep your existing
-project; Dex adds profiling, reviewable plans, dev builds, and drift checks.
-
-
-
- Map a demo warehouse and investigate its deliberately broken joins and keys.
- No cloud account or credentials needed.
-
-
- Install the skills, open your project, and ask your agent to explore or make
- a change.
-
-
-
-## What do you want to do?
-
-
-
- Understand unfamiliar data with a ranked map, measured keys, and verified joins.
-
-
- Review a model change, build on dev, and check the resulting rows.
-
-
- Find drift against a baseline and review the proposed fixes.
-
-
- Discover metric definitions and choose a path for querying or authoring them.
-
-
-
-## How it fits
-
-Run Dex from your project directory. Your agent drives the commands and reads
-their JSON results. The same commands work directly in a terminal.
-
-Exploration reads your source data. Authoring produces plans for your project
-files; applying a plan writes those files, and a build writes to a dev target.
-Your repository remains the source of truth.
-
-Cost checks and PII handling live in the engine. Before using a warehouse of your
-own, follow [Connect your data](/dex/connect) to set the scope and spending limits.
-For the precise boundaries, including the hosted dbt semantic-layer exception,
-read [cost controls](/dex/guardrails/cost-controls) and the
-[PII policy](/dex/guardrails/pii-policy).
-
-## Find the right level of detail
-
-**Documentation** takes you through setup and common tasks. **Reference** holds
-connector settings, command flags, compatibility rules, and integration contracts.
-If you know the command you need, go straight to the
-[CLI reference](/dex/cli/overview).
diff --git a/dex/installation.mdx b/dex/installation.mdx
deleted file mode 100644
index fcd1d85..0000000
--- a/dex/installation.mdx
+++ /dev/null
@@ -1,142 +0,0 @@
----
-title: Install Dex
-sidebarTitle: Installation
-description: Set up Dex for a coding agent or use its CLI directly. Choose one installation path, verify uv is available, and run from your project directory.
-og:title: Install Dex · Exmergo Dex
-twitter:title: Install Dex · Exmergo Dex
----
-
-
-Choose the way you want to use Dex. The skills guide an agent through the same
-engine that the CLI exposes directly.
-
-## Prerequisite
-
-Install [uv](https://docs.astral.sh/uv/getting-started/installation/) version
-0.13.4 or later and check that your terminal can find it:
-
-```bash
-uv --version
-```
-
-Dex's skill wrappers use uv to install and run the engine. Your agent needs a
-local shell and access to your project directory.
-
-## Choose one installation path
-
-
-
-
-Run this in your terminal and choose your agent when prompted:
-
-```bash
-npx skills add exmergo/dex
-```
-
-For Codex, you can select the agent explicitly:
-
-```bash
-npx skills add exmergo/dex --agent codex
-```
-
-Open your project in the agent and ask it to use Dex. The three skills are
-`explore`, `transform`, and `maintain`.
-
-
-
-
-Run these inside Claude Code, one at a time:
-
-```text
-/plugin marketplace add exmergo/exmergo-agent-plugins
-```
-
-```text
-/plugin install dex@exmergo
-```
-
-The skills appear as `/dex:explore`, `/dex:transform`, and `/dex:maintain`.
-Update the marketplace later with `/plugin marketplace update exmergo`.
-
-
-
-
-Start locally with DuckDB:
-
-```bash
-uv tool install "exmergo-dex-core[duckdb]"
-dex --help
-```
-
-For another warehouse, install its connector extra instead. For example:
-
-```bash
-uv tool install "exmergo-dex-core[snowflake]"
-```
-
-Dex supports Python 3.11 to 3.14, and `uv tool install` uses your newest
-Python. If that is 3.15, which Dex does not support yet, name a supported one:
-`uv tool install --python 3.14 "exmergo-dex-core[duckdb]"`. The agent skills
-pick a supported Python on their own.
-
-If Dex is already installed with a different set of extras, use
-`uv tool install --force` with the complete set you need, such as
-`"exmergo-dex-core[duckdb,snowflake]"`.
-
-
-
-
-## Start from the project directory
-
-Open the directory containing your project. Dex discovers `.dex/config.yml`
-up the directory tree, and uses the dbt project and semantic definitions in
-that repository.
-
-For CLI setup, run:
-
-```bash
-dex init
-```
-
-For skill users, ask your agent:
-
-```text
-Initialize this repository with Dex. Use the installed skill wrapper.
-```
-
-Installing skills does not necessarily install a `dex` executable. The wrapper
-and CLI run the same engine workflow. Setup creates a dbt-backed Dex project,
-adopts an existing dbt project, creates a complete local demo, or configures
-exploration without dbt. It verifies connectivity and reports any unfinished
-steps without exploring data or building models.
-
-Try this prompt after setup:
-
-```text
-Use Dex to map this warehouse. Show me the tables worth investigating,
-their likely grain, and the joins that need verification.
-```
-
-
-
-The skill wrapper downloads the engine and connector dependencies on its first
-run. Ask your agent to warm the installed wrapper with `--warm` if you want to
-pay that setup cost ahead of an interactive session. Warm-up installs packages;
-it does not query the warehouse.
-
-
-
-
-
-Point it at the repository's
-[AGENTS.md](https://github.com/exmergo/dex/blob/main/AGENTS.md).
-It contains the engine procedure and command contract.
-
-With the CLI installed, `dex procedure --block` also prints the current procedure
-for inclusion in an agent's instructions. See
-[`dex procedure`](/dex/cli/procedure) for checking that a copied procedure is current.
-
-
-
-Continue with the [local quickstart](/dex/quickstart), or
-[connect an existing warehouse](/dex/connect).
diff --git a/dex/navigation.json b/dex/navigation.json
deleted file mode 100644
index 3ca00a6..0000000
--- a/dex/navigation.json
+++ /dev/null
@@ -1,550 +0,0 @@
-{
- "product": "Dex",
- "description": "Agent-native analytics engineering",
- "versions": [
- {
- "version": "v1.18",
- "default": true,
- "tag": "Latest",
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get started",
- "pages": [
- "dex/index",
- "dex/quickstart",
- "dex/installation",
- "dex/connect"
- ]
- },
- {
- "group": "Workflows",
- "pages": [
- "dex/guides/explore",
- "dex/guides/transform",
- "dex/guides/maintain",
- "dex/guides/semantic-layer"
- ]
- },
- {
- "group": "Tutorials and help",
- "pages": [
- "dex/guides/ossie-semantic-layer",
- "dex/guides/troubleshooting"
- ]
- }
- ]
- },
- {
- "tab": "Reference",
- "groups": [
- {
- "group": "CLI",
- "pages": [
- "dex/cli/overview",
- "dex/cli/init",
- "dex/cli/connect",
- "dex/cli/explore",
- "dex/cli/transform",
- "dex/cli/semantic",
- "dex/cli/maintain",
- "dex/cli/config",
- "dex/cli/demo",
- "dex/cli/procedure",
- "dex/cli/feedback"
- ]
- },
- {
- "group": "Connectors",
- "pages": [
- "dex/connectors/duckdb",
- "dex/connectors/bigquery",
- "dex/connectors/snowflake",
- "dex/connectors/databricks",
- "dex/connectors/redshift",
- "dex/connectors/postgres",
- "dex/connectors/clickhouse",
- "dex/connectors/trino"
- ]
- },
- {
- "group": "Safety and spending",
- "pages": [
- "dex/guardrails/cost-controls",
- "dex/guardrails/pii-policy",
- "dex/guardrails/values-free-mode"
- ]
- },
- {
- "group": "Project and exploration",
- "pages": [
- "dex/concepts/source-of-truth",
- "dex/concepts/methodology",
- "dex/concepts/dbt-project"
- ]
- },
- {
- "group": "Semantic layer compatibility",
- "pages": [
- "dex/semantic-layers/dex-semantics",
- "dex/semantic-layers/overview",
- "dex/semantic-layers/ossie",
- "dex/semantic-layers/cube",
- "dex/semantic-layers/databricks-metric-views",
- "dex/semantic-layers/snowflake-semantic-views"
- ]
- },
- {
- "group": "Integration contracts",
- "pages": [
- "dex/reference/command-contract",
- "dex/reference/project-formats",
- "dex/reference/storage-backends",
- "dex/reference/host-integration"
- ]
- },
- {
- "group": "Project quality",
- "pages": [
- "dex/reference/evaluation"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "pages": [
- "dex/changelog"
- ]
- }
- ]
- },
- {
- "version": "v1.17",
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get started",
- "pages": [
- "dex/v1.17/index",
- "dex/v1.17/quickstart",
- "dex/v1.17/installation",
- "dex/v1.17/connect"
- ]
- },
- {
- "group": "Workflows",
- "pages": [
- "dex/v1.17/guides/explore",
- "dex/v1.17/guides/transform",
- "dex/v1.17/guides/maintain",
- "dex/v1.17/guides/semantic-layer"
- ]
- },
- {
- "group": "Tutorials and help",
- "pages": [
- "dex/v1.17/guides/ossie-semantic-layer",
- "dex/v1.17/guides/troubleshooting"
- ]
- }
- ]
- },
- {
- "tab": "Reference",
- "groups": [
- {
- "group": "CLI",
- "pages": [
- "dex/v1.17/cli/overview",
- "dex/v1.17/cli/init",
- "dex/v1.17/cli/connect",
- "dex/v1.17/cli/explore",
- "dex/v1.17/cli/transform",
- "dex/v1.17/cli/semantic",
- "dex/v1.17/cli/maintain",
- "dex/v1.17/cli/config",
- "dex/v1.17/cli/demo",
- "dex/v1.17/cli/procedure",
- "dex/v1.17/cli/feedback"
- ]
- },
- {
- "group": "Connectors",
- "pages": [
- "dex/v1.17/connectors/duckdb",
- "dex/v1.17/connectors/bigquery",
- "dex/v1.17/connectors/snowflake",
- "dex/v1.17/connectors/databricks",
- "dex/v1.17/connectors/redshift",
- "dex/v1.17/connectors/postgres",
- "dex/v1.17/connectors/clickhouse",
- "dex/v1.17/connectors/trino"
- ]
- },
- {
- "group": "Safety and spending",
- "pages": [
- "dex/v1.17/guardrails/cost-controls",
- "dex/v1.17/guardrails/pii-policy",
- "dex/v1.17/guardrails/values-free-mode"
- ]
- },
- {
- "group": "Project and exploration",
- "pages": [
- "dex/v1.17/concepts/source-of-truth",
- "dex/v1.17/concepts/methodology",
- "dex/v1.17/concepts/dbt-project"
- ]
- },
- {
- "group": "Semantic layer compatibility",
- "pages": [
- "dex/v1.17/semantic-layers/dex-semantics",
- "dex/v1.17/semantic-layers/overview",
- "dex/v1.17/semantic-layers/ossie",
- "dex/v1.17/semantic-layers/cube",
- "dex/v1.17/semantic-layers/databricks-metric-views",
- "dex/v1.17/semantic-layers/snowflake-semantic-views"
- ]
- },
- {
- "group": "Integration contracts",
- "pages": [
- "dex/v1.17/reference/command-contract",
- "dex/v1.17/reference/project-formats",
- "dex/v1.17/reference/storage-backends",
- "dex/v1.17/reference/host-integration"
- ]
- },
- {
- "group": "Project quality",
- "pages": [
- "dex/v1.17/reference/evaluation"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "pages": [
- "dex/v1.17/changelog"
- ]
- }
- ]
- },
- {
- "version": "v1.16",
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get started",
- "pages": [
- "dex/v1.16/index"
- ]
- },
- {
- "group": "Guardrails",
- "pages": [
- "dex/v1.16/guardrails/cost-controls",
- "dex/v1.16/guardrails/pii-policy",
- "dex/v1.16/guardrails/values-free-mode"
- ]
- },
- {
- "group": "Concepts",
- "pages": [
- "dex/v1.16/concepts/source-of-truth",
- "dex/v1.16/concepts/methodology",
- "dex/v1.16/concepts/dbt-project"
- ]
- },
- {
- "group": "Connectors",
- "pages": [
- "dex/v1.16/connectors/duckdb",
- "dex/v1.16/connectors/bigquery",
- "dex/v1.16/connectors/snowflake",
- "dex/v1.16/connectors/databricks",
- "dex/v1.16/connectors/redshift",
- "dex/v1.16/connectors/postgres",
- "dex/v1.16/connectors/clickhouse",
- "dex/v1.16/connectors/trino"
- ]
- },
- {
- "group": "Semantic layers",
- "pages": [
- "dex/v1.16/semantic-layers/overview",
- "dex/v1.16/semantic-layers/ossie",
- "dex/v1.16/semantic-layers/cube"
- ]
- },
- {
- "group": "Guides",
- "pages": [
- "dex/v1.16/guides/ossie-semantic-layer"
- ]
- }
- ]
- },
- {
- "tab": "Reference",
- "groups": [
- {
- "group": "CLI",
- "pages": [
- "dex/v1.16/cli/overview",
- "dex/v1.16/cli/connect",
- "dex/v1.16/cli/explore",
- "dex/v1.16/cli/transform",
- "dex/v1.16/cli/semantic",
- "dex/v1.16/cli/maintain",
- "dex/v1.16/cli/config",
- "dex/v1.16/cli/viz",
- "dex/v1.16/cli/demo"
- ]
- },
- {
- "group": "Using dex",
- "pages": [
- "dex/v1.16/reference/command-contract"
- ]
- },
- {
- "group": "Extending dex",
- "pages": [
- "dex/v1.16/reference/project-formats",
- "dex/v1.16/reference/storage-backends",
- "dex/v1.16/reference/host-integration"
- ]
- },
- {
- "group": "Project",
- "pages": [
- "dex/v1.16/reference/evaluation"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "pages": [
- "dex/v1.16/changelog"
- ]
- }
- ]
- },
- {
- "version": "v1.15",
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get started",
- "pages": [
- "dex/v1.15/index"
- ]
- },
- {
- "group": "Guardrails",
- "pages": [
- "dex/v1.15/guardrails/cost-controls",
- "dex/v1.15/guardrails/pii-policy",
- "dex/v1.15/guardrails/values-free-mode"
- ]
- },
- {
- "group": "Concepts",
- "pages": [
- "dex/v1.15/concepts/source-of-truth",
- "dex/v1.15/concepts/methodology",
- "dex/v1.15/concepts/dbt-project"
- ]
- },
- {
- "group": "Connectors",
- "pages": [
- "dex/v1.15/connectors/duckdb",
- "dex/v1.15/connectors/bigquery",
- "dex/v1.15/connectors/snowflake",
- "dex/v1.15/connectors/databricks",
- "dex/v1.15/connectors/redshift",
- "dex/v1.15/connectors/postgres",
- "dex/v1.15/connectors/clickhouse",
- "dex/v1.15/connectors/trino"
- ]
- },
- {
- "group": "Semantic layers",
- "pages": [
- "dex/v1.15/semantic-layers/overview",
- "dex/v1.15/semantic-layers/ossie"
- ]
- },
- {
- "group": "Guides",
- "pages": [
- "dex/v1.15/guides/ossie-semantic-layer"
- ]
- }
- ]
- },
- {
- "tab": "Reference",
- "groups": [
- {
- "group": "CLI",
- "pages": [
- "dex/v1.15/cli/overview",
- "dex/v1.15/cli/connect",
- "dex/v1.15/cli/explore",
- "dex/v1.15/cli/transform",
- "dex/v1.15/cli/semantic",
- "dex/v1.15/cli/maintain",
- "dex/v1.15/cli/config",
- "dex/v1.15/cli/viz",
- "dex/v1.15/cli/demo"
- ]
- },
- {
- "group": "Using dex",
- "pages": [
- "dex/v1.15/reference/command-contract"
- ]
- },
- {
- "group": "Extending dex",
- "pages": [
- "dex/v1.15/reference/project-formats",
- "dex/v1.15/reference/storage-backends",
- "dex/v1.15/reference/host-integration"
- ]
- },
- {
- "group": "Project",
- "pages": [
- "dex/v1.15/reference/evaluation"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "pages": [
- "dex/v1.15/changelog"
- ]
- }
- ]
- },
- {
- "version": "v1.14",
- "tabs": [
- {
- "tab": "Documentation",
- "groups": [
- {
- "group": "Get started",
- "pages": [
- "dex/v1.14/index"
- ]
- },
- {
- "group": "Guardrails",
- "pages": [
- "dex/v1.14/guardrails/cost-controls",
- "dex/v1.14/guardrails/pii-policy"
- ]
- },
- {
- "group": "Concepts",
- "pages": [
- "dex/v1.14/concepts/source-of-truth",
- "dex/v1.14/concepts/methodology",
- "dex/v1.14/concepts/dbt-project"
- ]
- },
- {
- "group": "Connectors",
- "pages": [
- "dex/v1.14/connectors/duckdb",
- "dex/v1.14/connectors/bigquery",
- "dex/v1.14/connectors/snowflake",
- "dex/v1.14/connectors/databricks",
- "dex/v1.14/connectors/redshift",
- "dex/v1.14/connectors/postgres",
- "dex/v1.14/connectors/clickhouse"
- ]
- },
- {
- "group": "Semantic layers",
- "pages": [
- "dex/v1.14/semantic-layers/overview",
- "dex/v1.14/semantic-layers/ossie"
- ]
- },
- {
- "group": "Guides",
- "pages": [
- "dex/v1.14/guides/ossie-semantic-layer"
- ]
- }
- ]
- },
- {
- "tab": "Reference",
- "groups": [
- {
- "group": "CLI",
- "pages": [
- "dex/v1.14/cli/overview",
- "dex/v1.14/cli/connect",
- "dex/v1.14/cli/explore",
- "dex/v1.14/cli/transform",
- "dex/v1.14/cli/semantic",
- "dex/v1.14/cli/maintain",
- "dex/v1.14/cli/config",
- "dex/v1.14/cli/viz",
- "dex/v1.14/cli/demo"
- ]
- },
- {
- "group": "Using dex",
- "pages": [
- "dex/v1.14/reference/command-contract"
- ]
- },
- {
- "group": "Extending dex",
- "pages": [
- "dex/v1.14/reference/project-formats",
- "dex/v1.14/reference/storage-backends",
- "dex/v1.14/reference/host-integration"
- ]
- },
- {
- "group": "Project",
- "pages": [
- "dex/v1.14/reference/evaluation"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "pages": [
- "dex/v1.14/changelog"
- ]
- }
- ]
- }
- ]
-}
diff --git a/dex/quickstart.mdx b/dex/quickstart.mdx
deleted file mode 100644
index 7dce4ec..0000000
--- a/dex/quickstart.mdx
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: Set up your Dex project
-sidebarTitle: Quickstart
-description: Install Dex, create a local demo warehouse, and investigate a broken key and join. Learn to read the results before connecting your own warehouse.
-og:title: Set up your Dex project · Exmergo Dex
-twitter:title: Set up your Dex project · Exmergo Dex
----
-
-
-Start with a local DuckDB warehouse that contains deliberate data defects. By the
-end, you will have a map of its tables and evidence about a key and a join that
-cannot be trusted.
-
-You need a terminal and [uv](https://docs.astral.sh/uv/getting-started/installation/).
-Installation downloads packages; the demo and exploration run locally afterwards.
-
-## 1. Install the CLI
-
-```bash
-uv tool install "exmergo-dex-core[duckdb]"
-dex --help
-```
-
-Already using the Dex skills? Ask your agent to run the commands below through
-its installed wrapper. The wrapper and the CLI use the same engine.
-
-## 2. Initialize the project
-
-For guided setup, run `dex init`. It recommends creating a Dex project backed
-by dbt and your chosen connector. The second option creates a complete local
-demo. Existing dbt projects are adopted without replacing their authored files;
-exploration-only and standalone semantic setups do not require dbt.
-
-Use a new directory outside an existing Dex project so the demo can create its
-own configuration.
-
-```bash
-mkdir dex-first-run
-cd dex-first-run
-dex init analytics --mode demo
-```
-
-The command creates `dex_demo.duckdb`, `.dex/config.yml`, a dbt skeleton under
-`analytics/`, a README, and managed agent instructions. The warehouse has seven
-tables and 29,512 rows. `.dex/` and onboarding docs stay at the repository root.
-Rerunning setup preserves authored content and updates only Dex-managed sections.
-
-Setup verifies the connection but does not explore data or run a dbt build.
-Read `data.readiness`: configuration, connection, build prerequisites, and an
-actual build are reported separately. Missing credentials leave setup incomplete
-with recovery instructions. No warehouse objects are created during cloud setup.
-The commands below are explicit follow-up work after initialization.
-
-## 3. Map the warehouse
-
-```bash
-dex explore map
-```
-
-Read `data.objects` for each table's grain, candidate key, and findings, then
-`data.edges` for the inferred joins. A candidate key is a measurement; a shared
-column name alone is not proof of a join.
-
-Every command prints a JSON envelope. Start with these fields:
-
-| Field | What to read |
-| --- | --- |
-| `status` | Whether the command succeeded, failed, or needs confirmation |
-| `data` | The map, profile, or other result you asked for |
-| `warnings` | Limits or qualifications that affect the result |
-| `errors` and `reason` | Why a command could not finish |
-
-## 4. Investigate the findings
-
-```bash
-dex explore profile order_items products
-dex explore relationships --verify
-```
-
-The demo's `order_item_id` has duplicates, so it is not a valid grain. The
-`web_events.customer_id` join also fails verification: its values do not match
-the customer keys. These are intentional defects, not installation failures.
-
-To ask a data question, use Dex's query command:
-
-```bash
-dex explore query "select count(*) as order_count from orders"
-```
-
-This returns 5,000 orders. Queries go through the same profiling and PII checks
-as the rest of exploration.
-
-
-
-```bash
-dex explore query "select email from customers"
-```
-
-This query is expected to be refused. The email column is flagged as personal
-data. Do not clear a flag just to make an example run; see the
-[PII policy](/dex/guardrails/pii-policy) for how flags are reviewed.
-
-
-
-## Next steps
-
-
-
- Choose a connector, verify access, and set the scope for exploration.
-
-
- Turn the map into a focused investigation and verify the joins it needs.
-
-
diff --git a/dex/redirects.json b/dex/redirects.json
deleted file mode 100644
index 4b302cf..0000000
--- a/dex/redirects.json
+++ /dev/null
@@ -1,218 +0,0 @@
-[
- {
- "source": "/dex/cli",
- "destination": "/dex/cli/overview"
- },
- {
- "source": "/dex/reference",
- "destination": "/dex/reference/command-contract"
- },
- {
- "source": "/dex/references/duckdb",
- "destination": "/dex/connectors/duckdb"
- },
- {
- "source": "/dex/references/duckdb.md",
- "destination": "/dex/connectors/duckdb"
- },
- {
- "source": "/dex/references/bigquery",
- "destination": "/dex/connectors/bigquery"
- },
- {
- "source": "/dex/references/bigquery.md",
- "destination": "/dex/connectors/bigquery"
- },
- {
- "source": "/dex/references/snowflake",
- "destination": "/dex/connectors/snowflake"
- },
- {
- "source": "/dex/references/snowflake.md",
- "destination": "/dex/connectors/snowflake"
- },
- {
- "source": "/dex/references/databricks",
- "destination": "/dex/connectors/databricks"
- },
- {
- "source": "/dex/references/databricks.md",
- "destination": "/dex/connectors/databricks"
- },
- {
- "source": "/dex/references/redshift",
- "destination": "/dex/connectors/redshift"
- },
- {
- "source": "/dex/references/redshift.md",
- "destination": "/dex/connectors/redshift"
- },
- {
- "source": "/dex/references/postgres",
- "destination": "/dex/connectors/postgres"
- },
- {
- "source": "/dex/references/postgres.md",
- "destination": "/dex/connectors/postgres"
- },
- {
- "source": "/dex/references/clickhouse",
- "destination": "/dex/connectors/clickhouse"
- },
- {
- "source": "/dex/references/clickhouse.md",
- "destination": "/dex/connectors/clickhouse"
- },
- {
- "source": "/dex/references/trino",
- "destination": "/dex/connectors/trino"
- },
- {
- "source": "/dex/references/trino.md",
- "destination": "/dex/connectors/trino"
- },
- {
- "source": "/dex/references/dex-semantics",
- "destination": "/dex/semantic-layers/dex-semantics"
- },
- {
- "source": "/dex/references/dex-semantics.md",
- "destination": "/dex/semantic-layers/dex-semantics"
- },
- {
- "source": "/dex/references/semantic-layer",
- "destination": "/dex/semantic-layers/overview"
- },
- {
- "source": "/dex/references/semantic-layer.md",
- "destination": "/dex/semantic-layers/overview"
- },
- {
- "source": "/dex/references/ossie-compatibility",
- "destination": "/dex/semantic-layers/ossie"
- },
- {
- "source": "/dex/references/ossie-compatibility.md",
- "destination": "/dex/semantic-layers/ossie"
- },
- {
- "source": "/dex/references/cube-compatibility",
- "destination": "/dex/semantic-layers/cube"
- },
- {
- "source": "/dex/references/cube-compatibility.md",
- "destination": "/dex/semantic-layers/cube"
- },
- {
- "source": "/dex/references/databricks-metric-views-compatibility",
- "destination": "/dex/semantic-layers/databricks-metric-views"
- },
- {
- "source": "/dex/references/databricks-metric-views-compatibility.md",
- "destination": "/dex/semantic-layers/databricks-metric-views"
- },
- {
- "source": "/dex/references/snowflake-semantic-views-compatibility",
- "destination": "/dex/semantic-layers/snowflake-semantic-views"
- },
- {
- "source": "/dex/references/snowflake-semantic-views-compatibility.md",
- "destination": "/dex/semantic-layers/snowflake-semantic-views"
- },
- {
- "source": "/dex/references/ossie-walkthrough",
- "destination": "/dex/guides/ossie-semantic-layer"
- },
- {
- "source": "/dex/references/ossie-walkthrough.md",
- "destination": "/dex/guides/ossie-semantic-layer"
- },
- {
- "source": "/dex/references/cost-controls",
- "destination": "/dex/guardrails/cost-controls"
- },
- {
- "source": "/dex/references/cost-controls.md",
- "destination": "/dex/guardrails/cost-controls"
- },
- {
- "source": "/dex/references/pii-policy",
- "destination": "/dex/guardrails/pii-policy"
- },
- {
- "source": "/dex/references/pii-policy.md",
- "destination": "/dex/guardrails/pii-policy"
- },
- {
- "source": "/dex/references/values-free-mode",
- "destination": "/dex/guardrails/values-free-mode"
- },
- {
- "source": "/dex/references/values-free-mode.md",
- "destination": "/dex/guardrails/values-free-mode"
- },
- {
- "source": "/dex/references/canonical-model",
- "destination": "/dex/concepts/source-of-truth"
- },
- {
- "source": "/dex/references/canonical-model.md",
- "destination": "/dex/concepts/source-of-truth"
- },
- {
- "source": "/dex/references/methodology",
- "destination": "/dex/concepts/methodology"
- },
- {
- "source": "/dex/references/methodology.md",
- "destination": "/dex/concepts/methodology"
- },
- {
- "source": "/dex/references/dbt-project",
- "destination": "/dex/concepts/dbt-project"
- },
- {
- "source": "/dex/references/dbt-project.md",
- "destination": "/dex/concepts/dbt-project"
- },
- {
- "source": "/dex/references/command-contract",
- "destination": "/dex/reference/command-contract"
- },
- {
- "source": "/dex/references/command-contract.md",
- "destination": "/dex/reference/command-contract"
- },
- {
- "source": "/dex/references/project",
- "destination": "/dex/reference/project-formats"
- },
- {
- "source": "/dex/references/project.md",
- "destination": "/dex/reference/project-formats"
- },
- {
- "source": "/dex/references/storage",
- "destination": "/dex/reference/storage-backends"
- },
- {
- "source": "/dex/references/storage.md",
- "destination": "/dex/reference/storage-backends"
- },
- {
- "source": "/dex/references/host-integration",
- "destination": "/dex/reference/host-integration"
- },
- {
- "source": "/dex/references/host-integration.md",
- "destination": "/dex/reference/host-integration"
- },
- {
- "source": "/dex/references/evaluation",
- "destination": "/dex/reference/evaluation"
- },
- {
- "source": "/dex/references/evaluation.md",
- "destination": "/dex/reference/evaluation"
- }
-]
diff --git a/dex/reference/command-contract.mdx b/dex/reference/command-contract.mdx
deleted file mode 100644
index db48891..0000000
--- a/dex/reference/command-contract.mdx
+++ /dev/null
@@ -1,2716 +0,0 @@
----
-title: The command contract
-sidebarTitle: Command contract
-description: 'The dex command contract: every subcommand, the single sanitized JSON envelope it prints, the query firewall, and the rules an agent relies on between calls.'
-og:title: The command contract · Exmergo Dex
-twitter:title: The command contract · Exmergo Dex
----
-
-This is the integration keystone. It is the boundary between the agent
-and the engine, and it is what keeps every agent surface thin: each surface calls
-the same subcommands and reads the same envelope, so no surface re-implements
-logic.
-
-## Shape of the boundary
-
-- A surface (SKILL.md or AGENTS.md) tells the agent which subcommand to run.
-- A thin PEP 723 wrapper (`skills//scripts/run.py`) runs it via
- `uv run --no-project` against the pinned engine version, installing the connector
- extra it resolves at runtime (an explicit `--connector`, then the `connector:` in the `.dex/config.yml`
- found by walking up from the run directory to the git root, then DuckDB), so the
- pin stays connector-neutral. `uv` is therefore a prerequisite, and the wrapper
- holds the envelope contract even there: with no `uv` on `PATH` it refuses with a
- `reason: prerequisite` error envelope naming the install command, rather than
- failing the exec. It is the one refusal built by hand, because the engine that
- would otherwise build it is what is missing. Two commands need more than a
- warehouse client, and both are resolved the same way, from the command being run
- rather than installed always: `explore cluster` adds `[cluster]`, and
- `explore semantic` adds `[semantic-api]` plus, where a statement might be
- rendered locally (any mode but `list`, without `--api`), `[semantic]`, and
- `[slayer]` where `semantic.vendor` is `slayer`, in place of `[semantic]`, since
- SLayer renders its own `query` and `values`. `[cube]` follows the same
- `semantic.vendor` read for the same commands where the vendor is `cube`, is
- always taken by `semantic cube`, and a
- Cube `query` or `values` never takes `[semantic]` either. `[metric-views]`
- follows the same read where the vendor is `databricks`, is always taken by
- `semantic databricks`, and never takes `[semantic]`. `[semantic-views]`
- follows the same read where the vendor is `snowflake` (also a connector name,
- whose extra still comes from `connector:` alone), is always taken by
- `semantic snowflake`, and never takes `[semantic]`.
- A repo that runs neither resolves neither scikit-learn nor MetricFlow.
-- That environment is uv's own, and `--no-project` is what keeps it so. Without it
- uv discovers whatever Python project the caller is standing in, builds it, leaves
- a `.venv/` and a `uv.lock` in their repo, and puts their dependencies on the
- engine's import path: unreviewed writes into a tree dex was asked only to read,
- and an engine no longer running against the closure it pinned. The invariant is
- asserted structurally on the commands the wrapper builds, in the safety spine.
-- `--warm` is the wrapper's own flag and the only one it answers itself, stripped
- before the argv reaches the engine. It resolves extras through the same path a
- real run does, installs them, prints one envelope naming what it installed, and
- exits without running a command. That is what lets a container build, a CI setup
- step, or a first-time install pay a cold resolution once instead of leaving it on
- an interactive caller's clock, and resolving through the shared path is what
- keeps it from warming an environment the next command would contradict.
-- The engine prints **exactly one** sanitized JSON envelope to stdout and nothing
- else. Diagnostics go to stderr.
-- Every envelope carries a constant `connection` block. On success it names the
- resolved connector, its non-secret target coordinates, and the source of that
- resolution (`flag`, `.dex/config.yml`, `environment variable`,
- `dbt profiles.yml`, or `directory-local inference`). Commands that resolve no
- warehouse keep the same shape with null/empty fields. This includes the
- wrapper's missing-uv refusal and warm-up responses: their connection fields are
- null/empty and all cost fields are null, because no warehouse was contacted or
- query priced. The block is assembled from facts already resolved by the command
- and never opens a connection or spends merely to describe one.
-- `DBT_PROFILES_DIR` locates `profiles.yml` for dbt operations and the
- last-resort credential fallback. It does **not** select dex's connector or
- override `--connector`/`--path` or `.dex/config.yml`; help and no-connector
- refusals say so explicitly.
-- The agent reads the envelope and decides the next step.
-
-State persists in the dbt project (the source of truth) and the `.dex/` cache, so
-subcommands are **stateless**: the agent orchestrates multi-step flows by
-re-reading them between calls. Credentials never cross this boundary, and nothing
-reaches agent context except through the sanitized envelope: values cross only
-from profiled, PII-cleared columns, bounded and capped by the query firewall.
-Every `errors` and `warnings` entry is redacted as the envelope is printed
-(`key=value` and `key: value` secrets, `Bearer` and `Authorization:` credentials,
-query-string secrets, and URL passwords), since a message often quotes text dex
-did not write.
-
-## The command surface
-
-Capabilities, not final spelling. Implemented incrementally: `demo`, `procedure`, `feedback`, `connect test`,
-the `config` group, the `explore` group, the authoring surface (`transform`,
-`semantic`), and the `maintain` group are live.
-
-```
-dex demo [path] -> generate a seeded local DuckDB warehouse (7 tables,
- 29,512 rows) plus a .dex/config.yml beside it, so a
- first run needs no warehouse and no credentials;
- reports both under data.created and names what to
- run next under data.next_steps. A relative path
- resolves against --repo-root and is reported
- relative to it; the next steps carry the same
- --repo-root so they run as printed. Create-only
- and not confirmable: an existing target refuses, no
- directory is ever created, and an existing config
- at or above the target is left alone with a warning
-dex procedure [--block] [--check ...]
- -> the agent procedure every skill and AGENTS.md
- carry, held once in the engine: data.text,
- data.digest, data.engine_version, data.markers.
- --block adds data.block, the text between the
- dex:procedure markers, to paste into CLAUDE.md or
- AGENTS.md (procedure itself writes neither). --check reads
- each file and reports its copy current, stale,
- missing, malformed, absent or unreadable under
- data.copies, never echoing content; any copy that
- is not current is status error (reason request).
- Routed before any engine: no config, no connector
- extra, no connection; allowed in values-free mode
-dex feedback [--command ] -> what a bug report needs: data.environment (versions,
- OS, connector and semantic vendor names, result
- mode; never a target, credential, path or value),
- data.links (bug and feature issue forms prefilled
- from it) and data.guidance. Nothing is sent. Routed
- before any engine; allowed in values-free mode. A
- reason: internal error envelope carries data.report,
- the same prefilled bug link, never the error text
-dex connect test -> {capabilities, dialect, read_only: true}
-dex config get [key] -> the effective value of every setting, or of those
- under key, as flat rows under data.settings: value,
- source (file, default, derived, or environment), the
- line it was written on, and as_written when the
- file's spelling was normalized. A value under a
- credential-like name is withheld. Reads only the
- file, before any engine exists: no connection, no
- connector extra. Refuses a file no command could
- load, naming its problems in data.problems
-dex config validate -> every problem in .dex/config.yml by setting and line,
- running nothing else: syntax, values the schema
- refuses, keys dex does not read (with the key each
- was probably meant to be), keys written twice,
- credential-like keys. problems[].fatal marks the ones
- that stop every other command. Any problem is status
- error, reason configuration, so it gates CI alone
-dex config set -> an in-place edit that keeps every comment, the key
- [...] order and every other line: needs_confirmation with
- the diff and nothing written, then the same command
- with --confirm writes it. is YAML read the
- way the field reads it. Several pairs make one
- change, for keys only valid together. Refuses a
- change that adds a problem stopping commands; one
- already in the file is a warning, so a broken file
- is repaired one key at a time. Refuses a
- credential-like name in the key or inside the
- value. data.changes is one row per value (key,
- before, after, or withheld)
-dex config unset [...] -> removes settings with the same in-place edit and
- handshake as set. Takes a key dex does not read and
- a whole block; a block left empty goes too, with
- one blank-line separator. A key the file does not
- write is ok, changed false, with a note naming the
- nearest key it does. A key inside one list item is
- refused: the list changes whole, through set.
- Refuses a removal that adds a problem stopping
- commands
-dex explore inventory [--rank] -> ranked object summary (counts, sizes; no rows). --rank caps at 30
- [--limit N] [--all] objects by default (kept by rank); --limit widens it, --all lifts
- it; both no-ops without --rank
-dex explore profile -> column profiles + PII flags + candidate keys, grain, data-quality warnings.
- [--columns all] Verdict fields (grain, keys, data quality, row count) lead the
- payload, columns trails; by default columns is summarized to the
- ones carrying a finding, with the rest in elided_column_count.
- --columns all restores every column. A per-column field that is
- null on every column shown is dropped from each and named once
- in suppressed_fields (always present; empty means nothing was
- dropped). Each value_domain carries its most frequent
- profile_value_domain_cap values (.dex/config.yml, default 25)
- with the rest counted in its elided. Both reduce the payload
- only, never the cached profile
- [--target dev] also reads the dev namespace for this one command (#893), as
- maintain verify --target dev does: a model whose only build is
- the dev one becomes profileable without widening the committed
- allowlist. --scope still only narrows, nothing is written back,
- the cost guard prices the scan; prod-looking targets refused.
- Also reads the namespaces dbt derives from the dev one for the
- project's models (a package's +schema, #1155), named in notes.
- DuckDB: its dev target is the file already read, so the flag
- widens nothing and a note says so
-dex explore relationships -> inferred + declared joins with confidences + inference notes
- (declared covers both a relationships test and a join the
- semantic layer declares; `semantic_join_count` splits them)
-dex explore map [--detail] -> write/update the .dex cache, and return the map:
- per top-ranked object its grain, key, notable
- columns, PII flags and data-quality findings,
- plus the join edges, alongside the counts. Every
- cap binds in every mode and every elision is
- counted in notes; --detail widens the selection,
- never the caps. No column value ever appears
-dex explore diagram -> the cached map as a Mermaid erDiagram, in `data.mermaid`;
- free and connectionless (a store read, no warehouse);
- declared joins solid (a relationships test or a shared
- semantic-layer entity, the latter naming the entity in
- its label), inferred dotted, and a cardinality
- drawn only where the cache proved it; draws profiled,
- joined objects with their grain/key/join/PII columns
- (--full for every eligible object and column); every
- elision is counted in notes; dex writes no file
-dex explore query "