/explore

name: explore
description: 'Use this whenever you need to know what is actually in a database, warehouse, or DuckDB file before you trust it: ranked inventory of what exists, column profiles, PII detection, grain and data-quality problems, verified join inference, Mermaid ER diagrams, guarded ad-hoc SQL probes, k-means segmentation, and reading the semantic layer a repo declares (dbt semantic models, a hosted dbt Cloud layer, or native Apache Ossie documents), producing a draft map without dumping the whole schema into context. Trigger it on an unmet precondition, not on any particular phrasing: if you are about to write or fix SQL against tables whose columns, types, grain, or join keys you have not verified in this session, use this FIRST. That includes dbt work: building a staging or mart model, fixing a broken model, or debugging wrong numbers, whenever the ticket names source tables without spelling out their schema. It also applies mid-task: if you are partway through and hit a table you have not inspected, stop and use this rather than guessing column names or firing off one-off SELECTs. Also use it for direct questions like "what''s in my duckdb", "which tables matter", "how do these tables relate", "is this data any good", "any PII in here", "how many orders have no customer", "cluster my customers", or "what metrics does this semantic layer define". Explore is read-only and writes nothing but the .dex/ cache. It does not author the model: pair it with transform, which writes the change once you know what you are writing against. To reconcile a project that has fallen out of sync, use maintain.'

Explore

Make sense of a warehouse or a local DuckDB database the way an analytics engineer does: rank what matters, drill selectively, and persist a draft map. This is the flagship, fully read-only skill. It absorbs profiling and relationship inference as capabilities; they are not separate skills.

How to drive it

Run the engine through the wrapper. It prints one sanitized JSON envelope and nothing else; read the envelope and decide the next step.

uv run --no-project --script "${CLAUDE_SKILL_DIR}/scripts/run.py" <subcommand> [flags]

dex runs its engine through `uv`, which is a prerequisite and is not installed by Claude Code. If the shell reports `uv: command not found`, stop and tell the user to install it (`curl -LsSf https://astral.sh/uv/install.sh | sh`, or `brew install uv`, or `pipx install uv`), then re-run. Never fall back to raw Python, `pip`, or a database CLI to do the work another way: the guardrails live in the engine, so any other path is unguarded.

The first command in a fresh environment installs the engine, so it can take tens of seconds where later ones take well under a second. `--warm` pays that install up front and exits without running anything:

uv run --no-project --script "${CLAUDE_SKILL_DIR}/scripts/run.py" --warm

Offer it once at setup. It is not something to run before an ordinary command.

If the user has no warehouse to point at and wants to see what dex does, `demo` generates one: a seeded local DuckDB warehouse plus the `.dex/config.yml` for it, with no credentials and no network, so every subcommand below then runs with no flags. It only ever creates, so it refuses rather than touch a file that already exists. Offer it rather than assuming it: a user who does have a warehouse wants that one read, not a fixture built beside it.

Subcommands, in the usual order:

1. `connect test --path <file.duckdb>` confirms a read-only connection and reports capabilities. 2. `explore inventory --rank` returns a ranked object summary (counts and sizes, never rows). 3. `explore profile <objects>` (space- or comma-separated) returns column profiles, PII flags recorded as (column, category, confidence) and never example values, plus candidate keys, the likely grain, and data-quality warnings (e.g. a non-unique id that will fan out on joins). A generic `*_name` flag's confidence is refined by value-shape evidence from the same scan, in both directions: person-shaped values corroborate it, a closed reference vocabulary or long labels de-rate it below the firewall's blocking threshold, and missing evidence changes nothing (the flag itself is never removed). Distinct counts are approximate for scale, but any column that looks unique within approximation noise is escalated to an exact COUNT(DISTINCT) (`distinct_count_exact: true`), so uniqueness and grain verdicts rest on proof; a `~` prefix in a warning marks a count that is still approximate. A requested object whose cached profile is still fresh (same connector, schema unchanged, within `profile_freshness_hours`, default 24) is served from the cache (`cache_hit_count`) instead of re-scanned, so profiling a table `map` just wrote costs nothing to spend; pass `--refresh` to force a re-scan when the source changed in a way the free metadata check cannot see. 4. `explore relationships` returns inferred and declared joins with confidences, plus notes explaining what the inference examined (so an empty list is meaningful). Add `--verify` to measure each inferred join with an aggregate overlap probe (orphan fraction, confidence adjusted). A declared join has two sources: a `relationships` test, and (with `--use-project`) an entity two semantic models share, which the layer states outright with the key named per model. `declared_by` on an edge names that entity, `semantic_join_count` says how many came that way, and the notes call out the ones name-based inference did not find, which is the interesting set: a semantic layer routinely joins columns that share no name at all. 5. `explore map` writes or updates the `.dex/` cache and returns the map (`--verify` works here too). Alongside the counts, `data.objects` gives each top-ranked object its row count, detected grain, candidate key, notable columns