Keep the repository correct as the world underneath it moves, on both of its\naxes: the dbt project and the semantic layer. Maintenance is the recurring half\nof the loop: warehouses drift, loads half-fail, models go stale, keys stop being\nunique, and business definitions change. This skill compares a known-good\nbaseline against current reality, classifies what drifted, and proposes the\nreconciling edit. It is manual and on-demand here; continuous drift detection and\nautomated PRs are the commercial product.
\nDrift is measured against a baseline (the .dex/snapshot.json fingerprint of\nthe warehouse map and the repository's per-layer definitions). Detection is\nread-only; only reconcile proposes edits.
The two project layers are fingerprinted independently. The transform layer\ncomes from the dbt project; the semantic layer comes from whichever vendor\nsemantic.vendor names, which may be dbt's own or a native format such as\nApache Ossie. A repository with a semantic layer and no dbt project at all still\ngets a baseline and still runs every free axis: transform_layer comes back\nnull, and the warning that names why no project was fingerprinted is reserved for\nthe case where neither layer answered, since that is the one you could otherwise\nmistake for a clean read.
Snapshot discipline matters. A snapshot is only as trustworthy as the moment\nit froze. Take one right after a known-good build (maintain snapshot), and\ncommit .dex/snapshot.json like a lockfile so the whole team diffs against\nthe same reference. Snapshot a state that is already drifted and check will\nmask the very drift you care about. When you accept a change as the new normal\n(re-run explore map first, then maintain snapshot); check warns when the\nbaseline looks stale.
On a warehouse past the rank cutoff, use explore map --full before\nsnapshotting. Past 50 objects explore map profiles the top 25 by rank and\nenters the rest as metadata alone, and the baseline can only compare columns for\nobjects it has columns for. Snapshotting a partial map is still valid, and the\nenvelope reports column_detail_count against dataset_count plus a warning\nnaming what it could not cover, so the gap is visible rather than silently\nmistaken for a clean bill.
uv run --no-project --script \"${CLAUDE_SKILL_DIR}/scripts/run.py\" <subcommand> [flags]\ndex runs its engine through uv, which is a prerequisite and is not installed by\nClaude Code. If the shell reports uv: command not found, stop and tell the user\nto install it (curl -LsSf https://astral.sh/uv/install.sh | sh, or\nbrew install uv, or pipx install uv), then re-run. Never fall back to diffing\nthe warehouse against the project by hand instead: the drift axes and the baseline\ncomparison live in the engine, so any other path is guesswork.
The first command in a fresh environment installs the engine, so it can take tens\nof seconds where later ones take well under a second. --warm pays that install up\nfront and exits without running anything:
uv run --no-project --script \"${CLAUDE_SKILL_DIR}/scripts/run.py\" --warm\nOffer it once at setup. It is not something to run before an ordinary command.
\nmaintain snapshot captures or refreshes the baseline. Run it after a clean\nexplore or transform session so later runs have a known-good reference. It pins\nthe current .dex/cache.json (so the grain baseline is the exact-distinct\nverdicts explore map already computed) plus per-layer fingerprints of the dbt\nproject and of the semantic layer. A native semantic layer contributes its\ndefinitions per dataset and per metric, each with a content hash, the relation\nbehind it, the column each field resolves to, its declared keys in the arity\nthey were written, and its relationships with every ordered column pair;\nwhether that side was captured is itself recorded, so a baseline written before\nit reports the relationship axis as unchecked rather than clean.\nWithout a cache it captures a metadata-only baseline and says so. It\nalso warns when the cache it pinned is thin (objects without column detail) or\nolder than the profile freshness window, because either makes an \"accept\ncurrent state\" only partly true.
maintain snapshot --project-only is for a project-only refactor, such as\nmoved model files or a dbt project rename. It refreshes transform and semantic\nfingerprints without opening the warehouse, carrying the previous warehouse\nevidence and original capture time forward instead. It requires an existing\nsnapshot and refuses connection-target flags.
maintain check is the everyday entry point: it sweeps every axis and returns\na report ranked by blast radius. Read-only.
maintain schema [<objects>] detects structural drift: source columns and\ntables added, dropped, retyped, or renamed; nullability changes; declared\nsources the warehouse no longer honors.
maintain volume [<objects>] detects freshness drift: row counts that\ncollapsed, spiked, or went to zero. This is the \"is the data still flowing\ncorrectly?\" axis, distinct from \"did the shape change?\".
maintain grain [<objects>] detects grain drift: a key that now has\nduplicates, a changed row-per-entity cardinality, or an increased join fanout.\nIt also re-verifies the grains the repository declares, which measurement on\nits own can miss: a dbt model-level unique_combination_of_columns, and a\nsemantic layer's own key declarations. A multi-column declaration is measured\nas one complete composite and never one column at a time. Uses aggregates,\nnever raw rows.
A native semantic layer's keys reach this axis and nothing else reaches it for\nthem, since such a layer is never the transformation project. They go through\nthe identical billed handshake on a metered warehouse: nothing here is cheaper\nor less gated because the declaration came from a document rather than from\ndbt.
\nTwo findings come out of the uniqueness checks and the difference is the\nbaseline. key_lost_uniqueness is a key that was proven unique and is not any\nmore: something changed in the data. declared_grain_not_unique is a declared\ncombination that does not hold, and nothing changed at all: the project asserts\na grain the data never had, so the fix is to the declaration (widen it, dedup\nupstream, or drop the claim) rather than to the data.
maintain semantic [<objects>] detects definition drift: definitions that\nchanged, were added, or were removed against the baseline; a source relation\nthat is gone; a dimension, entity, measure, or declared key naming a column\nthat is gone; a relationship whose endpoint or column pairs no longer resolve,\nwhich is high because a join nothing can resolve is a broken layer rather\nthan a stale one; and categorical dimensions whose set of values widened or\nnarrowed underneath their metrics.
Read unavailable on the layer before hunting for an element kind. A native\nOssie layer has no measures and no entities at all, so their absence is the\nformat rather than drift. Its cardinality half also never fires, because that\ncheck needs a semantic model naming a transformation model and Ossie names\nnone: on such a layer this command is free and offers no scan.
maintain verify [<selector>] answers a different question from every command\nabove it: not \"what changed since the baseline\" but \"is this project right\nnow\", and it needs no baseline at all, so it works on a project that was\nnever correct and on one somebody else just built. Two classes of finding.\nBuild status: nodes that failed, nodes skipped because a parent failed (naming\nthe one that actually failed), nodes that warned rather than failed, and models\nthe project declares that built no relation. A warning ranks low deliberately:\na project that runs relationship tests at severity: warn over documented gaps\nhas warnings by design, so this is a list to compare against last run's rather\nthan a defect on its own. What it must not be is missing, which is what leaves\na caller counting statuses in a run's raw node list to find out which tests\nwarned. Row population: row_loss where a model holds materially fewer rows\nthan its driving parent (the relation in its FROM clause, followed through\nthe CTE chain, as distinct from anything it joins) and nothing in its SQL\naccounts for the shortfall, and row_fanout where it holds materially more,\neach naming the join and its key and stating both counts.
Row population is conservative on purpose. A model with a WHERE, GROUP BY,\nDISTINCT, QUALIFY, LIMIT, a semi or anti join, or a set operation was\nwritten to hold a different number of rows and is never reported for loss; an\nincremental model is skipped outright. So a quiet answer here is weaker\nevidence than a finding, and the warnings say which models could not be\nlined up at all.
A project that does not compile is reported first and suppresses everything\nelse, since a manifest a broken project could not have produced is not\nevidence. Read data.suppressed before reading an empty data.findings as a\nclean bill of health.
The same sweep runs from the other side of the loop, as\ntransform build --verify, scoped to the nodes one build touched. Use that\nwhen the question is whether a change you just made is right; use this one\nwhen the question is the whole project, or when the build was somebody\nelse's.
maintain reconcile [<class>] proposes the dbt edits that bring the project\nback in sync, as reviewable diffs. Optionally scope it to one class (schema,\nvolume, grain, or semantic). It composes every layer's declarations\nfirst, so a grain the semantic layer already declares is not proposed as though\nnothing declared it. Where there is no editable dbt project it has nothing to\nauthor: every proposal is advisory and no plan is stored. Authoring into a\nnative semantic layer is semantic ossie in the transform skill, never this\ncommand.
The usual flow: check to triage, a focused detector to understand one axis in\ndepth, then reconcile to get the proposed fix. With no baseline, or on a\nproject whose numbers were never right, start at verify instead: it is the one\ncommand here that does not need a snapshot, and it answers \"is this right\"\nrather than \"what moved\".
Detection is read-only, but read-only is not the same as free on a metered\nconnector (BigQuery, Snowflake, Databricks, Postgres, Redshift, ClickHouse).\nThe axes split:
\nmaintain grain returns needs_confirmation with an estimate in\ncost.estimate (and a per-table breakdown). Surface it to the user in human\nunits, get an explicit budget, and re-issue the same command with\n--confirm --budget <magnitude> in the paradigm's unit (bytes on BigQuery,\nwarehouse-seconds on Snowflake and Databricks, compute-seconds on Redshift,\ndatabase-seconds on Postgres and\nClickHouse). Never invent a budget the user did not agree\nto, and never retry with a raised budget on an over-ceiling refusal without\nasking. An over-ceiling\nrefusal carries a calibration line from .dex/spend.jsonl (what this\nconnector's recent commands billed as a fraction of estimate, or a sentence\nsaying there is too little history to say): relay it, and note that the\nceiling binds on the estimate, so a budget set at that fraction of the\nestimate is refused again.verify is free except for the counts a warehouse does not keep. Its\nbuild-status findings read artifacts on disk, and its row counts come from\nobject metadata. A view has no stored row count anywhere, and a view is dbt's\ndefault materialization, so on a metered connector those counts are batched\ninto one aggregate-only statement, priced, and returned in data.offer beside\nfindings that are already final. On DuckDB there is no gate, so every count is\nmeasured rather than estimated and the findings come back exact.check, semantic and verify answer first and offer second. Their free axes\ncomplete on every call, so the envelope is ok and the findings in it are\nfinal. The price of the scanning axes sits in data.offer, with axes naming\nwhat it would add; data.axes_run names what already ran. Confirming is a\nchoice, not a required next step: quote the estimate, say which axes are still\ndark, and let the user decide. A triage pass that stops at the free axes is a\ncomplete piece of work, not an abandoned one.warnings on these responses, always. They carry the reasons the\nbaseline may no longer describe the warehouse (a cache newer than the\nsnapshot, a baseline pinned from a stale cache), which bound every finding\nabove them. A stale baseline is often the most important line in the response\nand it is never in findings.On DuckDB everything is free and local, so nothing prompts.
\nA needs_confirmation envelope carrying suggested_session_ceiling is the\nproject's one-time ask for a cumulative daily cap, separate from the\nper-command --budget. Surface it, get the user's answer, and add\n--session-ceiling <value> or --no-session-ceiling to the same re-issue; it is\nwritten to .dex/config.yml once and never asked again. Never answer it for\nthem.
Reconcile tags every proposal by kind, because the fix differs sharply by axis:
mechanical: schema drift reconciles in one of two shapes. On a\ndex-scaffolded staging model it re-scaffolds the model from the drifted source;\non a project format that places a declaration but authors no staging model, it\nedits the drifted columns into that declaration and says so. High-confidence, but\nstill a reviewable diff: read it for hand-written logic the scaffold cannot know\nabout.advisory: grain, volume, and semantic drift are decisions, not auto-fixes\n(dex cannot dedup your warehouse or decide whether a new 'refunded' status\nbelongs in a metric). The proposal is the decision surfaced, at most backed by a\ntest edit that makes the break visible in builds. It declines that test where\nthe test would be wrong: if your model declares a composite grain covering the\ncolumn, no column-level unique is proposed on it, and the warning names the\ncombination so you can tell \"re-baseline, this is still the grain\" from\n\"something relied on that column alone\".A type change is advisory on every format. Nothing dex writes declares a type,\nand the type it holds is the connector's own spelling rather than a canonical one\n(Snowflake reports NUMBER(38,0) and NUMBER(10,2) both as FIXED), so the\nproposal names both spellings and the edit is yours. One consequence to know: on\nClickHouse nullability is part of the type, so a column that starts accepting nulls\nis reported as a retype and gets advice where other connectors get an edit.
When reconcile produces edits it stores them as a plan and prints a plan_id.\nApply them with transform apply <plan-id> (the one apply door): a human edit made\nsince detection surfaces as a conflict, never a silent overwrite.
transform apply. Human edits to the project and to the semantic layer\nare authoritative; on conflict the engine surfaces the divergence and asks\nrather than overwriting..dex/ snapshot is a\nnon-canonical fingerprint used only to detect change.references/cost-controls.md.