diff --git a/.agents/README.md b/.agents/README.md
index a7ed1f5..e383558 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -8,7 +8,7 @@ Everything an AI coding agent needs to operate inside this repo. The `.claude 
 |---|---|
 | [`settings.json`](settings.json) | **Tracked** allow-list of safe, read-only Bash / git / WebFetch / pipeline commands. A fresh-clone agent gets these pre-approved so it doesn't burn turns on permission prompts. Side-effecting stages (build / fetch / extract / convert / tighten_variant) are intentionally *not* pre-approved here. |
 | `settings.local.json` | **Gitignored** per-machine override — additional permissions specific to the local agent's session. Don't commit. |
-| [`skills/`](skills/) | 16 invokable skills following the [Agent Skills](https://agentskills.io) standard — wrappers around pipeline entrypoints (`/raincloud-build`, `/raincloud-fetch`, `/raincloud-status`, `/raincloud-validate-manifest`, `/raincloud-list-datasets`, …) and procedural playbooks (`/raincloud-add-dataset`, `/raincloud-add-handler`, `/raincloud-debug-build`, …). See [`skills/README.md`](skills/README.md). |
+| [`skills/`](skills/) | 21 invokable skills following the [Agent Skills](https://agentskills.io) standard — wrappers around pipeline entrypoints (`/raincloud-build`, `/raincloud-fetch`, `/raincloud-status`, `/raincloud-validate-manifest`, `/raincloud-list-datasets`, `/raincloud-load`, `/raincloud-publish`, …) and procedural playbooks (`/raincloud-add-dataset`, `/raincloud-add-handler`, `/raincloud-debug-build`, …). See [`skills/README.md`](skills/README.md). |
 | [`context/`](context/) | Symlinks back to the repo-root canonical docs (`AGENTS.md`, `SKILLS.md`, `README.md`, `sources.schema.md`) so each `SKILL.md` can pull authoritative guidance via a stable relative path without copying. |
 | `scheduled_tasks.lock` | Gitignored — agent-runtime state. |
 
diff --git a/.agents/skills/README.md b/.agents/skills/README.md
index afd92e3..d254491 100644
--- a/.agents/skills/README.md
+++ b/.agents/skills/README.md
@@ -20,6 +20,10 @@ Wrappers around `python -m scripts.pipeline.<module>`. Side-effecting ones set `
 | `/raincloud-status` | `scripts.pipeline.status` | Per-slug filesystem state (raw / workdir / parquet / vortex / variant-pending). *(read-only, model-invocable.)* |
 | `/raincloud-validate-manifest` | `scripts.pipeline.validate_manifest` | Static checks for `sources.json` — JSON Schema + handler-registry / slug-uniqueness / fetch-auth cross-checks. *(read-only, model-invocable.)* |
 | `/raincloud-list-datasets` | `scripts.pipeline.list_datasets` | Filter/list slugs by handler / license / fetch-type / reader / vortex / tag / showcase / size / regex. *(read-only, model-invocable.)* |
+| `/raincloud-discover` | `scripts.pipeline.list_datasets` | Find "interesting" datasets via the discoverability flags — tag / showcase / size / trait / view. *(read-only, model-invocable.)* |
+| `/raincloud-profile` | `scripts.pipeline.profile` | Compute per-column statistics → `outputs/v1/<slug>/profile.json` (opt-in; feeds the TUI detail pane + `list_datasets --inspect`). *(writes `profile.json`; model-invocable.)* |
+| `/raincloud-load` | `raincloud.load` (loader API) | Load a prepared dataset (cache → mirror → local build) as a lazy `Dataset`; inspect metadata or materialize. *(`disable-model-invocation: true`.)* |
+| `/raincloud-publish` | `scripts.pipeline.publish` | Sync built `outputs/v1/...` artefacts to a mirror, gated on the snapshot sha256. *(side-effecting — `disable-model-invocation: true`.)* |
 
 ## Procedural playbooks (model-invocable)
 
diff --git a/.agents/skills/raincloud-add-dataset/SKILL.md b/.agents/skills/raincloud-add-dataset/SKILL.md
index a1e4be3..0d14b79 100644
--- a/.agents/skills/raincloud-add-dataset/SKILL.md
+++ b/.agents/skills/raincloud-add-dataset/SKILL.md
@@ -13,7 +13,7 @@ Steps:
    - The license — must permit redistribution-of-derivatives. Check SPDX ID and `source_url`.
    - Approximate row count (used for `expect.rows`; can be `null` on first build).
 
-2. **Append a `DatasetSpec` to `sources.json`** using the Python load-edit-dump pattern from [AGENTS.md](../../context/AGENTS.md#safe-ways-to-edit-sourcesjson) — never `sed`. Start from [`examples/minimal_spec.json`](../../../examples/minimal_spec.json) (every field present with placeholder values) rather than typing one from scratch. Minimal direct-HTTP shape:
+2. **Append a `DatasetSpec` to `sources.json`** using the Python load-edit-dump pattern from [AGENTS.md](../../context/AGENTS.md#safe-ways-to-edit-sourcesjson) — never `sed`. Start from [`templates/minimal_spec.json`](../../../templates/minimal_spec.json) (every field present with placeholder values) rather than typing one from scratch. Minimal direct-HTTP shape:
 
    ```jsonc
    {
diff --git a/.agents/skills/raincloud-add-handler/SKILL.md b/.agents/skills/raincloud-add-handler/SKILL.md
index 39428fd..713b721 100644
--- a/.agents/skills/raincloud-add-handler/SKILL.md
+++ b/.agents/skills/raincloud-add-handler/SKILL.md
@@ -20,7 +20,7 @@ Steps:
 
    - `parsed` contains one `(path, table)` tuple per parsed file; `table` is `None` when `parse.reader = "custom"`.
    - Return `[(output_slug, table), ...]` — one tuple per output parquet. Multi-output handlers emit several slugs from one source (see `glove_split`, `osm_pbf_split`, `stack_exchange_split`).
-   - **Streaming handlers** (write direct to parquet, bypass the write stage) return `[]`. Copy [`examples/streaming_handler.py.tmpl`](../../../examples/streaming_handler.py.tmpl) as the starting point — it has the `outputs_root()` / `duckdb_connect()` / cleanup wiring already shaped — and study `factbook_variant_parse`, `wikipedia_variant_parse`, `lichess_pgn_parse` for upstream-shape variations.
+   - **Streaming handlers** (write direct to parquet, bypass the write stage) return `[]`. Copy [`templates/streaming_handler.py.tmpl`](../../../templates/streaming_handler.py.tmpl) as the starting point — it has the `outputs_root()` / `duckdb_connect()` / cleanup wiring already shaped — and study `factbook_variant_parse`, `wikipedia_variant_parse`, `lichess_pgn_parse` for upstream-shape variations.
 
 2. **Register** in `scripts/pipeline/handlers/__init__.py`:
 
diff --git a/.agents/skills/raincloud-load/SKILL.md b/.agents/skills/raincloud-load/SKILL.md
new file mode 100644
index 0000000..61bec29
--- /dev/null
+++ b/.agents/skills/raincloud-load/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: raincloud-load
+description: Load a Raincloud dataset via the lightweight Python loader API (`raincloud.load(slug)`). Use when the user wants to read a prepared parquet/vortex artifact, inspect a slug's metadata, or pull a dataset for downstream analysis from cache → mirror → local build.
+argument-hint: <slug> [--format vortex|parquet] [--materialize to_arrow|scan|to_pandas]
+disable-model-invocation: true
+allowed-tools: Bash(python -c *), Bash(python -m raincloud *), Bash(python examples/use_loader.py *)
+---
+
+The Raincloud loader is a separate, lightweight Python package (`raincloud`) for reading **already-prepared** artifacts. Resolution order is `local cache → mirror → local build`; nothing is fetched until you call an accessor.
+
+## Most common shape
+
+```bash
+python -c "
+import raincloud
+ds = raincloud.load('$ARGUMENTS')   # default format='vortex' with parquet fallback
+print('rows   :', ds.num_rows)
+print('cols   :', ds.column_names[:5])
+print('source :', ds.info.get('source_url'))
+print('path   :', ds.path())        # triggers cache/mirror/build resolution
+"
+```
+
+## Materialization
+
+| Accessor | Returns | Notes |
+|---|---|---|
+| `ds.path()` | `pathlib.Path` to the on-disk artifact | First call resolves; subsequent calls are cache hits. |
+| `ds.to_arrow()` | `pyarrow.Table` | Materializes the whole table; expensive on multi-GB slugs. |
+| `ds.to_vortex()` | `vortex.VortexFile` (lazy) | Vortex-native handle. |
+| `ds.scan()` | `duckdb.DuckDBPyRelation` | Requires `raincloud[duckdb]`. Always reads the parquet sibling — if the slug was loaded as vortex, you'll see a `[raincloud]` stderr note before the parquet is resolved. |
+| `ds.to_pandas()` | `pandas.DataFrame` | Requires `raincloud[pandas]`. |
+| `ds.schema` | `pyarrow.Schema` | Footer-only read for parquet; opens the file for vortex. |
+
+## Config via env vars
+
+| Env var | Effect |
+|---|---|
+| `RAINCLOUD_CACHE` | Local artifact cache dir (default `~/.cache/raincloud`). |
+| `RAINCLOUD_MIRROR` | Mirror URL (`s3://…`, `https://…`, `file://…`). Tried before the local build. |
+| `RAINCLOUD_OFFLINE=1` | Block mirror + build; raise `OfflineMiss` on cache miss. |
+| `RAINCLOUD_SNAPSHOT` | Override `docs/v1/snapshot.json` (catalog). |
+| `RAINCLOUD_MANIFEST` | Override `sources.json`. |
+
+## Drift semantics
+
+When a slug has a `sha256` pinned in the snapshot and the mirror or local build produces bytes that disagree, the loader prints a `[raincloud] WARN: <slug> from <mirror|build> sha256 drifted ...` to stderr and adopts the new bytes anyway. Upstream content drifts; that's not a panic case. Catch + escalate via `raincloud.ChecksumMismatch` only if you want a hard gate (e.g. `_cache.adopt(..., strict=True)` — used by `python -m scripts.pipeline.publish`).
+
+## Errors (all subclass `raincloud.RaincloudError`)
+
+`UnknownSlug`, `FormatUnavailable`, `ArtifactNotFound`, `OfflineMiss`, `BuildToolingMissing`, `MissingDependency`, `ChecksumMismatch`.
+
+## Worked example
+
+```bash
+python examples/use_loader.py --slug $ARGUMENTS              # metadata only
+python examples/use_loader.py --slug $ARGUMENTS --materialize  # full path
+```
+
+[`examples/use_loader.py`](../../../examples/use_loader.py) walks the full API end-to-end against the packaged catalog with no network.
+
+## Install tiers
+
+```bash
+pip install raincloud                # lightweight loader
+pip install 'raincloud[duckdb]'      # adds .scan()
+pip install 'raincloud[pandas]'      # adds .to_pandas()
+pip install 'raincloud[s3]'          # s3:// mirror transport
+pip install 'raincloud[http]'        # https:// mirror transport
+pip install 'raincloud[build]'       # adds local-build fallback (heavyweight)
+```
+
+Context: [AGENTS.md "The loader package"](../../../AGENTS.md), [`examples/use_loader.py`](../../../examples/use_loader.py).
diff --git a/.agents/skills/raincloud-publish/SKILL.md b/.agents/skills/raincloud-publish/SKILL.md
new file mode 100644
index 0000000..0f3afd5
--- /dev/null
+++ b/.agents/skills/raincloud-publish/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: raincloud-publish
+description: Push locally-built Raincloud artifacts to a mirror (`scripts.pipeline.publish`). Use when the maintainer wants to upload one or more slugs' parquet/vortex bytes to a configured mirror after a successful build, gated on the snapshot's recorded sha256.
+argument-hint: <slug>... | --all  --mirror <s3://… | https://… | file://…>  [--dry-run]
+disable-model-invocation: true
+allowed-tools: Bash(python -m scripts.pipeline.publish *)
+---
+
+Sync locally-built artifacts to a mirror so downstream `raincloud.load()` users can fetch them. The CLI verifies each artifact's sha256 against `docs/v1/snapshot.json` before upload — mismatches block the push (publish is the one place an integrity gate is correct: corrupted bytes should never reach a shared mirror).
+
+## Most common shape
+
+```bash
+python -m scripts.pipeline.publish $ARGUMENTS
+```
+
+Selection (one required):
+- `<slug>...` — positional dataset slugs (any number).
+- `--all` — every slug whose parquet OR vortex artifact exists locally under `outputs/v{n}/<slug>/`.
+
+Required:
+- `--mirror <url>` — destination root. Examples:
+  - `s3://my-bucket/raincloud` (needs `pip install raincloud[s3]`)
+  - `https://artifacts.example.com/raincloud` (needs `raincloud[http]`)
+  - `file:///mnt/shared/raincloud-mirror` (built-in)
+- `RAINCLOUD_MIRROR=<url>` env var works as an alternative to the flag.
+
+Modifiers:
+- `--dry-run` — print the upload plan (paths + keys) without writing. Always preview large publishes this way first.
+
+## Before publishing
+
+1. **Build the slug locally first** (`/raincloud-build <slug>` or `python -m scripts.pipeline.build <slug>`). Publish does not build; it only pushes what's already in `outputs/v{n}/<slug>/`.
+2. **Regenerate the snapshot** (`/raincloud-docs` or `python -m scripts.pipeline.docs`). The publish gate compares local bytes against `parquet_sha256` / `vortex_sha256` in `docs/v1/snapshot.json` — a stale snapshot causes false `PublishMismatch` failures.
+3. **Verify the mirror URL** with a dry-run first.
+
+## What gets uploaded
+
+For each slug × format pair (`parquet`, `vortex`) where a local artifact exists:
+- Key: `v1/<slug>/<fmt>/<slug>.<ext>`
+- Body: the raw artifact bytes
+- Gate: `sha256(local) == snapshot[<fmt>_sha256]` (raises `PublishMismatch` on disagree; an unpinned slug — `sha256` is `null` — uploads without verification, so prefer to regen the snapshot first).
+
+## Failure modes
+
+| Error | Meaning | Fix |
+|---|---|---|
+| `PublishMismatch: ...` | Local bytes diverge from the snapshot's recorded sha. | Re-run `/raincloud-docs` to refresh the snapshot, OR confirm the local artifact is correct and commit the new snapshot. |
+| `FileNotFoundError: outputs/v1/<slug>/...` | Slug isn't built locally. | Run `/raincloud-build <slug>` first. |
+| `ImportError: Install s3fs ...` | `s3://` mirror without `[s3]` extra. | `pip install 'raincloud[s3]'`. |
+
+## After publishing
+
+Downstream users can now `raincloud.load(<slug>)` and the loader will pull from the configured mirror (cache → mirror → build).
+
+Context: [AGENTS.md "The loader package"](../../../AGENTS.md), [`scripts/pipeline/publish.py`](../../../scripts/pipeline/publish.py).
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fa673c0..a633ca3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -6,6 +6,12 @@ on:
   pull_request:
     branches: [develop]
 
+# Minimal token scope: every job is read-only (checkout + deps + lint/tests);
+# none posts comments, uploads artifacts, or writes to the repo. Without this,
+# the GITHUB_TOKEN defaults to broad write scope (flagged by CodeQL).
+permissions:
+  contents: read
+
 # Cancel in-progress runs when a new commit lands on the same branch.
 concurrency:
   group: ci-${{ github.ref }}
@@ -26,11 +32,14 @@ jobs:
         run: uv python install 3.11
 
       # `--extra dev` brings in pytest + ruff. `--extra tui` brings in
-      # textual so the test_browse suite runs instead of skipping. Skip
-      # kaggle/huggingface — those deps are only needed at fetch time and
-      # neither test path imports them.
+      # textual so the test_browse suite runs instead of skipping. `--extra
+      # build` brings in the heavy pipeline deps (duckdb, osmium, pyreadstat,
+      # zstandard, jsonschema, …) — required because validate_manifest +
+      # pytest collection import the handler registry, which transitively
+      # pulls those. Skip kaggle/huggingface — those deps are only needed at
+      # fetch time and neither test path imports them.
       - name: Install dependencies
-        run: uv sync --extra dev --extra tui
+        run: uv sync --extra dev --extra tui --extra build
 
       - name: Lint (ruff)
         run: uv run ruff check
@@ -40,3 +49,38 @@ jobs:
 
       - name: Test (pytest)
         run: uv run pytest -q
+
+  wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Pin Python
+        run: uv python install 3.11
+      - name: Install dev deps (for pytest + vortex base dep used by fixtures)
+        run: uv sync --extra dev
+      # Scope collection to test_wheel.py: this env intentionally omits the
+      # [build] extra, but pytest imports every collected module before -m
+      # filtering, and test_manifest/test_profile import jsonschema (a [build]
+      # dep) at module top. All wheel-marked tests live in test_wheel.py.
+      - name: Run wheel tests
+        run: uv run pytest --run-wheel -m wheel -v tests/test_wheel.py
+
+  realbuild:
+    runs-on: ubuntu-latest
+    continue-on-error: true   # non-blocking: upstream flakiness never reds the build
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Pin Python
+        run: uv python install 3.11
+      - name: Install dev + build deps
+        run: uv sync --extra dev --extra build
+      - name: Run real-build network tests
+        run: uv run pytest --run-network -m network -v
diff --git a/AGENTS.md b/AGENTS.md
index c89a9d4..66651e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,7 @@ On a fresh clone `outputs/` is empty — that's expected. The `outputs/v1/<slug>
 python -m scripts.pipeline.status --fast --missing-only
 ```
 
-It loads `sources.json`, walks the manifest, and prints per-slug filesystem state in seconds with no side effects. If it errors, fix the env (`uv sync --inexact`) before running any build. Always pass `--inexact` to `uv sync`: without it, syncing one extra (e.g. `--extra dev`) silently uninstalls the others (kaggle, huggingface, tui), so a subsequent build of an HF/Kaggle slug will fail.
+It loads `sources.json`, walks the manifest, and prints per-slug filesystem state in seconds with no side effects. A bare `uv sync --inexact` (or `pip install "raincloud @ git+https://github.com/spiraldb/raincloud"` from GitHub — not PyPI) installs only the lightweight loader; running any **build** needs the heavy toolchain, so fix the env with `uv sync --extra build --inexact` before invoking `scripts.pipeline.build`. Always pass `--inexact` to `uv sync`: without it, syncing one extra (e.g. `--extra dev`) silently uninstalls the others (build, kaggle, huggingface, tui), so a subsequent build of an HF/Kaggle slug will fail.
 
 For a manifest sanity check that doesn't touch the filesystem at all:
 
@@ -42,9 +42,9 @@ uv sync --extra dev --inexact   # one-time — installs pytest, preserves other
 pytest
 ```
 
-Copy-pasteable templates for the two most common edits live under [`examples/`](examples/) — `minimal_spec.json` for new manifest entries, `streaming_handler.py.tmpl` for memory-constrained transform handlers.
+Copy-pasteable templates for the two most common edits live under [`templates/`](templates/) — `minimal_spec.json` for new manifest entries, `streaming_handler.py.tmpl` for memory-constrained transform handlers. (Runnable demos of the `raincloud.load` API live under [`examples/`](examples/).)
 
-If your agent harness supports the [Agent Skills](https://agentskills.io) standard (Claude Code, Codex, etc.), the `.agents/skills/` directory carries 16 invokable skills wrapping every pipeline entry point and procedural playbook — see [`.agents/skills/README.md`](.agents/skills/README.md). `.claude → .agents` is a symlink so both naming conventions resolve. The `.agents/settings.json` at the same level is a tracked allow-list of safe, read-only commands so a fresh-clone agent doesn't burn turns on permission prompts; per-machine overrides go in the gitignored `.agents/settings.local.json`.
+If your agent harness supports the [Agent Skills](https://agentskills.io) standard (Claude Code, Codex, etc.), the `.agents/skills/` directory carries 21 invokable skills wrapping every pipeline entry point and procedural playbook — see [`.agents/skills/README.md`](.agents/skills/README.md). `.claude → .agents` is a symlink so both naming conventions resolve. The `.agents/settings.json` at the same level is a tracked allow-list of safe, read-only commands so a fresh-clone agent doesn't burn turns on permission prompts; per-machine overrides go in the gitignored `.agents/settings.local.json`.
 
 ## Don't read the giant derived docs cover-to-cover
 
@@ -67,6 +67,31 @@ Raincloud is a **client-reproducible pipeline** for building a curated catalog o
 
 The pipeline flow is: **fetch → extract → parse → transform → write → validate → convert** (stage 7 opt-in per-spec), orchestrated by `scripts.pipeline.build`.
 
+## The loader package (`raincloud`)
+
+Separate from the build pipeline under `scripts/`, the repo also ships an importable **`raincloud`** package — a lightweight loader for *already-prepared* artefacts. `raincloud.load("<slug>")` (alias `load_dataset`) returns a lazy `Dataset` handle; nothing is fetched until you call `.path()` / `.to_arrow()` / `.scan()` / `.to_pandas()`. Resolution order is **local cache → mirror → local build** (`raincloud/_resolve.py`): a cache hit short-circuits, otherwise it pulls from the configured mirror, and only on a cache+mirror miss does it shell out to `scripts.pipeline.build` as a last resort.
+
+The install is **layered** — this is a behaviour change from earlier releases:
+
+- A bare `uv sync --inexact` (or a `pip install` from the GitHub repo) installs only the lightweight loader: base deps are `pyarrow`, `numpy`, `vortex-data`, `fsspec`. Transport backends are per-scheme extras (`[s3]` → s3fs, `[http]` → aiohttp; `file://` needs neither); `[duckdb]` / `[pandas]` back `Dataset.scan()` / `.to_pandas()`.
+- **Building datasets now requires `uv sync --extra build --inexact`** — the heavy toolchain (duckdb, osmium, pyreadstat, pandas, openpyxl, py7zr, unlzw3, zstandard, jsonschema) moved behind the `[build]` extra. A bare sync no longer pulls these, so any `scripts.pipeline.build` / handler work needs `--extra build` first.
+
+The mirror is a **private/internal artefact store** — a bucket a team points its own CI at, configured via the `RAINCLOUD_MIRROR` env var (`s3://bucket/prefix`, `file:///path`, etc.); there is no public Raincloud-hosted endpoint, and this does not change the no-redistribution posture in [`DISCLAIMER.md`](DISCLAIMER.md). `RAINCLOUD_CACHE` overrides the cache dir and `RAINCLOUD_OFFLINE` forces cache-only (mirror/build misses raise). Maintainers publish built `outputs/v1/...` to a mirror with `python -m scripts.pipeline.publish <slugs|--all> --mirror <url>`, gated on a snapshot sha256 match. Integrity: `docs/v1/snapshot.json` carries per-slug `parquet_sha256` / `vortex_sha256` (recorded only for slugs already built + hashed locally — today a minority of the catalog) plus a byte size for *every* slug. `publish` refuses to upload an artifact whose on-disk sha disagrees with the snapshot (slugs with no recorded sha are uploaded ungated). The loader, by default, **warns-and-adopts** on a checksum mismatch (drift is an alert, not a blocker — upstream data shifts) and falls back to the byte size as a cheap corruption check when no sha is pinned; set `RAINCLOUD_STRICT_CHECKSUM=1` to turn a mismatch on mirror bytes into a hard `ChecksumMismatch`. Locally-built artefacts are never strict-gated against the maintainer's sha (a client build legitimately differs); instead they're trusted via a provenance pin (`origin=build` + the snapshot pin they were built against) and served from cache until that snapshot pin changes — so a strict, mirror-less deployment rebuilds a slug once when the source of truth moves, not on every load. To backfill checksums for the rest of the catalog, build the slugs and run `python -m scripts.pipeline.docs snapshot --rehash`.
+
+**Build data-area env vars** (separate from the loader's cache vars above): the build pipeline writes artefacts under a configurable root. In a checkout, that root is the repo directory; in a `pip install raincloud[build]` wheel install, it defaults to `~/.cache/raincloud` (XDG-aware, no init step). The resolution logic lives in `scripts/pipeline/spec.py:data_root()`.
+
+| Env var | Controls | Default |
+|---|---|---|
+| `RAINCLOUD_HOME` | build data-area root | checkout root (if `sources.json` present), else `~/.cache/raincloud` |
+| `RAINCLOUD_OUTPUTS` | built-artifact base (`/v{n}` under it) | `$RAINCLOUD_HOME/outputs` |
+| `RAINCLOUD_RAW_DOWNLOADS` | cached raw upstream bytes | `$RAINCLOUD_OUTPUTS/raw_downloads` |
+| `RAINCLOUD_WORKDIR` | extract/scratch space | `$RAINCLOUD_HOME/_workdir` |
+| `RAINCLOUD_MANIFEST` | `sources.json` path | checkout copy, else the wheel-packaged copy |
+
+In the defaults above, `$RAINCLOUD_HOME` / `$RAINCLOUD_OUTPUTS` mean the *resolved* roots — when those vars are unset they fall back to the checkout (or `~/.cache/raincloud`) and `<root>/outputs` respectively.
+
+From an agent context: on a fresh clone all five default to the repo tree (existing behaviour). On a wheel install with no checkout present, builds silently use `~/.cache/raincloud` (honoring `XDG_CACHE_HOME`) — same root `RAINCLOUD_CACHE` defaults to — so the loader's cache-hit path fires after the first build without any extra config.
+
 ## Invariants (don't break these)
 
 1. **`sources.json` is authoritative.** Every row of every derived artefact maps back to a `DatasetSpec` here. If you're tempted to hand-edit `docs/*.md` or drop a parquet into `outputs/v1/<slug>/` by hand — stop, fix the manifest, re-run the build, re-run `docs.py`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac6f156..68558bb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,194 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-05-29
+
+### Added
+
+- **`raincloud` loader package.** A new importable package
+  (separate from the `scripts/` build pipeline) for loading
+  *already-prepared* artefacts. `raincloud.load("<slug>")` (alias
+  `load_dataset`) returns a lazy `Dataset` handle — nothing is fetched
+  until you call `.path()` / `.to_arrow()` / `.scan()` / `.to_pandas()`.
+  Resolution order is **local cache → mirror → local build**: a cache
+  hit short-circuits, otherwise it pulls from the configured mirror,
+  and only on a cache+mirror miss does it shell out to
+  `scripts.pipeline.build`. Configured via env vars: `RAINCLOUD_MIRROR`
+  (an `fsspec` base such as `s3://bucket/prefix` or `file:///path` —
+  a private/internal artefact store, not a public Raincloud endpoint),
+  `RAINCLOUD_CACHE` (cache dir override), `RAINCLOUD_OFFLINE`
+  (cache-only; mirror/build misses raise), `RAINCLOUD_STRICT_CHECKSUM`
+  (opt-in hard integrity gate; see below). When the snapshot records a
+  checksum, a drift from it warns-and-adopts by default (see "Drift is an
+  alert"); where no checksum is recorded yet — most of the catalog today —
+  the pinned byte size is used as a cheap corruption check instead.
+- **`scripts.pipeline.publish` mirror-sync CLI.**
+  `python -m scripts.pipeline.publish <slugs|--all> --mirror <url>`
+  uploads built `outputs/v1/...` artefacts to a mirror, gated on each
+  artefact's on-disk sha256 matching `docs/v1/snapshot.json` (slugs with
+  no recorded sha are uploaded ungated). Each upload streams to a
+  `<key>.<uuid>.part` temp key and renames into place, so a mid-stream
+  crash never leaves a truncated object at the canonical key. The
+  snapshot is resolved via the same `RAINCLOUD_SNAPSHOT` → checkout →
+  wheel precedence the loader uses, not a hardcoded checkout path.
+  `--dry-run` previews the upload plan.
+- **`parquet_sha256` / `vortex_sha256` in `docs/v1/snapshot.json`** —
+  per-slug artefact checksums, used by both the loader (download
+  integrity) and `publish` (the snapshot-match gate).
+- **`examples/use_loader.py`** — runnable walkthrough of the loader API
+  (metadata access, `.to_arrow` / `.scan` / `.to_pandas` materialization,
+  format override, env-var configuration, the full
+  `RaincloudError` hierarchy). Runs against the packaged catalog with
+  no network; `--materialize` exercises the full resolution path.
+- **Code-path example scripts in `examples/`.** Single-file demos that
+  `load()` a real catalog dataset and run a query: `nyc_taxi_tip_rate.py`
+  (DuckDB over `.scan()` on 48.7M yellow-cab trips — what share left no
+  recorded tip, by `payment_type`), `kepler_exoplanets.py` (pandas
+  disposition counts + smallest confirmed planet), `wine_quality_correlations.py`
+  (feature↔quality correlations), and `olympic_medals.py` (medals by NOC /
+  decade). `tests/test_examples.py` byte-compiles every example and (under
+  `--run-network`) runs the kepler one end-to-end.
+- **New agent skills: `raincloud-load` and `raincloud-publish`.** Wrap
+  the loader API and the publish CLI respectively, matching the
+  existing `raincloud-*` skill conventions (name-only,
+  `disable-model-invocation: true`).
+
+### Changed
+
+- **`examples/` is now runnable demos; authoring templates moved to
+  `templates/`.** `minimal_spec.json` and `streaming_handler.py.tmpl` (config
+  templates for adding a source) live under the new top-level `templates/`;
+  `examples/` is reserved for code-path scripts that use the `raincloud.load`
+  API. Doc and skill references updated accordingly.
+- **Packaging: the project is now a hatchling-built, installable
+  package** (installed from GitHub: `pip install "raincloud @ git+https://github.com/spiraldb/raincloud"`, not PyPI). The wheel force-includes
+  `docs/v1/snapshot.json` and `sources.json` as packaged data under
+  `raincloud/_data/`, so the catalog resolves with no repo checkout.
+- **BREAKING (install): the heavy build toolchain moved out of the base
+  dependency set into the `[build]` extra.** A bare `uv sync --inexact`
+  (or a `pip install` from the GitHub repo) now installs only the lightweight loader
+  (`pyarrow`, `numpy`, `vortex-data`, `fsspec`); **building datasets
+  requires `uv sync --extra build --inexact`** (duckdb, pandas, osmium,
+  pyreadstat, openpyxl, py7zr, unlzw3, zstandard, jsonschema). Transport
+  backends are per-scheme extras (`[s3]` → s3fs, `[http]` → aiohttp;
+  `file://` needs neither); `[duckdb]` / `[pandas]` back
+  `Dataset.scan()` / `.to_pandas()`. This does not change the
+  no-redistribution posture in [`DISCLAIMER.md`](DISCLAIMER.md).
+- **Drift is an alert, not a blocker.** When a slug's sha256 is pinned
+  in the snapshot and the mirror or local build produces different
+  bytes, the loader now prints `[raincloud] WARN: <slug> from <origin>
+  sha256 drifted ...` to stderr and adopts the new bytes anyway.
+  Upstream content changes are common and benign; the build should
+  still work, with the user informed. The loader's mirror-fetch path is
+  the strict-capable caller — under `RAINCLOUD_STRICT_CHECKSUM` it passes
+  `_cache.adopt(..., strict=True)` so a mirror mismatch raises
+  `ChecksumMismatch`. (`scripts.pipeline.publish` is a *separate* gate: it
+  refuses to upload via its own `PublishMismatch`, not through `adopt`.)
+  Adopted bytes are recorded in a `.<name>.pin` sidecar — the snapshot sha
+  reconciled against, the on-disk size, and the origin (`mirror`/`build`)
+  — so later loads serve them straight from cache; a genuine snapshot
+  revision (the pinned sha changed) still re-fetches, and a post-adoption
+  size change still falls through to a fresh fetch. In the default
+  (non-strict) mode a sha-present cache hit is served on a byte-size match
+  without rehashing (the multi-GB rehash-avoidance fast path), so a
+  same-size on-disk content swap isn't caught until strict mode forces a
+  rehash.
+
+  Set `RAINCLOUD_STRICT_CHECKSUM=1` to opt the loader into a hard gate:
+  for a sha-pinned slug from the mirror, a mismatch on download AND on a
+  cache hit raises `ChecksumMismatch` (the cached file is rehashed each
+  load, catching even same-size tampering). Sha-less slugs have nothing to
+  rehash against, so strict leaves their size/pin corruption check
+  unchanged. The **local build path is never strict-gated against the
+  maintainer's sha**: a client's rebuild legitimately differs (columnar
+  output is rarely bit-reproducible), so the built artefact is tagged
+  `origin=build` in its pin and served from cache by that provenance —
+  even under strict — instead of being rebuilt every load. It is rebuilt
+  only when the snapshot pin it was built against changes (the source of
+  truth moved) or the cached file is corrupted. For full cryptographic
+  integrity, point strict deployments at a mirror.
+
+### Fixed
+
+- **Wheel-install path crashes after long-running work.**
+  `scripts/pipeline/hydrate.py` (success-log + the FileNotFoundError
+  message),
+  `scripts/pipeline/tighten_variant.py` (workdir +
+  three log lines),
+  `scripts/pipeline/overnight_profile.py`
+  (`LOG_PATH`, `STATE_PATH`, `_slug_already_built`, `_wipe_slug`,
+  manifest loader),
+  `scripts/pipeline/list_datasets.py`, and
+  `scripts/pipeline/browse.py` all routed through
+  `REPO_ROOT / "outputs/..."` or `.relative_to(REPO_ROOT)` — fragile
+  under wheel installs and any `RAINCLOUD_HOME` / `RAINCLOUD_OUTPUTS` /
+  `RAINCLOUD_WORKDIR` redirect, where it raised `ValueError` at the
+  tail of a multi-hour build. All call sites now use the env-aware
+  `display_path()` / `outputs_root()` / `raw_downloads_root()` /
+  `workdir_root()` helpers. New
+  `tests/test_pipeline_path_hermeticity.py` greps the pipeline package
+  on every test run and fails on regressions.
+- **Build-availability now distinguishes a missing extra from a broken
+  install.** `_resolve` captures *why* `scripts.pipeline.build` can't be
+  imported: a plain `ImportError`/`ModuleNotFoundError` (the `[build]`
+  extra isn't installed) still yields the "install `raincloud[build]`"
+  hint, but any other module-init failure (a handler raising at top
+  level, a malformed packaged manifest) now surfaces the real exception
+  in the `BuildToolingMissing` message instead of misdirecting the user
+  to a `pip install` they've already done.
+- **Local build failures are typed.** A non-zero
+  `scripts.pipeline.build` subprocess now raises `BuildFailed`
+  (a `RaincloudError`) instead of leaking a raw
+  `subprocess.CalledProcessError` past the loader's typed-error contract.
+- **`read_pin` rejects non-object JSON.** A torn/partial or tampered
+  `.pin` sidecar containing valid-but-non-dict JSON (`42`, `[...]`) now
+  returns `None` rather than a value whose later `.get(...)` would raise
+  `AttributeError` inside `resolve()`.
+- **Sha-less cache files are size-checked, not trusted on existence.**
+  For a slug with no pinned sha (most of the catalog), a cache hit serves
+  via the adoption pin or a snapshot-byte-size match; a cached file whose
+  size diverges from the snapshot with no pin vouching for it is treated
+  as corruption and re-fetched, rather than served on mere existence.
+- **Catalog parquet visibility for snapshot-only slugs.** When a slug
+  is in `docs/v1/snapshot.json` but absent from `sources.json`
+  (legacy / deprecated entry still on a mirror), `Catalog.entry()` now
+  exposes the parquet format via the same
+  `snap.get('parquet_bytes') is not None` clause that already covered
+  vortex. Loadable now; previously raised `FormatUnavailable`.
+- **`Dataset.scan()` stderr note.** When a slug was loaded as vortex
+  but `scan()` needs the parquet sibling (DuckDB has no Vortex
+  reader), the loader prints `[raincloud] scan() needs parquet but
+  <slug> was loaded as 'vortex'; resolving parquet sibling ...` before
+  the resolve, so an implicit mirror fetch isn't a surprise.
+- **`.part` tmp race fixed.** `_resolve.resolve` now writes to
+  `f".<name>.<pid>-<uuid8>.part"` (per-process unique) and sweeps
+  stale `.part` siblings older than six hours on each resolve, so
+  concurrent loaders no longer clobber each other's in-flight writes
+  and SIGKILL leftovers don't accumulate.
+
+### Performance
+
+- **Cache-hit skips sha256 rehash when artifact size matches the
+  snapshot.** `_resolve.resolve` uses
+  `dest.stat().st_size == FormatInfo.nbytes` as the fast path — a full
+  sha256 over multi-GB artifacts on every load defeated the cache.
+  Cuts repeat-load cost on the 34 GB Wikipedia parquet from minutes
+  to milliseconds. The full rehash only runs when size disagrees *and*
+  the pin sidecar doesn't already vouch for the file; a same-size,
+  different-content snapshot revision is the one case the size fast-path
+  can't distinguish (an accepted blind spot, same as before).
+- **Snapshot regen reuses prior sha when size unchanged.** `docs.py`
+  snapshot regen (`_sha256_or_reuse`) skips re-streaming an artifact
+  when its bytes-on-disk match the prior snapshot's recorded size and
+  the prior sha is known. A full-catalog regen on 250 slugs
+  (including the multi-GB heavyweights) drops from hours to seconds
+  when nothing's changed. Pass `--rehash` (`python -m
+  scripts.pipeline.docs snapshot --rehash`) to force a full recompute —
+  needed only in the rare case a rebuild changed an artifact's content
+  without changing its byte length, which would otherwise wedge
+  `publish`'s checksum gate; unlike `--overwrite-missing` it preserves
+  prior data for slugs not built this run.
+
 ## [0.1.5] - 2026-05-17
 
 ### Fixed
@@ -303,6 +491,8 @@ This release bundles:
   this repository" button in the repo sidebar with BibTeX / APA / Chicago
   exports.
 
+[0.2.0]: https://github.com/spiraldb/raincloud/releases/tag/v0.2.0
+[0.1.5]: https://github.com/spiraldb/raincloud/releases/tag/v0.1.5
 [0.1.4]: https://github.com/spiraldb/raincloud/releases/tag/v0.1.4
 [0.1.3]: https://github.com/spiraldb/raincloud/releases/tag/v0.1.3
 [0.1.2]: https://github.com/spiraldb/raincloud/releases/tag/v0.1.2
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80d263e..6b1ba66 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,11 +13,15 @@ cd raincloud
 uv sync --extra dev --inexact
 ```
 
-`--extra dev` pulls in `pytest`. Add `--extra kaggle` or `--extra huggingface`
-if your work touches those upstream types, or `--extra all` for everything.
-Always pass `--inexact` — without it, each `uv sync --extra X` removes the
-extras from the previous one (e.g. syncing `--extra dev` after `--extra
-huggingface` uninstalls `huggingface_hub`).
+`--extra dev` pulls in `pytest`. The base install is the lightweight loader
+(`pyarrow`, `numpy`, `vortex-data`, `fsspec`); the heavy build toolchain
+(duckdb, pandas, osmium, pyreadstat, openpyxl, …) now lives behind the `build`
+extra, so **add `--extra build` when working on the pipeline or handlers** —
+otherwise the build stages fail on a missing import. Add `--extra kaggle` or
+`--extra huggingface` if your work touches those upstream types, or `--extra
+all` for everything. Always pass `--inexact` — without it, each `uv sync
+--extra X` removes the extras from the previous one (e.g. syncing `--extra dev`
+after `--extra huggingface` uninstalls `huggingface_hub`).
 
 ## Before you open a PR
 
@@ -26,13 +30,17 @@ Three sub-second checks are the minimum gate (CI runs all three):
 ```bash
 ruff check                                     # lint (pyflakes + pycodestyle + isort)
 python -m scripts.pipeline.validate_manifest   # JSON Schema + cross-checks on sources.json
-pytest                                         # smoke regression net (manifest, schema, registry, examples)
+pytest                                         # smoke regression net (manifest, schema, registry, examples, loader)
 ```
 
-If you touched the build pipeline, also run a small end-to-end build to make
-sure it still produces the expected output:
+`pytest` now also covers the `raincloud` loader package (catalog resolution,
+cache/mirror/build dispatch, sha256 integrity) alongside the manifest checks.
+
+If you touched the build pipeline, install the build extra and run a small
+end-to-end build to make sure it still produces the expected output:
 
 ```bash
+uv sync --extra build --inexact
 python -m scripts.pipeline.build countries-of-the-world   # ~200 ms, 227 rows
 ```
 
@@ -41,7 +49,7 @@ For larger builds, see [`SKILLS.md`](SKILLS.md#running-a-large-build-safely).
 ## What to send a PR for
 
 - **New datasets** — see [`SKILLS.md`](SKILLS.md#adding-a-new-dataset). Most
-  entries copy [`examples/minimal_spec.json`](examples/minimal_spec.json) and
+  entries copy [`templates/minimal_spec.json`](templates/minimal_spec.json) and
   pick an existing handler from [`docs/v1/handlers.md`](docs/v1/handlers.md).
 - **New transform handlers** — see
   [`SKILLS.md`](SKILLS.md#adding-a-new-transform-handler). One handler per
diff --git a/README.md b/README.md
index 0633874..7bdca9a 100644
--- a/README.md
+++ b/README.md
@@ -30,10 +30,10 @@ python -m scripts.pipeline.browse
 
 A read-only Textual TUI over `sources.json`. Click any column header to sort; right pane shows description, license, fetch URL, and on-disk state for the highlighted slug. Press `q` to quit.
 
-**Tell Raincloud which dataset you want; get back a Parquet + Vortex file on disk.**
+**Tell Raincloud which dataset you want; get back a Parquet + Vortex file on disk.** Building needs the heavy toolchain behind the `build` extra (a bare `uv sync --inexact` installs only the lightweight loader — see [Upstream-specific extras](#upstream-specific-extras)):
 
 ```bash
-uv sync --inexact
+uv sync --extra build --inexact
 python -m scripts.pipeline.status --fast --missing-only   # read-only env check
 python -m scripts.pipeline.build countries-of-the-world
 ```
@@ -45,6 +45,36 @@ outputs/v1/countries-of-the-world/vortex/countries-of-the-world.vortex
 
 The command runs every pipeline stage — fetch, extract, parse, transform, write, validate, convert — and leaves both a Parquet file and its converted Vortex sibling under per-format subdirectories of `outputs/v1/<slug>/`.
 
+### Load prepared files in your own scripts / CI
+
+Install just the loader (no build toolchain):
+
+```bash
+# from GitHub (not published to PyPI); pin a tag like @v0.2.0 for reproducible CI
+pip install "raincloud @ git+https://github.com/spiraldb/raincloud"
+# remote-mirror backends: "raincloud[s3] @ git+https://github.com/spiraldb/raincloud"
+```
+
+```python
+import raincloud
+ds = raincloud.load("countries-of-the-world")  # lazy handle, default Vortex
+table = ds.to_arrow()                      # materialize when you want it
+path  = ds.path()                          # or just the cached file path
+```
+
+Resolution is **cache → mirror → local build**. Point CI at a prepared-artifact
+bucket and loads become downloads, not multi-hour rebuilds:
+
+```bash
+export RAINCLOUD_MIRROR=s3://your-bucket/raincloud   # or file:///path
+```
+
+When the catalog records a checksum for an artifact, a drift from it warns and
+adopts by default (`RAINCLOUD_STRICT_CHECKSUM=1` makes it a hard failure); where
+no checksum is recorded yet, the pinned byte size is used as a cheap corruption
+check. The `raincloud[build]` extra adds the full pipeline for the local-build
+fallback on a cache + mirror miss.
+
 ### Discover
 
 Run `python -m scripts.pipeline.browse` and click the **Encoding** preset. The left panel filters by domain, size, shape traits, license, or fetch type; click a slug to see its description, on-disk state, and per-column profile (run `python -m scripts.pipeline.profile <slug>` first to populate it).
@@ -68,6 +98,14 @@ python -m scripts.pipeline.build clickbench-hits            # 100 M rows, ~10 GB
 
 ### Upstream-specific extras
 
+A bare `uv sync --inexact` (or a `pip install` from the GitHub URL above) installs only the lightweight loader — `pyarrow`, `numpy`, `vortex-data`, `fsspec`. **Building datasets requires the heavy toolchain behind the `build` extra:**
+
+```bash
+uv sync --extra build --inexact   # duckdb, pandas, osmium, pyreadstat, openpyxl, …
+```
+
+Add `--extra build` before running `python -m scripts.pipeline.build` (or working on a handler); without it the build stages fail on a missing import.
+
 157 of 249 manifest entries fetch from direct HTTPS endpoints and need no additional setup. The rest:
 
 ```bash
@@ -92,8 +130,8 @@ If you're an AI coding agent landing in this repo:
 2. Run `python -m scripts.pipeline.status --fast --missing-only` to verify the env, then `python -m scripts.pipeline.validate_manifest` to confirm `sources.json` is well-formed. Both are sub-second and side-effect-free.
 3. Run `pytest` (after `uv sync --extra dev --inexact`) for a regression net before any non-trivial change to the manifest, schema, or handler registry.
 4. For catalog questions ("which slugs use handler X", "what's CC0-licensed"), use `python -m scripts.pipeline.list_datasets` rather than greping `sources.json` or scrolling [`docs/v1/datasets.md`](docs/v1/datasets.md).
-5. Copy-pasteable templates for new manifest entries and streaming handlers live in [`examples/`](examples/).
-6. Harnesses that follow the [Agent Skills](https://agentskills.io) standard get 16 invokable skills under [`.agents/skills/`](.agents/skills/) (the `.claude → .agents` symlink means Claude Code sees the same files). Tracked safe-default permissions in [`.agents/settings.json`](.agents/settings.json) — see [`.agents/README.md`](.agents/README.md) for the full layout.
+5. Copy-pasteable templates for new manifest entries and streaming handlers live in [`templates/`](templates/); runnable demos of the `raincloud.load` API are in [`examples/`](examples/).
+6. Harnesses that follow the [Agent Skills](https://agentskills.io) standard get 21 invokable skills under [`.agents/skills/`](.agents/skills/) (the `.claude → .agents` symlink means Claude Code sees the same files). Tracked safe-default permissions in [`.agents/settings.json`](.agents/settings.json) — see [`.agents/README.md`](.agents/README.md) for the full layout.
 
 ## Repository layout
 
@@ -105,6 +143,7 @@ AGENTS.md                       # invariants + first-contact guide for AI coding
 SKILLS.md                       # narrative playbooks
 HYDRATING.md                    # hand-maintained hydration policy / philosophy
 DISCLAIMER.md                   # AS IS posture, content/license disclaimers, dataset-removal reporting
+raincloud/                      # importable loader package — raincloud.load("<slug>") → lazy Dataset (cache → mirror → build)
 scripts/
   pipeline/
     build.py                    # orchestrator — ties the 7 stages together
@@ -118,6 +157,7 @@ scripts/
     convert.py                  # stage 7 (optional): emit sibling .vortex per spec's convert.vortex flag
     hydrate.py                  # stage 8 (optional, opt-in): dereference URL columns into parquet-hydrated/
     docs.py                     # regenerate docs/datasets.md + handlers.md (other catalog views live in list_datasets / TUI)
+    publish.py                  # sync built outputs/v1/ artifacts to a mirror (snapshot-sha256-gated)
     tighten_variant.py          # in-place JSON → VARIANT pass
     validate_manifest.py        # static checks on sources.json (schema + cross-checks)
     list_datasets.py            # filter/list slugs by handler / license / tag / size / etc.
@@ -126,8 +166,9 @@ scripts/
     spec.py                     # manifest loader, path helpers, duckdb_connect
     handlers/                   # named transform handlers
 tests/                          # pytest smoke suite (manifest, schema, handler registry, examples)
-examples/                       # copy-pasteable templates (minimal_spec.json, streaming_handler.py.tmpl)
-.agents/                        # tracked agent allow-list (settings.json) + 16 invokable skills (.claude → .agents)
+templates/                      # copy-pasteable authoring templates (minimal_spec.json, streaming_handler.py.tmpl)
+examples/                       # runnable code-path demos of raincloud.load (use_loader.py, nyc_taxi_tip_rate.py, …)
+.agents/                        # tracked agent allow-list (settings.json) + 21 invokable skills (.claude → .agents)
 outputs/
   raw_downloads/<slug>/         # stage 1 output — unversioned, cached
   v{schema_version}/<slug>/     # stage 5 output — version-scoped
@@ -214,6 +255,24 @@ RAINCLOUD_DUCKDB_TEMP_DIRECTORY=/mnt/scratch/duckdb-tmp \
 
 Persistent DuckDB databases are opened with `storage_compatibility_version=v1.5.0` automatically (required for VARIANT columns).
 
+### Data locations
+
+By default, builds write under the repo root (if `sources.json` is present — the checkout case) or under `~/.cache/raincloud` (wheel-install case). All five paths are overridable:
+
+| Env var | Controls | Default |
+|---|---|---|
+| `RAINCLOUD_HOME` | build data-area root | checkout root (if `sources.json` is present), else `~/.cache/raincloud` |
+| `RAINCLOUD_OUTPUTS` | built-artifact base (`/v{n}` under it) | `$RAINCLOUD_HOME/outputs` |
+| `RAINCLOUD_RAW_DOWNLOADS` | cached raw upstream bytes | `$RAINCLOUD_OUTPUTS/raw_downloads` |
+| `RAINCLOUD_WORKDIR` | extract/scratch space | `$RAINCLOUD_HOME/_workdir` |
+| `RAINCLOUD_MANIFEST` | `sources.json` path | checkout copy, else the wheel-packaged copy |
+
+In the defaults above, `$RAINCLOUD_HOME` / `$RAINCLOUD_OUTPUTS` mean the *resolved* roots — when those vars are unset they fall back to the checkout (or `~/.cache/raincloud`) and `<root>/outputs` respectively.
+
+In a **checkout** (`uv sync --extra build --inexact`), builds write to `<repo>/outputs/` as before — unchanged. In a **wheel install** (`pip install raincloud[build]`), builds default to `~/.cache/raincloud` (same cache tier as Hugging Face `datasets`, honoring `XDG_CACHE_HOME`) — no init step required.
+
+`RAINCLOUD_CACHE` (the loader's *download* cache for already-built artefacts fetched via mirror) is independent of the above and always defaults to `~/.cache/raincloud` (honoring `XDG_CACHE_HOME`).
+
 ## The manifest (`sources.json`)
 
 See [`sources.schema.md`](sources.schema.md) for the human-friendly reference and [`sources.schema.json`](sources.schema.json) for the machine-readable JSON Schema (Draft 2020-12). After editing the manifest, run
diff --git a/SKILLS.md b/SKILLS.md
index b91b128..f1372df 100644
--- a/SKILLS.md
+++ b/SKILLS.md
@@ -2,10 +2,12 @@
 
 Playbooks for common operations in this repo. Each section is a self-contained recipe — copy and adapt.
 
-Prereqs: Python 3.11+ and [uv](https://docs.astral.sh/uv/). Run `uv sync --inexact` in the repo root to install the pinned core deps (`pyarrow`, `duckdb`, `vortex-data`, `zstandard`, `py7zr`, `unlzw3`, `pandas`, `openpyxl`, `pyreadstat`, `osmium`, `jsonschema`). Add `--extra kaggle` for Kaggle-hosted datasets, `--extra huggingface` for Hugging Face ones, or `--extra dev` for `pytest` — see [`README.md`](README.md#upstream-specific-extras). Always pass `--inexact` so subsequent extras accumulate instead of overwriting prior ones (uv's default is "exact" sync, which removes anything not requested by the current invocation). Invoke Python as `.venv/bin/python` (or activate the venv).
+Prereqs: Python 3.11+ and [uv](https://docs.astral.sh/uv/). A bare `uv sync --inexact` installs only the lightweight loader (`pyarrow`, `numpy`, `vortex-data`, `fsspec`); **running the build pipeline needs the heavy toolchain behind the `build` extra** — `uv sync --extra build --inexact` (pulls `duckdb`, `zstandard`, `py7zr`, `unlzw3`, `pandas`, `openpyxl`, `pyreadstat`, `osmium`, `jsonschema`). Add `--extra kaggle` for Kaggle-hosted datasets, `--extra huggingface` for Hugging Face ones, or `--extra dev` for `pytest` — see [`README.md`](README.md#upstream-specific-extras). Always pass `--inexact` so subsequent extras accumulate instead of overwriting prior ones (uv's default is "exact" sync, which removes anything not requested by the current invocation). Invoke Python as `.venv/bin/python` (or activate the venv).
 
 ## Index
 
+- [Loading prepared datasets](#loading-prepared-datasets) — `raincloud.load` from cache / mirror
+- [Publishing artefacts to a mirror](#publishing-artefacts-to-a-mirror) — `scripts.pipeline.publish`
 - [Opening a DuckDB connection](#opening-a-duckdb-connection)
 - [Running the test suite](#running-the-test-suite) — pytest smoke regression net
 - [Querying the catalog](#querying-the-catalog) — `list_datasets` filters
@@ -23,7 +25,37 @@ Prereqs: Python 3.11+ and [uv](https://docs.astral.sh/uv/). Run `uv sync --inexa
 - [Regenerating specific docs](#regenerating-specific-docs)
 - [Removing a dataset](#removing-a-dataset)
 
-Templates referenced by the playbooks: [`examples/minimal_spec.json`](examples/minimal_spec.json) (new manifest entry), [`examples/streaming_handler.py.tmpl`](examples/streaming_handler.py.tmpl) (memory-constrained handler).
+Templates referenced by the playbooks: [`templates/minimal_spec.json`](templates/minimal_spec.json) (new manifest entry), [`templates/streaming_handler.py.tmpl`](templates/streaming_handler.py.tmpl) (memory-constrained handler).
+
+## Loading prepared datasets
+
+Use the importable `raincloud` loader to pull an *already-prepared* artefact instead of rebuilding it. The base install (a `pip install` from the GitHub repo, or a bare `uv sync --inexact`) is the lightweight loader only — add `[s3]` / `[http]` for a remote mirror, `[duckdb]` / `[pandas]` for `.scan()` / `.to_pandas()`.
+
+```python
+import raincloud
+ds = raincloud.load("countries-of-the-world")  # lazy handle, default Vortex
+table = ds.to_arrow()                           # materialize when you want it
+path  = ds.path()                               # or just the cached file path
+```
+
+Resolution is **cache → mirror → local build**: a local cache hit short-circuits; otherwise it pulls from `RAINCLOUD_MIRROR` (a private/internal artefact store — `s3://bucket/prefix`, `file:///path`); only on a cache+mirror miss does it shell out to `scripts.pipeline.build` (which needs the `[build]` extra). When `docs/v1/snapshot.json` records a checksum, a drift warns-and-adopts by default (`RAINCLOUD_STRICT_CHECKSUM=1` for a hard gate); otherwise the pinned byte size is the corruption check.
+
+```bash
+export RAINCLOUD_MIRROR=s3://your-bucket/raincloud   # point CI at a prepared-artefact bucket
+export RAINCLOUD_CACHE=/var/cache/raincloud          # optional cache-dir override
+export RAINCLOUD_OFFLINE=1                            # cache-only; mirror/build misses raise OfflineMiss
+```
+
+## Publishing artefacts to a mirror
+
+Maintainers sync built `outputs/v1/...` artefacts up to a mirror bucket with the `publish` CLI. Each artefact's on-disk sha256 must match `docs/v1/snapshot.json` (regenerate the snapshot via `python -m scripts.pipeline.docs` after a build first), otherwise the upload is gated off with a `PublishMismatch`.
+
+```bash
+python -m scripts.pipeline.publish countries-of-the-world --mirror s3://your-bucket/raincloud
+python -m scripts.pipeline.publish --all --mirror file:///tmp/mirror --dry-run   # preview the plan
+```
+
+The mirror is a private/internal store you control — there is no public Raincloud-hosted endpoint, and publishing here does not change the no-redistribution posture in [`DISCLAIMER.md`](DISCLAIMER.md). The `--mirror` base is an `fsspec` URL; `s3://` needs `[s3]`, `http(s)://` needs `[http]`, `file://` needs neither.
 
 ## Opening a DuckDB connection
 
@@ -55,7 +87,7 @@ uv sync --extra dev --inexact   # one-time — installs pytest, preserves other
 pytest                          # ~0.5 s on the full suite
 ```
 
-`tests/` carries a sub-second smoke suite for the manifest, the schema, the handler registry, and the example templates. No fetch, no build, no filesystem writes. Run after any change to `sources.json`, `sources.schema.json`, `scripts/pipeline/handlers/__init__.py`, or `examples/`. Tests exercise the same `validate_manifest` codepath the `/raincloud-validate-manifest` skill runs.
+`tests/` carries a sub-second smoke suite for the manifest, the schema, the handler registry, and the example templates. No fetch, no build, no filesystem writes. Run after any change to `sources.json`, `sources.schema.json`, `scripts/pipeline/handlers/__init__.py`, `templates/`, or `examples/`. Tests exercise the same `validate_manifest` codepath the `/raincloud-validate-manifest` skill runs.
 
 ## Querying the catalog
 
diff --git a/docs/v1/snapshot.json b/docs/v1/snapshot.json
index e2f636c..d3e7eba 100644
--- a/docs/v1/snapshot.json
+++ b/docs/v1/snapshot.json
@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "generated_at": "2026-05-17T01:07:13Z",
+  "generated_at": "2026-05-27T18:14:16Z",
   "note": "Auto-generated by scripts/pipeline/docs.py. Read by the TUI as a fallback when a local parquet isn't built. Regenerate after any build / schema change with `python -m scripts.pipeline.docs snapshot`.",
   "slugs": {
     "clickbench-hits": {
@@ -1201,6 +1201,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 73701591,
       "vortex_bytes": 118973792,
+      "parquet_sha256": "ab7ab80dd49faba78e8321b1454fc2ff6cdbb5b5e872848e362853105e78c394",
+      "vortex_sha256": "d149b58bd8d59b157c68520d5de756cdd5755c08eeb9e25d9221ac7fcab7ef56",
       "columns": [
         {
           "name": "Country Name",
@@ -1795,6 +1797,8 @@
       "last_built_row_groups": 21,
       "parquet_bytes": 1558628820,
       "vortex_bytes": 2112544400,
+      "parquet_sha256": "fc7c1413ea8eeed4a8993888ea2cd3511513037b294478aa74d07891aaa91cab",
+      "vortex_sha256": "aeffbfe87959f63ca38b03ef832d121a4f362377d0040822380f873d1221dc84",
       "columns": [
         {
           "name": "Unique Key",
@@ -2437,6 +2441,8 @@
       "last_built_row_groups": 701,
       "parquet_bytes": 9976102966,
       "vortex_bytes": 15508324928,
+      "parquet_sha256": "18749a23f34f9f8ff4d9341d695ad6c22154d604ccd31ca3cbc739efaaf53d21",
+      "vortex_sha256": "37c93f284ea84be60ca53242454cd02eaef3542634560e9003f20fa54da95b11",
       "columns": [
         {
           "name": "id",
@@ -2499,22 +2505,25 @@
     },
     "osm-germany-relations": {
       "expected_rows": null,
-      "last_built_rows": 889712,
-      "parquet_bytes": 95642737,
-      "vortex_bytes": 155687156,
+      "last_built_rows": 890059,
+      "last_built_row_groups": 9,
+      "parquet_bytes": 95699411,
+      "vortex_bytes": 155627324,
+      "parquet_sha256": "0203b9678f731279507b2bf06047331081617779c4a496cb98ffe0f166d8842d",
+      "vortex_sha256": "4f7646e656293d31a83278a76ae17e36ae0a3d4ae242b8477945faf319e1057b",
       "columns": [
         {
           "name": "id",
           "type": "int64",
-          "length": 2775802,
+          "length": 2776912,
           "null_count": 0,
           "min": 882,
-          "max": 20620429
+          "max": 20631777
         },
         {
           "name": "version",
           "type": "int32",
-          "length": 494032,
+          "length": 488930,
           "null_count": 0,
           "min": 1,
           "max": 3154
@@ -2522,15 +2531,15 @@
         {
           "name": "timestamp",
           "type": "string",
-          "length": 4659107,
+          "length": 4663690,
           "null_count": 0,
           "min": "2007-10-17T19:07:38+00:00",
-          "max": "2026-05-03T20:14:56+00:00"
+          "max": "2026-05-05T20:18:32+00:00"
         },
         {
           "name": "members",
           "type": "list<element: struct<ref: int64, role: string, type: string>>",
-          "length": 65420639,
+          "length": 65466557,
           "null_count": null,
           "min": null,
           "max": null
@@ -2538,12 +2547,21 @@
         {
           "name": "tags",
           "type": "list<element: struct<key: string, value: string>>",
-          "length": 22281959,
+          "length": 22292153,
           "null_count": null,
           "min": null,
           "max": null
         }
-      ]
+      ],
+      "size_bucket": "s",
+      "shape_traits": {
+        "has_nested": true,
+        "has_timestamp": false,
+        "has_variant": false,
+        "string_heavy": false,
+        "wide_row": false,
+        "high_cardinality_present": null
+      }
     },
     "hacker-news": {
       "expected_rows": null,
@@ -3585,6 +3603,8 @@
       "last_built_row_groups": 8,
       "parquet_bytes": 150924485,
       "vortex_bytes": 134835552,
+      "parquet_sha256": "2c39fae00b1dee42909f942299c0ddcfd35b5c3aca428a953e3fb6c15641a8d6",
+      "vortex_sha256": "873bae0250a5c1a86c4cd6bd6503d8580ca6ad21fee7bbc6515407a656a2fa26",
       "columns": [
         {
           "name": "word",
@@ -30061,6 +30081,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 2732,
       "vortex_bytes": 10056,
+      "parquet_sha256": "72ed0dd70848acef0c2c94ad58385144a50f21484fa012c18b15dfa53ed25538",
+      "vortex_sha256": "4d3e683f6d911a2d3876e28cda03e22d029b051427ef3cfd65e3e367de4d5300",
       "columns": [
         {
           "name": "sepal_length",
@@ -30239,6 +30261,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 82836,
       "vortex_bytes": 112248,
+      "parquet_sha256": "74b2cce0f54f063391e4d3812bc11afa86bf4f8bdd1885dce327f49ab8d27ded",
+      "vortex_sha256": "289df4c7c09e02ac190a4d23187f4bbbbfdcdde2cc562de0b444fd9cd6c35f7f",
       "columns": [
         {
           "name": "fixed_acidity",
@@ -31169,6 +31193,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 3085946,
       "vortex_bytes": 3470324,
+      "parquet_sha256": "c0d99b2907203d9d4e495967ff2555b9346118013df67a8c44484269237e9dcc",
+      "vortex_sha256": "1dc992e33ecba1a8b7c0b3b7282a8baa37bc1c6e8069760c9f1b3c9c0488ab4a",
       "columns": [
         {
           "name": "invoiceno",
@@ -32075,6 +32101,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 90533,
       "vortex_bytes": 131396,
+      "parquet_sha256": "0cc25809dfa9aee37a9e0703f1951568287f6d321994965417c25ccf6a7aaab9",
+      "vortex_sha256": "ead9e91500dfd44271d9f2119b76ce6004a4ebb7ce2bd281b496798eea94c0a4",
       "columns": [
         {
           "name": "patient_id",
@@ -37469,6 +37497,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 195535,
       "vortex_bytes": 158968,
+      "parquet_sha256": "151fd25027af4d233c47b90e60923f9ad824f50976a28a835f190ead0ffc015e",
+      "vortex_sha256": "5ef0007940e02b7ddce829a32094bc3198219c151242e1466e94f8bf40a4f4d5",
       "columns": [
         {
           "name": "instant",
@@ -38228,8 +38258,11 @@
     "uci-spambase": {
       "expected_rows": 4601,
       "last_built_rows": 4601,
+      "last_built_row_groups": 1,
       "parquet_bytes": 169587,
       "vortex_bytes": 377572,
+      "parquet_sha256": "0e2e06c5444e8db618fd6fd26048733c592982c0557224497c5fe7f6e0819005",
+      "vortex_sha256": "f56e3bf6c7b8e87969400bd7d2056a830df1a492d5a74e2c8deb2cd7dfd17290",
       "columns": [
         {
           "name": "word_freq_make",
@@ -38695,7 +38728,16 @@
           "min": 0,
           "max": 1
         }
-      ]
+      ],
+      "size_bucket": "xs",
+      "shape_traits": {
+        "has_nested": false,
+        "has_timestamp": false,
+        "has_variant": false,
+        "string_heavy": false,
+        "wide_row": true,
+        "high_cardinality_present": null
+      }
     },
     "uci-magic-gamma-telescope": {
       "expected_rows": 19020,
@@ -41231,6 +41273,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 10725,
       "vortex_bytes": 20992,
+      "parquet_sha256": "59639068c918f2f3f46532b3b2ee47605d1d3a59580cbb3872259f1c5becd886",
+      "vortex_sha256": "ca0daddc46e7db5934e7655b42fa5be57eed3b22b9a7629ca53d25b9bf1c9ad0",
       "columns": [
         {
           "name": "col_0",
@@ -48369,6 +48413,8 @@
       "last_built_row_groups": 2,
       "parquet_bytes": 62325617,
       "vortex_bytes": 53679308,
+      "parquet_sha256": "7db14cf55edb24cc4fd4befaa07b0f5e767e3bc9d0724d435e83dd928583fd7d",
+      "vortex_sha256": "10a8f8953cc87f36b0156ec06fe03b657c6340f6ecab2a617e7a313e4a45bd20",
       "columns": [
         {
           "name": "Organization Group Code",
@@ -52699,6 +52745,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 4637420,
       "vortex_bytes": 5825840,
+      "parquet_sha256": "c39dfd34997d7ebeea5ec7389d2f22e28eadb143c43bc06ab81a2410433d3bb1",
+      "vortex_sha256": "aa8953e69d38d2765f4d2c62af08aaa7336e9c6bb5eefc65bd949f223656b080",
       "columns": [
         {
           "name": "ID",
@@ -102741,6 +102789,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 930532,
       "vortex_bytes": 1577848,
+      "parquet_sha256": "402ea0920378fa61637c8e4047cbb2461d418ac26e833002ac58c3eef8eb0ac9",
+      "vortex_sha256": "01e1aa77bac5296c7cf72693024f3323d56756bdcaf7415c0083ebd0a0bc7efa",
       "columns": [
         {
           "name": "hotel",
@@ -103335,6 +103385,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 3322173,
       "vortex_bytes": 3315556,
+      "parquet_sha256": "a9bf0bddc568e719ab789f341cc6805d79eaddb2ea779bdef593ab9fbc1f4d5d",
+      "vortex_sha256": "9a57a490f584e08dd8f943fc8e31f0907c6a81d14807770bc9c96800ed19e8d9",
       "columns": [
         {
           "name": "kepid",
@@ -112465,6 +112517,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 29295473,
       "vortex_bytes": 90073420,
+      "parquet_sha256": "a079040cebf707cc6ae94cb36880ecf5562350e2c4fda5e9b94e6b61613a1708",
+      "vortex_sha256": "c4fe5dd81cd9a10f171942c8c2cd0c4f0582b6108d525ae23b223fd318c3f849",
       "columns": [
         {
           "name": "answer",
@@ -112723,6 +112777,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 1106214411,
       "vortex_bytes": 1652406076,
+      "parquet_sha256": "2f917f7469b6f43e28d5680b72ed84f43a7b3e06927e7553b95eac7099767a3c",
+      "vortex_sha256": "f0007332c751b9a9bf502bed47fb75acd02c1354cc2d65d14b140ef6d5f303b0",
       "columns": [
         {
           "name": "prompt",
@@ -113533,6 +113589,8 @@
       "last_built_row_groups": 7,
       "parquet_bytes": 8130454405,
       "vortex_bytes": 11784725216,
+      "parquet_sha256": "4f46f3efd2aae547a4ad19a35be0c0801bf74cbc67ae1cd19965a12681b44664",
+      "vortex_sha256": "a8e3b94b68a33fe0c0b67335ea47289592cf780dea66b319dd76c8153a0c124b",
       "columns": [
         {
           "name": "id",
@@ -113591,6 +113649,8 @@
       "last_built_row_groups": 3,
       "parquet_bytes": 664283863,
       "vortex_bytes": 962524448,
+      "parquet_sha256": "4edd26c9198483aab39e58c14f4f7f86285151c417423bbf6de5dc80c4a6e033",
+      "vortex_sha256": "6fa4dc3b21e27e8f4c0229607aa0f07e8cde62c0e6dfbbba044b87202734d142",
       "columns": [
         {
           "name": "text",
@@ -113625,6 +113685,8 @@
       "last_built_row_groups": 4,
       "parquet_bytes": 4806167375,
       "vortex_bytes": 6089862740,
+      "parquet_sha256": "a0c3ab9b0b050b3e882711fcea7f705e567ffc3f9a9c16aad8dc8845ea76d6c7",
+      "vortex_sha256": "636cdea4268af7f5b6e1c2c4ef423326151dd1903546b182322afea164584bd9",
       "columns": [
         {
           "name": "text",
@@ -113739,6 +113801,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 7294437,
       "vortex_bytes": 13304260,
+      "parquet_sha256": "b54e8f4ab980f80ebe6be48356a6dd904dadfc10e4d35dde8a14e3f800dc2792",
+      "vortex_sha256": "96043c7527071d73a7d88621fa00fbd4d3cd92d6e014a78e8a8d3d0c2254af09",
       "columns": [
         {
           "name": "text",
@@ -113949,6 +114013,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 2121169743,
       "vortex_bytes": 3268285484,
+      "parquet_sha256": "52428549cbc520a0a12cb475d2582f6999ac271dc3b5a9d0b3d1773c0f2be9e9",
+      "vortex_sha256": "f9493ed6a760c4cb304b7229c3ffc2b842cdd0dc1712d6de72601eecbd34a1f7",
       "columns": [
         {
           "name": "text_token_length",
@@ -114023,6 +114089,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 22934195,
       "vortex_bytes": 38332972,
+      "parquet_sha256": "3b9023a42c3aed1d8e5e4f3de8c8bff433dbb667be8a687a6e4522d21928a804",
+      "vortex_sha256": "b7b3b0156c0c87baf1776951057d4c0d6d541acb60af088d2df4b01cedbea486",
       "columns": [
         {
           "name": "id",
@@ -114137,6 +114205,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 1520738958,
       "vortex_bytes": 1943240616,
+      "parquet_sha256": "e0fa14e94a3a8b13b189e18fd2309fa2cc3a3f1bada5f5a9cc37496f46571a29",
+      "vortex_sha256": "4f24e6f06b90b8c4cbbb7ebe891273c253d28a554aa7e4c201b5dd144d19e010",
       "columns": [
         {
           "name": "id",
@@ -114487,6 +114557,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 633824764,
       "vortex_bytes": 645264768,
+      "parquet_sha256": "e8f14b8ce7e80b6c2f2de9c7c06676d90901b89b06b8afb7af1e40a3aa8831e7",
+      "vortex_sha256": "9e007f67c6043d028640cdf2e3c6091f16218dd9760163fb93f72fc79adad849",
       "columns": [
         {
           "name": "images",
@@ -114529,6 +114601,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 60551,
       "vortex_bytes": 103864,
+      "parquet_sha256": "bd65bb1e42c0f3eea4f5e41629271abc4f42b37d68b8cff96a6d032b5329bd11",
+      "vortex_sha256": "b6adfd55352022ec7c462182e96d8ac9c8a997b46705b75e0ac0a5a7fcaa86c7",
       "columns": [
         {
           "name": "task_id",
@@ -114595,6 +114669,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 187862,
       "vortex_bytes": 331456,
+      "parquet_sha256": "cc02b069245fbade0263629f7a23b16f199643a756127eb94ef9ae2cc52537ff",
+      "vortex_sha256": "9b41c6bd7c9c846392c18745d0ead6bd60cbb17c3b551455f14dd7466a4126fd",
       "columns": [
         {
           "name": "question",
@@ -114645,6 +114721,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 3633313707,
       "vortex_bytes": 3675267604,
+      "parquet_sha256": "a72bafdbec981a21cf5b850f561db97b3902c5a28cf9119e6b8b3411f7c3359f",
+      "vortex_sha256": "b7ea53a0d1e5566d946f26bf7d2af198d5a5965a7440f4464e1cbdbbccdcc42a",
       "columns": [
         {
           "name": "id",
@@ -114799,6 +114877,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 793523,
       "vortex_bytes": 1103536,
+      "parquet_sha256": "85acd4636fd9468718e66f795bb33f32d16709dee50ab9105c2f286efd1e04e6",
+      "vortex_sha256": "e56c0c71829bb4e2b42edab83c1868e632f3f57979c6841f4cfab2ff9a61b4b3",
       "columns": [
         {
           "name": "id",
@@ -114857,6 +114937,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 751960,
       "vortex_bytes": 1055580,
+      "parquet_sha256": "55ae2ffe9b74516d7668efb73dd5e84e8c046bcf68233b9f320d49ed2d5e6a85",
+      "vortex_sha256": "6135bc9f6e6f4424b21c479138fb82391800598afdab284909c2ea01f5cb208b",
       "columns": [
         {
           "name": "pubid",
@@ -114923,6 +115005,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 56312765,
       "vortex_bytes": 74216104,
+      "parquet_sha256": "2f99c4dab111c4c8b7d0a9715ea68df56fcc3ac7c0fe930d65426791d6f8dbb8",
+      "vortex_sha256": "375462e51d41963e0e7d9536987ff3e3ac6b166579af276fe47485249b2a7590",
       "columns": [
         {
           "name": "id",
@@ -115037,6 +115121,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 275730042,
       "vortex_bytes": 359519012,
+      "parquet_sha256": "b6756a27e19367d4f37adbba86cf9ee4572730445eaec637674687b2c98cf1d1",
+      "vortex_sha256": "8ee29f0c19bf44e33f866961444cf5337efeff3860930cb5a930cceafd611f19",
       "columns": [
         {
           "name": "id",
@@ -115119,6 +115205,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 569684836,
       "vortex_bytes": 748493424,
+      "parquet_sha256": "492009418c2afbd12fd18596f3ac32ede9f4455dcb6912cbacb01e2fce5654d1",
+      "vortex_sha256": "99b800dbd9448a3df1a7a2efa063725ba742c0c824f0460ff703154a6010b6d6",
       "columns": [
         {
           "name": "article",
@@ -115169,6 +115257,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 15873453,
       "vortex_bytes": 20423644,
+      "parquet_sha256": "48533689b58e91740da03c67114473d38c61d1c31a8f47d12514b24f5857cec4",
+      "vortex_sha256": "00955c30842af9d7890fe52364e9b16b05fb3e21fd6d7c8347f08d06ac066fa6",
       "columns": [
         {
           "name": "image",
@@ -115211,6 +115301,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 152938,
       "vortex_bytes": 242304,
+      "parquet_sha256": "e8f476fc08222703d6f77da35178c1888b06e0a3f814c161293688fb8b16d9b2",
+      "vortex_sha256": "d8d664d93a91691aa02262069a3109c17f44f5abe103acb695ebda8796747528",
       "columns": [
         {
           "name": "task_id",
@@ -115285,6 +115377,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 4307899453,
       "vortex_bytes": null,
+      "parquet_sha256": "029e8c97e41a971d5d6bc91dd1dde7c934a7f9abfdbc05842b25b0a84885526d",
+      "vortex_sha256": null,
       "columns": [
         {
           "name": "name",
@@ -115471,6 +115565,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 346051024,
       "vortex_bytes": 367513008,
+      "parquet_sha256": "9902c1b94252b424dc361bf5fd7354e8ebff610ea53d22150f92b8cbbbf66386",
+      "vortex_sha256": "ed724fd452bca8579d2bb70fb7f11697881f2a6d9e9533d67bfa07cd4db9da77",
       "columns": [
         {
           "name": "file",
@@ -115545,6 +115641,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 2306373926,
       "vortex_bytes": 2458934716,
+      "parquet_sha256": "19fd17c4ab293450bd635e0a7b14237edf19fb5d4fdf99f68d73b16db3c78429",
+      "vortex_sha256": "dfe64038a4f814d13fd3aa94a4f4f2bceae7d420d147390b8e5652a150de942d",
       "columns": [
         {
           "name": "id",
@@ -115603,6 +115701,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 562911303,
       "vortex_bytes": 571225152,
+      "parquet_sha256": "eae8a9cb5a57711580c0e374bd14fe901aaa5c903cd5ce29dbdf078cef32b20f",
+      "vortex_sha256": "76a96582a6ddcf66c84f9a36f14b838276eaf3cc532fcd7e3d1f8d1481f35eb6",
       "columns": [
         {
           "name": "id",
@@ -115677,6 +115777,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 165968,
       "vortex_bytes": 256980,
+      "parquet_sha256": "941578c6cc5e69739cfb8db43ce4055902b949927aa4b28dc91c34c2b5028e1c",
+      "vortex_sha256": "1e1c3d4f4a345eb859d1ed978d8be34696e8780f85fdac1fb5cb06e290615281",
       "columns": [
         {
           "name": "Unnamed: 0",
@@ -115831,6 +115933,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 265872790,
       "vortex_bytes": 429778304,
+      "parquet_sha256": "63bd6e330c8a356a026a08abf8a1b6c74c7683114b0b5ac21f0699fe8f716955",
+      "vortex_sha256": "4604c8573de84acb62eb61d056de9d57841a5fa7eb3235c526b1f4921a2b83e5",
       "columns": [
         {
           "name": "video_id",
@@ -115961,6 +116065,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 1641372431,
       "vortex_bytes": 2257731372,
+      "parquet_sha256": "c8250d75e6f5fab02cb576111aae982b46eb85d8691bb4735648881170b0b05c",
+      "vortex_sha256": "271bba9a5c2c8c06cc60e87f4408dd33063faa220aa69899ac59a7e3e989afc4",
       "columns": [
         {
           "name": "synth_id",
@@ -116099,6 +116205,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 13207283,
       "vortex_bytes": 21735488,
+      "parquet_sha256": "eef8dd021b7ec65fe5ae5dfaa7359746a25085b32db507d3c6f6b935d1fc533b",
+      "vortex_sha256": "0ed4dbc889df05c9f0e28256ffbc339188c6a1679c98c56db67cc716a92ebd45",
       "columns": [
         {
           "name": "prompt",
@@ -116181,6 +116289,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 3190047,
       "vortex_bytes": 5669032,
+      "parquet_sha256": "63ce777948587a5b82a98b80cccc448bfaf4a44d4d285a0b5f38abbbb91c7c54",
+      "vortex_sha256": "b5c2d7bf860455a435c69bc551f4bf079e3d2289baa3c031baf7df259aeeb20e",
       "columns": [
         {
           "name": "transcript_id",
@@ -116223,6 +116333,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 104135565,
       "vortex_bytes": 170067388,
+      "parquet_sha256": "39ce8864e3b1d19de6976da4a19133ddd27261071e8522ada64e8e0db2ff1a88",
+      "vortex_sha256": "b534a6f2db918cb994ad8362808a25ad9c2afa6b5d4304fe449a8df4f29ba8fb",
       "columns": [
         {
           "name": "inputs",
@@ -116297,6 +116409,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 103944240,
       "vortex_bytes": 168069836,
+      "parquet_sha256": "9b42772dc63b9508f5e63334d9d5253455bf9dc50c89240b50e31cd4fabaa079",
+      "vortex_sha256": "c513d9f234b94f69b1b9a11a6b4aa331cc732e9db7612fb4054701f0553232f0",
       "columns": [
         {
           "name": "id",
@@ -116403,6 +116517,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 58178780,
       "vortex_bytes": 106617292,
+      "parquet_sha256": "35516084f5f51199e1459eb1ffba0e8d9dcdbb64b2dd9e2248a85dd276adf941",
+      "vortex_sha256": "75cd4bcc086c0643b9edd0420c0f3bdd64ef4635d5183bbd6ce35fabb5af8dd3",
       "columns": [
         {
           "name": "instruction",
@@ -116445,6 +116561,8 @@
       "last_built_row_groups": 2,
       "parquet_bytes": 19485316,
       "vortex_bytes": 21301348,
+      "parquet_sha256": "63402d6ee1adba5117d54549d776ba566528a247b8fa335aa2598ed1de195659",
+      "vortex_sha256": "5e4c2c6cb932eaae0bd40b4af2d21459d638f5623b5682cf0ce3cbe363fb7698",
       "columns": [
         {
           "name": "unix_ts",
@@ -116559,6 +116677,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 263543,
       "vortex_bytes": 426464,
+      "parquet_sha256": "fd894bd09380724d679cb64a8e713891d233d50cca2522216323ae91058d9d32",
+      "vortex_sha256": "33da5a1918a80a5e896702796f14e48f6d8449ada6978527cb4fe633b2549a18",
       "columns": [
         {
           "name": "f0",
@@ -116625,6 +116745,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 5624277,
       "vortex_bytes": 7621292,
+      "parquet_sha256": "12da59ce3b1895a968f8d2e708246fa1df210ced3e6986395e91a0ab107d1dde",
+      "vortex_sha256": "7e19e46cf134805c3e376d2ebffb8cac5a85d2d392a0f3a440a00d2b2daa96be",
       "columns": [
         {
           "name": "No",
@@ -116787,6 +116909,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 3747845,
       "vortex_bytes": 6080116,
+      "parquet_sha256": "e54895929c1f8e54f31a59d061f476aa2f2cfd28da1928af9b3e34c6501271c1",
+      "vortex_sha256": "d39b7c358464a299cc43d83650d4361fe532fae635f56274729403ab687709ec",
       "columns": [
         {
           "name": "geo_id",
@@ -116885,6 +117009,8 @@
       "last_built_row_groups": 1,
       "parquet_bytes": 28713325,
       "vortex_bytes": 41394396,
+      "parquet_sha256": "4a0b6e364f0271940bb6c4182602890491b41516c87cc0e4e043905b196bee90",
+      "vortex_sha256": "a0abe7c51aefd60ef7f93db053ddc07eb86f79b2b6e0c8fd421b14113174cc89",
       "columns": [
         {
           "name": "answer_choices",
diff --git a/examples/README.md b/examples/README.md
index 478327b..e0a23ac 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,12 +1,27 @@
 # examples
 
-Copy-pasteable templates for the two most common tasks against this repo.
+Runnable, single-file demos of the `raincloud.load(slug)` datasets-like API —
+load a real catalog dataset and run an actual query. (For *authoring* templates —
+new manifest entries and streaming handlers — see [`../templates/`](../templates/).)
 
-| File | Purpose |
-|---|---|
-| [`minimal_spec.json`](minimal_spec.json) | Full `DatasetSpec` with every field present and placeholder values. Validates against [`../sources.schema.json`](../sources.schema.json). Use as the starting point for a new entry in `sources.json`. |
-| [`streaming_handler.py.tmpl`](streaming_handler.py.tmpl) | Template for a streaming transform handler — the pattern for datasets that don't fit in RAM. Copy into `scripts/pipeline/handlers/`, fill in the ingest loop, register in `scripts/pipeline/handlers/__init__.py`. |
+| File | What it does | Engine | Cost on first run |
+|---|---|---|---|
+| [`use_loader.py`](use_loader.py) | API basics: metadata, format override, `.to_arrow` / `.scan` / `.to_pandas`, env vars, the typed exception hierarchy. | — | none (metadata is network-free; `--materialize` resolves one artifact) |
+| [`nyc_taxi_tip_rate.py`](nyc_taxi_tip_rate.py) | Of "probably-valid" 2025 yellow-cab trips, what % left no recorded tip? Broken down by `payment_type` to expose that the TLC only records *card* tips. | DuckDB over `.scan()` | ~900 MB (48.7M rows, 12 monthly parquets) |
+| [`kepler_exoplanets.py`](kepler_exoplanets.py) | How many Kepler candidates are CONFIRMED vs FALSE POSITIVE, and what's the smallest confirmed planet? | pandas | ~3 MB, seconds |
+| [`wine_quality_correlations.py`](wine_quality_correlations.py) | Which physicochemical features correlate with a wine's quality score? | pandas `.corr()` | ~80 KB, instant |
+| [`olympic_medals.py`](olympic_medals.py) | Top medal-winning nations and medals per decade across 120 years of the Games. | DuckDB over `.scan()` | ~5 MB, seconds |
 
-These mirror the inline templates in [`../SKILLS.md`](../SKILLS.md) but live as real files so `git grep`, IDE schema validation, and copy-paste-without-markdown-quirks all work.
+## Running them
 
-After dropping a new entry into `sources.json`, run [`/raincloud-validate-manifest`](../.agents/skills/raincloud-validate-manifest/SKILL.md) to confirm the shape is correct before paying for a fetch.
+```bash
+pip install "raincloud[build,duckdb,pandas] @ git+https://github.com/spiraldb/raincloud"
+python examples/kepler_exoplanets.py
+```
+
+There is **no public Raincloud mirror**, so the first run of an example
+fetches the upstream data and builds the artifact locally (this is what the
+`[build]` extra is for); subsequent runs hit the local cache and are fast. If
+your team runs a private mirror, set `RAINCLOUD_MIRROR=s3://bucket/prefix` (or
+`file:///path`) and the examples pull from it instead of building. `[duckdb]`
+backs `.scan()`, `[pandas]` backs `.to_pandas()`.
diff --git a/examples/kepler_exoplanets.py b/examples/kepler_exoplanets.py
new file mode 100644
index 0000000..3a0927f
--- /dev/null
+++ b/examples/kepler_exoplanets.py
@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""How many Kepler candidates panned out — and what's the smallest one?
+
+Loads the Kepler Objects of Interest table (`kepler-exoplanet-search-results`,
+~9.5k rows) into a pandas DataFrame and does two quick passes: the
+CONFIRMED / CANDIDATE / FALSE POSITIVE disposition breakdown, and the
+smallest-radius CONFIRMED planet. Small enough that pandas is the right tool —
+no SQL engine needed.
+
+Run it:
+
+    python examples/kepler_exoplanets.py
+
+Install (raincloud is not on PyPI — install from GitHub):
+
+    pip install "raincloud[build,pandas] @ git+https://github.com/spiraldb/raincloud"   # build: first-run fetch; pandas: .to_pandas()
+
+First run fetches ~3 MB from upstream (or a configured RAINCLOUD_MIRROR) and is
+cached; it runs in seconds thereafter.
+"""
+from __future__ import annotations
+
+import sys
+
+import raincloud
+
+SLUG = "kepler-exoplanet-search-results"
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        df = raincloud.load(SLUG).to_pandas()
+    except raincloud.MissingDependency as e:
+        print(f"this example needs pandas: {e}\n"
+              '  pip install "raincloud[pandas] @ git+https://github.com/spiraldb/raincloud"')
+        return 1
+    except raincloud.RaincloudError as e:
+        print(f"could not load {SLUG}: {type(e).__name__}: {e}")
+        print('  hint: pip install "raincloud[build] @ git+https://github.com/spiraldb/raincloud" '
+              "(first run fetches ~3 MB) or set RAINCLOUD_MIRROR=<url>")
+        return 1
+
+    import pandas as pd
+
+    print(f"Kepler Objects of Interest: {len(df):,}\n")
+    print("disposition breakdown:")
+    for disp, n in df["koi_disposition"].value_counts().items():
+        print(f"  {disp:<15}{n:>7,}  ({100 * n / len(df):.1f}%)")
+
+    confirmed = df[df["koi_disposition"] == "CONFIRMED"].dropna(subset=["koi_prad"])
+    smallest = confirmed.nsmallest(1, "koi_prad").iloc[0]
+    name = smallest["kepler_name"]
+    if pd.isna(name):
+        name = smallest["kepoi_name"]
+    print("\nsmallest CONFIRMED planet by radius:")
+    print(f"  {name}: {smallest['koi_prad']:.2f} Earth radii, "
+          f"{smallest['koi_period']:.2f}-day orbit")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+
+# --- Sample output (captured 2026-05-29 against live upstream; exact numbers
+#     drift as the archive is revised) ---
+#
+#   Kepler Objects of Interest: 9,564
+#
+#   disposition breakdown:
+#     FALSE POSITIVE   4,839  (50.6%)
+#     CONFIRMED        2,747  (28.7%)
+#     CANDIDATE        1,978  (20.7%)
+#
+#   smallest CONFIRMED planet by radius:
+#     Kepler-37 b: 0.27 Earth radii, 13.37-day orbit
diff --git a/examples/nyc_taxi_tip_rate.py b/examples/nyc_taxi_tip_rate.py
new file mode 100644
index 0000000..bfcf91a
--- /dev/null
+++ b/examples/nyc_taxi_tip_rate.py
@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""How many NYC yellow-cab riders left no tip in 2025?
+
+Loads the full 2025 yellow-taxi trip record (`yellow_tripdata_2025`,
+~48.7M rows) and asks: of the *probably-valid* trips — those whose metered
+fare cleared the city's minimum (the flag-drop initial charge) — what share
+left no recorded tip? The answer is then broken down by `payment_type`, which
+reveals the catch: the TLC only records tips paid by **card**, so cash trips
+always show a $0 tip. The headline "no tip" rate is really a "paid cash" rate.
+
+This is the OLAP-on-a-big-dataset showcase: the query runs in DuckDB directly
+over the parquet via `Dataset.scan()`, so nothing materializes 48M rows into
+memory — only the small grouped result comes back as a DataFrame.
+
+Run it:
+
+    python examples/nyc_taxi_tip_rate.py
+
+Install (raincloud is not on PyPI — install from GitHub):
+
+    pip install "raincloud[build,duckdb] @ git+https://github.com/spiraldb/raincloud"   # build: first-run fetch; duckdb: .scan()
+
+First run downloads ~900 MB (12 monthly parquet files, merged) unless a mirror
+is configured via RAINCLOUD_MIRROR; subsequent runs hit the local cache.
+"""
+from __future__ import annotations
+
+import sys
+
+import raincloud
+
+SLUG = "yellow_tripdata_2025"
+
+# NYC yellow-cab initial charge ("flag drop") for 2025 — the smallest metered
+# fare a real trip can record. Filtering above it drops $0 / negative / voided
+# rows. See https://www.nyc.gov/site/tlc/passengers/taxi-fare.page
+BASE_FARE_2025 = 3.00
+
+# TLC trip-record `payment_type` codes (data dictionary).
+PAYMENT_TYPES = {1: "Credit card", 2: "Cash", 3: "No charge",
+                 4: "Dispute", 5: "Unknown", 6: "Voided trip"}
+
+QUERY = f"""
+    SELECT
+        payment_type,
+        count(*)                                AS trips,
+        count(*) FILTER (WHERE tip_amount <= 0) AS no_tip
+    FROM taxi
+    WHERE fare_amount > {BASE_FARE_2025}
+    GROUP BY payment_type
+    ORDER BY trips DESC
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        # Load as parquet (not the vortex default): DuckDB reads parquet, and a
+        # vortex handle's .scan() would resolve the parquet sibling anyway.
+        rel = raincloud.load(SLUG, format="parquet").scan()
+    except raincloud.MissingDependency as e:
+        print(f"this example needs DuckDB: {e}\n"
+              '  pip install "raincloud[duckdb] @ git+https://github.com/spiraldb/raincloud"')
+        return 1
+    except raincloud.RaincloudError as e:
+        print(f"could not load {SLUG}: {type(e).__name__}: {e}")
+        print('  hint: pip install "raincloud[build] @ git+https://github.com/spiraldb/raincloud" '
+              "(first run fetches ~900 MB) or set RAINCLOUD_MIRROR=<url>")
+        return 1
+
+    df = rel.query("taxi", QUERY).df()
+    total = int(df["trips"].sum())
+    no_tip = int(df["no_tip"].sum())
+
+    print(f"NYC yellow cab 2025 — valid trips (fare > ${BASE_FARE_2025:.2f}): {total:,}")
+    print(f"  left no recorded tip: {no_tip:,}  ({100 * no_tip / total:.1f}%)\n")
+    print(f"  {'payment type':<14}{'trips':>14}{'no tip':>14}{'% no tip':>10}")
+    for r in df.itertuples():
+        label = PAYMENT_TYPES.get(int(r.payment_type), f"code {r.payment_type}")
+        pct = 100 * r.no_tip / r.trips if r.trips else 0.0
+        print(f"  {label:<14}{r.trips:>14,}{r.no_tip:>14,}{pct:>9.1f}%")
+
+    print("\nThe TLC records tips only for card payments, so cash trips always show")
+    print("a $0 tip — most of the headline 'no tip' rate is really 'paid cash'.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+
+# --- Sample output (captured 2026-05-29 against live upstream; exact numbers
+#     drift as the TLC revises the year's data) ---
+#
+#   NYC yellow cab 2025 — valid trips (fare > $3.00): 45,387,796
+#     left no recorded tip: 15,836,419  (34.9%)
+#
+#     payment type           trips        no tip  % no tip
+#     Credit card       31,025,313     2,282,009      7.4%
+#     code 0             9,280,676     8,473,528     91.3%   # an unmapped code that
+#     Cash               4,380,579     4,380,337    100.0%   # appeared in 2025 data;
+#     Dispute              534,317       533,846     99.9%   # the fallback labels it
+#     No charge            166,910       166,698     99.9%   # gracefully rather than
+#     Unknown                    1             1    100.0%   # guessing its meaning
+#
+#   The TLC records tips only for card payments, so cash trips always show
+#   a $0 tip — most of the headline 'no tip' rate is really 'paid cash'.
diff --git a/examples/olympic_medals.py b/examples/olympic_medals.py
new file mode 100644
index 0000000..f0e5c94
--- /dev/null
+++ b/examples/olympic_medals.py
@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Who wins the most Olympic medals, and how has the haul grown over time?
+
+Loads 120 years of Olympic athlete results
+(`120-years-of-olympic-history-athletes-and-results`, ~271k athlete-event rows)
+and runs two DuckDB group-bys over `Dataset.scan()`: the top medal-winning
+national committees (NOC), and medals awarded per decade. Each row is one
+athlete in one event, so a medal row is a medal won (team events count once
+per athlete — a known quirk of this dataset).
+
+Run it:
+
+    python examples/olympic_medals.py
+
+Install (raincloud is not on PyPI — install from GitHub):
+
+    pip install "raincloud[build,duckdb] @ git+https://github.com/spiraldb/raincloud"   # build: first-run fetch; duckdb: .scan()
+
+First run fetches ~5 MB from upstream (or a configured RAINCLOUD_MIRROR), then
+it's cached.
+"""
+from __future__ import annotations
+
+import sys
+
+import raincloud
+
+SLUG = "120-years-of-olympic-history-athletes-and-results"
+
+TOP_NOCS = """
+    SELECT NOC, count(*) AS medals
+    FROM games
+    WHERE Medal IS NOT NULL
+    GROUP BY NOC
+    ORDER BY medals DESC
+    LIMIT 10
+"""
+
+PER_DECADE = """
+    SELECT (Year // 10) * 10 AS decade, count(*) AS medals
+    FROM games
+    WHERE Medal IS NOT NULL
+    GROUP BY decade
+    ORDER BY decade
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        rel = raincloud.load(SLUG, format="parquet").scan()
+    except raincloud.MissingDependency as e:
+        print(f"this example needs DuckDB: {e}\n"
+              '  pip install "raincloud[duckdb] @ git+https://github.com/spiraldb/raincloud"')
+        return 1
+    except raincloud.RaincloudError as e:
+        print(f"could not load {SLUG}: {type(e).__name__}: {e}")
+        print('  hint: pip install "raincloud[build] @ git+https://github.com/spiraldb/raincloud" '
+              "(first run fetches ~5 MB) or set RAINCLOUD_MIRROR=<url>")
+        return 1
+
+    top = rel.query("games", TOP_NOCS).df()
+    decades = rel.query("games", PER_DECADE).df()
+
+    print("top 10 medal-winning national committees (1896-2016):")
+    for r in top.itertuples():
+        print(f"  {r.NOC:<5}{r.medals:>8,}")
+
+    print("\nmedals awarded per decade:")
+    peak = decades["medals"].max()
+    for r in decades.itertuples():
+        bar = "#" * round(40 * r.medals / peak)
+        print(f"  {int(r.decade)}s  {r.medals:>6,}  {bar}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+
+# --- Sample output (captured 2026-05-29 against live upstream; exact numbers
+#     drift as the dataset is revised) ---
+#
+#   top 10 medal-winning national committees (1896-2016):
+#     USA     5,637
+#     URS     2,503
+#     GER     2,165
+#     GBR     2,068
+#     FRA     1,777
+#     ITA     1,637
+#     SWE     1,536
+#     CAN     1,352
+#     AUS     1,320
+#     RUS     1,165
+#
+#   medals awarded per decade:
+#     1890s     143  #
+#     1900s   2,379  #############
+#     1910s     941  #####
+#     1920s   3,093  ##################
+#     1930s   1,764  ##########
+#     1940s     987  ######
+#     1950s   2,076  ############
+#     1960s   3,529  ####################
+#     1970s   2,945  #################
+#     1980s   5,145  #############################
+#     1990s   4,643  ##########################
+#     2000s   7,057  ########################################
+#     2010s   5,081  #############################
diff --git a/examples/use_loader.py b/examples/use_loader.py
new file mode 100644
index 0000000..6f84e9c
--- /dev/null
+++ b/examples/use_loader.py
@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Worked example: the Raincloud loader API.
+
+Demonstrates the `raincloud.load(slug)` flow end-to-end:
+
+  * cheap, network-free metadata access (rows, columns, license, source URL)
+  * format selection: vortex (default) vs parquet
+  * materialization: .to_arrow(), .to_vortex(), .scan() (DuckDB),
+    .to_pandas()
+  * configuration via env vars: RAINCLOUD_CACHE, RAINCLOUD_MIRROR,
+    RAINCLOUD_OFFLINE, RAINCLOUD_STRICT_CHECKSUM (hard integrity gate)
+  * the typed exception hierarchy (UnknownSlug, FormatUnavailable,
+    OfflineMiss, BuildToolingMissing, ChecksumMismatch, MissingDependency)
+
+Run it:
+
+    # Metadata-only demo against the packaged catalog (no network):
+    python examples/use_loader.py
+
+    # Pick a specific slug (any slug name in the catalog):
+    python examples/use_loader.py --slug clickbench-hits
+
+    # Full materialization demo (needs RAINCLOUD_MIRROR or local cache hit):
+    RAINCLOUD_MIRROR=file:///path/to/mirror \\
+        python examples/use_loader.py --materialize
+
+Install (raincloud is not on PyPI — install from GitHub):
+
+    pip install "raincloud @ git+https://github.com/spiraldb/raincloud"           # loader only
+    pip install "raincloud[duckdb] @ git+https://github.com/spiraldb/raincloud"   # Dataset.scan()
+    pip install "raincloud[pandas] @ git+https://github.com/spiraldb/raincloud"   # Dataset.to_pandas()
+    pip install "raincloud[build] @ git+https://github.com/spiraldb/raincloud"    # local-build fallback
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+import raincloud
+
+
+def show_metadata(slug: str) -> None:
+    """Pure-metadata path: walks the packaged catalog, no I/O beyond it."""
+    print(f"\n== metadata for {slug!r} ==")
+    ds = raincloud.load(slug)  # default format='vortex' with parquet fallback
+    print(f"  repr            : {ds!r}")
+    print(f"  format          : {ds.format}")
+    print(f"  num_rows        : {ds.num_rows}")
+    print(f"  column count    : {len(ds.column_names)}")
+    print(f"  first 5 columns : {ds.column_names[:5]}")
+    info = ds.info
+    print(f"  short_name      : {info.get('short_name')}")
+    print(f"  license (SPDX)  : {(info.get('license') or {}).get('spdx')}")
+    print(f"  source_url      : {info.get('source_url')}")
+
+
+def show_materialization(slug: str) -> None:
+    """The four materialization shapes. Resolves the artifact on first call."""
+    print(f"\n== materialize {slug!r} ==")
+    ds = raincloud.load(slug)
+    print("  .path() ->", ds.path(), "(cache or mirror or local build)")
+    if ds.format == "parquet":
+        schema = ds.schema  # parquet footer read — cheap
+        print(f"  .schema  : {len(schema)} fields")
+    table = ds.to_arrow()
+    print(f"  .to_arrow().num_rows : {table.num_rows}")
+
+    # .to_vortex() opens the vortex artifact (vortex-data is a base dep).
+    # Guarded for parquet-only slugs that have no vortex sibling.
+    try:
+        vf = ds.to_vortex()
+        print(f"  .to_vortex()     : {type(vf).__name__}")
+    except raincloud.FormatUnavailable as e:
+        print(f"  .to_vortex()     : skipped ({e})")
+
+    # Optional backends — guarded so the demo runs without [duckdb]/[pandas].
+    try:
+        rel = ds.scan()
+        # `.scan()` always resolves the parquet sibling; if you loaded as
+        # vortex, you'll see a [raincloud] note on stderr before resolution.
+        head = rel.limit(3).fetchall()
+        print(f"  .scan() head     : {head}")
+    except raincloud.MissingDependency as e:
+        print(f"  .scan()          : skipped ({e})")
+    try:
+        df = ds.to_pandas()
+        print(f"  .to_pandas() rows: {len(df)}")
+    except raincloud.MissingDependency as e:
+        print(f"  .to_pandas()     : skipped ({e})")
+
+
+def show_format_override(slug: str) -> None:
+    """Pick a format explicitly. Falls back from vortex -> parquet automatically."""
+    print(f"\n== format override for {slug!r} ==")
+    for fmt in ("vortex", "parquet"):
+        try:
+            ds = raincloud.load(slug, format=fmt)
+            print(f"  format={fmt!r:>8} -> resolved as {ds.format!r}")
+        except raincloud.FormatUnavailable as e:
+            print(f"  format={fmt!r:>8} -> unavailable ({e})")
+
+
+def show_error_handling() -> None:
+    """Every loader error is a RaincloudError subclass."""
+    print("\n== error handling ==")
+    try:
+        raincloud.load("definitely-not-a-real-slug")
+    except raincloud.UnknownSlug as e:
+        print(f"  UnknownSlug caught: {e}")
+
+    # Offline mode blocks mirror+build fallback.
+    os.environ["RAINCLOUD_OFFLINE"] = "1"
+    try:
+        # Pick a slug that's unlikely to be cached locally.
+        from raincloud._catalog import load_catalog
+        load_catalog.cache_clear()
+        ds = raincloud.load(next(iter(load_catalog().slugs())))
+        ds.path()
+    except raincloud.OfflineMiss as e:
+        print(f"  OfflineMiss caught: {e}")
+    except raincloud.RaincloudError as e:
+        # Any other RaincloudError is fine for the demo — it's the catch-all.
+        print(f"  {type(e).__name__} caught: {e}")
+    finally:
+        del os.environ["RAINCLOUD_OFFLINE"]
+        from raincloud._catalog import load_catalog
+        load_catalog.cache_clear()
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    p.add_argument("--slug", help="specific slug to load (default: catalog's first)")
+    p.add_argument("--materialize", action="store_true",
+                   help="exercise .to_arrow/.scan/.to_pandas (needs cache or mirror)")
+    args = p.parse_args(argv)
+
+    from raincloud._catalog import load_catalog
+    slugs = load_catalog().slugs()
+    slug = args.slug or slugs[0]
+    print(f"raincloud {raincloud.__version__} — {len(slugs)} slugs in catalog")
+    print(f"using slug: {slug}")
+
+    show_metadata(slug)
+    show_format_override(slug)
+    if args.materialize:
+        try:
+            show_materialization(slug)
+        except (raincloud.OfflineMiss, raincloud.BuildToolingMissing) as e:
+            print(f"\n[materialize] skipped: {type(e).__name__}: {e}")
+            print('  hint: set RAINCLOUD_MIRROR=<url>, or pip install '
+                  '"raincloud[build] @ git+https://github.com/spiraldb/raincloud"')
+    show_error_handling()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/examples/wine_quality_correlations.py b/examples/wine_quality_correlations.py
new file mode 100644
index 0000000..4ef91d6
--- /dev/null
+++ b/examples/wine_quality_correlations.py
@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Which measurable properties of a wine track its quality score?
+
+Loads the UCI wine-quality table (`uci-wine-quality`, 6,497 red + white wines
+with 11 physicochemical measurements plus a 0-10 sensory `quality` score) into
+pandas and correlates each numeric feature against `quality`, sorted. A tiny,
+instant example of the load -> DataFrame -> explore loop.
+
+Run it:
+
+    python examples/wine_quality_correlations.py
+
+Install (raincloud is not on PyPI — install from GitHub):
+
+    pip install "raincloud[build,pandas] @ git+https://github.com/spiraldb/raincloud"   # build: first-run fetch; pandas: .to_pandas()
+
+First run fetches ~80 KB from upstream (or a configured RAINCLOUD_MIRROR), then
+it's cached.
+"""
+from __future__ import annotations
+
+import sys
+
+import raincloud
+
+SLUG = "uci-wine-quality"
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        df = raincloud.load(SLUG).to_pandas()
+    except raincloud.MissingDependency as e:
+        print(f"this example needs pandas: {e}\n"
+              '  pip install "raincloud[pandas] @ git+https://github.com/spiraldb/raincloud"')
+        return 1
+    except raincloud.RaincloudError as e:
+        print(f"could not load {SLUG}: {type(e).__name__}: {e}")
+        print('  hint: pip install "raincloud[build] @ git+https://github.com/spiraldb/raincloud" '
+              "(first run fetches ~80 KB) or set RAINCLOUD_MIRROR=<url>")
+        return 1
+
+    # numeric_only drops the non-numeric `color` (red/white) column.
+    corr = df.corr(numeric_only=True)["quality"].drop("quality").sort_values()
+
+    print(f"{SLUG}: {len(df):,} wines (red + white)\n")
+    print("correlation of each feature with the quality score:")
+    for feat, c in corr.items():
+        print(f"  {feat:<22}{c:+.3f}")
+    print(f"\nstrongest positive: {corr.index[-1]} ({corr.iloc[-1]:+.3f})")
+    print(f"strongest negative: {corr.index[0]} ({corr.iloc[0]:+.3f})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+
+# --- Sample output (captured 2026-05-29 against live upstream; exact numbers
+#     drift as the dataset is revised) ---
+#
+#   uci-wine-quality: 6,497 wines (red + white)
+#
+#   correlation of each feature with the quality score:
+#     density               -0.306
+#     volatile_acidity      -0.266
+#     chlorides             -0.201
+#     fixed_acidity         -0.077
+#     total_sulfur_dioxide  -0.041
+#     residual_sugar        -0.037
+#     ph                    +0.020
+#     sulphates             +0.038
+#     free_sulfur_dioxide   +0.055
+#     citric_acid           +0.086
+#     alcohol               +0.444
+#
+#   strongest positive: alcohol (+0.444)
+#   strongest negative: density (-0.306)
diff --git a/pyproject.toml b/pyproject.toml
index 42fb770..96e687e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "raincloud"
-version = "0.1.5"
+version = "0.2.0"
 description = "Client-reproducible pipeline for building a curated catalog of public datasets as Parquet + Vortex files."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -9,44 +9,31 @@ license = "Apache-2.0"
 license-files = ["LICENSE"]
 
 dependencies = [
-    # Core Arrow / Parquet handling — used by every stage.
     "pyarrow>=23.0",
     "numpy>=2.0",
-    "duckdb>=1.5.0",            # VARIANT type requires storage_compatibility_version ≥ v1.5.0
-    # Vortex conversion. The package was renamed from `vortex-array` to
-    # `vortex-data` in the 0.32 → 0.69 move and the API isn't yet stable
-    # across minor versions, so we cap at the next minor. Loosen once the
-    # public API (`vxio.write(pa_table, path)` is what we depend on) is
-    # backed by a stability guarantee.
     "vortex-data>=0.69.0,<0.70.0",
-    # Streaming decompression formats surfaced in specific upstreams.
-    "zstandard>=0.25.0",        # lichess .pgn.zst monthly dumps
-    "py7zr>=1.1.0",             # 7z archives
-    "unlzw3>=0.2.0",            # UCI diabetes .tar.Z (Unix compress / LZW)
-    # Format-specific parsers.
-    "pandas>=2.0",              # xlsx_parse (online-retail-ii)
-    "openpyxl>=3.1",            # pandas xlsx backend
-    "pyreadstat>=1.3",          # sas_xpt_parse (CDC BRFSS .xpt)
-    "osmium>=4.3",              # osm_pbf_split (OSM Germany Geofabrik extract)
-    "jsonschema>=4.0",          # validate_manifest.py — sources.json structural checks
+    "fsspec>=2024.0",
 ]
 
 [project.optional-dependencies]
-# Only needed for fetch.type = "kaggle" (≈9 slugs). Requires ~/.kaggle/kaggle.json
-# credentials to be set up once per machine.
+s3 = ["s3fs>=2024.0"]
+http = ["aiohttp>=3.9"]
+duckdb = ["duckdb>=1.5.0"]
+pandas = ["pandas>=2.0"]
+# Full build pipeline (enables the local-build fallback). Mirrors the
+# pre-split heavy dependency set.
+build = [
+    "duckdb>=1.5.0", "zstandard>=0.25.0", "py7zr>=1.1.0", "unlzw3>=0.2.0",
+    "pandas>=2.0", "openpyxl>=3.1", "pyreadstat>=1.3", "osmium>=4.3",
+    "jsonschema>=4.0",
+]
 kaggle = ["kaggle>=2.0"]
-# Only needed for fetch.type = "huggingface" (1 slug: dbpedia-embeddings).
 huggingface = ["huggingface-hub>=0.25"]
-# Read-only TUI browser for sources.json — `python -m scripts.pipeline.browse`.
 tui = ["textual>=0.80"]
-# Convenience alias.
+dev = ["pytest>=8.0", "ruff>=0.13"]
 all = [
-    "kaggle>=2.0",
-    "huggingface-hub>=0.25",
-    "textual>=0.80",
+    "raincloud[s3,http,duckdb,pandas,build,kaggle,huggingface,tui]",
 ]
-# Test runner + linter — install with `uv sync --extra dev`.
-dev = ["pytest>=8.0", "ruff>=0.13"]
 
 [tool.ruff]
 line-length = 120
@@ -64,9 +51,20 @@ select = ["E", "F", "W", "I"]
 # better as one-liners than split across multiple lines.
 ignore = ["E501", "E701", "E702"]
 
-[tool.uv]
-# Currently consumed in-place from a clone, but the dependency posture
-# (loose lower-bound constraints, no committed uv.lock) is set up for
-# library publication. Flip `package = false` to `true` and add a build
-# backend ([build-system]) when you're ready to ship.
-package = false
+[tool.pytest.ini_options]
+markers = [
+    "wheel: builds the wheel + spins venvs (slow; gated by --run-wheel)",
+    "network: hits real upstream sources (flaky; gated by --run-network)",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["raincloud", "scripts"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"docs/v1/snapshot.json" = "raincloud/_data/snapshot.json"
+"sources.json" = "raincloud/_data/sources.json"
+"sources.schema.json" = "raincloud/_data/sources.schema.json"
diff --git a/raincloud/__init__.py b/raincloud/__init__.py
new file mode 100644
index 0000000..277ac59
--- /dev/null
+++ b/raincloud/__init__.py
@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Raincloud loader: datasets-style access to prepared Vortex/Parquet files."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import _resolve
+from ._catalog import load_catalog
+from .exceptions import (  # noqa: F401
+    ArtifactNotFound,
+    BuildFailed,
+    BuildToolingMissing,
+    ChecksumMismatch,
+    FormatUnavailable,
+    MissingDependency,
+    OfflineMiss,
+    RaincloudError,
+    UnknownSlug,
+)
+
+__version__ = "0.2.0"
+
+_DEFAULT_FORMAT = "vortex"
+
+
+class Dataset:
+    """Lazy handle to a prepared artifact. Nothing is fetched until you ask."""
+
+    def __init__(self, slug: str, fmt: str, *, mirror: str | None,
+                 offline: bool | None, entry=None):
+        self.slug = slug
+        self.format = fmt
+        self._mirror = mirror
+        self._offline = offline
+        # `entry` is passed in by load() (which already resolved it) to avoid
+        # rebuilding the Entry; direct construction falls back to a lookup.
+        self._entry = entry if entry is not None else load_catalog().entry(slug)
+
+    def __repr__(self) -> str:
+        return f"Dataset(slug={self.slug!r}, format={self.format!r})"
+
+    # --- cheap metadata (no I/O beyond the in-memory catalog) ---
+    @property
+    def num_rows(self) -> int | None:
+        return self._entry.rows
+
+    @property
+    def column_names(self) -> list[str]:
+        return self._entry.column_names
+
+    @property
+    def info(self) -> dict:
+        return self._entry.info
+
+    # --- resolution ---
+    def path(self) -> Path:
+        return self.path_for(self.format)
+
+    def path_for(self, fmt: str) -> Path:
+        # Reuse the already-resolved Entry (covers every format of this slug)
+        # so resolve() doesn't rebuild it a third time.
+        return _resolve.resolve(self.slug, fmt, mirror=self._mirror,
+                                offline=self._offline, entry=self._entry)
+
+    # --- materialization ---
+    def to_arrow(self):
+        import pyarrow.parquet as pq
+        if self.format == "parquet":
+            return pq.read_table(self.path())
+        import vortex
+        return vortex.open(str(self.path())).to_arrow().read_all()
+
+    def to_vortex(self):
+        import vortex
+        return vortex.open(str(self.path_for("vortex")))
+
+    @property
+    def schema(self):
+        import pyarrow.parquet as pq
+        if self.format == "parquet":
+            return pq.read_schema(self.path())  # footer-only, cheap
+        import vortex
+        # vortex path must open the file (heavier than the parquet footer read)
+        return vortex.open(str(self.path())).to_arrow().schema
+
+    def scan(self):
+        """Return a DuckDB relation over the dataset.
+
+        Always reads the parquet artifact (DuckDB has no native Vortex
+        reader), resolving the parquet sibling even when this handle's
+        format is vortex.
+        """
+        try:
+            import duckdb
+        except ImportError as e:
+            raise MissingDependency(
+                "scan() needs DuckDB — install `raincloud[duckdb]`"
+            ) from e
+        # Only warn about resolving the sibling when one actually exists; for a
+        # vortex-only slug, path_for("parquet") raises FormatUnavailable and the
+        # note would be misleading.
+        if self.format != "parquet" and "parquet" in self._entry.formats:
+            import sys
+            print(
+                f"[raincloud] scan() needs parquet but {self.slug} was loaded as "
+                f"{self.format!r}; resolving parquet sibling (may trigger a "
+                f"cache/mirror fetch).",
+                file=sys.stderr,
+            )
+        pq_path = self.path_for("parquet")
+        return duckdb.connect().read_parquet(str(pq_path))
+
+    def to_pandas(self):
+        try:
+            import pandas  # noqa: F401
+        except ImportError as e:
+            raise MissingDependency(
+                "to_pandas() needs pandas — install `raincloud[pandas]`"
+            ) from e
+        return self.to_arrow().to_pandas()
+
+
+def load(slug: str, *, format: str = _DEFAULT_FORMAT,
+         offline: bool | None = None, mirror: str | None = None) -> Dataset:
+    """Return a lazy Dataset handle for `slug`.
+
+    `format` defaults to "vortex" and falls back to "parquet" when the slug
+    has no vortex artifact. Raises UnknownSlug for an unknown slug and
+    FormatUnavailable when neither the requested nor a fallback format exists.
+    """
+    entry = load_catalog().entry(slug)  # raises UnknownSlug
+    fmt = format
+    if fmt not in entry.formats:
+        if fmt == "vortex" and "parquet" in entry.formats:
+            fmt = "parquet"
+        else:
+            raise FormatUnavailable(
+                f"{slug}: format {format!r} unavailable; have {sorted(entry.formats)}"
+            )
+    return Dataset(slug, fmt, mirror=mirror, offline=offline, entry=entry)
+
+
+load_dataset = load  # datasets-muscle-memory alias
+
+__all__ = [
+    "load", "load_dataset", "Dataset", "__version__",
+    "RaincloudError", "UnknownSlug", "FormatUnavailable", "ArtifactNotFound",
+    "ChecksumMismatch", "BuildToolingMissing", "BuildFailed", "OfflineMiss",
+    "MissingDependency",
+]
diff --git a/raincloud/_cache.py b/raincloud/_cache.py
new file mode 100644
index 0000000..ca90a9a
--- /dev/null
+++ b/raincloud/_cache.py
@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Local artifact cache: paths, sha256 verification, atomic adoption."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+from .exceptions import ChecksumMismatch
+
+# Format -> on-disk file extension. Identity for today's two formats, but kept
+# as a map so a future format whose extension differs from its name (e.g. a
+# "parquet-hydrated" tier -> "parquet") slots in without touching call sites.
+EXT = {"parquet": "parquet", "vortex": "vortex"}
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def cache_root() -> Path:
+    env = os.environ.get("RAINCLOUD_CACHE")
+    if env:
+        # .expanduser() for parity with _catalog._data_file and
+        # scripts.pipeline.spec._env_path so `RAINCLOUD_CACHE=~/foo` resolves
+        # to the home dir rather than a literal ./~/foo.
+        return Path(env).expanduser()
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "raincloud"
+
+
+def cache_path(slug: str, fmt: str) -> Path:
+    # schema_version is 1 today; hardcoded to match the loader's artifact_key + the pipeline's outputs/v1 layout
+    return cache_root() / "v1" / slug / fmt / f"{slug}.{EXT[fmt]}"
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):  # 1 MiB chunks
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def is_offline() -> bool:
+    return os.environ.get("RAINCLOUD_OFFLINE", "").lower() in _TRUTHY
+
+
+def strict_checksum() -> bool:
+    """True if `RAINCLOUD_STRICT_CHECKSUM` opts into hard checksum failures.
+
+    Default (off) is the 'drift is an alert' policy: a sha mismatch warns and
+    adopts. Strict (on) is for security-sensitive deployments / CI:
+
+      - A slug that HAS a pinned sha and comes from the mirror is rehashed on
+        every cache hit and on download; a mismatch raises ChecksumMismatch
+        (catches even same-size on-disk tampering of a previously-verified
+        file). This is the integrity property strict buys, at the cost of a
+        rehash per load.
+      - A slug with NO pinned sha has nothing to rehash against, so strict
+        changes nothing for it — the size/pin corruption check still applies.
+      - A LOCALLY-BUILT artifact can't be verified against the maintainer's
+        sha (a non-reproducible build legitimately differs), so it is trusted
+        via its provenance pin (origin=build + the snapshot pin it was built
+        against) rather than rebuilt every load. It is rebuilt only when that
+        snapshot pin changes (the source of truth moved) — see _resolve.
+        For full cryptographic integrity, point strict deployments at a mirror.
+    """
+    return os.environ.get("RAINCLOUD_STRICT_CHECKSUM", "").lower() in _TRUTHY
+
+
+def pin_path(dest: Path) -> Path:
+    """Sidecar recording which snapshot pin a cached file was reconciled against."""
+    return dest.parent / f".{dest.name}.pin"
+
+
+def read_pin(dest: Path) -> dict | None:
+    """Return {"snap_sha": str|None, "size": int, "origin": str|None} for
+    `dest`, or None.
+
+    Returns None when the sidecar is absent, unreadable, or contains valid JSON
+    that isn't an object (e.g. a torn/partial write leaving `42` or `[...]`) —
+    callers do `pin.get(...)`, so a non-dict must not slip through and raise
+    AttributeError inside resolve(). `origin` is absent on pins written before
+    it was added; callers must treat a missing `origin` as untrusted (None).
+    """
+    try:
+        pin = json.loads(pin_path(dest).read_text())
+    except (OSError, ValueError):
+        return None
+    return pin if isinstance(pin, dict) else None
+
+
+def _write_pin(dest: Path, snap_sha: str | None, size: int,
+               origin: str | None = None) -> None:
+    """Best-effort: record the snapshot sha (may be None), on-disk size, and
+    origin (`build` / `mirror` / None) of the bytes we just adopted.
+
+    Lets a later resolve() recognise bytes it deliberately adopted and serve
+    them from cache instead of re-fetching/rebuilding every load. This covers
+    cases the snapshot size alone can't bless: (a) already-adopted *drift*
+    (bytes diverging from a pinned sha), (b) a slug with no pinned sha at all
+    (`snap_sha=None`), and (c) a locally-built artifact whose bytes legitimately
+    differ from the maintainer's snapshot. `origin` is what lets strict mode
+    distinguish "my own local build against this snapshot pin" (trust the
+    provenance) from "mirror bytes" (must rehash). A pin is hygiene, not
+    correctness — a write failure just costs a rehash on the next load.
+    """
+    p = pin_path(dest)
+    tmp = p.parent / f"{p.name}.{os.getpid()}.tmp"
+    try:
+        tmp.write_text(json.dumps({"snap_sha": snap_sha, "size": size, "origin": origin}))
+        os.replace(tmp, p)  # atomic: a concurrent reader never sees a torn pin
+    except OSError:
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+
+
+def adopt(
+    tmp: Path,
+    dest: Path,
+    expected_sha256: str | None,
+    *,
+    strict: bool = False,
+    slug: str | None = None,
+    origin: str | None = None,
+) -> Path:
+    """Atomically move tmp -> dest, optionally checking against a known sha.
+
+    Default semantics (`strict=False`): if `expected_sha256` is set and the
+    bytes disagree, print a `[raincloud]` warning to stderr identifying the
+    slug + origin, then adopt anyway. Upstream data drifts; we want the user
+    informed, not blocked. The loader's mirror-fetch path passes
+    `strict=strict` (i.e. `strict=True` under RAINCLOUD_STRICT_CHECKSUM) to
+    turn a mismatch into a `ChecksumMismatch`; the local-build path always
+    passes `strict=False` (a client build legitimately differs from the
+    maintainer's bytes). NOTE: `scripts.pipeline.publish` does NOT go through
+    adopt — it gates uploads with its own `PublishMismatch` in `plan_uploads`.
+
+    When `expected_sha256` is None, verification is skipped — there's nothing
+    pinned to alert against.
+
+    `origin` (`build` / `mirror`) is recorded in the pin so a later strict
+    resolve can trust a locally-built artifact by provenance instead of
+    rebuilding it every load.
+
+    On any failure, the tmp file is removed and dest is left untouched.
+    """
+    try:
+        if expected_sha256 is not None:
+            actual = sha256_file(tmp)
+            if actual != expected_sha256:
+                if strict:
+                    raise ChecksumMismatch(
+                        f"{tmp}: expected sha256 {expected_sha256}, got {actual}"
+                    )
+                label = slug or dest.name
+                where = f" from {origin}" if origin else ""
+                # A local build legitimately differs from the maintainer's
+                # snapshot bytes (parquet/vortex output is rarely bit-stable
+                # across library versions), so don't cry "upstream changed".
+                why = ("locally built; differs from the maintainer's snapshot "
+                       "(expected for non-reproducible formats)"
+                       if origin == "build"
+                       else "adopting anyway — upstream may have changed")
+                print(
+                    f"[raincloud] WARN: {label}{where} sha256 drifted "
+                    f"(got {actual[:12]}…, snapshot expected {expected_sha256[:12]}…); "
+                    f"{why}.",
+                    file=sys.stderr,
+                )
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(tmp, dest)  # atomic within a filesystem
+        # Always record (snap_sha, size, origin) we just adopted so a later
+        # resolve() can serve these exact bytes from cache without a rehash —
+        # see _write_pin for the cases this covers (drift, sha-less slugs,
+        # locally-built artifacts). origin lets strict mode trust a local
+        # build by provenance instead of rebuilding it every load.
+        _write_pin(dest, expected_sha256, dest.stat().st_size, origin)
+        return dest
+    finally:
+        if tmp.exists():
+            tmp.unlink()
diff --git a/raincloud/_catalog.py b/raincloud/_catalog.py
new file mode 100644
index 0000000..e9fad3c
--- /dev/null
+++ b/raincloud/_catalog.py
@@ -0,0 +1,126 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Catalog: per-slug metadata + checksums from the shipped snapshot + manifest."""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+
+from .exceptions import UnknownSlug
+
+
+def _repo_root() -> Path:
+    # raincloud/_catalog.py -> repo root is two parents up in a source checkout.
+    return Path(__file__).resolve().parent.parent
+
+
+def _data_file(kind: str) -> Path:
+    """Locate a data file. kind in {"snapshot", "manifest"}.
+
+    Precedence: env override -> repo source copy -> wheel-packaged copy. This
+    matches `scripts.pipeline.spec._default_manifest` and the documented
+    intent ("checkout copy, else the wheel-packaged copy") so the loader and
+    the build pipeline never read different copies in an editable install.
+    """
+    env = {"snapshot": "RAINCLOUD_SNAPSHOT", "manifest": "RAINCLOUD_MANIFEST"}[kind]
+    override = os.environ.get(env)
+    if override:
+        # `.expanduser()` matches scripts.pipeline.spec._env_path so a
+        # `RAINCLOUD_MANIFEST=~/x` resolves identically for loader and build.
+        return Path(override).expanduser()
+    repo_name = {"snapshot": "docs/v1/snapshot.json", "manifest": "sources.json"}[kind]
+    repo = _repo_root() / repo_name
+    if repo.is_file():
+        return repo
+    packaged_name = {"snapshot": "snapshot.json", "manifest": "sources.json"}[kind]
+    try:
+        p = resources.files("raincloud").joinpath("_data", packaged_name)
+        if p.is_file():
+            return Path(str(p))
+    except FileNotFoundError:
+        pass
+    return repo  # let open() error point at the expected checkout path
+
+
+@dataclass(frozen=True)
+class FormatInfo:
+    sha256: str | None
+    nbytes: int | None
+
+
+@dataclass(frozen=True)
+class Entry:
+    slug: str
+    rows: int | None
+    columns: list[dict] = field(default_factory=list)
+    formats: dict[str, FormatInfo] = field(default_factory=dict)
+    info: dict = field(default_factory=dict)
+
+    @property
+    def column_names(self) -> list[str]:
+        return [c["name"] for c in self.columns]
+
+
+class Catalog:
+    def __init__(self, snapshot: dict, manifest: dict):
+        self._slugs = snapshot.get("slugs", {})
+        self._specs = {d["slug"]: d for d in manifest.get("datasets", [])}
+
+    def __contains__(self, slug: str) -> bool:
+        return slug in self._slugs or slug in self._specs
+
+    def slugs(self) -> list[str]:
+        return sorted(set(self._slugs) | set(self._specs))
+
+    def entry(self, slug: str) -> Entry:
+        if slug not in self:
+            raise UnknownSlug(slug)
+        snap = self._slugs.get(slug, {})
+        spec = self._specs.get(slug, {})
+        formats: dict[str, FormatInfo] = {}
+        # Parquet: produced for every manifest slug, OR already recorded in the
+        # snapshot (covers slugs the maintainer dropped from sources.json but
+        # still publishes — e.g. legacy/deprecated mirror entries).
+        if slug in self._specs or snap.get("parquet_bytes") is not None:
+            formats["parquet"] = FormatInfo(
+                sha256=snap.get("parquet_sha256"),
+                nbytes=snap.get("parquet_bytes"),
+            )
+        # Vortex: produced when convert.vortex is true in the manifest, OR when
+        # already present in the snapshot (same legacy-slug rationale).
+        wants_vortex = bool((spec.get("convert") or {}).get("vortex"))
+        if wants_vortex or snap.get("vortex_bytes") is not None:
+            formats["vortex"] = FormatInfo(
+                sha256=snap.get("vortex_sha256"),
+                nbytes=snap.get("vortex_bytes"),
+            )
+        lic = spec.get("license", {}) or {}
+        urls = (spec.get("fetch", {}) or {}).get("urls") or []
+        info = {
+            "short_name": spec.get("short_name"),
+            "full_name": spec.get("full_name"),
+            "description": spec.get("description"),
+            "license": lic,
+            "source_url": urls[0] if urls else lic.get("source_url"),
+        }
+        return Entry(
+            slug=slug,
+            # Prefer last_built_rows, fall back to expected_rows. Truthiness
+            # means rows==0 falls through to expected_rows — benign: no slug
+            # has last_built_rows==0.
+            rows=snap.get("last_built_rows") or snap.get("expected_rows"),
+            columns=snap.get("columns") or [],
+            formats=formats,
+            info=info,
+        )
+
+
+@lru_cache(maxsize=1)
+def load_catalog() -> Catalog:
+    snapshot = json.loads(_data_file("snapshot").read_text())
+    manifest = json.loads(_data_file("manifest").read_text())
+    return Catalog(snapshot, manifest)
diff --git a/raincloud/_resolve.py b/raincloud/_resolve.py
new file mode 100644
index 0000000..99abfe1
--- /dev/null
+++ b/raincloud/_resolve.py
@@ -0,0 +1,285 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Resolution order: local cache -> mirror -> local build."""
+from __future__ import annotations
+
+import importlib
+import os
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+
+from . import _cache, _transport
+from ._catalog import load_catalog
+from .exceptions import (
+    ArtifactNotFound,
+    BuildFailed,
+    BuildToolingMissing,
+    FormatUnavailable,
+    OfflineMiss,
+)
+
+# Stale .part files (crash / SIGKILL leftovers) older than this get swept on
+# the next resolve() attempt for the same dest. Long enough that an actively
+# running multi-hour download is safe; short enough that orphans don't pile up.
+_STALE_PART_SECONDS = 6 * 3600
+
+
+def _tmp_path(dest: Path) -> Path:
+    """Per-process-unique .part path so concurrent loaders don't race."""
+    return dest.parent / f".{dest.name}.{os.getpid()}-{uuid.uuid4().hex[:8]}.part"
+
+
+def _sweep_stale_parts(dest: Path) -> None:
+    """Best-effort cleanup of orphaned .part files in dest.parent.
+
+    Matches `.<dest.name>.*.part` siblings whose mtime is older than the
+    stale threshold. Silently ignores errors — sweep is hygiene, not
+    correctness.
+    """
+    if not dest.parent.exists():
+        return
+    cutoff = time.time() - _STALE_PART_SECONDS
+    prefix = f".{dest.name}."
+    suffix = ".part"
+    try:
+        for p in dest.parent.iterdir():
+            n = p.name
+            if not (n.startswith(prefix) and n.endswith(suffix)):
+                continue
+            try:
+                if p.stat().st_mtime < cutoff:
+                    p.unlink()
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def artifact_key(slug: str, fmt: str) -> str:
+    # v1 is hardcoded across the loader; revisit at a schema_version bump
+    return f"v1/{slug}/{fmt}/{slug}.{_cache.EXT[fmt]}"
+
+
+def _mirror_base(mirror: str | None) -> str | None:
+    base = mirror if mirror is not None else os.environ.get("RAINCLOUD_MIRROR")
+    return base.rstrip("/") if base else None
+
+
+def _build_import_error() -> BaseException | None:
+    """Return the exception that blocks importing the build pipeline, or None.
+
+    `scripts.pipeline.build` is packaged into the wheel even in a loader-only
+    install, so `find_spec` is insufficient (it only checks the file exists).
+    The module must be actually importable, which requires the `[build]` extra.
+
+    We distinguish two failure classes so resolve() can give the right hint:
+      - ImportError (incl. ModuleNotFoundError): the `[build]` extra isn't
+        installed → "install raincloud[build]".
+      - any other exception at module-init (a handler raising at top level, a
+        malformed packaged manifest): the toolchain IS present but broken →
+        surface the actual error rather than misdirecting to a pip install.
+    Either way the build is unavailable; the caller decides the message.
+    """
+    try:
+        importlib.import_module("scripts.pipeline.build")
+        return None
+    except Exception as e:  # noqa: BLE001 — both classes mean "can't build"
+        return e
+
+
+def _build_available() -> bool:
+    # Boolean convenience wrapper. resolve() uses _build_import_error() directly
+    # (it needs the exception to craft the right message); this stays as the
+    # readable predicate exercised by the test suite.
+    return _build_import_error() is None
+
+
+def resolve(
+    slug: str,
+    fmt: str,
+    *,
+    mirror: str | None = None,
+    offline: bool | None = None,
+    allow_build: bool = True,
+    entry=None,
+) -> Path:
+    # `entry` is passed by Dataset.path_for (already resolved); fall back to a
+    # lookup for direct callers. load_catalog().entry(slug) raises UnknownSlug.
+    if entry is None:
+        entry = load_catalog().entry(slug)
+    if fmt not in entry.formats:
+        raise FormatUnavailable(
+            f"{slug}: format {fmt!r} not available; have {sorted(entry.formats)}"
+        )
+    dest = _cache.cache_path(slug, fmt)
+    expected = entry.formats[fmt].sha256
+    expected_size = entry.formats[fmt].nbytes
+
+    # 1) cache hit. Several short-circuits, cheapest first, so a full sha256
+    #    over multi-GB artifacts never runs on the common load:
+    #
+    #    No pinned sha (the ~80% of the catalog with only a byte size): a pin
+    #    matching the on-disk size serves immediately (covers deliberately
+    #    adopted / locally-built bytes); else the snapshot byte size is used as
+    #    a cheap corruption check — a size mismatch with no vouching pin warns
+    #    and re-fetches rather than serving possibly-truncated bytes on trust.
+    #
+    #    With a pinned sha:
+    #      a) size matches the pin   -> treat as the blessed artifact. (A
+    #         same-size, different-content snapshot revision is the one case
+    #         this can't tell apart — an accepted, pre-existing blind spot.)
+    #      b) bytes are drift we already adopted against THIS snapshot pin
+    #         (pin sidecar records snap sha + adopted size, and the file is
+    #         still that size) -> serve it. Without this, knowingly-adopted
+    #         drift matches neither (a) nor a sha match and would be
+    #         re-fetched/rebuilt on *every* load.
+    #      c) full sha matches the pin -> serve (legacy cache w/o a pin, or a
+    #         post-revision re-download landing here).
+    #    Otherwise warn and fall through to re-fetch (genuine snapshot revision
+    #    or external corruption).
+    #
+    #    Strict mode (RAINCLOUD_STRICT_CHECKSUM) only changes behavior for a
+    #    slug that HAS a pinned sha: it rehashes such a cache hit and serves
+    #    only a sha match (so mirror drift adopted by a prior non-strict run
+    #    can't slip through) — with ONE provenance exception: a locally-built
+    #    artifact (origin=build pin) adopted against the current snapshot pin
+    #    is served without rehashing, since there's no maintainer sha a
+    #    non-reproducible build could match. Sha-less slugs have nothing to
+    #    rehash against, so strict leaves their size/pin path unchanged.
+    strict = _cache.strict_checksum()
+    if dest.exists():
+        cached_size = dest.stat().st_size
+        if expected is None:
+            # No pinned sha (true for ~80% of the catalog today). We can't
+            # rehash, so the snapshot byte size is the cheap corruption check —
+            # but mirror semantics mirror the strict branch: only a
+            # *build-origin* pin overrides a size disagreement (a local build
+            # legitimately differs from the maintainer's size, so its provenance
+            # is the trust signal). A mirror/pin-less artifact must still match
+            # the snapshot size, so a snapshot revision that ships a new
+            # (still-sha-less) size is detected as stale and re-fetched instead
+            # of serving the old cache forever.
+            pin = _cache.read_pin(dest)
+            if (pin is not None and pin.get("origin") == "build"
+                    and pin.get("size") == cached_size):
+                return dest
+            if expected_size is None or cached_size == expected_size:
+                return dest
+            print(
+                f"[raincloud] WARN: cached {slug}/{fmt} size {cached_size} != snapshot "
+                f"{expected_size} and no local-build pin vouches for it; re-fetching.",
+                file=sys.stderr,
+            )
+        elif strict:
+            # Strict verifies UNTRUSTED bytes (mirror / pin-less) against the
+            # snapshot sha on every load — this catches even same-size on-disk
+            # tampering of a previously-verified file. But a locally-built
+            # artifact has no maintainer sha to match (a non-reproducible build
+            # legitimately differs), so trust its provenance pin instead of
+            # rebuilding every load: an origin=build artifact adopted against
+            # THIS snapshot pin (snap_sha == expected) and unchanged on disk
+            # (size match) is served. A snapshot revision (expected changes)
+            # makes the pin stale, so it falls through and the slug is rebuilt
+            # — the cache is trusted until the source of truth moves.
+            pin = _cache.read_pin(dest)
+            if (pin is not None and pin.get("origin") == "build"
+                    and pin.get("snap_sha") == expected
+                    and pin.get("size") == cached_size):
+                return dest
+            if _cache.sha256_file(dest) == expected:
+                return dest
+            print(
+                f"[raincloud] WARN: cached {slug}/{fmt} sha256 != snapshot (strict); "
+                f"re-fetching from mirror/build.",
+                file=sys.stderr,
+            )
+        else:
+            if expected_size is not None and cached_size == expected_size:
+                return dest
+            pin = _cache.read_pin(dest)
+            if pin is not None and pin.get("snap_sha") == expected and pin.get("size") == cached_size:
+                return dest
+            if _cache.sha256_file(dest) == expected:
+                return dest
+            print(
+                f"[raincloud] WARN: cached {slug}/{fmt} sha256 drifted from snapshot; "
+                f"re-fetching from mirror/build.",
+                file=sys.stderr,
+            )
+
+    is_offline = _cache.is_offline() if offline is None else offline
+    if is_offline:
+        raise OfflineMiss(f"{slug}/{fmt} not cached and offline mode is on")
+
+    # 2) mirror. Drifted bytes warn-and-adopt (upstream changes are not panic
+    #    cases); a clean miss falls through to local build.
+    base = _mirror_base(mirror)
+    if base is not None:
+        url = f"{base}/{artifact_key(slug, fmt)}"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        _sweep_stale_parts(dest)
+        tmp = _tmp_path(dest)
+        try:
+            _transport.fetch(url, tmp)
+            return _cache.adopt(tmp, dest, expected, strict=strict, slug=slug, origin="mirror")
+        except ArtifactNotFound:
+            pass  # fall through to build
+
+    # 3) local build. Works from a wheel install too: scripts.pipeline reads the
+    #    packaged manifest and writes under data_root() (~/.cache/raincloud) when
+    #    there's no checkout. Requires the [build] extra (see _build_import_error).
+    #    Only probe importability when we'd actually build — the import is wasted
+    #    work when allow_build is False.
+    if allow_build:
+        build_err = _build_import_error()
+        if build_err is None:
+            try:
+                subprocess.run(
+                    [sys.executable, "-m", "scripts.pipeline.build", slug], check=True
+                )
+            except (subprocess.CalledProcessError, OSError) as e:
+                # Honour the typed-error contract — callers catch RaincloudError,
+                # not raw subprocess errors. CalledProcessError = non-zero exit;
+                # OSError = couldn't even spawn (e.g. a bogus sys.executable).
+                raise BuildFailed(f"build of {slug} failed: {e}") from e
+            from scripts.pipeline.spec import output_format_dir  # type: ignore
+
+            built = output_format_dir(slug, fmt) / f"{slug}.{_cache.EXT[fmt]}"
+            if not built.exists():
+                raise ArtifactNotFound(f"build produced no {fmt} for {slug}")
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            _sweep_stale_parts(dest)
+            tmp = _tmp_path(dest)
+            try:
+                shutil.copyfile(built, tmp)
+                # adopt(strict=False, origin="build"): a client's local build
+                # legitimately differs from the maintainer's snapshot bytes
+                # (columnar output is rarely bit-reproducible), so we never
+                # strict-gate it on the maintainer's sha. `expected` is still
+                # passed so the pin records (snap_sha, size, origin=build) —
+                # that provenance lets BOTH non-strict and strict later loads
+                # serve these bytes straight from cache (no rebuild loop). The
+                # slug is rebuilt only when the snapshot pin changes (the source
+                # of truth moved) or the cached file is corrupted (size drift).
+                return _cache.adopt(tmp, dest, expected, strict=False, slug=slug, origin="build")
+            except Exception:
+                if tmp.exists():
+                    tmp.unlink()
+                raise
+        if not isinstance(build_err, ImportError):
+            # The [build] subtree is present but failed to import for a
+            # non-import reason (broken handler, malformed manifest). Surface
+            # the real cause rather than telling the user to `pip install`
+            # something they already have.
+            raise BuildToolingMissing(
+                f"{slug}/{fmt} not cached and not in mirror; the build pipeline is "
+                f"installed but failed to import: {type(build_err).__name__}: {build_err}"
+            )
+    raise BuildToolingMissing(
+        f"{slug}/{fmt} not cached and not in mirror; "
+        f"install `raincloud[build]` or set RAINCLOUD_MIRROR"
+    )
diff --git a/raincloud/_transport.py b/raincloud/_transport.py
new file mode 100644
index 0000000..30b9034
--- /dev/null
+++ b/raincloud/_transport.py
@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""fsspec transport-only: copy a remote URL to a local temp file."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import fsspec
+
+from .exceptions import ArtifactNotFound
+
+
+def fetch(url: str, dest: Path) -> None:
+    """Stream the object at `url` into `dest`. Raise ArtifactNotFound on a miss.
+
+    `url` is any fsspec-understood URL (file://, s3://, https://, ...). The
+    matching backend extra (raincloud[s3]/[http]) must be installed for
+    non-local schemes; fsspec raises ImportError otherwise, which we let
+    propagate as an actionable message.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with fsspec.open(url, "rb") as src, open(dest, "wb") as out:
+            for chunk in iter(lambda: src.read(1024 * 1024), b""):
+                out.write(chunk)
+    except FileNotFoundError as e:
+        if dest.exists():
+            dest.unlink()
+        raise ArtifactNotFound(url) from e
+    except Exception:
+        if dest.exists():
+            dest.unlink()
+        raise
diff --git a/raincloud/exceptions.py b/raincloud/exceptions.py
new file mode 100644
index 0000000..d877c4e
--- /dev/null
+++ b/raincloud/exceptions.py
@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Typed error hierarchy for the raincloud loader."""
+from __future__ import annotations
+
+
+class RaincloudError(Exception):
+    """Base class for all loader errors."""
+
+
+class UnknownSlug(RaincloudError):
+    """Requested slug is not in the catalog."""
+
+
+class FormatUnavailable(RaincloudError):
+    """Requested format is not available for this slug."""
+
+
+class ArtifactNotFound(RaincloudError):
+    """Artifact key was not present at the transport source (clean miss)."""
+
+
+class ChecksumMismatch(RaincloudError):
+    """Downloaded artifact's sha256 did not match the catalog."""
+
+
+class BuildToolingMissing(RaincloudError):
+    """Local build was needed but `raincloud[build]` is not installed (or the
+    build subtree failed to import for another reason — the message says which)."""
+
+
+class BuildFailed(RaincloudError):
+    """The local build subprocess ran but exited non-zero."""
+
+
+class OfflineMiss(RaincloudError):
+    """Offline mode is on and the artifact is not in the local cache."""
+
+
+class MissingDependency(RaincloudError):
+    """An optional convenience dependency (duckdb/pandas) is not installed."""
diff --git a/scripts/pipeline/browse.py b/scripts/pipeline/browse.py
index e6bcd34..3bbc269 100644
--- a/scripts/pipeline/browse.py
+++ b/scripts/pipeline/browse.py
@@ -65,6 +65,7 @@
     REPO_ROOT,
     iter_datasets,
     load_manifest,
+    outputs_base,
     outputs_root,
     prepared_parquet,
     prepared_parquet_hydrated,
@@ -1571,9 +1572,9 @@ def on_input_changed(self, event: Input.Changed) -> None:
             import traceback
             tb = traceback.format_exc()
             try:
-                (REPO_ROOT / "outputs" / "_browse_search_error.log").parent.mkdir(
-                    parents=True, exist_ok=True)
-                (REPO_ROOT / "outputs" / "_browse_search_error.log").write_text(tb)
+                err_log = outputs_base() / "_browse_search_error.log"
+                err_log.parent.mkdir(parents=True, exist_ok=True)
+                err_log.write_text(tb)
             except Exception:
                 pass
             try:
diff --git a/scripts/pipeline/build.py b/scripts/pipeline/build.py
index 6b7eec3..ccb545b 100644
--- a/scripts/pipeline/build.py
+++ b/scripts/pipeline/build.py
@@ -26,7 +26,7 @@
 from .extract import extract
 from .fetch import fetch
 from .parse import parse
-from .spec import REPO_ROOT, iter_datasets, load_manifest
+from .spec import display_path, iter_datasets, load_manifest, workdir_root
 from .transform import transform
 from .validate import validate
 from .write import write
@@ -45,10 +45,10 @@ def run_one(spec: dict, *, strict: bool, clean_workdir: bool = False) -> bool:
         validate(spec, written, strict=strict)
         convert(spec)  # no-op unless spec sets convert.vortex = true
         if clean_workdir:
-            wd = REPO_ROOT / "_workdir" / spec["slug"]
+            wd = workdir_root() / spec["slug"]
             if wd.exists():
                 shutil.rmtree(wd, ignore_errors=True)
-                print(f"  [clean] removed {wd.relative_to(REPO_ROOT)}")
+                print(f"  [clean] removed {display_path(wd)}")
         return True
     except NotImplementedError as e:
         print(f"  SKIP (not yet implemented): {e}")
diff --git a/scripts/pipeline/convert.py b/scripts/pipeline/convert.py
index 586a655..01d960a 100644
--- a/scripts/pipeline/convert.py
+++ b/scripts/pipeline/convert.py
@@ -54,7 +54,7 @@
 import pyarrow.parquet as pq
 
 from .spec import (
-    REPO_ROOT,
+    display_path,
     iter_datasets,
     load_manifest,
     prepared_parquet,
@@ -140,10 +140,7 @@ def batches():
 
     sz_p = parquet.stat().st_size
     sz_v = vortex_path.stat().st_size
-    try:
-        log_path = vortex_path.relative_to(REPO_ROOT)
-    except ValueError:
-        log_path = vortex_path
+    log_path = display_path(vortex_path)
     print(
         f"  wrote {log_path}  "
         f"{sz_v / 1e6:.1f} MB (ratio {sz_v / sz_p:.3f}) in {elapsed:.1f}s"
@@ -163,7 +160,7 @@ def convert(spec: dict) -> Path | None:
     out_slug = spec["slug"]
     parquet = prepared_parquet(out_slug)
     if not parquet.exists():
-        raise FileNotFoundError(f"no parquet at {parquet.relative_to(REPO_ROOT)}")
+        raise FileNotFoundError(f"no parquet at {display_path(parquet)}")
 
     return _convert_one(parquet, prepared_vortex(out_slug), out_slug)
 
diff --git a/scripts/pipeline/custom_fetch.py b/scripts/pipeline/custom_fetch.py
index b7ef119..ef07c2d 100644
--- a/scripts/pipeline/custom_fetch.py
+++ b/scripts/pipeline/custom_fetch.py
@@ -15,7 +15,7 @@
 from pathlib import Path
 
 from .fetch import slug_dir
-from .spec import REPO_ROOT, spec_field
+from .spec import display_path, spec_field
 
 
 def _http_download(url: str, dest: Path, timeout: int = 300) -> None:
@@ -68,11 +68,11 @@ def public_bi_fetch(spec: dict) -> list[Path]:
         name = url.rsplit("/", 1)[-1]
         dest = target_dir / name
         if dest.exists():
-            print(f"    [cached] {dest.relative_to(REPO_ROOT)} ({dest.stat().st_size:,} B)")
+            print(f"    [cached] {display_path(dest)} ({dest.stat().st_size:,} B)")
         else:
             print(f"    fetching {url}")
             _http_download(url, dest)
-            print(f"      -> {dest.relative_to(REPO_ROOT)} ({dest.stat().st_size:,} B)")
+            print(f"      -> {display_path(dest)} ({dest.stat().st_size:,} B)")
         out.append(dest)
 
     # 3. Download each partition's `<W>_N.table.sql`. The handler needs them
@@ -86,7 +86,7 @@ def public_bi_fetch(spec: dict) -> list[Path]:
         )
         schema_dest = target_dir / f"{workload}_{n}.table.sql"
         if schema_dest.exists():
-            print(f"    [cached] {schema_dest.relative_to(REPO_ROOT)}")
+            print(f"    [cached] {display_path(schema_dest)}")
         else:
             print(f"    fetching {schema_url}")
             try:
diff --git a/scripts/pipeline/docs.py b/scripts/pipeline/docs.py
index b677e5b..61e726e 100644
--- a/scripts/pipeline/docs.py
+++ b/scripts/pipeline/docs.py
@@ -57,6 +57,49 @@
 )
 
 
+def _sha256_or_reuse(
+    path,
+    current_size: int | None,
+    prior_size: int | None,
+    prior_sha: str | None,
+    *,
+    force: bool = False,
+) -> str | None:
+    """Reuse `prior_sha` when size is unchanged + prior sha is known; else hash.
+
+    Bytes-on-disk are content-addressed in the snapshot, so a matching size
+    is a near-perfect indicator the content is unchanged. Avoids re-streaming
+    multi-GB artifacts on every snapshot regen.
+
+    The size-only reuse has one blind spot: a rebuild that produces
+    *different content at the same byte length* keeps the stale sha, which then
+    permanently fails `publish`'s integrity gate (re-running plain `docs
+    snapshot` reuses the same stale sha). `force=True` (the `--rehash` flag)
+    recomputes every present file's sha to break out of that, while still
+    preserving the prior sha for files that are missing this run.
+    """
+    if current_size is None:
+        # File missing; preserve the prior sha so partial regens don't dash
+        # out tracked ground truth (existing fallback semantics).
+        return prior_sha
+    if not force and prior_sha is not None and prior_size == current_size:
+        return prior_sha
+    return _sha256_for_path(path)
+
+
+def _sha256_for_path(path) -> str | None:
+    """Stream a file's sha256, or None if it doesn't exist.
+
+    Delegates to the loader's single sha256 implementation so the pipeline and
+    the loader can't drift on chunk size / semantics.
+    """
+    from raincloud._cache import sha256_file
+    p = Path(path)
+    if not p.exists():
+        return None
+    return sha256_file(p)
+
+
 def _generation_header(kind: str) -> str:
     ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
     return (f"<!-- AUTO-GENERATED {kind} by scripts/pipeline/docs.py at {ts}. "
@@ -499,7 +542,7 @@ def _snapshot_for_slug(*, slug: str, parquet_path: Path, prior_snapshot: dict |
     return record
 
 
-def generate_snapshot(*, overwrite_missing: bool = False):
+def generate_snapshot(*, overwrite_missing: bool = False, rehash: bool = False):
     """Per-slug record of canonical-build state for the TUI / agents.
 
     Walks the manifest; for each slug, captures:
@@ -517,6 +560,13 @@ def generate_snapshot(*, overwrite_missing: bool = False):
     Pass overwrite_missing=True to emit null entries for slugs without
     fresh build data, regardless of any prior snapshot — use this for a
     full from-scratch regeneration.
+
+    Pass rehash=True to recompute every present file's sha256 instead of
+    reusing the prior sha on a size match. Use this (the `--rehash` flag) when
+    a rebuild changed an artifact's content without changing its byte length —
+    the only case the size-based reuse misses, which otherwise wedges
+    `publish`'s checksum gate. Unlike overwrite_missing, it preserves prior
+    data for slugs not built this run, so it's safe on a partial checkout.
     """
     import json
     manifest = load_manifest()
@@ -544,12 +594,30 @@ def generate_snapshot(*, overwrite_missing: bool = False):
         vortex = prepared_vortex(slug)
         expected_rows = spec_field(spec, "expect.rows")
         prior_for_slug = existing_slugs.get(slug)
+        prior = prior_for_slug or {}
+        parquet_bytes = parquet.stat().st_size if parquet.exists() else None
+        vortex_bytes = vortex.stat().st_size if vortex.exists() else None
         fresh: dict = {
             "expected_rows": expected_rows,
             "last_built_rows": None,        # populated below from parquet metadata
             "last_built_row_groups": None,  # populated below from parquet metadata
-            "parquet_bytes": parquet.stat().st_size if parquet.exists() else None,
-            "vortex_bytes": vortex.stat().st_size if vortex.exists() else None,
+            "parquet_bytes": parquet_bytes,
+            "vortex_bytes": vortex_bytes,
+            # Skip the multi-GB rehash when size + prior sha both unchanged —
+            # a full-catalog regen used to re-stream every artifact on every
+            # invocation (hours on Wikipedia 34 GB + JSONBench 10 GB). Falls
+            # back to full sha256 only when size disagrees with the prior
+            # snapshot or the prior had no sha recorded.
+            "parquet_sha256": _sha256_or_reuse(
+                parquet, parquet_bytes,
+                prior.get("parquet_bytes"), prior.get("parquet_sha256"),
+                force=rehash,
+            ),
+            "vortex_sha256": _sha256_or_reuse(
+                vortex, vortex_bytes,
+                prior.get("vortex_bytes"), prior.get("vortex_sha256"),
+                force=rehash,
+            ),
             "columns": None,  # populated below when schema is readable
         }
         if parquet.exists():
@@ -600,13 +668,14 @@ def generate_snapshot(*, overwrite_missing: bool = False):
 
 def main(argv):
     overwrite_missing = "--overwrite-missing" in argv
+    rehash = "--rehash" in argv
     targets = [a for a in argv if not a.startswith("-")] or ["datasets", "handlers", "snapshot"]
     if "datasets" in targets:
         generate_datasets_md()
     if "handlers" in targets:
         generate_handlers_md()
     if "snapshot" in targets:
-        generate_snapshot(overwrite_missing=overwrite_missing)
+        generate_snapshot(overwrite_missing=overwrite_missing, rehash=rehash)
     return 0
 
 
diff --git a/scripts/pipeline/extract.py b/scripts/pipeline/extract.py
index 5a49cd0..5b82777 100644
--- a/scripts/pipeline/extract.py
+++ b/scripts/pipeline/extract.py
@@ -18,13 +18,12 @@
 import zipfile
 from pathlib import Path
 
-from .spec import REPO_ROOT, spec_field
-
-WORKDIR = REPO_ROOT / "_workdir"
+from . import spec
+from .spec import display_path, spec_field
 
 
 def slug_workdir(slug: str) -> Path:
-    d = WORKDIR / slug
+    d = spec.workdir_root() / slug
     d.mkdir(parents=True, exist_ok=True)
     return d
 
@@ -54,7 +53,7 @@ def extract_zip(spec: dict, inputs: list[Path]) -> list[Path]:
     out = []
     for src in inputs:
         if not src.name.endswith(".zip"): continue
-        print(f"  unzip {src.name} -> {wd.relative_to(REPO_ROOT)}")
+        print(f"  unzip {src.name} -> {display_path(wd)}")
         with zipfile.ZipFile(src) as z:
             for name in z.namelist():
                 # Strip trailing whitespace for glob matching / disk write
@@ -84,7 +83,7 @@ def extract_tar(spec: dict, inputs: list[Path]) -> list[Path]:
     for src in inputs:
         if not (src.name.endswith(".tar") or src.name.endswith(".tar.gz") or src.name.endswith(".tgz")):
             continue
-        print(f"  untar {src.name} -> {wd.relative_to(REPO_ROOT)}")
+        print(f"  untar {src.name} -> {display_path(wd)}")
         with tarfile.open(src) as t:
             for member in t.getmembers():
                 if include and not any(fnmatch.fnmatch(member.name, pat) for pat in include): continue
@@ -115,7 +114,7 @@ def extract_7z(spec: dict, inputs: list[Path]) -> list[Path]:
     out = []
     for src in inputs:
         if not src.name.endswith(".7z"): continue
-        print(f"  un-7z {src.name} -> {wd.relative_to(REPO_ROOT)}")
+        print(f"  un-7z {src.name} -> {display_path(wd)}")
         with py7zr.SevenZipFile(src, mode="r") as z:
             names = z.getnames()
             keep = []
diff --git a/scripts/pipeline/fetch.py b/scripts/pipeline/fetch.py
index 41d2fa1..5705f21 100644
--- a/scripts/pipeline/fetch.py
+++ b/scripts/pipeline/fetch.py
@@ -22,16 +22,12 @@
 import warnings
 from pathlib import Path
 
-from .spec import REPO_ROOT, load_manifest, spec_field
-
-# Raw downloads are NOT version-scoped — the same upstream bytes are fetched
-# regardless of pipeline schema_version. Only the `prepared/` outputs are
-# versioned, because their layout / column conventions can change.
-ORIGINALS_DIR = REPO_ROOT / "outputs" / "raw_downloads"
+from . import spec
+from .spec import display_path, load_manifest, spec_field
 
 
 def slug_dir(slug: str) -> Path:
-    d = ORIGINALS_DIR / slug
+    d = spec.raw_downloads_root() / slug
     d.mkdir(parents=True, exist_ok=True)
     return d
 
@@ -75,7 +71,8 @@ def _find_sibling_cache(target_dir: Path, url: str, name: str,
     the manifest, and (when declared) still verify size + sha as defense in
     depth.
     """
-    if not ORIGINALS_DIR.exists():
+    raw_root = spec.raw_downloads_root()
+    if not raw_root.exists():
         return None
     target_slug = target_dir.name
     for ds in _cached_manifest()["datasets"]:
@@ -83,7 +80,7 @@ def _find_sibling_cache(target_dir: Path, url: str, name: str,
             continue
         if url not in spec_field(ds, "fetch.urls", []):
             continue
-        candidate = ORIGINALS_DIR / ds["slug"] / name
+        candidate = raw_root / ds["slug"] / name
         if not candidate.exists():
             continue
         if ex_bytes is not None and candidate.stat().st_size != ex_bytes:
@@ -124,12 +121,12 @@ def fetch_http(spec: dict) -> list[Path]:
         size_hint = ex_bytes if len(urls) == 1 else None
         sha_hint = ex_sha if len(urls) == 1 else None
         if _already_ok(dest, size_hint, sha_hint):
-            print(f"  [cached] {dest.relative_to(REPO_ROOT)}")
+            print(f"  [cached] {display_path(dest)}")
             out.append(dest)
             continue
         sibling = _find_sibling_cache(target_dir, url, name, size_hint, sha_hint)
         if sibling is not None:
-            print(f"  [reuse] hardlink from {sibling.relative_to(REPO_ROOT)} -> {dest.relative_to(REPO_ROOT)}")
+            print(f"  [reuse] hardlink from {display_path(sibling)} -> {display_path(dest)}")
             try:
                 os.link(sibling, dest)
             except OSError:
@@ -144,7 +141,7 @@ def fetch_http(spec: dict) -> list[Path]:
         if not verify_tls:
             print("  [warn] verify_tls=false — TLS verification disabled (integrity gated by expected_sha256)")
             urlopen_kwargs["context"] = _unverified_ssl_context()
-        print(f"  fetching {url} -> {dest.relative_to(REPO_ROOT)}")
+        print(f"  fetching {url} -> {display_path(dest)}")
         req = urllib.request.Request(url, headers={"User-Agent": "raincloud-pipeline/0.1"})
         # Per-URL retry (transient network failures common on S3 with 100-file fetches)
         for attempt in range(3):
@@ -192,12 +189,12 @@ def fetch_kaggle(spec: dict) -> list[Path]:
         ref = f"{m.group(1)}/{m.group(2)}"
         # Skip if anything already present for this slug
         if any(target_dir.iterdir()):
-            print(f"  [cached] {target_dir.relative_to(REPO_ROOT)} (non-empty)")
+            print(f"  [cached] {display_path(target_dir)} (non-empty)")
         else:
             if needs_accept:
-                print(f"  kaggle (ToS-gated): {ref} -> {target_dir.relative_to(REPO_ROOT)}")
+                print(f"  kaggle (ToS-gated): {ref} -> {display_path(target_dir)}")
             else:
-                print(f"  kaggle: {ref} -> {target_dir.relative_to(REPO_ROOT)}")
+                print(f"  kaggle: {ref} -> {display_path(target_dir)}")
             try:
                 api.dataset_download_files(ref, path=str(target_dir), quiet=False, unzip=False)
             except Exception as e:
@@ -243,7 +240,7 @@ def fetch_huggingface(spec: dict) -> list[Path]:
         if revision:
             scope += f" revision={revision}"
         gate = " (gated)" if needs_accept else ""
-        print(f"  huggingface{gate}: {repo_id} -> {target_dir.relative_to(REPO_ROOT)}{scope}")
+        print(f"  huggingface{gate}: {repo_id} -> {display_path(target_dir)}{scope}")
         try:
             snapshot_download(
                 repo_id,
diff --git a/scripts/pipeline/handlers/beijing_pm25_parse.py b/scripts/pipeline/handlers/beijing_pm25_parse.py
index cbd3c39..dd60961 100644
--- a/scripts/pipeline/handlers/beijing_pm25_parse.py
+++ b/scripts/pipeline/handlers/beijing_pm25_parse.py
@@ -28,7 +28,7 @@
 import pyarrow as pa
 import pyarrow.csv as pac
 
-from ..spec import REPO_ROOT
+from ..spec import workdir_root
 from .tighten_types import tighten_types
 
 
@@ -43,7 +43,7 @@ def beijing_pm25_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]],
         )
     inner_zip_path = inner_zips[0]
 
-    work = REPO_ROOT / "_workdir" / spec["slug"] / "inner"
+    work = workdir_root() / spec["slug"] / "inner"
     work.mkdir(parents=True, exist_ok=True)
     with zipfile.ZipFile(inner_zip_path) as z:
         z.extractall(work)
diff --git a/scripts/pipeline/handlers/factbook_variant_parse.py b/scripts/pipeline/handlers/factbook_variant_parse.py
index 1e616aa..5c91246 100644
--- a/scripts/pipeline/handlers/factbook_variant_parse.py
+++ b/scripts/pipeline/handlers/factbook_variant_parse.py
@@ -44,7 +44,7 @@ def factbook_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]
     print(f"  {len(records)} country records across "
           f"{len({r for r, _, _ in records})} regions")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(spec, "write.output", f"{spec['slug']}.parquet")
     out_path.parent.mkdir(parents=True, exist_ok=True)
     compression = spec_field(spec, "write.compression", "zstd")
@@ -65,5 +65,5 @@ def factbook_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]
         f"COPY facts TO '{out_path}' (FORMAT PARQUET, COMPRESSION '{compression}')"
     )
     con.close()
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}")
+    print(f"  wrote {display_path(out_path)}")
     return []
diff --git a/scripts/pipeline/handlers/ghcn_daily_parse.py b/scripts/pipeline/handlers/ghcn_daily_parse.py
index 0bf2e5d..d330985 100644
--- a/scripts/pipeline/handlers/ghcn_daily_parse.py
+++ b/scripts/pipeline/handlers/ghcn_daily_parse.py
@@ -102,7 +102,7 @@ def ghcn_daily_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]], *,
     """
     import pyarrow.parquet as pq
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
 
     if not parsed:
         raise ValueError("ghcn_daily_parse: no input files")
@@ -164,5 +164,5 @@ def _flush(writer):
     finally:
         writer.close()
 
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}  rows={total:,} stations≈{file_count}")
+    print(f"  wrote {display_path(out_path)}  rows={total:,} stations≈{file_count}")
     return []
diff --git a/scripts/pipeline/handlers/har_parse.py b/scripts/pipeline/handlers/har_parse.py
index 558ee3a..4afeea5 100644
--- a/scripts/pipeline/handlers/har_parse.py
+++ b/scripts/pipeline/handlers/har_parse.py
@@ -38,7 +38,7 @@
 
 import pyarrow as pa
 
-from ..spec import REPO_ROOT
+from ..spec import workdir_root
 
 
 def _read_whitespace(text: str) -> list[list[str]]:
@@ -59,7 +59,7 @@ def har_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]],
     inner_zip_path = outer_inputs[0]
 
     # Unpack the inner zip to a scratch dir for file-by-file reads.
-    work = REPO_ROOT / "_workdir" / spec["slug"] / "inner"
+    work = workdir_root() / spec["slug"] / "inner"
     work.mkdir(parents=True, exist_ok=True)
     with zipfile.ZipFile(inner_zip_path) as z:
         z.extractall(work)
diff --git a/scripts/pipeline/handlers/jsonbench_variant_parse.py b/scripts/pipeline/handlers/jsonbench_variant_parse.py
index 89db516..e1ed6f8 100644
--- a/scripts/pipeline/handlers/jsonbench_variant_parse.py
+++ b/scripts/pipeline/handlers/jsonbench_variant_parse.py
@@ -48,7 +48,7 @@ def jsonbench_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None
         gz_files = gz_files[:files_limit]
     print(f"  processing {len(gz_files)} .json.gz files")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(spec, "write.output", f"{spec['slug']}.parquet")
     out_path.parent.mkdir(parents=True, exist_ok=True)
     compression = spec_field(spec, "write.compression", "zstd")
@@ -86,7 +86,7 @@ def jsonbench_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None
             print(f"    {i}/{len(gz_files)} {gz_path.name}: {n:,} rows  (running total: {total:,})")
 
         glob_pattern = str(gz_files[0].parent / "*.json.gz")
-        print(f"  writing {total:,} rows to {out_path.relative_to(REPO_ROOT) if out_path.is_relative_to(REPO_ROOT) else out_path}")
+        print(f"  writing {total:,} rows to {display_path(out_path)}")
         con.execute(f"""
             COPY (
                 SELECT CAST(line AS VARIANT) AS data
@@ -111,5 +111,5 @@ def jsonbench_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None
             p.unlink()
         tmpdir.rmdir()
 
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}")
+    print(f"  wrote {display_path(out_path)}")
     return []
diff --git a/scripts/pipeline/handlers/jsonl_as_string_parse.py b/scripts/pipeline/handlers/jsonl_as_string_parse.py
index 5b052fb..af51b49 100644
--- a/scripts/pipeline/handlers/jsonl_as_string_parse.py
+++ b/scripts/pipeline/handlers/jsonl_as_string_parse.py
@@ -34,7 +34,7 @@ def jsonl_as_string_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]]
     if not paths:
         raise ValueError("jsonl_as_string_parse: no input files")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(
         spec, "write.output", f"{spec['slug']}.parquet"
     )
@@ -64,5 +64,5 @@ def jsonl_as_string_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None]]
     finally:
         writer.close()
 
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}  rows={total:,}")
+    print(f"  wrote {display_path(out_path)}  rows={total:,}")
     return []
diff --git a/scripts/pipeline/handlers/public_bi_merge.py b/scripts/pipeline/handlers/public_bi_merge.py
index bcf54e0..5d2abf7 100644
--- a/scripts/pipeline/handlers/public_bi_merge.py
+++ b/scripts/pipeline/handlers/public_bi_merge.py
@@ -150,7 +150,7 @@ def public_bi_merge(spec: dict, parsed: list[tuple[Path, pa.Table | None]], *,
     print(f"  unified schema: {len(unified_order)} cols "
           f"(partition widths: {sorted(len(v) for v in per_partition_schema.values())})")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(
         spec, "write.output", f"{spec['slug']}.parquet")
     out_path.parent.mkdir(parents=True, exist_ok=True)
@@ -208,6 +208,6 @@ def public_bi_merge(spec: dict, parsed: list[tuple[Path, pa.Table | None]], *,
             print(f"    [{i}/{len(sorted_parts)}] {p.name} ({len(part_cols)} cols): "
                   f"{part_rows:,} rows (total {total_rows:,})", flush=True)
 
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}  "
+    print(f"  wrote {display_path(out_path)}  "
           f"({total_rows:,} rows across {len(sorted_parts)} partitions)")
     return []
diff --git a/scripts/pipeline/handlers/stack_exchange_split.py b/scripts/pipeline/handlers/stack_exchange_split.py
index 2620022..fe71ee4 100644
--- a/scripts/pipeline/handlers/stack_exchange_split.py
+++ b/scripts/pipeline/handlers/stack_exchange_split.py
@@ -112,7 +112,7 @@ def stack_exchange_split(spec: dict, parsed: list[tuple[Path, pa.Table | None]],
     path = xml_files[0]
     print(f"  streaming {path.name} ({path.stat().st_size / 1e9:.2f} GB on disk, table={table})")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(spec, "write.output", f"{spec['slug']}.parquet")
     out_path.parent.mkdir(parents=True, exist_ok=True)
     compression = spec_field(spec, "write.compression", "zstd")
@@ -152,5 +152,5 @@ def flush(writer):
                 if count % (batch_size * 10) == 0:
                     print(f"    {count:,} rows flushed")
         flush(writer)
-    print(f"    total: {count:,} rows written to {out_path.relative_to(REPO_ROOT)}")
+    print(f"    total: {count:,} rows written to {display_path(out_path)}")
     return []
diff --git a/scripts/pipeline/handlers/wikipedia_variant_parse.py b/scripts/pipeline/handlers/wikipedia_variant_parse.py
index 2a3d02b..8df5c1c 100644
--- a/scripts/pipeline/handlers/wikipedia_variant_parse.py
+++ b/scripts/pipeline/handlers/wikipedia_variant_parse.py
@@ -65,12 +65,12 @@ def wikipedia_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None
     print(f"  reading {len(jsonl_files)} JSONL files under {common_root.name}/ "
           f"({sum(p.stat().st_size for p in jsonl_files) / 1e9:.1f} GB raw)")
 
-    from ..spec import REPO_ROOT, output_format_dir, spec_field
+    from ..spec import display_path, output_format_dir, spec_field, workdir_root
     out_path = output_format_dir(spec["slug"], "parquet") / spec_field(spec, "write.output", f"{spec['slug']}.parquet")
     out_path.parent.mkdir(parents=True, exist_ok=True)
     compression = spec_field(spec, "write.compression", "zstd")
 
-    workdir = REPO_ROOT / "_workdir" / spec["slug"]
+    workdir = workdir_root() / spec["slug"]
     workdir.mkdir(parents=True, exist_ok=True)
     db_path = workdir / "variant.db"
     if db_path.exists(): db_path.unlink()
@@ -112,5 +112,5 @@ def wikipedia_variant_parse(spec: dict, parsed: list[tuple[Path, pa.Table | None
             if d.is_dir() and d.name.endswith(".tmp"):
                 shutil.rmtree(d, ignore_errors=True)
 
-    print(f"  wrote {out_path.relative_to(REPO_ROOT)}")
+    print(f"  wrote {display_path(out_path)}")
     return []
diff --git a/scripts/pipeline/hydrate.py b/scripts/pipeline/hydrate.py
index 195956b..a833a9a 100644
--- a/scripts/pipeline/hydrate.py
+++ b/scripts/pipeline/hydrate.py
@@ -106,12 +106,13 @@
 import pyarrow.parquet as pq
 
 from .spec import (
-    REPO_ROOT,
+    display_path,
     iter_datasets,
     load_manifest,
     prepared_parquet,
     prepared_parquet_hydrated,
     spec_field,
+    workdir_root,
 )
 
 # ---------- Provenance schema ----------
@@ -209,13 +210,14 @@ def load_blocklist(paths: list[Path]) -> set[str]:
 
 
 _URLHAUS_URL = "https://urlhaus.abuse.ch/downloads/hostfile/"
-_URLHAUS_CACHE = REPO_ROOT / "_workdir" / ".urlhaus.hostfile"
 _URLHAUS_TTL_S = 24 * 3600
 
 
 def fetch_urlhaus_hostlist(*, force: bool = False) -> set[str]:
     """Download (or cache) the abuse.ch URLhaus hostfile. 24h TTL."""
-    cache = _URLHAUS_CACHE
+    # Resolved lazily so $RAINCLOUD_WORKDIR / $RAINCLOUD_HOME are honored and
+    # a wheel install doesn't try to write under site-packages at import time.
+    cache = workdir_root() / ".urlhaus.hostfile"
     cache.parent.mkdir(parents=True, exist_ok=True)
     if cache.exists() and not force:
         age = time.time() - cache.stat().st_mtime
@@ -370,7 +372,7 @@ def hydrate(
 
     base = prepared_parquet(spec["slug"])
     if not base.exists():
-        raise FileNotFoundError(f"base parquet missing: {base.relative_to(REPO_ROOT)}")
+        raise FileNotFoundError(f"base parquet missing: {display_path(base)}")
 
     table = pq.read_table(base)
     if url_col not in table.column_names:
@@ -448,7 +450,7 @@ def _process(i: int) -> tuple[int, bytes | str | None, dict]:
     n_blocked = (counts[FilterDecision.BLOCKED_SCHEME]
                  + counts[FilterDecision.BLOCKED_BY_HOST]
                  + counts[FilterDecision.BLOCKED_BY_URLHAUS])
-    print(f"  wrote {out.relative_to(REPO_ROOT)}  "
+    print(f"  wrote {display_path(out)}  "
           f"({n_present:,} hydrated / {n_blocked:,} blocked / "
           f"{counts[FilterDecision.FETCH_ERROR]:,} errored / {n_total:,} total)")
 
diff --git a/scripts/pipeline/list_datasets.py b/scripts/pipeline/list_datasets.py
index 77062c3..e8d7e45 100644
--- a/scripts/pipeline/list_datasets.py
+++ b/scripts/pipeline/list_datasets.py
@@ -56,6 +56,7 @@
 )
 from .spec import (
     REPO_ROOT,
+    display_path,
     iter_datasets,
     load_manifest,
     outputs_root,
@@ -375,13 +376,9 @@ def _inspect(slug: str) -> int:
         if last_error is not None:
             print(f"profile.json malformed at {last_error_path}: {last_error}", file=sys.stderr)
             return 2
-        try:
-            tracked_display = tracked_path.relative_to(REPO_ROOT)
-        except ValueError:
-            tracked_display = tracked_path
         print(
             f"no profile yet for {slug} — checked {built_path} and {tracked_path}; "
-            f"run `python -m scripts.pipeline.profile {slug}` or check tracked mirror at {tracked_display}"
+            f"run `python -m scripts.pipeline.profile {slug}` or check tracked mirror at {display_path(tracked_path)}"
         )
         return 0
     print(f"rows: {profile['row_count']}   sample_rows: {profile.get('sample_rows')}")
diff --git a/scripts/pipeline/overnight_profile.py b/scripts/pipeline/overnight_profile.py
index 640b509..de8c75d 100644
--- a/scripts/pipeline/overnight_profile.py
+++ b/scripts/pipeline/overnight_profile.py
@@ -36,15 +36,35 @@
 import time
 from pathlib import Path
 
+from .spec import (
+    load_manifest,
+    outputs_base,
+    outputs_root,
+    prepared_parquet,
+    raw_downloads_root,
+    workdir_root,
+)
+
+# Maintainer-only tool: promotes into `docs/v1/profiles/` which only exists
+# in a checkout. REPO_ROOT is intentional here. Other paths route through the
+# env-aware *_root() helpers so a build redirected via $RAINCLOUD_OUTPUTS /
+# $RAINCLOUD_WORKDIR still gets cleaned up in the right tree.
 REPO_ROOT = Path(__file__).resolve().parents[2]
-LOG_PATH = REPO_ROOT / "outputs" / "_overnight.log"
-STATE_PATH = REPO_ROOT / "outputs" / "_overnight.state"
+
+
+def _log_path() -> Path:
+    return outputs_base() / "_overnight.log"
+
+
+def _state_path() -> Path:
+    return outputs_base() / "_overnight.state"
 
 
 def _log(event: dict) -> None:
-    LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    log_path = _log_path()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
     event["ts"] = time.strftime("%Y-%m-%dT%H:%M:%S")
-    with open(LOG_PATH, "a") as f:
+    with open(log_path, "a") as f:
         f.write(json.dumps(event) + "\n")
     # Also echo to stdout for tailing.
     print(json.dumps(event), flush=True)
@@ -55,7 +75,7 @@ def _profiled_slugs() -> set[str]:
 
 
 def _slug_already_built(slug: str) -> bool:
-    return (REPO_ROOT / "outputs" / "v1" / slug / "parquet" / f"{slug}.parquet").exists()
+    return prepared_parquet(slug).exists()
 
 
 def _wipe_slug(slug: str) -> None:
@@ -64,9 +84,9 @@ def _wipe_slug(slug: str) -> None:
     Doesn't touch outputs/v1/<slug>/profile.json — that's a build product
     too, but the promote step has already copied it to docs/v1/profiles/."""
     for p in [
-        REPO_ROOT / "outputs" / "raw_downloads" / slug,
-        REPO_ROOT / "outputs" / "v1" / slug,
-        REPO_ROOT / "_workdir" / slug,
+        raw_downloads_root() / slug,
+        outputs_root() / slug,
+        workdir_root() / slug,
     ]:
         if p.exists():
             try:
@@ -144,7 +164,7 @@ def main(argv: list[str] | None = None) -> int:
 
     budget = args.budget_mins * 60 if args.budget_mins else None
 
-    m = json.loads((REPO_ROOT / "sources.json").read_text())
+    m = load_manifest()
     profiled = _profiled_slugs()
     LARGE_BLOCKLIST = {
         # Known multi-hour builds — opt-in only.
@@ -183,8 +203,9 @@ def main(argv: list[str] | None = None) -> int:
         except Exception as e:
             result = {"slug": slug, "status": "driver-error", "error": str(e)}
         _log(result)
-        STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
-        STATE_PATH.write_text(json.dumps({
+        state_path = _state_path()
+        state_path.parent.mkdir(parents=True, exist_ok=True)
+        state_path.write_text(json.dumps({
             "last_slug": slug, "last_result": result, "processed": processed + 1,
         }, indent=2) + "\n")
         processed += 1
diff --git a/scripts/pipeline/publish.py b/scripts/pipeline/publish.py
new file mode 100644
index 0000000..62062e7
--- /dev/null
+++ b/scripts/pipeline/publish.py
@@ -0,0 +1,126 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Sync built artifacts to a mirror bucket, gated on snapshot sha256 match.
+
+    python -m scripts.pipeline.publish <slug>... --mirror s3://bucket/prefix
+    python -m scripts.pipeline.publish --all --mirror file:///tmp/mirror --dry-run
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import uuid
+from pathlib import Path
+
+import fsspec
+
+from raincloud._cache import sha256_file
+from raincloud._resolve import artifact_key
+
+from .spec import default_snapshot, load_manifest
+from .spec import outputs_root as _outputs_root
+
+
+class PublishMismatch(Exception):
+    """On-disk artifact sha256 disagrees with the snapshot."""
+
+
+def plan_uploads(slugs, snapshot, *, outputs_root: Path):
+    """Return [(local_path, remote_key)] for present artifacts.
+
+    `outputs_root` is the UNVERSIONED `outputs/` directory; the version segment
+    is supplied by the loader's `artifact_key` (so local path, remote key, and
+    the path the loader reads are derived from ONE source). An artifact whose
+    on-disk sha256 disagrees with the snapshot raises PublishMismatch; an
+    artifact with no snapshot checksum yet (None) is included without a gate
+    (e.g. a freshly built, not-yet-snapshotted slug).
+    """
+    slug_snaps = snapshot.get("slugs", {})
+    plan: list[tuple[Path, str]] = []
+    for slug in slugs:
+        snap = slug_snaps.get(slug, {})
+        for fmt in ("parquet", "vortex"):
+            key = artifact_key(slug, fmt)  # "v1/<slug>/<fmt>/<slug>.<ext>"
+            local = outputs_root / key
+            if not local.exists():
+                continue
+            expected = snap.get(f"{fmt}_sha256")
+            if expected is not None and sha256_file(local) != expected:
+                raise PublishMismatch(
+                    f"{slug}/{fmt}: on-disk sha256 != snapshot. Regenerate the "
+                    f"snapshot with `python -m scripts.pipeline.docs snapshot "
+                    f"--rehash` (a plain regen reuses the stale sha on a size "
+                    f"match) and re-promote docs/v1/snapshot.json before publishing."
+                )
+            plan.append((local, key))
+    return plan
+
+
+def _upload(local: Path, target: str) -> None:
+    """Stream `local` to the fsspec URL `target` via a temp key + rename.
+
+    Writing straight to the canonical key would leave a truncated object there
+    on a mid-stream crash, which the loader's mirror path would then warn-and-
+    adopt (non-strict) or adopt silently (no sha). Uploading to `<key>.<uuid>.part`
+    and renaming means the final key only ever appears complete.
+    """
+    fs, path = fsspec.core.url_to_fs(target)
+    parent = path.rsplit("/", 1)[0] if "/" in path else ""
+    if parent:
+        # url_to_fs's LocalFileSystem defaults to auto_mkdir=False; object
+        # stores treat this as a no-op. Guard so a fresh mirror prefix works.
+        try:
+            fs.makedirs(parent, exist_ok=True)
+        except (FileExistsError, NotImplementedError):
+            pass
+    tmp = f"{path}.{uuid.uuid4().hex}.part"
+    try:
+        with open(local, "rb") as src, fs.open(tmp, "wb") as out:
+            for chunk in iter(lambda: src.read(1024 * 1024), b""):
+                out.write(chunk)
+        fs.mv(tmp, path)
+    except Exception:
+        try:
+            if fs.exists(tmp):
+                fs.rm(tmp)
+        except Exception:
+            pass
+        raise
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Publish built artifacts to a mirror.")
+    ap.add_argument("slugs", nargs="*")
+    ap.add_argument("--all", action="store_true")
+    ap.add_argument("--mirror", required=True, help="fsspec base, e.g. s3://b/p")
+    ap.add_argument("--dry-run", action="store_true")
+    args = ap.parse_args(argv)
+
+    if args.all and args.slugs:
+        ap.error("pass slugs or --all, not both")
+
+    manifest = load_manifest()
+    slugs = ([d["slug"] for d in manifest["datasets"]] if args.all else args.slugs)
+    if not slugs:
+        ap.error("pass slugs or --all")
+
+    # Resolve the snapshot the same way the loader does (RAINCLOUD_SNAPSHOT ->
+    # checkout -> wheel-packaged), so publish gates against the file the loader
+    # will trust rather than a hardcoded REPO_ROOT path.
+    snapshot = json.loads(default_snapshot().read_text())
+    # _outputs_root() returns the versioned dir (outputs/v1); artifact_key
+    # re-adds the version segment, so pass the unversioned parent here.
+    plan = plan_uploads(slugs, snapshot, outputs_root=_outputs_root(manifest).parent)
+    base = args.mirror.rstrip("/")
+    for local, key in plan:
+        target = f"{base}/{key}"
+        print(("DRY " if args.dry_run else "") + f"{local} -> {target}")
+        if not args.dry_run:
+            _upload(local, target)
+    print(f"{'planned' if args.dry_run else 'published'} {len(plan)} artifact(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/pipeline/spec.py b/scripts/pipeline/spec.py
index fe32026..630c720 100644
--- a/scripts/pipeline/spec.py
+++ b/scripts/pipeline/spec.py
@@ -14,11 +14,74 @@
 from typing import Any, Iterator
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-DEFAULT_MANIFEST = REPO_ROOT / "sources.json"
+
+
+def _env_path(name: str) -> Path | None:
+    v = os.environ.get(name)
+    return Path(v).expanduser() if v else None
+
+
+def _xdg_cache() -> Path:
+    return _env_path("XDG_CACHE_HOME") or (Path.home() / ".cache")
+
+
+def data_root() -> Path:
+    """Writable root for build artifacts.
+
+    `$RAINCLOUD_HOME` if set; else the checkout (`REPO_ROOT` when it carries
+    `sources.json`) so clone builds are unchanged; else the XDG cache dir
+    (`~/.cache/raincloud`) for wheel installs. Created lazily by callers.
+    """
+    home = _env_path("RAINCLOUD_HOME")
+    if home:
+        return home
+    if (REPO_ROOT / "sources.json").exists():
+        return REPO_ROOT
+    return _xdg_cache() / "raincloud"
+
+
+def _packaged_data(name: str) -> Path | None:
+    """Path to a file shipped in the wheel under raincloud/_data/, or None."""
+    try:
+        from importlib import resources
+        p = resources.files("raincloud").joinpath("_data", name)
+        return Path(str(p)) if p.is_file() else None
+    except (ModuleNotFoundError, FileNotFoundError):
+        return None
+
+
+def _default_manifest() -> Path:
+    override = _env_path("RAINCLOUD_MANIFEST")
+    if override:
+        return override
+    repo = REPO_ROOT / "sources.json"
+    if repo.exists():
+        return repo
+    packaged = _packaged_data("sources.json")
+    if packaged is not None:
+        return packaged
+    return repo  # let open() error point at the expected checkout path
+
+
+def default_snapshot() -> Path:
+    """Locate `snapshot.json` the same way `_default_manifest` locates the
+    manifest: `$RAINCLOUD_SNAPSHOT` -> checkout `docs/v1/snapshot.json` -> the
+    wheel-packaged copy. Keeps `publish` reading the same snapshot the loader
+    (`raincloud._catalog`) trusts, instead of a hardcoded `REPO_ROOT` path."""
+    override = _env_path("RAINCLOUD_SNAPSHOT")
+    if override:
+        return override
+    repo = REPO_ROOT / "docs" / "v1" / "snapshot.json"
+    if repo.exists():
+        return repo
+    packaged = _packaged_data("snapshot.json")
+    if packaged is not None:
+        return packaged
+    return repo  # let open() error point at the expected checkout path
 
 
 def load_manifest(path: Path | None = None) -> dict:
-    p = Path(path) if path else DEFAULT_MANIFEST
+    p = Path(path) if path else _default_manifest()
     with open(p) as f:
         m = json.load(f)
     if m.get("schema_version") != 1:
@@ -26,15 +89,38 @@ def load_manifest(path: Path | None = None) -> dict:
     return m
 
 
+def outputs_base() -> Path:
+    return _env_path("RAINCLOUD_OUTPUTS") or (data_root() / "outputs")
+
+
 def outputs_root(manifest: dict | None = None) -> Path:
-    """Version-scoped output root: outputs/v{schema_version}/.
+    """Version-scoped output root: <outputs_base>/v{schema_version}/.
 
-    All pipeline stages (fetch, write, docs) read the `schema_version` field
-    of `sources.json` to resolve the layout. A manifest bump to v2 would
-    land new builds under `outputs/v2/` while v1 artefacts remain intact.
+    `outputs_base()` is `$RAINCLOUD_OUTPUTS` or `data_root()/outputs`. In a
+    checkout `data_root()==REPO_ROOT`, so this stays `<repo>/outputs/v{n}/`.
     """
     m = manifest if manifest is not None else load_manifest()
-    return REPO_ROOT / "outputs" / f"v{m['schema_version']}"
+    return outputs_base() / f"v{m['schema_version']}"
+
+
+def raw_downloads_root() -> Path:
+    """Unversioned raw-download cache: $RAINCLOUD_RAW_DOWNLOADS or
+    <outputs_base>/raw_downloads."""
+    return _env_path("RAINCLOUD_RAW_DOWNLOADS") or (outputs_base() / "raw_downloads")
+
+
+def workdir_root() -> Path:
+    """Extract/scratch root: $RAINCLOUD_WORKDIR or data_root()/_workdir."""
+    return _env_path("RAINCLOUD_WORKDIR") or (data_root() / "_workdir")
+
+
+def display_path(p) -> str:
+    """Render `p` relative to data_root() for logs; absolute if outside it."""
+    p = Path(p)
+    try:
+        return str(p.relative_to(data_root()))
+    except ValueError:
+        return str(p)
 
 
 def output_format_dir(slug: str, fmt: str = "parquet",
diff --git a/scripts/pipeline/status.py b/scripts/pipeline/status.py
index 3a81546..7966f43 100644
--- a/scripts/pipeline/status.py
+++ b/scripts/pipeline/status.py
@@ -28,20 +28,20 @@
 
 import pyarrow.parquet as pq
 
-from .fetch import ORIGINALS_DIR
 from .spec import (
-    REPO_ROOT,
     iter_datasets,
     load_manifest,
     prepared_parquet,
     prepared_vortex,
+    raw_downloads_root,
     spec_field,
+    workdir_root,
 )
 from .tighten_variant import _json_columns
 
 
 def _raw_status(spec: dict) -> dict:
-    d = ORIGINALS_DIR / spec["slug"]
+    d = raw_downloads_root() / spec["slug"]
     if not d.exists() or not any(d.iterdir()):
         return {"present": False}
     files = [p for p in d.rglob("*") if p.is_file()]
@@ -57,7 +57,7 @@ def _raw_status(spec: dict) -> dict:
 
 
 def _workdir_status(slug: str) -> dict:
-    d = REPO_ROOT / "_workdir" / slug
+    d = workdir_root() / slug
     if not d.exists() or not any(d.iterdir()):
         return {"present": False}
     return {"present": True}
diff --git a/scripts/pipeline/tighten_variant.py b/scripts/pipeline/tighten_variant.py
index 61850d1..6197c83 100644
--- a/scripts/pipeline/tighten_variant.py
+++ b/scripts/pipeline/tighten_variant.py
@@ -39,7 +39,7 @@
 
 import pyarrow.parquet as pq
 
-from .spec import REPO_ROOT, duckdb_connect, outputs_root, prepared_parquet
+from .spec import display_path, duckdb_connect, outputs_root, prepared_parquet, workdir_root
 
 
 def _json_columns(parquet: Path) -> list[str]:
@@ -95,12 +95,12 @@ def _tighten_chunked(parquet: Path, tmp: Path, replace_clause: str,
     pf = pq.ParquetFile(parquet)
     n_rg = pf.metadata.num_row_groups
 
-    workdir = REPO_ROOT / "_workdir" / parquet.parent.name
+    workdir = workdir_root() / parquet.parent.name
     workdir.mkdir(parents=True, exist_ok=True)
     db_path = workdir / "tighten_variant.db"
     if db_path.exists():
         raise RuntimeError(
-            f"{db_path.relative_to(REPO_ROOT)} already exists from a prior run. "
+            f"{display_path(db_path)} already exists from a prior run. "
             f"Move or remove it manually before retrying — this function does "
             f"not auto-delete intermediates."
         )
@@ -145,7 +145,7 @@ def tighten_one(parquet: Path, *, dry_run: bool = False, chunked: bool = False)
     json_cols = _json_columns(parquet)
     if not json_cols:
         return False
-    rel = parquet.relative_to(REPO_ROOT)
+    rel = display_path(parquet)
     mode = "chunked" if chunked else "single-shot"
     print(f"  {rel}: promote {json_cols} -> VARIANT ({mode})", flush=True)
     if dry_run:
@@ -194,7 +194,7 @@ def main(argv):
         for s in args.slugs:
             p = prepared_parquet(s)
             if not p.exists():
-                print(f"  skip {s}: no parquet at {p.relative_to(REPO_ROOT)}", file=sys.stderr)
+                print(f"  skip {s}: no parquet at {display_path(p)}", file=sys.stderr)
                 continue
             candidates.append(p)
     else:
diff --git a/scripts/pipeline/validate_manifest.py b/scripts/pipeline/validate_manifest.py
index fca248a..9dad5f3 100644
--- a/scripts/pipeline/validate_manifest.py
+++ b/scripts/pipeline/validate_manifest.py
@@ -35,9 +35,15 @@
 from collections import Counter, defaultdict
 
 from .discovery import SHOWCASE_TIERS, TAG_VOCAB
-from .spec import REPO_ROOT, load_manifest
+from .spec import REPO_ROOT, _packaged_data, load_manifest
 
-SCHEMA_PATH = REPO_ROOT / "sources.schema.json"
+
+def _schema_path():
+    repo = REPO_ROOT / "sources.schema.json"
+    if repo.exists():
+        return repo
+    packaged = _packaged_data("sources.schema.json")
+    return packaged if packaged is not None else repo
 
 
 def _schema_errors(manifest: dict) -> tuple[list[str], str | None]:
@@ -50,9 +56,10 @@ def _schema_errors(manifest: dict) -> tuple[list[str], str | None]:
         import jsonschema
     except ImportError:
         return [], "jsonschema not installed (uv pip install jsonschema for full schema checks)"
-    if not SCHEMA_PATH.exists():
-        return [f"sources.schema.json missing at {SCHEMA_PATH}"], None
-    schema = json.loads(SCHEMA_PATH.read_text())
+    schema_path = _schema_path()
+    if not schema_path.exists():
+        return [f"sources.schema.json missing at {schema_path}"], None
+    schema = json.loads(schema_path.read_text())
     v = jsonschema.Draft202012Validator(schema)
     errs = []
     for e in v.iter_errors(manifest):
diff --git a/scripts/pipeline/write.py b/scripts/pipeline/write.py
index 0636cb9..d365c4e 100644
--- a/scripts/pipeline/write.py
+++ b/scripts/pipeline/write.py
@@ -8,7 +8,7 @@
 import pyarrow as pa
 import pyarrow.parquet as pq
 
-from .spec import REPO_ROOT, output_format_dir, spec_field
+from .spec import display_path, output_format_dir, spec_field
 
 
 def write(spec: dict, tables: list[tuple[str, pa.Table]]) -> list[Path]:
@@ -21,7 +21,7 @@ def write(spec: dict, tables: list[tuple[str, pa.Table]]) -> list[Path]:
         format_dir = output_format_dir(out_slug, "parquet")
         format_dir.mkdir(parents=True, exist_ok=True)
         dest = format_dir / f"{out_slug}.parquet"
-        print(f"[write] {dest.relative_to(REPO_ROOT)}  rows={table.num_rows:,}")
+        print(f"[write] {display_path(dest)}  rows={table.num_rows:,}")
         pq.write_table(
             table, dest,
             compression=compression,
diff --git a/templates/README.md b/templates/README.md
new file mode 100644
index 0000000..8f0ec00
--- /dev/null
+++ b/templates/README.md
@@ -0,0 +1,14 @@
+# templates
+
+Copy-pasteable starting points for the two most common ways to extend the
+pipeline with a new upstream source. These are authoring references, not
+runnable scripts — for runnable demos of the loader API see [`../examples/`](../examples/).
+
+| File | Purpose |
+|---|---|
+| [`minimal_spec.json`](minimal_spec.json) | Full `DatasetSpec` with every field present and placeholder values. Validates against [`../sources.schema.json`](../sources.schema.json). Use as the starting point for a new entry in `sources.json`. |
+| [`streaming_handler.py.tmpl`](streaming_handler.py.tmpl) | Template for a streaming transform handler — the pattern for datasets that don't fit in RAM. Copy into `scripts/pipeline/handlers/`, fill in the ingest loop, register in `scripts/pipeline/handlers/__init__.py`. |
+
+The playbooks in [`../SKILLS.md`](../SKILLS.md) carry shorter inline snippets; these standalone files are the full versions, so `git grep`, IDE schema validation, and copy-paste-without-markdown-quirks all work.
+
+After dropping a new entry into `sources.json`, run [`/raincloud-validate-manifest`](../.agents/skills/raincloud-validate-manifest/SKILL.md) to confirm the shape is correct before paying for a fetch.
diff --git a/examples/minimal_spec.json b/templates/minimal_spec.json
similarity index 100%
rename from examples/minimal_spec.json
rename to templates/minimal_spec.json
diff --git a/examples/streaming_handler.py.tmpl b/templates/streaming_handler.py.tmpl
similarity index 100%
rename from examples/streaming_handler.py.tmpl
rename to templates/streaming_handler.py.tmpl
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..866dad3
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Pytest configuration: opt-in flags for slow/network tests.
+
+The default `pytest` invocation skips:
+  - @pytest.mark.wheel    — builds the wheel + spins throwaway venvs (slow)
+  - @pytest.mark.network  — fetches real upstream data (flaky)
+
+Enable each via `--run-wheel` / `--run-network` on the command line.
+The flags are independent: passing one does not enable the other.
+"""
+from __future__ import annotations
+
+import pytest
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--run-wheel", action="store_true", default=False,
+        help="Run @pytest.mark.wheel tests (builds the wheel + spins venvs).",
+    )
+    parser.addoption(
+        "--run-network", action="store_true", default=False,
+        help="Run @pytest.mark.network tests (hits real upstream sources).",
+    )
+
+
+def pytest_collection_modifyitems(config, items):
+    skip_wheel = pytest.mark.skip(reason="needs --run-wheel")
+    skip_network = pytest.mark.skip(reason="needs --run-network")
+    run_wheel = config.getoption("--run-wheel")
+    run_network = config.getoption("--run-network")
+    for item in items:
+        if "wheel" in item.keywords and not run_wheel:
+            item.add_marker(skip_wheel)
+        if "network" in item.keywords and not run_network:
+            item.add_marker(skip_network)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_loader_cache(tmp_path, monkeypatch):
+    """Belt-and-suspenders hermeticity for every test.
+
+    Points the loader cache at a per-test tmp dir so no test can read or write
+    the developer's real ~/.cache/raincloud (the loader's cache_root() default),
+    and clears the catalog lru_cache around each test so a snapshot/manifest set
+    by one test never leaks into the next. Tests that need a specific cache
+    location just set RAINCLOUD_CACHE again — a later monkeypatch.setenv wins.
+    """
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "_loader_cache"))
+
+    def _clear():
+        try:
+            from raincloud._catalog import load_catalog
+            load_catalog.cache_clear()
+        except Exception:
+            pass
+
+    _clear()
+    yield
+    _clear()
diff --git a/tests/test_data_root.py b/tests/test_data_root.py
new file mode 100644
index 0000000..4aaf2db
--- /dev/null
+++ b/tests/test_data_root.py
@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import json
+from pathlib import Path
+
+from scripts.pipeline import spec
+
+
+def test_data_root_honors_raincloud_home(monkeypatch, tmp_path):
+    monkeypatch.setenv("RAINCLOUD_HOME", str(tmp_path / "home"))
+    assert spec.data_root() == tmp_path / "home"
+
+
+def test_data_root_detects_checkout(monkeypatch, tmp_path):
+    monkeypatch.delenv("RAINCLOUD_HOME", raising=False)
+    (tmp_path / "sources.json").write_text("{}")
+    monkeypatch.setattr(spec, "REPO_ROOT", tmp_path)
+    assert spec.data_root() == tmp_path
+
+
+def test_data_root_falls_back_to_xdg_cache(monkeypatch, tmp_path):
+    monkeypatch.delenv("RAINCLOUD_HOME", raising=False)
+    monkeypatch.setattr(spec, "REPO_ROOT", tmp_path / "no-manifest-here")
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+    assert spec.data_root() == tmp_path / "xdg" / "raincloud"
+
+
+def test_path_helpers_honor_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("RAINCLOUD_HOME", str(tmp_path / "h"))
+    monkeypatch.setenv("RAINCLOUD_OUTPUTS", str(tmp_path / "out"))
+    monkeypatch.setenv("RAINCLOUD_RAW_DOWNLOADS", str(tmp_path / "raw"))
+    monkeypatch.setenv("RAINCLOUD_WORKDIR", str(tmp_path / "wd"))
+    assert spec.outputs_base() == tmp_path / "out"
+    assert spec.outputs_root({"schema_version": 1}) == tmp_path / "out" / "v1"
+    assert spec.raw_downloads_root() == tmp_path / "raw"
+    assert spec.workdir_root() == tmp_path / "wd"
+
+
+def test_path_helpers_default_under_data_root(monkeypatch, tmp_path):
+    monkeypatch.setenv("RAINCLOUD_HOME", str(tmp_path))
+    for v in ("RAINCLOUD_OUTPUTS", "RAINCLOUD_RAW_DOWNLOADS", "RAINCLOUD_WORKDIR"):
+        monkeypatch.delenv(v, raising=False)
+    assert spec.outputs_base() == tmp_path / "outputs"
+    assert spec.raw_downloads_root() == tmp_path / "outputs" / "raw_downloads"
+    assert spec.workdir_root() == tmp_path / "_workdir"
+
+
+def test_display_path_relative_under_root_else_absolute(monkeypatch, tmp_path):
+    monkeypatch.setenv("RAINCLOUD_HOME", str(tmp_path))
+    inside = tmp_path / "outputs" / "v1" / "x.parquet"
+    assert spec.display_path(inside) == "outputs/v1/x.parquet"
+    outside = Path("/var/somewhere/else.bin")
+    assert spec.display_path(outside) == "/var/somewhere/else.bin"
+
+
+def test_fetch_and_extract_honor_redirected_roots(monkeypatch, tmp_path):
+    monkeypatch.setenv("RAINCLOUD_RAW_DOWNLOADS", str(tmp_path / "raw"))
+    monkeypatch.setenv("RAINCLOUD_WORKDIR", str(tmp_path / "wd"))
+    from scripts.pipeline import extract, fetch
+    assert fetch.slug_dir("demo") == tmp_path / "raw" / "demo"
+    assert extract.slug_workdir("demo") == tmp_path / "wd" / "demo"
+
+
+def test_load_manifest_packaged_fallback(monkeypatch, tmp_path):
+    # No env override and no checkout manifest -> _default_manifest() consults
+    # the packaged copy via _packaged_data(). Patch it to a tmp fixture so the
+    # fallback logic is tested without needing a built wheel.
+    fake = tmp_path / "packaged_sources.json"
+    fake.write_text(json.dumps({"schema_version": 1, "datasets": [{"slug": "x"}]}))
+    monkeypatch.delenv("RAINCLOUD_MANIFEST", raising=False)
+    monkeypatch.setattr(spec, "REPO_ROOT", tmp_path / "no-checkout")
+    monkeypatch.setattr(spec, "_packaged_data",
+                        lambda name: fake if name == "sources.json" else None)
+    m = spec.load_manifest()
+    assert m["schema_version"] == 1
+    assert m["datasets"][0]["slug"] == "x"
+
+
+def test_validate_manifest_schema_packaged_fallback(monkeypatch, tmp_path):
+    from scripts.pipeline import validate_manifest as vm
+    # No checkout schema present -> _schema_path() consults the packaged copy.
+    fake = tmp_path / "packaged_sources.schema.json"
+    fake.write_text("{}")
+    monkeypatch.setattr(vm, "REPO_ROOT", tmp_path / "no-checkout")
+    monkeypatch.setattr(vm, "_packaged_data",
+                        lambda name: fake if name == "sources.schema.json" else None)
+    assert vm._schema_path() == fake
diff --git a/tests/test_examples.py b/tests/test_examples.py
new file mode 100644
index 0000000..d038da6
--- /dev/null
+++ b/tests/test_examples.py
@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Guards for the runnable examples/ demos.
+
+- compile check: every examples/*.py must byte-compile (catches syntax/indent
+  rot on every default `pytest` run, no network).
+- end-to-end: one small example (kepler) actually runs against real upstream
+  data — load -> build -> query -> print — gated behind --run-network so the
+  default suite stays hermetic. Exercises the real code path at least once.
+"""
+from __future__ import annotations
+
+import os
+import py_compile
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+EXAMPLES_DIR = Path(__file__).resolve().parents[1] / "examples"
+
+
+def _example_files() -> list[Path]:
+    return sorted(EXAMPLES_DIR.glob("*.py"))
+
+
+def test_examples_dir_has_scripts():
+    assert _example_files(), "no example scripts found under examples/"
+
+
+@pytest.mark.parametrize("path", _example_files(), ids=lambda p: p.name)
+def test_example_compiles(path):
+    """Each example byte-compiles (syntax/indentation/obvious-name guard)."""
+    py_compile.compile(str(path), doraise=True)
+
+
+@pytest.mark.network
+def test_kepler_example_runs_end_to_end(tmp_path):
+    """Run the kepler example for real: small upstream fetch + build + query.
+
+    Non-blocking in CI (the realbuild job is continue-on-error). Proves the
+    examples' load->materialize->query path works against live data, not just
+    that the file parses.
+    """
+    script = EXAMPLES_DIR / "kepler_exoplanets.py"
+    # Scrub the developer's ambient RAINCLOUD_* (OUTPUTS / WORKDIR /
+    # STRICT_CHECKSUM / MIRROR / OFFLINE) so the run is hermetic, then set only
+    # HOME + CACHE under tmp_path. Mirrors test_wheel._clean_env.
+    env = {k: v for k, v in os.environ.items() if not k.startswith("RAINCLOUD_")}
+    env["RAINCLOUD_HOME"] = str(tmp_path / "home")
+    env["RAINCLOUD_CACHE"] = str(tmp_path / "cache")
+    cp = subprocess.run(
+        [sys.executable, str(script)],
+        capture_output=True, text=True, env=env, timeout=600,
+    )
+    assert cp.returncode == 0, f"stdout={cp.stdout!r}\nstderr={cp.stderr!r}"
+    assert "CONFIRMED" in cp.stdout, f"unexpected output: {cp.stdout!r}"
+    assert "Earth radii" in cp.stdout, f"missing smallest-planet line: {cp.stdout!r}"
diff --git a/tests/test_fetch.py b/tests/test_fetch.py
index 0c0382c..3901235 100644
--- a/tests/test_fetch.py
+++ b/tests/test_fetch.py
@@ -12,7 +12,6 @@
 from pathlib import Path
 
 from scripts.pipeline import fetch as fetch_mod
-from scripts.pipeline.spec import REPO_ROOT
 
 
 class _FakeResponse:
@@ -43,16 +42,9 @@ def fake_urlopen(req, **kwargs):
 
 
 def _patch_originals_dir(monkeypatch, tmp_path: Path) -> None:
-    # fetch.py prints dest.relative_to(REPO_ROOT), so the scratch dir must live
-    # under REPO_ROOT. Use a unique pytest-tmp subdir inside the repo's gitignored
-    # _workdir/ area so we stay hermetic without breaking the relative_to call.
-    # Fresh dir per test invocation — fetch.py treats a present file as cached.
-    import shutil
-    scratch = REPO_ROOT / "_workdir" / "test_fetch_scratch" / tmp_path.name
-    if scratch.exists():
-        shutil.rmtree(scratch)
+    scratch = tmp_path / "raw_downloads"
     scratch.mkdir(parents=True, exist_ok=True)
-    monkeypatch.setattr(fetch_mod, "ORIGINALS_DIR", scratch)
+    monkeypatch.setenv("RAINCLOUD_RAW_DOWNLOADS", str(scratch))
     # Disable the sibling-cache lookup so the test stays hermetic.
     monkeypatch.setattr(fetch_mod, "_find_sibling_cache", lambda *a, **kw: None)
 
diff --git a/tests/test_loader_cache.py b/tests/test_loader_cache.py
new file mode 100644
index 0000000..ca18a7c
--- /dev/null
+++ b/tests/test_loader_cache.py
@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+
+import pytest
+
+
+def _sha(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def test_cache_path_honors_env(tmp_path, monkeypatch):
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path))
+    from raincloud import _cache
+    p = _cache.cache_path("foo", "vortex")
+    assert p == tmp_path / "v1" / "foo" / "vortex" / "foo.vortex"
+
+
+def test_cache_root_default_branch(tmp_path, monkeypatch):
+    """With RAINCLOUD_CACHE unset, cache_root honors XDG_CACHE_HOME, else
+    ~/.cache/raincloud. (The autouse isolation fixture sets RAINCLOUD_CACHE, so
+    delete it here to actually exercise the default branch.)"""
+    from pathlib import Path
+
+    from raincloud import _cache
+    monkeypatch.delenv("RAINCLOUD_CACHE", raising=False)
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg"))
+    assert _cache.cache_root() == tmp_path / "xdg" / "raincloud"
+    monkeypatch.delenv("XDG_CACHE_HOME", raising=False)
+    assert _cache.cache_root() == Path.home() / ".cache" / "raincloud"
+
+
+def test_cache_root_expands_tilde(monkeypatch):
+    """RAINCLOUD_CACHE=~/... expands, matching _data_file / spec env handling."""
+    from pathlib import Path
+
+    from raincloud import _cache
+    monkeypatch.setenv("RAINCLOUD_CACHE", "~/rc-cache-tilde-test")
+    assert _cache.cache_root() == Path.home() / "rc-cache-tilde-test"
+
+
+def test_sha256_file(tmp_path):
+    from raincloud import _cache
+    f = tmp_path / "a.bin"; f.write_bytes(b"hello")
+    assert _cache.sha256_file(f) == _sha(b"hello")
+
+
+def test_adopt_verifies_and_renames(tmp_path):
+    from raincloud import _cache
+    src = tmp_path / "t.part"; src.write_bytes(b"data")
+    dest = tmp_path / "v1" / "s" / "parquet" / "s.parquet"
+    out = _cache.adopt(src, dest, _sha(b"data"))
+    assert out == dest and dest.read_bytes() == b"data"
+    assert not src.exists()
+
+
+def test_adopt_strict_mismatch_raises_and_cleans(tmp_path):
+    from raincloud import _cache
+    from raincloud.exceptions import ChecksumMismatch
+    src = tmp_path / "t.part"; src.write_bytes(b"data")
+    dest = tmp_path / "out.parquet"
+    with pytest.raises(ChecksumMismatch):
+        _cache.adopt(src, dest, "deadbeef", strict=True)
+    assert not src.exists() and not dest.exists()
+
+
+def test_adopt_default_mismatch_warns_but_adopts(tmp_path, capsys):
+    """Upstream content drifts; the contract is alert-the-user, don't block."""
+    from raincloud import _cache
+    src = tmp_path / "t.part"; src.write_bytes(b"new-upstream-bytes")
+    dest = tmp_path / "v1" / "demo" / "parquet" / "demo.parquet"
+    out = _cache.adopt(src, dest, "deadbeef" * 8, slug="demo", origin="mirror")
+    # The drifted bytes still landed at dest — the build did not panic.
+    assert out == dest
+    assert dest.read_bytes() == b"new-upstream-bytes"
+    assert not src.exists()
+    err = capsys.readouterr().err
+    assert "[raincloud] WARN" in err
+    assert "demo" in err and "mirror" in err and "drifted" in err
+
+
+def test_is_offline(monkeypatch):
+    from raincloud import _cache
+    monkeypatch.setenv("RAINCLOUD_OFFLINE", "1")
+    assert _cache.is_offline() is True
+    monkeypatch.setenv("RAINCLOUD_OFFLINE", "0")
+    assert _cache.is_offline() is False
+    monkeypatch.setenv("RAINCLOUD_OFFLINE", "TRUE")
+    assert _cache.is_offline() is True
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+    assert _cache.is_offline() is False
+
+
+def test_adopt_none_checksum_skips_verification(tmp_path):
+    from raincloud import _cache
+    src = tmp_path / "t.part"; src.write_bytes(b"locally-built")
+    dest = tmp_path / "v1" / "s" / "vortex" / "s.vortex"
+    # None checksum => trusted local build, no verification, must still adopt.
+    out = _cache.adopt(src, dest, None)
+    assert out == dest and dest.read_bytes() == b"locally-built"
+    assert not src.exists()
+
+
+def test_adopt_writes_pin_even_without_sha(tmp_path):
+    """A pin is written on every adopt — including sha-less artifacts — so a
+    later resolve() can serve them from cache via the size pin."""
+    from raincloud import _cache
+    src = tmp_path / "t.part"; src.write_bytes(b"sizeable")
+    dest = tmp_path / "v1" / "s" / "parquet" / "s.parquet"
+    _cache.adopt(src, dest, None)
+    pin = _cache.read_pin(dest)
+    assert pin == {"snap_sha": None, "size": len(b"sizeable"), "origin": None}
+
+
+def test_read_pin_rejects_non_dict_json(tmp_path):
+    """A torn/partial or tampered .pin holding valid-but-non-object JSON must
+    return None, not a list/int that later .get() calls would choke on."""
+    from raincloud import _cache
+    dest = tmp_path / "v1" / "s" / "parquet" / "s.parquet"
+    dest.parent.mkdir(parents=True)
+    pin = _cache.pin_path(dest)
+    for junk in ("[1, 2, 3]", "42", '"a string"', "not json at all"):
+        pin.write_text(junk)
+        assert _cache.read_pin(dest) is None
diff --git a/tests/test_loader_catalog.py b/tests/test_loader_catalog.py
new file mode 100644
index 0000000..b598430
--- /dev/null
+++ b/tests/test_loader_catalog.py
@@ -0,0 +1,205 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import json
+
+import pytest
+
+
+class _FakePackaged:
+    """Stand-in for an importlib.resources traversable pointing at a wheel
+    `raincloud/_data/<name>` copy, so the packaged-fallback branch can be
+    exercised without building a wheel."""
+    def __init__(self, path):
+        self._path = path
+
+    def is_file(self):
+        return True
+
+    def __str__(self):
+        return str(self._path)
+
+
+@pytest.mark.parametrize("kind,repo_rel,packaged_name", [
+    ("snapshot", "docs/v1/snapshot.json", "snapshot.json"),
+    ("manifest", "sources.json", "sources.json"),
+])
+def test_data_file_prefers_repo_over_packaged(tmp_path, monkeypatch, kind, repo_rel, packaged_name):
+    """Finding 5: precedence must be env -> repo checkout -> wheel-packaged,
+    matching scripts.pipeline.spec._default_manifest and the documented intent.
+    A checkout copy must win over a packaged copy when both exist."""
+    from importlib import resources
+
+    from raincloud import _catalog
+
+    env = {"snapshot": "RAINCLOUD_SNAPSHOT", "manifest": "RAINCLOUD_MANIFEST"}[kind]
+    monkeypatch.delenv(env, raising=False)
+
+    repo = tmp_path / "repo"
+    repo_file = repo / repo_rel
+    repo_file.parent.mkdir(parents=True, exist_ok=True)
+    repo_file.write_text("{}")
+    packaged_file = tmp_path / "wheel_data" / packaged_name
+    packaged_file.parent.mkdir(parents=True, exist_ok=True)
+    packaged_file.write_text("{}")
+
+    monkeypatch.setattr(_catalog, "_repo_root", lambda: repo)
+    monkeypatch.setattr(resources, "files", lambda pkg: _Joiner(packaged_file))
+
+    # Both present -> repo wins.
+    assert _catalog._data_file(kind) == repo_file
+    # Repo absent -> packaged wins (the wheel-install path).
+    repo_file.unlink()
+    assert str(_catalog._data_file(kind)) == str(packaged_file)
+
+
+class _Joiner:
+    def __init__(self, path):
+        self._path = path
+
+    def joinpath(self, *parts):
+        return _FakePackaged(self._path)
+
+
+@pytest.fixture
+def fake_catalog(tmp_path, monkeypatch):
+    snapshot = {
+        "schema_version": 1,
+        "slugs": {
+            "tiny": {
+                "expected_rows": 3, "last_built_rows": 3,
+                "parquet_bytes": 100, "vortex_bytes": 120,
+                "parquet_sha256": "aa", "vortex_sha256": "bb",
+                "columns": [{"name": "x", "type": "int64"}],
+            },
+            "pq_only": {
+                "expected_rows": 5, "last_built_rows": 5,
+                "parquet_bytes": 50, "vortex_bytes": None,
+                "parquet_sha256": "cc", "vortex_sha256": None,
+                "columns": [{"name": "y", "type": "string"}],
+            },
+        },
+    }
+    manifest = {"schema_version": 1, "datasets": [
+        {"slug": "tiny", "short_name": "Tiny", "full_name": "Tiny set",
+         "description": "a tiny set",
+         "license": {"spdx": "CC0-1.0", "source_url": "http://x",
+                     "redistribution_permitted": True, "attribution_required": False},
+         "fetch": {"urls": ["http://src/tiny.csv"]}},
+        {"slug": "pq_only", "short_name": "PQ", "full_name": "PQ only",
+         "description": "p", "license": {"spdx": "MIT", "source_url": "http://y"},
+         "fetch": {"urls": ["http://src/pq.csv"]}},
+    ]}
+    sp = tmp_path / "snapshot.json"; sp.write_text(json.dumps(snapshot))
+    mp = tmp_path / "sources.json"; mp.write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(sp))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(mp))
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    yield _catalog.load_catalog()
+    _catalog.load_catalog.cache_clear()
+
+
+def test_entry_formats_and_checksums(fake_catalog):
+    e = fake_catalog.entry("tiny")
+    assert e.rows == 3
+    assert set(e.formats) == {"parquet", "vortex"}
+    assert e.formats["vortex"].sha256 == "bb"
+    assert e.formats["parquet"].nbytes == 100
+
+
+def test_format_availability_excludes_missing(fake_catalog):
+    e = fake_catalog.entry("pq_only")
+    assert set(e.formats) == {"parquet"}  # vortex_bytes was None
+
+
+def test_info_fields(fake_catalog):
+    e = fake_catalog.entry("tiny")
+    assert e.info["short_name"] == "Tiny"
+    assert e.info["license"]["spdx"] == "CC0-1.0"
+    assert e.info["source_url"] == "http://src/tiny.csv"
+    assert e.column_names == ["x"]
+
+
+def test_unknown_slug(fake_catalog):
+    from raincloud.exceptions import UnknownSlug
+    assert "nope" not in fake_catalog
+    with pytest.raises(UnknownSlug):
+        fake_catalog.entry("nope")
+
+
+def test_entry_formats_from_manifest_only(tmp_path, monkeypatch):
+    """A manifest slug never written to the snapshot should still be loadable.
+
+    Manifest declares the slug + convert.vortex=true; snapshot has no bytes/sha
+    for it. Both parquet and vortex must be exposed with None checksums.
+    """
+    import json
+    snapshot = {"schema_version": 1, "slugs": {"new_slug": {"expected_rows": 100}}}
+    manifest = {"schema_version": 1, "datasets": [{
+        "slug": "new_slug", "short_name": "New", "license": {},
+        "fetch": {"urls": []}, "convert": {"vortex": True},
+    }]}
+    sp = tmp_path / "snapshot.json"; sp.write_text(json.dumps(snapshot))
+    mp = tmp_path / "sources.json"; mp.write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(sp))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(mp))
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    try:
+        e = _catalog.load_catalog().entry("new_slug")
+        assert set(e.formats) == {"parquet", "vortex"}
+        assert e.formats["parquet"].sha256 is None
+        assert e.formats["parquet"].nbytes is None
+        assert e.formats["vortex"].sha256 is None
+        assert e.formats["vortex"].nbytes is None
+        # rows still resolves from expected_rows in snapshot
+        assert e.rows == 100
+    finally:
+        _catalog.load_catalog.cache_clear()
+
+
+def test_entry_parquet_visible_for_snapshot_only_slug(tmp_path, monkeypatch):
+    """A slug present in the snapshot but dropped from the manifest (legacy/
+    deprecated entries still on a mirror) must still expose parquet — the
+    snapshot's recorded parquet_bytes is the loader's signal that bytes exist.
+    Mirrors the vortex_bytes fallback that already covers the same case.
+    """
+    snapshot = {"schema_version": 1, "slugs": {"legacy": {
+        "expected_rows": 7, "last_built_rows": 7,
+        "parquet_bytes": 999, "parquet_sha256": "ff" * 32,
+    }}}
+    manifest = {"schema_version": 1, "datasets": []}
+    sp = tmp_path / "snapshot.json"; sp.write_text(json.dumps(snapshot))
+    mp = tmp_path / "sources.json"; mp.write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(sp))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(mp))
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    try:
+        e = _catalog.load_catalog().entry("legacy")
+        assert "parquet" in e.formats
+        assert e.formats["parquet"].sha256 == "ff" * 32
+        assert e.formats["parquet"].nbytes == 999
+    finally:
+        _catalog.load_catalog.cache_clear()
+
+
+def test_entry_no_vortex_when_convert_vortex_false(tmp_path, monkeypatch):
+    """A manifest slug with convert.vortex=false (or absent) exposes parquet only."""
+    import json
+    snapshot = {"schema_version": 1, "slugs": {"pq_slug": {"expected_rows": 50}}}
+    manifest = {"schema_version": 1, "datasets": [{
+        "slug": "pq_slug", "short_name": "PQ", "license": {},
+        "fetch": {"urls": []}, "convert": {"vortex": False},
+    }]}
+    sp = tmp_path / "snapshot.json"; sp.write_text(json.dumps(snapshot))
+    mp = tmp_path / "sources.json"; mp.write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(sp))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(mp))
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    try:
+        e = _catalog.load_catalog().entry("pq_slug")
+        assert set(e.formats) == {"parquet"}
+    finally:
+        _catalog.load_catalog.cache_clear()
diff --git a/tests/test_loader_e2e.py b/tests/test_loader_e2e.py
new file mode 100644
index 0000000..27e0f9d
--- /dev/null
+++ b/tests/test_loader_e2e.py
@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import json
+
+import pyarrow as pa
+import vortex
+
+
+def _sha(p) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+def test_e2e_vortex_through_file_mirror(tmp_path, monkeypatch):
+    table = pa.table({"x": [10, 20, 30], "y": ["a", "b", "c"]})
+    mirror = tmp_path / "mirror"
+    vkey = mirror / "v1" / "tiny" / "vortex" / "tiny.vortex"
+    vkey.parent.mkdir(parents=True)
+    vortex.io.write(table, str(vkey))  # the public write API we depend on
+    snapshot = {
+        "schema_version": 1,
+        "slugs": {
+            "tiny": {
+                "expected_rows": 3,
+                "last_built_rows": 3,
+                "parquet_bytes": None,
+                "vortex_bytes": vkey.stat().st_size,
+                "parquet_sha256": None,
+                "vortex_sha256": _sha(vkey),
+                "columns": [
+                    {"name": "x", "type": "int64"},
+                    {"name": "y", "type": "string"},
+                ],
+            }
+        },
+    }
+    manifest = {
+        "schema_version": 1,
+        "datasets": [
+            {
+                "slug": "tiny",
+                "short_name": "Tiny",
+                "license": {"spdx": "CC0-1.0"},
+                "fetch": {"urls": []},
+            }
+        ],
+    }
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "snapshot.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "sources.json"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{mirror}")
+
+    import raincloud
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    try:
+        ds = raincloud.load("tiny")              # default vortex, available
+        assert ds.format == "vortex"
+        tbl = ds.to_arrow()
+        assert tbl.num_rows == 3
+        assert tbl.column_names == ["x", "y"]
+        assert tbl["x"].to_pylist() == [10, 20, 30]   # roundtrip proof, not just shape
+        assert tbl["y"].to_pylist() == ["a", "b", "c"]
+        assert ds.path().exists()                 # cached after first resolve
+    finally:
+        _catalog.load_catalog.cache_clear()
diff --git a/tests/test_loader_load.py b/tests/test_loader_load.py
new file mode 100644
index 0000000..5ba252e
--- /dev/null
+++ b/tests/test_loader_load.py
@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import json
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pytest
+
+
+def _sha(p) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+@pytest.fixture
+def loaded(tmp_path, monkeypatch):
+    table = pa.table({"x": [1, 2, 3]})
+    mirror = tmp_path / "mirror"
+    pqkey = mirror / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    pqkey.parent.mkdir(parents=True); pq.write_table(table, pqkey)
+    snapshot = {"schema_version": 1, "slugs": {"tiny": {
+        "expected_rows": 3, "last_built_rows": 3,
+        "parquet_bytes": pqkey.stat().st_size, "vortex_bytes": None,
+        "parquet_sha256": _sha(pqkey), "vortex_sha256": None,
+        "columns": [{"name": "x", "type": "int64"}]}}}
+    manifest = {"schema_version": 1, "datasets": [{"slug": "tiny",
+        "short_name": "Tiny", "full_name": "Tiny", "description": "d",
+        "license": {"spdx": "CC0-1.0"}, "fetch": {"urls": ["http://s"]}}]}
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "snapshot.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "sources.json"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{mirror}")
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    yield
+    _catalog.load_catalog.cache_clear()
+
+
+def test_load_metadata_is_cheap(loaded):
+    import raincloud
+    ds = raincloud.load("tiny", format="parquet")
+    assert ds.num_rows == 3
+    assert ds.column_names == ["x"]
+    assert ds.info["license"]["spdx"] == "CC0-1.0"
+
+
+def test_load_to_arrow(loaded):
+    import raincloud
+    ds = raincloud.load("tiny", format="parquet")
+    tbl = ds.to_arrow()
+    assert tbl.num_rows == 3 and tbl.column_names == ["x"]
+    assert ds.path().exists()
+
+
+def test_default_format_falls_back_to_parquet(loaded):
+    import raincloud
+    ds = raincloud.load("tiny")  # default vortex, but only parquet exists
+    assert ds.format == "parquet"
+
+
+def test_unknown_slug_raises(loaded):
+    import raincloud
+    from raincloud.exceptions import UnknownSlug
+    with pytest.raises(UnknownSlug):
+        raincloud.load("nope")
+
+
+def test_load_dataset_alias(loaded):
+    import raincloud
+    assert raincloud.load_dataset is raincloud.load
+
+
+def test_format_unavailable_raises(tmp_path, monkeypatch):
+    # Snapshot-only slug (not in manifest): only vortex bytes recorded, no
+    # parquet bytes. Catalog falls back to legacy snapshot-only behaviour, so
+    # requesting parquet (which is absent from the snapshot) must raise.
+    snapshot = {"schema_version": 1, "slugs": {"vx": {
+        "expected_rows": 1, "last_built_rows": 1,
+        "parquet_bytes": None, "vortex_bytes": 10,
+        "parquet_sha256": None, "vortex_sha256": "aa",
+        "columns": [{"name": "x", "type": "int64"}]}}}
+    manifest = {"schema_version": 1, "datasets": []}  # vx not in manifest
+    (tmp_path / "s.json").write_text(json.dumps(snapshot))
+    (tmp_path / "m.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "s.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "m.json"))
+    import raincloud
+    from raincloud import _catalog
+    from raincloud.exceptions import FormatUnavailable
+    _catalog.load_catalog.cache_clear()
+    try:
+        # snapshot-only slug with only vortex bytes; parquet not available
+        with pytest.raises(FormatUnavailable):
+            raincloud.load("vx", format="parquet")
+    finally:
+        _catalog.load_catalog.cache_clear()
diff --git a/tests/test_loader_materialize.py b/tests/test_loader_materialize.py
new file mode 100644
index 0000000..e5b9c05
--- /dev/null
+++ b/tests/test_loader_materialize.py
@@ -0,0 +1,95 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Default-lane coverage for the Dataset materialization API.
+
+`.scan()`, `.to_pandas()`, `.to_vortex()`, and `.schema` were previously
+exercised ONLY in the `--run-wheel`-gated subprocess tests, so a regression in
+any of them sailed through the blocking `pytest` lane. duckdb + pandas are
+installed via `--extra build` in that lane, so these run hermetically against a
+file:// mirror with no network and no wheel build.
+"""
+import hashlib
+import json
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pytest
+import vortex
+
+
+def sha256_path(p) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+@pytest.fixture
+def both_formats(tmp_path, monkeypatch):
+    """A file:// mirror carrying BOTH parquet and vortex for slug 'tiny'."""
+    table = pa.table({"x": [1, 2, 3], "y": ["a", "b", "c"]})
+    mirror = tmp_path / "mirror"
+    pqkey = mirror / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    vxkey = mirror / "v1" / "tiny" / "vortex" / "tiny.vortex"
+    pqkey.parent.mkdir(parents=True)
+    vxkey.parent.mkdir(parents=True)
+    pq.write_table(table, pqkey)
+    vortex.io.write(table, str(vxkey))
+    snapshot = {"schema_version": 1, "slugs": {"tiny": {
+        "expected_rows": 3, "last_built_rows": 3,
+        "parquet_bytes": pqkey.stat().st_size, "vortex_bytes": vxkey.stat().st_size,
+        "parquet_sha256": sha256_path(pqkey), "vortex_sha256": sha256_path(vxkey),
+        "columns": [{"name": "x", "type": "int64"}, {"name": "y", "type": "string"}]}}}
+    manifest = {"schema_version": 1, "datasets": [{
+        "slug": "tiny", "short_name": "Tiny", "license": {"spdx": "CC0-1.0"},
+        "fetch": {"urls": []}, "convert": {"vortex": True}}]}
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "snapshot.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "sources.json"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{mirror}")
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    yield
+    _catalog.load_catalog.cache_clear()
+
+
+def test_scan_returns_queryable_relation(both_formats):
+    import raincloud
+    ds = raincloud.load("tiny", format="parquet")
+    rel = ds.scan()
+    assert rel.aggregate("count(*)").fetchone()[0] == 3
+    assert rel.filter("x >= 2").aggregate("count(*)").fetchone()[0] == 2
+
+
+def test_scan_from_vortex_resolves_parquet_sibling(both_formats, capsys):
+    """A vortex-loaded handle has no native DuckDB reader, so scan() resolves
+    the parquet sibling and warns first so the implicit fetch isn't a surprise."""
+    import raincloud
+    ds = raincloud.load("tiny")  # default vortex (available here)
+    assert ds.format == "vortex"
+    rel = ds.scan()
+    assert rel.aggregate("count(*)").fetchone()[0] == 3
+    err = capsys.readouterr().err
+    assert "scan() needs parquet" in err and "tiny" in err
+
+
+def test_to_pandas_returns_dataframe(both_formats):
+    import raincloud
+    df = raincloud.load("tiny", format="parquet").to_pandas()
+    assert list(df.columns) == ["x", "y"]
+    assert len(df) == 3
+    assert df["x"].tolist() == [1, 2, 3]
+
+
+def test_to_vortex_returns_openable(both_formats):
+    import raincloud
+    vf = raincloud.load("tiny").to_vortex()
+    assert vf.to_arrow().read_all().num_rows == 3
+
+
+def test_schema_parquet_and_vortex_agree(both_formats):
+    import raincloud
+    pq_schema = raincloud.load("tiny", format="parquet").schema
+    vx_schema = raincloud.load("tiny").schema
+    assert pq_schema.names == ["x", "y"]
+    assert vx_schema.names == ["x", "y"]
diff --git a/tests/test_loader_package.py b/tests/test_loader_package.py
new file mode 100644
index 0000000..7875023
--- /dev/null
+++ b/tests/test_loader_package.py
@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+def test_import_and_version():
+    import raincloud
+    assert isinstance(raincloud.__version__, str)
+    assert raincloud.__version__  # non-empty
+    # top-level re-exports are present and wired to the hierarchy
+    from raincloud import RaincloudError, UnknownSlug
+    assert issubclass(UnknownSlug, RaincloudError)
+
+
+def test_exceptions_hierarchy():
+    from raincloud.exceptions import (
+        ArtifactNotFound,
+        BuildToolingMissing,
+        ChecksumMismatch,
+        FormatUnavailable,
+        MissingDependency,
+        OfflineMiss,
+        RaincloudError,
+        UnknownSlug,
+    )
+    for exc in (UnknownSlug, FormatUnavailable, ArtifactNotFound, ChecksumMismatch,
+                BuildToolingMissing, OfflineMiss, MissingDependency):
+        assert issubclass(exc, RaincloudError)
diff --git a/tests/test_loader_resolve.py b/tests/test_loader_resolve.py
new file mode 100644
index 0000000..381a61d
--- /dev/null
+++ b/tests/test_loader_resolve.py
@@ -0,0 +1,600 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import json
+
+import pytest
+
+
+def _sha(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+@pytest.fixture
+def env(tmp_path, monkeypatch):
+    """A file:// mirror with one artifact + a catalog describing it."""
+    payload = b"PARQUETBYTES"
+    mirror = tmp_path / "mirror"
+    key = mirror / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    key.parent.mkdir(parents=True)
+    key.write_bytes(payload)
+    snapshot = {
+        "schema_version": 1,
+        "slugs": {
+            "tiny": {
+                "expected_rows": 3,
+                "last_built_rows": 3,
+                "parquet_bytes": len(payload),
+                "vortex_bytes": None,
+                "parquet_sha256": _sha(payload),
+                "vortex_sha256": None,
+                "columns": [{"name": "x", "type": "int64"}],
+            }
+        },
+    }
+    manifest = {
+        "schema_version": 1,
+        "datasets": [
+            {"slug": "tiny", "short_name": "T", "license": {}, "fetch": {"urls": []}}
+        ],
+    }
+    sp = tmp_path / "snapshot.json"
+    sp.write_text(json.dumps(snapshot))
+    mp = tmp_path / "sources.json"
+    mp.write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(sp))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(mp))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{mirror}")
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+    from raincloud import _catalog
+
+    _catalog.load_catalog.cache_clear()
+    yield {"payload": payload, "mirror": mirror, "tmp": tmp_path}
+    _catalog.load_catalog.cache_clear()
+
+
+def test_artifact_key():
+    from raincloud import _resolve
+
+    assert _resolve.artifact_key("tiny", "parquet") == "v1/tiny/parquet/tiny.parquet"
+
+
+def test_resolve_from_mirror_then_cache(env):
+    from raincloud import _cache, _resolve
+
+    p = _resolve.resolve("tiny", "parquet")
+    assert p == _cache.cache_path("tiny", "parquet")
+    assert p.read_bytes() == env["payload"]
+    # second call is a pure cache hit (corrupt the mirror to prove no refetch)
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"X")
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == env["payload"]
+
+
+def test_cache_hit_size_match_skips_full_rehash(env, monkeypatch):
+    """Repeat loads of a cached file must NOT re-stream the full sha256.
+
+    Defeats the cache on multi-GB artifacts (the original bug). Size match
+    with a pinned snapshot size is the fast path; full rehash only runs when
+    size disagrees.
+    """
+    from raincloud import _cache, _resolve
+
+    # Prime the cache via a mirror fetch.
+    _resolve.resolve("tiny", "parquet")
+    rehash_calls = []
+    real_sha = _cache.sha256_file
+    monkeypatch.setattr(
+        _cache, "sha256_file",
+        lambda p: (rehash_calls.append(p), real_sha(p))[1],
+    )
+    # Cache hit with matching size — must NOT call sha256_file.
+    _resolve.resolve("tiny", "parquet")
+    assert rehash_calls == [], (
+        f"cache hit re-streamed sha256 ({len(rehash_calls)} calls); "
+        f"size short-circuit failed"
+    )
+
+
+def test_resolve_mirror_drift_warns_and_returns_artifact(env, capsys):
+    """Mirror bytes that diverge from the snapshot sha are not a panic case.
+
+    The user gets a warning naming the slug + origin; the artifact is still
+    adopted into the cache so downstream work proceeds. Refusing to load
+    would defeat the build over what is usually a benign upstream content
+    refresh — exactly the kind of drift the loader is supposed to absorb.
+    """
+    from raincloud import _cache, _resolve
+
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+    p = _resolve.resolve("tiny", "parquet")
+    assert p == _cache.cache_path("tiny", "parquet")
+    assert p.read_bytes() == b"drifted"
+    err = capsys.readouterr().err
+    assert "[raincloud] WARN" in err
+    assert "tiny" in err and "mirror" in err and "drifted" in err
+
+
+def test_resolve_adopted_drift_served_from_cache_no_refetch(env, monkeypatch):
+    """Once drifted bytes are adopted, later loads must serve them from cache.
+
+    Regression: the cache-hit check only accepted a cached file whose size or
+    sha matched the (stale) snapshot pin. Adopted drift matches neither, so
+    every subsequent resolve re-fetched the mirror (or, with no mirror, re-ran
+    the multi-hour build) — forever. A different-size drift (7 != 12 bytes) is
+    the worst case because it can't ride the size fast-path.
+    """
+    from raincloud import _resolve, _transport
+
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+
+    calls = []
+    real_fetch = _transport.fetch
+    monkeypatch.setattr(
+        _transport, "fetch",
+        lambda url, dest: (calls.append(url), real_fetch(url, dest))[1],
+    )
+    for _ in range(3):
+        p = _resolve.resolve("tiny", "parquet")
+    assert p.read_bytes() == b"drifted"
+    assert len(calls) == 1, (
+        f"adopted drift re-fetched {len(calls)}x across 3 resolves "
+        f"(expected 1 — the drift loop is back)"
+    )
+
+
+def test_resolve_adopted_drift_refetches_if_cache_truncated(env):
+    """The pin records the adopted size, so post-adoption corruption (a torn
+    write / truncation that changes the size) is NOT served blindly — it falls
+    through to a fresh fetch instead of trusting the pin."""
+    from raincloud import _cache, _resolve
+
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+    cached = _resolve.resolve("tiny", "parquet")
+    assert cached.read_bytes() == b"drifted"
+
+    # Corrupt the cached file (different size than the pin recorded), and have
+    # the mirror now serve good drifted bytes again.
+    cached.write_bytes(b"trunc")
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == b"drifted"
+    # And the freshly re-adopted file is once again a clean cache hit.
+    assert _cache.read_pin(cached)["size"] == len(b"drifted")
+
+
+def test_resolve_snapshot_revision_refetches_over_stale_cache(env, monkeypatch):
+    """A genuine snapshot revision must still pull the new artifact.
+
+    Distinct from adopted-drift: here the *snapshot* pins new bytes while the
+    cache holds the old ones. The loader must re-fetch, not serve stale cache.
+    """
+    from raincloud import _catalog, _resolve
+
+    # Prime cache with the original blessed artifact.
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == env["payload"]
+
+    # Publish new bytes to the mirror AND revise the snapshot pin to match.
+    new = b"REVISED-CONTENT-LONGER"
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(new)
+    snap_path = env["tmp"] / "snapshot.json"
+    snap = json.loads(snap_path.read_text())
+    snap["slugs"]["tiny"]["parquet_bytes"] = len(new)
+    snap["slugs"]["tiny"]["parquet_sha256"] = _sha(new)
+    snap_path.write_text(json.dumps(snap))
+    _catalog.load_catalog.cache_clear()
+
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == new
+
+
+def test_resolve_strict_checksum_hard_fails_on_mirror_drift(env, monkeypatch):
+    """RAINCLOUD_STRICT_CHECKSUM flips drift from warn-and-adopt to a hard
+    ChecksumMismatch — the opt-in integrity gate for security-sensitive use."""
+    from raincloud import _resolve
+    from raincloud.exceptions import ChecksumMismatch
+
+    monkeypatch.setenv("RAINCLOUD_STRICT_CHECKSUM", "1")
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+    with pytest.raises(ChecksumMismatch):
+        _resolve.resolve("tiny", "parquet")
+
+
+def test_resolve_strict_ignores_prior_drift_pin(env, monkeypatch):
+    """Drift adopted by an earlier non-strict run must NOT be served once strict
+    mode is on: the pin sidecar vouches for it, but strict rehashes and refuses."""
+    from raincloud import _cache, _resolve
+    from raincloud.exceptions import ChecksumMismatch
+
+    # Non-strict: adopt drifted bytes (writes a drift pin that vouches for them).
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"drifted")
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == b"drifted"
+    assert _cache.read_pin(_cache.cache_path("tiny", "parquet")) is not None
+
+    # Strict: the pin is ignored, the cached bytes are rehashed, and since the
+    # mirror still serves the same drift, the strict re-fetch hard-fails.
+    monkeypatch.setenv("RAINCLOUD_STRICT_CHECKSUM", "1")
+    with pytest.raises(ChecksumMismatch):
+        _resolve.resolve("tiny", "parquet")
+
+
+def test_resolve_strict_serves_matching_cache(env, monkeypatch):
+    """Strict mode still serves a cache file whose sha matches the snapshot."""
+    from raincloud import _resolve
+
+    _resolve.resolve("tiny", "parquet")  # prime cache with blessed bytes
+    monkeypatch.setenv("RAINCLOUD_STRICT_CHECKSUM", "1")
+    # corrupt the mirror to prove strict served from cache, not a re-fetch
+    (env["mirror"] / "v1" / "tiny" / "parquet" / "tiny.parquet").write_bytes(b"X")
+    assert _resolve.resolve("tiny", "parquet").read_bytes() == env["payload"]
+
+
+def test_tmp_path_is_unique_and_sweepable(tmp_path):
+    """Per-process-unique .part names so concurrent loaders don't clobber, and
+    they match the prefix/suffix _sweep_stale_parts looks for."""
+    from raincloud import _resolve
+    dest = tmp_path / "tiny.parquet"
+    a, b = _resolve._tmp_path(dest), _resolve._tmp_path(dest)
+    assert a != b
+    for p in (a, b):
+        assert p.name.startswith(".tiny.parquet.") and p.name.endswith(".part")
+
+
+def test_sweep_stale_parts_removes_only_old(tmp_path):
+    """Orphaned .part files older than the threshold are swept; an actively
+    written one (fresh mtime) and unrelated files are left alone."""
+    import os
+
+    from raincloud import _resolve
+    dest = tmp_path / "tiny.parquet"
+    stale = _resolve._tmp_path(dest); stale.write_bytes(b"x")
+    fresh = _resolve._tmp_path(dest); fresh.write_bytes(b"y")
+    unrelated = tmp_path / "keepme.parquet"; unrelated.write_bytes(b"z")
+    old = _resolve.time.time() - _resolve._STALE_PART_SECONDS - 60
+    os.utime(stale, (old, old))
+
+    _resolve._sweep_stale_parts(dest)
+    assert not stale.exists(), "stale .part should have been swept"
+    assert fresh.exists(), "fresh in-flight .part must be preserved"
+    assert unrelated.exists(), "non-.part siblings must be untouched"
+
+
+def test_resolve_build_fallback_adopts_built_artifact(env, monkeypatch):
+    """Cache miss + mirror miss + build available: resolve() shells out to the
+    build, then adopts the produced artifact into the cache. Exercised
+    hermetically (the real path is otherwise only under --run-network).
+    """
+    from raincloud import _cache, _resolve
+
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")  # mirror miss
+    monkeypatch.setenv("RAINCLOUD_OUTPUTS", str(env["tmp"] / "out"))      # build writes here
+    monkeypatch.setattr(_resolve, "_build_import_error", lambda: None)    # build available
+
+    built_calls = []
+
+    def fake_build(cmd, check):
+        built_calls.append(cmd)
+        from scripts.pipeline.spec import output_format_dir
+        d = output_format_dir("tiny", "parquet")
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "tiny.parquet").write_bytes(env["payload"])  # bytes match snapshot sha
+
+    monkeypatch.setattr(_resolve.subprocess, "run", fake_build)
+
+    p = _resolve.resolve("tiny", "parquet")
+    assert built_calls, "build subprocess was never invoked"
+    assert p == _cache.cache_path("tiny", "parquet")
+    assert p.read_bytes() == env["payload"]
+
+
+def test_resolve_build_produces_nothing_raises(env, monkeypatch):
+    """If the build runs but emits no artifact, resolve() raises ArtifactNotFound
+    rather than returning a phantom path."""
+    from raincloud import _resolve
+    from raincloud.exceptions import ArtifactNotFound
+
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")
+    monkeypatch.setenv("RAINCLOUD_OUTPUTS", str(env["tmp"] / "out"))
+    monkeypatch.setattr(_resolve, "_build_import_error", lambda: None)  # build available
+    monkeypatch.setattr(_resolve.subprocess, "run", lambda cmd, check: None)  # writes nothing
+
+    with pytest.raises(ArtifactNotFound):
+        _resolve.resolve("tiny", "parquet")
+
+
+def test_resolve_offline_miss(env, monkeypatch):
+    from raincloud import _resolve
+    from raincloud.exceptions import OfflineMiss
+
+    monkeypatch.setenv("RAINCLOUD_OFFLINE", "1")
+    with pytest.raises(OfflineMiss):
+        _resolve.resolve("tiny", "parquet")
+
+
+def test_resolve_mirror_miss_no_build(env, monkeypatch):
+    from raincloud import _resolve
+    from raincloud.exceptions import BuildToolingMissing
+
+    # point mirror somewhere empty; disable build (missing [build] extra)
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")
+    monkeypatch.setattr(_resolve, "_build_import_error",
+                        lambda: ImportError("No module named 'zstandard'"))
+    with pytest.raises(BuildToolingMissing) as ei:
+        _resolve.resolve("tiny", "parquet", allow_build=True)
+    # ImportError -> the actionable "install the extra" hint.
+    assert "raincloud[build]" in str(ei.value)
+
+
+def test_build_available_false_when_build_import_fails(monkeypatch):
+    import importlib
+
+    from raincloud import _resolve
+    real_import = importlib.import_module
+
+    def fake_import(name, *args, **kwargs):
+        if name == "scripts.pipeline.build":
+            raise ModuleNotFoundError("No module named 'zstandard'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(importlib, "import_module", fake_import)
+    assert _resolve._build_available() is False
+
+
+def test_build_available_false_when_handler_module_init_raises(monkeypatch):
+    """A non-ImportError raised at module-init in the build subtree must
+
+    flip _build_available to False, not propagate up through resolve().
+    A regression in a handler's top-level code shouldn't break the loader's
+    BuildToolingMissing fallback message.
+    """
+    import importlib
+
+    from raincloud import _resolve
+    real_import = importlib.import_module
+
+    def fake_import(name, *args, **kwargs):
+        if name == "scripts.pipeline.build":
+            raise RuntimeError("top-of-module assertion in some handler")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(importlib, "import_module", fake_import)
+    assert _resolve._build_available() is False
+
+
+def test_resolve_propagates_non_notfound_transport_error(env, monkeypatch):
+    from raincloud import _resolve, _transport
+
+    def boom(url, dest):
+        raise PermissionError("403 denied")
+
+    monkeypatch.setattr(_transport, "fetch", boom)
+    # A transport error that is NOT a clean miss must propagate, not silently
+    # fall through to a (potentially multi-hour) local build.
+    with pytest.raises(PermissionError):
+        _resolve.resolve("tiny", "parquet")
+
+
+def test_resolve_build_failure_raises_buildfailed(env, monkeypatch):
+    """A non-zero build subprocess must surface as a typed BuildFailed, not a
+    raw subprocess.CalledProcessError that escapes the RaincloudError hierarchy."""
+    import subprocess as sp
+
+    from raincloud import _resolve
+    from raincloud.exceptions import BuildFailed, RaincloudError
+
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")  # mirror miss
+    monkeypatch.setattr(_resolve, "_build_import_error", lambda: None)    # build available
+
+    def boom(cmd, check):
+        raise sp.CalledProcessError(2, cmd)
+
+    monkeypatch.setattr(_resolve.subprocess, "run", boom)
+    with pytest.raises(BuildFailed) as ei:
+        _resolve.resolve("tiny", "parquet")
+    assert isinstance(ei.value, RaincloudError)  # typed, catchable as the base
+
+
+def test_resolve_build_import_broken_says_so(env, monkeypatch):
+    """When the [build] subtree is present but fails to import for a NON-import
+    reason, the message must surface that — not misdirect to `pip install`."""
+    from raincloud import _resolve
+    from raincloud.exceptions import BuildToolingMissing
+
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")  # mirror miss
+    monkeypatch.setattr(_resolve, "_build_import_error",
+                        lambda: RuntimeError("a handler exploded at import"))
+    with pytest.raises(BuildToolingMissing) as ei:
+        _resolve.resolve("tiny", "parquet")
+    msg = str(ei.value)
+    assert "failed to import" in msg and "RuntimeError" in msg
+    assert "pip install" not in msg  # not the wrong-remediation message
+
+
+def _strict_build_env(env, monkeypatch):
+    """Wire strict mode + a mirror miss + a fake build that writes bytes which
+    deliberately differ from the snapshot sha; return the build-invocation log."""
+    from raincloud import _resolve
+
+    monkeypatch.setenv("RAINCLOUD_STRICT_CHECKSUM", "1")
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{env['tmp']}/empty")  # mirror miss
+    monkeypatch.setenv("RAINCLOUD_OUTPUTS", str(env["tmp"] / "out"))
+    monkeypatch.setattr(_resolve, "_build_import_error", lambda: None)
+    builds = []
+
+    def fake_build(cmd, check):
+        builds.append(cmd)
+        from scripts.pipeline.spec import output_format_dir
+        d = output_format_dir("tiny", "parquet")
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "tiny.parquet").write_bytes(b"locally-built-different-bytes")
+
+    monkeypatch.setattr(_resolve.subprocess, "run", fake_build)
+    return builds
+
+
+def test_resolve_strict_build_serves_from_cache_not_rebuild(env, monkeypatch):
+    """A client's local build legitimately differs from the maintainer's
+    snapshot bytes. Under strict mode the build path must NOT hard-fail with
+    ChecksumMismatch, AND a SECOND load must serve the built artifact from
+    cache via its origin=build provenance pin — not rebuild every load. (The
+    earlier single-resolve version of this test hid a rebuild-every-load cliff.)
+    """
+    from raincloud import _cache, _resolve
+
+    builds = _strict_build_env(env, monkeypatch)
+    p1 = _resolve.resolve("tiny", "parquet")
+    assert p1 == _cache.cache_path("tiny", "parquet")
+    assert p1.read_bytes() == b"locally-built-different-bytes"
+    # Second strict load: served from cache via the origin=build pin, no rebuild.
+    p2 = _resolve.resolve("tiny", "parquet")
+    assert p2.read_bytes() == b"locally-built-different-bytes"
+    assert len(builds) == 1, (
+        f"strict mode rebuilt instead of serving the cached local build "
+        f"({len(builds)} builds across 2 loads — the rebuild-every-load cliff)"
+    )
+
+
+def test_resolve_strict_build_rebuilds_when_snapshot_pin_changes(env, monkeypatch):
+    """The origin=build pin is honored under strict only while the snapshot pin
+    is unchanged. A genuine snapshot revision (the maintainer republished new
+    bytes) makes the cached local build stale, so it is rebuilt against the new
+    source of truth rather than served forever."""
+    from raincloud import _catalog, _resolve
+
+    builds = _strict_build_env(env, monkeypatch)
+    _resolve.resolve("tiny", "parquet")
+    assert len(builds) == 1
+
+    # Maintainer revises the snapshot pin (new published sha) -> the cached
+    # local build is now stale against the source of truth.
+    snap_path = env["tmp"] / "snapshot.json"
+    snap = json.loads(snap_path.read_text())
+    snap["slugs"]["tiny"]["parquet_sha256"] = _sha(b"REVISED-PUBLISHED-BYTES")
+    snap_path.write_text(json.dumps(snap))
+    _catalog.load_catalog.cache_clear()
+
+    _resolve.resolve("tiny", "parquet")
+    assert len(builds) == 2, "stale local build (snapshot pin changed) not rebuilt under strict"
+
+
+# ---- sha-less slugs: the snapshot byte size is the integrity check ----
+
+@pytest.fixture
+def shaless_env(tmp_path, monkeypatch):
+    """Like `env`, but the snapshot records only a byte size (no sha256) — the
+    common case for ~80% of the catalog."""
+    payload = b"NO-SHA-BYTES"
+    mirror = tmp_path / "mirror"
+    key = mirror / "v1" / "ns" / "parquet" / "ns.parquet"
+    key.parent.mkdir(parents=True)
+    key.write_bytes(payload)
+    snapshot = {
+        "schema_version": 1,
+        "slugs": {"ns": {"expected_rows": 1, "parquet_bytes": len(payload),
+                         "vortex_bytes": None, "parquet_sha256": None,
+                         "vortex_sha256": None, "columns": []}},
+    }
+    manifest = {"schema_version": 1, "datasets": [
+        {"slug": "ns", "short_name": "N", "license": {}, "fetch": {"urls": []}}]}
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "snapshot.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "sources.json"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_MIRROR", f"file://{mirror}")
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    yield {"payload": payload, "mirror": mirror, "tmp": tmp_path}
+    _catalog.load_catalog.cache_clear()
+
+
+def test_shaless_cache_served_via_pin_no_refetch(shaless_env, monkeypatch):
+    """A sha-less slug, once adopted, serves from cache via its size pin without
+    re-fetching — even though there's no sha to match."""
+    from raincloud import _resolve, _transport
+
+    _resolve.resolve("ns", "parquet")  # prime cache (adopt writes a {None,size} pin)
+    calls = []
+    real = _transport.fetch
+    monkeypatch.setattr(_transport, "fetch",
+                        lambda u, d: (calls.append(u), real(u, d))[1])
+    # corrupt the mirror to prove the second load doesn't re-fetch
+    (shaless_env["mirror"] / "v1" / "ns" / "parquet" / "ns.parquet").write_bytes(b"X")
+    assert _resolve.resolve("ns", "parquet").read_bytes() == shaless_env["payload"]
+    assert calls == []
+
+
+def test_shaless_size_mismatch_without_pin_refetches(shaless_env, capsys):
+    """A sha-less cache file whose size != the snapshot byte size and has NO pin
+    vouching for it is treated as corruption: warn + re-fetch, rather than
+    serving possibly-truncated bytes on mere existence (the old behavior)."""
+    from raincloud import _cache, _resolve
+
+    dest = _cache.cache_path("ns", "parquet")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(b"TRUNC")  # 5 bytes != 12; no pin written
+    p = _resolve.resolve("ns", "parquet")
+    assert p.read_bytes() == shaless_env["payload"]  # re-fetched the good bytes
+    assert "size" in capsys.readouterr().err
+
+
+def test_shaless_size_match_without_pin_served(shaless_env, monkeypatch):
+    """A legacy sha-less cache file (no pin) whose size matches the snapshot byte
+    size is trusted and served without a re-fetch."""
+    from raincloud import _cache, _resolve, _transport
+
+    dest = _cache.cache_path("ns", "parquet")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(shaless_env["payload"])  # right size, no pin
+    calls = []
+    real = _transport.fetch
+    monkeypatch.setattr(_transport, "fetch",
+                        lambda u, d: (calls.append(u), real(u, d))[1])
+    assert _resolve.resolve("ns", "parquet").read_bytes() == shaless_env["payload"]
+    assert calls == []
+
+
+def test_shaless_mirror_revision_refetches(shaless_env):
+    """A sha-less slug whose mirror bytes are revised to a DIFFERENT size (and
+    the snapshot byte size updated to match) must re-fetch — the old cached
+    bytes are stale against the new source of truth, not served forever.
+    Regression: the sha-less cache-hit used to serve on ANY size-matching pin,
+    shadowing the snapshot-size check, so a revision was never seen."""
+    from raincloud import _catalog, _resolve
+
+    # Prime the cache from the mirror (mirror-origin pin, old size).
+    assert _resolve.resolve("ns", "parquet").read_bytes() == shaless_env["payload"]
+    # Maintainer republishes new, larger bytes and updates the snapshot size
+    # (still no sha — this slug stays sha-less).
+    new = b"REVISED-NS-BYTES-LONGER"
+    (shaless_env["mirror"] / "v1" / "ns" / "parquet" / "ns.parquet").write_bytes(new)
+    snap_path = shaless_env["tmp"] / "snapshot.json"
+    snap = json.loads(snap_path.read_text())
+    snap["slugs"]["ns"]["parquet_bytes"] = len(new)
+    snap_path.write_text(json.dumps(snap))
+    _catalog.load_catalog.cache_clear()
+
+    assert _resolve.resolve("ns", "parquet").read_bytes() == new
+
+
+def test_shaless_sizeless_serves_on_existence(tmp_path, monkeypatch):
+    """A slug with NEITHER a pinned sha NOR a byte size has nothing to check,
+    so a pre-existing cache file is served on existence alone. (Offline is on,
+    so any fall-through to fetch/build would raise instead of serving.)"""
+    from raincloud import _cache, _catalog, _resolve
+    snapshot = {"schema_version": 1, "slugs": {"nn": {
+        "expected_rows": 1, "parquet_bytes": None, "vortex_bytes": None,
+        "parquet_sha256": None, "vortex_sha256": None, "columns": []}}}
+    manifest = {"schema_version": 1, "datasets": [
+        {"slug": "nn", "short_name": "N", "license": {}, "fetch": {"urls": []}}]}
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(tmp_path / "snapshot.json"))
+    monkeypatch.setenv("RAINCLOUD_MANIFEST", str(tmp_path / "sources.json"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.setenv("RAINCLOUD_OFFLINE", "1")
+    _catalog.load_catalog.cache_clear()
+    dest = _cache.cache_path("nn", "parquet")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(b"whatever-bytes")
+    assert _resolve.resolve("nn", "parquet").read_bytes() == b"whatever-bytes"
+    _catalog.load_catalog.cache_clear()
diff --git a/tests/test_loader_transport.py b/tests/test_loader_transport.py
new file mode 100644
index 0000000..d48cb82
--- /dev/null
+++ b/tests/test_loader_transport.py
@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import pytest
+
+
+def test_fetch_copies_bytes(tmp_path):
+    from raincloud import _transport
+    src = tmp_path / "remote.bin"; src.write_bytes(b"payload")
+    dest = tmp_path / "local.part"
+    _transport.fetch(f"file://{src}", dest)
+    assert dest.read_bytes() == b"payload"
+
+
+def test_fetch_missing_raises_artifact_not_found(tmp_path):
+    from raincloud import _transport
+    from raincloud.exceptions import ArtifactNotFound
+    dest = tmp_path / "local.part"
+    with pytest.raises(ArtifactNotFound):
+        _transport.fetch(f"file://{tmp_path}/does-not-exist.bin", dest)
+    assert not dest.exists()  # cleanup contract: no partial file left on a miss
diff --git a/tests/test_manifest.py b/tests/test_manifest.py
index 9c2415f..87f122a 100644
--- a/tests/test_manifest.py
+++ b/tests/test_manifest.py
@@ -279,11 +279,11 @@ def test_spec_field_walks_dotted_path(manifest):
 # ---------- examples ----------
 
 def test_minimal_spec_example_validates(schema):
-    """examples/minimal_spec.json is a valid DatasetSpec.
+    """templates/minimal_spec.json is a valid DatasetSpec.
 
     Catches drift between the example template and the schema.
     """
-    raw = json.loads((REPO_ROOT / "examples" / "minimal_spec.json").read_text())
+    raw = json.loads((REPO_ROOT / "templates" / "minimal_spec.json").read_text())
     raw.pop("_comment", None)
     fake_manifest = {"schema_version": 1, "datasets": [raw]}
     v = jsonschema.Draft202012Validator(schema)
diff --git a/tests/test_pipeline_e2e.py b/tests/test_pipeline_e2e.py
new file mode 100644
index 0000000..018365b
--- /dev/null
+++ b/tests/test_pipeline_e2e.py
@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Source-tree synthetic build + handler-function tests.
+
+Always-on hermetic guard for the pipeline stage chain: drives the real
+`build.run_one(spec)` against a synthetic file:// source with all output
+dirs under `tmp_path`. No marker — runs in the default `pytest`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+
+def _synth_spec(csv: Path) -> dict:
+    return {
+        "slug": "synth-e2e",
+        "short_name": "Synth E2E",
+        "full_name": "Synth E2E",
+        "description": "synthetic file:// CSV through the full stage chain",
+        "license": {"spdx": "CC0-1.0"},
+        "fetch": {"type": "http", "urls": [csv.as_uri()]},
+        "extract": {"type": "passthrough"},
+        "parse": {"reader": "csv"},
+        "transform": {"handler": "tighten_types"},
+        "write": {"output": "synth-e2e.parquet", "compression": "zstd"},
+        "expect": {"rows": 3},
+        "convert": {"vortex": True},
+    }
+
+
+def test_pipeline_e2e_synthetic_build(tmp_path, monkeypatch):
+    """fetch → extract → parse → transform → write → validate → convert end-to-end
+    on a synthetic file:// CSV, all writes under tmp."""
+    csv = tmp_path / "tiny.csv"
+    csv.write_text("n,s\n1,a\n2,b\n3,c\n")
+    monkeypatch.setenv("RAINCLOUD_HOME", str(tmp_path / "home"))
+    # No mirror, no offline; data_root() resolves outputs under RAINCLOUD_HOME.
+    monkeypatch.delenv("RAINCLOUD_MIRROR", raising=False)
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+
+    from scripts.pipeline.build import run_one
+
+    spec = _synth_spec(csv)
+    ok = run_one(spec, strict=True)
+    assert ok, "run_one returned False — see captured stderr for stage failure"
+
+    outputs = tmp_path / "home" / "outputs" / "v1" / "synth-e2e"
+    parquet = outputs / "parquet" / "synth-e2e.parquet"
+    vortex_path = outputs / "vortex" / "synth-e2e.vortex"
+    assert parquet.exists(), parquet
+    assert vortex_path.exists(), vortex_path
+
+    # Validate the parquet content.
+    tbl = pq.read_table(parquet)
+    assert tbl.num_rows == 3
+    assert tbl.column_names == ["n", "s"]
+    # tighten_types should narrow the small-int 'n' column away from int64.
+    n_type = str(tbl.schema.field("n").type)
+    assert n_type != "int64", f"tighten_types did not narrow 'n' (got {n_type})"
+
+    # Validate the vortex output round-trips.
+    import vortex
+
+    vt = vortex.open(str(vortex_path)).to_arrow().read_all()
+    assert vt.num_rows == 3 and vt.column_names == ["n", "s"]
+
+
+def test_handlers_identity_and_tighten_types_function():
+    """Direct invocation: handlers *function* on synthetic Arrow tables."""
+    from scripts.pipeline.handlers import identity, tighten_types
+
+    src = pa.table(
+        {"x": pa.array([1, 2, 3], type=pa.int64()), "s": ["a", "b", "c"]}
+    )
+    # identity: returns the single input table as the output.
+    # Signature: (spec, [(Path, table)]) -> [(slug_str, table)]
+    out = identity({"slug": "x"}, [(Path("ignore.csv"), src)])
+    assert isinstance(out, list) and out and out[0][1].num_rows == 3
+
+    # tighten_types: narrows int64 with tiny values to a smaller int dtype.
+    out2 = tighten_types({"slug": "x"}, [(Path("ignore.csv"), src)])
+    assert isinstance(out2, list) and out2
+    narrowed = out2[0][1]
+    assert str(narrowed.schema.field("x").type) != "int64"
diff --git a/tests/test_pipeline_path_hermeticity.py b/tests/test_pipeline_path_hermeticity.py
new file mode 100644
index 0000000..5dec3c7
--- /dev/null
+++ b/tests/test_pipeline_path_hermeticity.py
@@ -0,0 +1,57 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Regression guard against REPO_ROOT path fragility in scripts/pipeline/.
+
+Long-running build / hydrate / tighten stages must not crash on log or
+cleanup operations when their outputs live outside the checkout (wheel
+install, $RAINCLOUD_HOME or $RAINCLOUD_OUTPUTS redirect). The contract:
+
+  * Format paths for display via `display_path()`, not `.relative_to(REPO_ROOT)`
+    — the latter raises ValueError on any path outside the repo and has
+    bitten us when invoked at the tail of a multi-hour run.
+  * Route artifact/scratch paths through `outputs_root()`,
+    `raw_downloads_root()`, `workdir_root()`, `prepared_parquet()`, etc. —
+    hardcoded `REPO_ROOT / "outputs" / ...` and `REPO_ROOT / "_workdir" / ...`
+    fragments wipe the wrong tree (or write to a read-only one).
+
+This test greps the pipeline package and fails on any new occurrence. To
+opt out in a tracked-data, checkout-only context, append a trailing
+`# allow-repo-root-path` comment on the offending line and document why.
+"""
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+PIPELINE_DIR = REPO_ROOT / "scripts" / "pipeline"
+
+# spec.py defines REPO_ROOT and is the one place these fragments are allowed.
+ALLOWED_FILES = {"spec.py"}
+
+OPT_OUT_TAG = "# allow-repo-root-path"
+
+PATTERNS = {
+    "relative_to_repo_root": re.compile(r"\.relative_to\(\s*REPO_ROOT\s*\)"),
+    "outputs_under_repo_root": re.compile(r'REPO_ROOT\s*/\s*"outputs"'),
+    "workdir_under_repo_root": re.compile(r'REPO_ROOT\s*/\s*"_workdir"'),
+}
+
+
+def test_pipeline_files_do_not_hardcode_repo_root_paths():
+    offenders: list[str] = []
+    for py in sorted(PIPELINE_DIR.rglob("*.py")):
+        if py.name in ALLOWED_FILES:
+            continue
+        for lineno, line in enumerate(py.read_text().splitlines(), start=1):
+            if OPT_OUT_TAG in line:
+                continue
+            for name, pat in PATTERNS.items():
+                if pat.search(line):
+                    rel = py.relative_to(REPO_ROOT)
+                    offenders.append(f"{rel}:{lineno} [{name}]  {line.strip()}")
+    assert not offenders, (
+        "Found REPO_ROOT path fragility that breaks wheel installs and "
+        "redirected $RAINCLOUD_HOME/$RAINCLOUD_OUTPUTS runs. Use "
+        "display_path() / outputs_root() / workdir_root() instead, or add "
+        f"`{OPT_OUT_TAG}` with a justification:\n  "
+        + "\n  ".join(offenders)
+    )
diff --git a/tests/test_pipeline_real.py b/tests/test_pipeline_real.py
new file mode 100644
index 0000000..0d0503c
--- /dev/null
+++ b/tests/test_pipeline_real.py
@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Real network build tests (opt-in via --run-network, non-blocking in CI).
+
+Each parametrized case calls raincloud.load('<slug>'), which exercises the
+loader's real build-fallback against a live upstream: load → cache miss →
+mirror absent → subprocess build (fetch→…→convert) → adopt → materialize.
+Three tiny slugs across two hosts and three handlers for coverage.
+"""
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.network
+
+
+@pytest.mark.parametrize("slug,expected_rows", [
+    ("uci-iris", 150),
+    ("uci-seeds", 210),
+    ("countries-of-the-world", 262),
+])
+def test_real_build_via_load(tmp_path, monkeypatch, slug, expected_rows):
+    monkeypatch.setenv("RAINCLOUD_HOME",  str(tmp_path / "home"))
+    monkeypatch.setenv("RAINCLOUD_CACHE", str(tmp_path / "cache"))
+    monkeypatch.delenv("RAINCLOUD_MIRROR",  raising=False)
+    monkeypatch.delenv("RAINCLOUD_OFFLINE", raising=False)
+
+    import raincloud
+    from raincloud import _catalog
+    _catalog.load_catalog.cache_clear()
+    try:
+        ds = raincloud.load(slug)
+        tbl = ds.to_arrow()
+        assert tbl.num_rows == expected_rows, (
+            f"{slug}: expected {expected_rows} rows, got {tbl.num_rows}"
+        )
+        # Pin the RAINCLOUD_HOME hermeticity invariant: the build subprocess
+        # must have written its outputs under tmp, NOT the repo's outputs/v1.
+        # Without this, a regression that ignored RAINCLOUD_HOME would silently
+        # corrupt the repo's tracked outputs while the row-count assertion
+        # above still passed (the loader cache would adopt the wrong-location
+        # artifact).
+        built = tmp_path / "home" / "outputs" / "v1" / slug / "parquet" / f"{slug}.parquet"
+        assert built.exists(), (
+            f"{slug}: build did not write under RAINCLOUD_HOME; "
+            f"expected {built}, repo's outputs/v1/ may have been written instead"
+        )
+    finally:
+        _catalog.load_catalog.cache_clear()
diff --git a/tests/test_promote_profiles.py b/tests/test_promote_profiles.py
index 9d86e23..4565c02 100644
--- a/tests/test_promote_profiles.py
+++ b/tests/test_promote_profiles.py
@@ -19,7 +19,6 @@ def fake_repo(tmp_path, monkeypatch):
     """Redirect REPO_ROOT to tmp_path in both modules that read it."""
     from scripts.pipeline import promote_profiles, spec
     monkeypatch.setattr(spec, "REPO_ROOT", tmp_path)
-    monkeypatch.setattr(spec, "DEFAULT_MANIFEST", tmp_path / "sources.json")
     monkeypatch.setattr(promote_profiles, "REPO_ROOT", tmp_path)
     (tmp_path / "sources.json").write_text(
         json.dumps({"schema_version": 1, "datasets": [{"slug": "alpha"}, {"slug": "beta"}]})
diff --git a/tests/test_publish.py b/tests/test_publish.py
new file mode 100644
index 0000000..0388550
--- /dev/null
+++ b/tests/test_publish.py
@@ -0,0 +1,138 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+import json
+
+import pytest
+
+
+def test_plan_uploads_matching_slug(tmp_path):
+    from scripts.pipeline import publish
+    art = tmp_path / "outputs" / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    art.parent.mkdir(parents=True); art.write_bytes(b"data")
+    sha = hashlib.sha256(b"data").hexdigest()
+    snapshot = {"slugs": {"tiny": {"parquet_bytes": 4, "parquet_sha256": sha,
+                                   "vortex_bytes": None, "vortex_sha256": None}}}
+    plan = publish.plan_uploads(["tiny"], snapshot,
+                                outputs_root=tmp_path / "outputs")
+    assert plan == [(art, "v1/tiny/parquet/tiny.parquet")]
+
+
+def test_plan_refuses_on_mismatch(tmp_path):
+    from scripts.pipeline import publish
+    art = tmp_path / "outputs" / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    art.parent.mkdir(parents=True); art.write_bytes(b"data")
+    snapshot = {"slugs": {"tiny": {"parquet_bytes": 4, "parquet_sha256": "WRONG",
+                                   "vortex_bytes": None, "vortex_sha256": None}}}
+    with pytest.raises(publish.PublishMismatch) as ei:
+        publish.plan_uploads(["tiny"], snapshot, outputs_root=tmp_path / "outputs")
+    # Finding 2: the remediation must point at --rehash, since a plain
+    # `docs snapshot` regen reuses the stale sha on a size match and re-fails.
+    assert "--rehash" in str(ei.value)
+
+
+def test_plan_includes_vortex_and_skips_absent(tmp_path):
+    """Both formats are planned when present; an absent format is skipped, not
+    errored. A None snapshot sha is published ungated (freshly built slug)."""
+    from scripts.pipeline import publish
+    root = tmp_path / "outputs"
+    pqf = root / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    vxf = root / "v1" / "tiny" / "vortex" / "tiny.vortex"
+    pqf.parent.mkdir(parents=True); pqf.write_bytes(b"P")
+    vxf.parent.mkdir(parents=True); vxf.write_bytes(b"V")
+    snapshot = {"slugs": {"tiny": {
+        "parquet_bytes": 1, "parquet_sha256": hashlib.sha256(b"P").hexdigest(),
+        "vortex_bytes": None, "vortex_sha256": None}}}  # vortex sha unknown -> ungated
+    plan = publish.plan_uploads(["tiny"], snapshot, outputs_root=root)
+    keys = {k for _, k in plan}
+    assert keys == {"v1/tiny/parquet/tiny.parquet", "v1/tiny/vortex/tiny.vortex"}
+
+
+def test_main_uploads_to_file_mirror(tmp_path, monkeypatch):
+    """Non-dry-run path actually writes bytes to the (file://) mirror, via a
+    temp key + rename that leaves no `.part` debris at the canonical key."""
+    from scripts.pipeline import publish
+    repo = tmp_path
+    art = repo / "outputs" / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    art.parent.mkdir(parents=True); art.write_bytes(b"REALBYTES")
+    sha = hashlib.sha256(b"REALBYTES").hexdigest()
+    snap = repo / "snapshot.json"
+    snap.write_text(json.dumps(
+        {"slugs": {"tiny": {"parquet_bytes": 9, "parquet_sha256": sha,
+                            "vortex_bytes": None, "vortex_sha256": None}}}))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(snap))
+    monkeypatch.setattr(publish, "load_manifest",
+                        lambda: {"schema_version": 1, "datasets": [{"slug": "tiny"}]})
+    monkeypatch.setattr(publish, "_outputs_root", lambda m=None: repo / "outputs" / "v1")
+    mirror = tmp_path / "mirror"
+    rc = publish.main(["tiny", "--mirror", f"file://{mirror}"])
+    assert rc == 0
+    uploaded = mirror / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    assert uploaded.read_bytes() == b"REALBYTES"
+    # No leftover temp-key debris from the atomic upload.
+    assert list((mirror / "v1" / "tiny" / "parquet").glob("*.part")) == []
+
+
+def test_upload_cleans_up_temp_key_on_crash(tmp_path, monkeypatch):
+    """A failure during the rename must not leave a `.part` object on the
+    mirror, and must not create the canonical key."""
+    import fsspec
+
+    from scripts.pipeline import publish
+    local = tmp_path / "src.parquet"; local.write_bytes(b"PAYLOAD")
+    mirror = tmp_path / "mirror"; mirror.mkdir()
+    target = f"file://{mirror}/v1/tiny/parquet/tiny.parquet"
+
+    real_url_to_fs = fsspec.core.url_to_fs
+
+    def fake_url_to_fs(t):
+        fs, path = real_url_to_fs(t)
+
+        def boom(*a, **k):
+            raise OSError("simulated mirror rename failure")
+
+        monkeypatch.setattr(fs, "mv", boom)
+        return fs, path
+
+    monkeypatch.setattr(fsspec.core, "url_to_fs", fake_url_to_fs)
+    with pytest.raises(OSError):
+        publish._upload(local, target)
+    # The temp .part was cleaned up and the canonical key never appeared.
+    assert list((mirror / "v1" / "tiny" / "parquet").glob("*")) == []
+
+
+def test_main_rejects_all_with_slugs(tmp_path, monkeypatch):
+    from scripts.pipeline import publish
+    monkeypatch.setattr(publish, "load_manifest",
+                        lambda: {"schema_version": 1, "datasets": []})
+    with pytest.raises(SystemExit):
+        publish.main(["tiny", "--all", "--mirror", f"file://{tmp_path}/m"])
+
+
+def test_main_rejects_no_targets(tmp_path, monkeypatch):
+    from scripts.pipeline import publish
+    monkeypatch.setattr(publish, "load_manifest",
+                        lambda: {"schema_version": 1, "datasets": []})
+    with pytest.raises(SystemExit):
+        publish.main(["--mirror", f"file://{tmp_path}/m"])
+
+
+def test_main_dry_run_finds_artifact(tmp_path, monkeypatch, capsys):
+    from scripts.pipeline import publish
+    repo = tmp_path
+    art = repo / "outputs" / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    art.parent.mkdir(parents=True); art.write_bytes(b"data")
+    sha = hashlib.sha256(b"data").hexdigest()
+    snap = repo / "snapshot.json"
+    snap.write_text(
+        json.dumps({"slugs": {"tiny": {"parquet_bytes": 4, "parquet_sha256": sha,
+                                       "vortex_bytes": None, "vortex_sha256": None}}}))
+    monkeypatch.setenv("RAINCLOUD_SNAPSHOT", str(snap))
+    monkeypatch.setattr(publish, "load_manifest",
+                        lambda: {"schema_version": 1, "datasets": [{"slug": "tiny"}]})
+    monkeypatch.setattr(publish, "_outputs_root", lambda m=None: repo / "outputs" / "v1")
+    rc = publish.main(["tiny", "--mirror", f"file://{tmp_path}/mirror", "--dry-run"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    assert "v1/tiny/parquet/tiny.parquet" in out
+    assert "planned 1 artifact" in out
diff --git a/tests/test_snapshot_checksums.py b/tests/test_snapshot_checksums.py
new file mode 100644
index 0000000..ba3b82f
--- /dev/null
+++ b/tests/test_snapshot_checksums.py
@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+import hashlib
+
+
+def test_sha256_for_path_helper(tmp_path):
+    from scripts.pipeline.docs import _sha256_for_path
+    f = tmp_path / "x.bin"; f.write_bytes(b"abc")
+    assert _sha256_for_path(f) == hashlib.sha256(b"abc").hexdigest()
+    assert _sha256_for_path(tmp_path / "missing") is None
+
+
+def test_sha256_or_reuse_reuses_on_size_match(tmp_path):
+    """Default fast path: same size + known prior sha -> reuse without hashing."""
+    from scripts.pipeline.docs import _sha256_or_reuse
+    f = tmp_path / "x.bin"; f.write_bytes(b"NEWCONTENT")  # 10 bytes
+    # prior recorded 10 bytes + a (now stale) sha; reuse keeps the stale sha.
+    assert _sha256_or_reuse(f, 10, 10, "STALE") == "STALE"
+
+
+def test_sha256_or_reuse_force_recomputes_same_size_drift(tmp_path):
+    """force=True (the --rehash flag) breaks the publish deadlock: a rebuild
+    that changes content without changing byte length must get a fresh sha,
+    not the stale prior one the size-match would otherwise reuse."""
+    from scripts.pipeline.docs import _sha256_or_reuse
+    f = tmp_path / "x.bin"; f.write_bytes(b"NEWCONTENT")  # 10 bytes
+    real = hashlib.sha256(b"NEWCONTENT").hexdigest()
+    # Without force: stale sha survives (the bug). With force: real sha.
+    assert _sha256_or_reuse(f, 10, 10, "STALE") == "STALE"
+    assert _sha256_or_reuse(f, 10, 10, "STALE", force=True) == real
+
+
+def test_sha256_or_reuse_force_preserves_missing(tmp_path):
+    """force must still preserve the prior sha for files absent this run, so
+    --rehash on a partial checkout doesn't dash out tracked ground truth."""
+    from scripts.pipeline.docs import _sha256_or_reuse
+    missing = tmp_path / "gone.bin"
+    assert _sha256_or_reuse(missing, None, 10, "PRIOR", force=True) == "PRIOR"
diff --git a/tests/test_wheel.py b/tests/test_wheel.py
new file mode 100644
index 0000000..4c33805
--- /dev/null
+++ b/tests/test_wheel.py
@@ -0,0 +1,465 @@
+# SPDX-FileCopyrightText: 2026 Raincloud Maintainers
+# SPDX-License-Identifier: Apache-2.0
+"""Wheel build + install-tier + loader-API + build-proof tests.
+
+All tests in this module are `@pytest.mark.wheel` — gated by --run-wheel
+(see tests/conftest.py). A session fixture builds the wheel once via
+`uv build --wheel`; per-test helpers create throwaway venvs with `uv venv`
+and install the wheel (± extras) via `uv pip install`.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+pytestmark = pytest.mark.wheel
+
+
+def _clean_env(**overrides: str) -> dict:
+    """A subprocess env with the developer's ambient RAINCLOUD_* scrubbed.
+
+    `os.environ.copy()` would otherwise leak the maintainer's exported
+    RAINCLOUD_OUTPUTS / RAINCLOUD_WORKDIR / RAINCLOUD_STRICT_CHECKSUM / etc. into
+    the venv subprocess, breaking hermeticity (artifacts written outside
+    tmp_path; strict mode flipping warn-and-adopt into a hard failure). We start
+    from a copy, drop every RAINCLOUD_* key, then layer on only the overrides
+    the test sets explicitly.
+    """
+    env = {k: v for k, v in os.environ.items() if not k.startswith("RAINCLOUD_")}
+    env.update(overrides)
+    return env
+
+
+@pytest.fixture(scope="session")
+def built_wheel():
+    """Build the raincloud wheel once per pytest session; return its Path."""
+    # `uv build --wheel` writes to <repo>/dist/. Pick the newest matching
+    # wheel after — multiple runs may leave older wheels lying around.
+    subprocess.run(["uv", "build", "--wheel"], cwd=REPO_ROOT, check=True)
+    wheels = sorted(
+        (REPO_ROOT / "dist").glob("raincloud-*.whl"),
+        key=lambda p: p.stat().st_mtime,
+    )
+    assert wheels, "uv build did not produce a wheel under dist/"
+    return wheels[-1]
+
+
+def _make_venv(tmp_path: Path, wheel: Path, extras: str = "") -> Path:
+    """Create a throwaway venv and install raincloud[extras] from the wheel.
+
+    `extras` is e.g. "[s3]" or "[build,duckdb]" (PEP 508 form), or "" for base.
+    Returns the venv root path.
+    """
+    venv = tmp_path / "venv"
+    subprocess.run(["uv", "venv", str(venv)], check=True)
+    pkg = f"raincloud{extras}" if extras else "raincloud"
+    subprocess.run(
+        [
+            "uv",
+            "pip",
+            "install",
+            "--python",
+            str(venv / "bin" / "python"),
+            f"{pkg} @ {wheel.as_uri()}",
+        ],
+        check=True,
+    )
+    return venv
+
+
+def _run_py(
+    venv: Path, code: str, env: dict | None = None
+) -> subprocess.CompletedProcess:
+    """Run a Python snippet in the venv via subprocess; capture stdout/stderr."""
+    return subprocess.run(
+        [str(venv / "bin" / "python"), "-c", code],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def test_wheel_builds_and_base_install_imports(built_wheel, tmp_path):
+    """Smoke: wheel builds, base venv installs it, `import raincloud` succeeds,
+    and the packaged catalog resolves with no env overrides (> 200 slugs)."""
+    venv = _make_venv(tmp_path, built_wheel)
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "import importlib.metadata as _md\n"
+            "from raincloud._catalog import load_catalog\n"
+            "print(raincloud.__version__, _md.version('raincloud'),"
+            "      len(load_catalog().slugs()))\n"
+        ),
+    )
+    assert cp.returncode == 0, cp.stderr
+    out = cp.stdout.strip().split()
+    # Version is non-empty, PEP 440-shaped (starts with a digit), and
+    # __version__ matches the installed dist's metadata (the sync invariant
+    # pyproject already enforces). Avoids hardcoding the literal version.
+    assert out[0] and out[0][0].isdigit(), f"version string looks wrong: {out[0]!r}"
+    assert out[0] == out[1], f"__version__ {out[0]!r} != dist metadata {out[1]!r}"
+    assert int(out[2]) > 200
+
+
+def test_base_install_excludes_heavy_deps(built_wheel, tmp_path):
+    """Base install MUST NOT pull osmium/pyreadstat/zstandard (those moved to [build])."""
+    venv = _make_venv(tmp_path, built_wheel)
+    cp = _run_py(
+        venv,
+        (
+            "import importlib.util\n"
+            "names = ['osmium', 'pyreadstat', 'zstandard', 'py7zr', 'unlzw3', 'openpyxl']\n"
+            "present = [n for n in names if importlib.util.find_spec(n) is not None]\n"
+            "print(','.join(present))\n"
+        ),
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert cp.stdout.strip() == "", (
+        f"base install unexpectedly pulled heavy deps: {cp.stdout.strip()!r}"
+    )
+
+
+def test_base_install_scan_and_to_pandas_raise_missing_dependency(built_wheel, tmp_path):
+    """`.scan()` and `.to_pandas()` in a base install raise MissingDependency
+    (duckdb/pandas absent), without needing any I/O — the lazy guard fires
+    before resolution."""
+    venv = _make_venv(tmp_path, built_wheel)
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "from raincloud._catalog import load_catalog\n"
+            "# pick any slug whose entry exists in the packaged catalog\n"
+            "slug = next(iter(load_catalog().slugs()))\n"
+            "ds = raincloud.load(slug)\n"
+            "errors = []\n"
+            "try:\n"
+            "    ds.scan()\n"
+            "except raincloud.MissingDependency as e:\n"
+            "    errors.append(('scan', 'duckdb' in str(e).lower()))\n"
+            "try:\n"
+            "    ds.to_pandas()\n"
+            "except raincloud.MissingDependency as e:\n"
+            "    errors.append(('to_pandas', 'pandas' in str(e).lower()))\n"
+            "print(errors)\n"
+        ),
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "('scan', True)" in cp.stdout and "('to_pandas', True)" in cp.stdout
+
+
+def test_build_extra_installs_heavy_deps_and_build_is_available(built_wheel, tmp_path):
+    """`[build]` install pulls the heavy toolchain AND _build_available() is True
+    (the real import-probe succeeds when [build] is installed)."""
+    venv = _make_venv(tmp_path, built_wheel, extras="[build]")
+    cp = _run_py(
+        venv,
+        (
+            "import osmium, pyreadstat, zstandard\n"
+            "from raincloud import _resolve\n"
+            "print(_resolve._build_available())\n"
+        ),
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert cp.stdout.strip() == "True"
+
+
+@pytest.mark.parametrize(
+    "extra,backend",
+    [
+        ("[s3]", "s3fs"),
+        ("[http]", "aiohttp"),
+        ("[duckdb]", "duckdb"),
+        ("[pandas]", "pandas"),
+    ],
+)
+def test_extra_installs_its_backend(built_wheel, tmp_path, extra, backend):
+    """Each per-scheme/convenience extra wires its named backend module."""
+    venv = _make_venv(tmp_path, built_wheel, extras=extra)
+    cp = _run_py(venv, f"import {backend}; print('ok')")
+    assert cp.returncode == 0, cp.stderr
+    assert cp.stdout.strip() == "ok"
+
+
+def _write_loader_fixture(tmp_path: Path):
+    """Build a tmp file:// mirror with a real parquet + vortex artifact for slug 'tiny'.
+
+    Creates the artifacts in the outer test env (vortex-data is a base dep,
+    so vortex.io.write is available here), writes a fixture snapshot + manifest
+    pinning their real sha256, and returns (env_dict, mirror_dir) where env_dict
+    is ready to pass as `env=` to subprocess. The venv then reads the fixture
+    via RAINCLOUD_* env overrides — hermetic.
+    """
+    import hashlib
+    import json
+
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+    import vortex
+
+    table = pa.table({"x": [1, 2, 3], "y": ["a", "b", "c"]})
+    mirror = tmp_path / "mirror"
+    pq_key = mirror / "v1" / "tiny" / "parquet" / "tiny.parquet"
+    vx_key = mirror / "v1" / "tiny" / "vortex" / "tiny.vortex"
+    pq_key.parent.mkdir(parents=True)
+    vx_key.parent.mkdir(parents=True)
+    pq.write_table(table, pq_key)
+    vortex.io.write(table, str(vx_key))
+
+    def sha(p):
+        return hashlib.sha256(p.read_bytes()).hexdigest()
+
+    snapshot = {
+        "schema_version": 1,
+        "slugs": {
+            "tiny": {
+                "expected_rows": 3,
+                "last_built_rows": 3,
+                "parquet_bytes": pq_key.stat().st_size,
+                "vortex_bytes": vx_key.stat().st_size,
+                "parquet_sha256": sha(pq_key),
+                "vortex_sha256": sha(vx_key),
+                "columns": [
+                    {"name": "x", "type": "int64"},
+                    {"name": "y", "type": "string"},
+                ],
+            }
+        },
+    }
+    manifest = {
+        "schema_version": 1,
+        "datasets": [
+            {
+                "slug": "tiny",
+                "short_name": "Tiny",
+                "full_name": "Tiny",
+                "description": "d",
+                "license": {"spdx": "CC0-1.0"},
+                "fetch": {"urls": ["http://s"]},
+                "convert": {"vortex": True},
+            }
+        ],
+    }
+    (tmp_path / "snapshot.json").write_text(json.dumps(snapshot))
+    (tmp_path / "sources.json").write_text(json.dumps(manifest))
+
+    env = _clean_env(
+        RAINCLOUD_SNAPSHOT=str(tmp_path / "snapshot.json"),
+        RAINCLOUD_MANIFEST=str(tmp_path / "sources.json"),
+        RAINCLOUD_CACHE=str(tmp_path / "cache"),
+        RAINCLOUD_MIRROR=f"file://{mirror}",
+    )
+    return env, mirror
+
+
+def test_loader_happy_paths_against_wheel(built_wheel, tmp_path):
+    """`load(); to_arrow/to_vortex/schema/path/num_rows/column_names/info`
+    + vortex->parquet format fallback, against the installed wheel."""
+    env, _mirror = _write_loader_fixture(tmp_path)
+    venv = _make_venv(tmp_path, built_wheel)
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "ds = raincloud.load('tiny')\n"
+            "assert ds.format == 'vortex'\n"
+            "assert ds.num_rows == 3\n"
+            "assert ds.column_names == ['x', 'y']\n"
+            "assert ds.info['license']['spdx'] == 'CC0-1.0'\n"
+            "tbl = ds.to_arrow()\n"
+            "assert tbl.num_rows == 3 and tbl.column_names == ['x', 'y']\n"
+            "assert tbl['x'].to_pylist() == [1, 2, 3]\n"
+            "vf = ds.to_vortex()\n"
+            "assert vf is not None\n"
+            "schema = ds.schema\n"
+            "assert [f.name for f in schema] == ['x', 'y']\n"
+            "p = ds.path()\n"
+            "assert p.exists()\n"
+            "ds_pq = raincloud.load('tiny', format='parquet')\n"
+            "assert ds_pq.to_arrow().num_rows == 3\n"
+            "print('ok')\n"
+        ),
+        env=env,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "ok" in cp.stdout
+
+
+def test_loader_error_paths_against_wheel(built_wheel, tmp_path):
+    """OfflineMiss + drift warn-and-adopt against the installed wheel."""
+    env, mirror = _write_loader_fixture(tmp_path)
+    venv = _make_venv(tmp_path, built_wheel)
+
+    # 1) OfflineMiss: cache empty, RAINCLOUD_OFFLINE=1 -> can't fetch.
+    # Use a dedicated cache subdir so this call cannot prime the cache for later calls.
+    env_off = {**env, "RAINCLOUD_OFFLINE": "1", "RAINCLOUD_CACHE": str(tmp_path / "cache_offline")}
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "try:\n"
+            "    raincloud.load('tiny').path()\n"
+            "except raincloud.OfflineMiss:\n"
+            "    print('offline_ok')\n"
+        ),
+        env=env_off,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "offline_ok" in cp.stdout, (
+        f"OfflineMiss not raised; stdout={cp.stdout!r} stderr={cp.stderr!r}"
+    )
+
+    # 2) Drift warn-and-adopt: the mirror serves bytes whose sha disagrees with
+    #    the snapshot pin. Policy is alert-not-block — the loader warns on
+    #    stderr and adopts anyway (a fresh cache subdir so no prior clean copy
+    #    short-circuits). A second load must then be a pure cache hit (the pin
+    #    sidecar vouches for the adopted bytes), not a re-fetch.
+    (mirror / "v1" / "tiny" / "vortex" / "tiny.vortex").write_bytes(b"DRIFTED-UPSTREAM")
+    env_drift = {**env, "RAINCLOUD_CACHE": str(tmp_path / "cache_drift")}
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "p1 = raincloud.load('tiny').path()\n"
+            "assert p1.read_bytes() == b'DRIFTED-UPSTREAM', p1.read_bytes()\n"
+            "# second load: served from cache, bytes unchanged\n"
+            "p2 = raincloud.load('tiny').path()\n"
+            "assert p2.read_bytes() == b'DRIFTED-UPSTREAM'\n"
+            "print('drift_adopt_ok')\n"
+        ),
+        env=env_drift,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "drift_adopt_ok" in cp.stdout, (
+        f"drift not adopted; stdout={cp.stdout!r} stderr={cp.stderr!r}"
+    )
+    assert "WARN" in cp.stderr and "drifted" in cp.stderr, (
+        f"expected a drift warning on stderr; stderr={cp.stderr!r}"
+    )
+
+    # 3) UnknownSlug: a slug nowhere in the catalog.
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "try:\n"
+            "    raincloud.load('does-not-exist')\n"
+            "except raincloud.UnknownSlug:\n"
+            "    print('unknown_ok')\n"
+        ),
+        env=env,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "unknown_ok" in cp.stdout, (
+        f"UnknownSlug not raised; stdout={cp.stdout!r} stderr={cp.stderr!r}"
+    )
+
+
+def test_scan_works_with_duckdb_extra(built_wheel, tmp_path):
+    """`[duckdb]` venv: `.scan()` returns a queryable relation against a file:// parquet."""
+    env, _mirror = _write_loader_fixture(tmp_path)
+    venv = _make_venv(tmp_path, built_wheel, extras="[duckdb]")
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "ds = raincloud.load('tiny', format='parquet')\n"
+            "rel = ds.scan()\n"
+            "rows = rel.fetchall()\n"
+            "assert len(rows) == 3, rows\n"
+            "print('ok')\n"
+        ),
+        env=env,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "ok" in cp.stdout
+
+
+def test_to_pandas_works_with_pandas_extra(built_wheel, tmp_path):
+    """`[pandas]` venv: `.to_pandas()` returns a DataFrame with the expected rows/cols."""
+    env, _mirror = _write_loader_fixture(tmp_path)
+    venv = _make_venv(tmp_path, built_wheel, extras="[pandas]")
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "df = raincloud.load('tiny').to_pandas()\n"
+            "assert list(df.columns) == ['x', 'y']\n"
+            "assert len(df) == 3 and df['x'].tolist() == [1, 2, 3]\n"
+            "print('ok')\n"
+        ),
+        env=env,
+    )
+    assert cp.returncode == 0, cp.stderr
+    assert "ok" in cp.stdout
+
+
+def _write_synth_manifest(tmp_path: Path) -> tuple[Path, Path, int]:
+    """Write a tmp CSV + a synthetic sources.json describing one slug fetched
+    via file://. Returns (manifest_path, csv_path, expected_rows).
+    """
+    import json
+
+    csv = tmp_path / "tiny.csv"
+    csv.write_text("a,b\n1,x\n2,y\n3,z\n")
+    expected_rows = 3
+    manifest = {
+        "schema_version": 1,
+        "datasets": [
+            {
+                "slug": "synth",
+                "short_name": "Synth",
+                "full_name": "Synthetic build proof",
+                "description": "tmp CSV via file://",
+                "license": {"spdx": "CC0-1.0"},
+                "fetch": {"type": "http", "urls": [csv.as_uri()]},
+                "extract": {"type": "passthrough"},
+                "parse": {"reader": "csv"},
+                "transform": {"handler": "tighten_types"},
+                "write": {"output": "synth.parquet", "compression": "zstd"},
+                "expect": {"rows": expected_rows},
+                "convert": {"vortex": True},
+            }
+        ],
+    }
+    mp = tmp_path / "sources.json"
+    mp.write_text(json.dumps(manifest))
+    return mp, csv, expected_rows
+
+
+def test_wheel_build_proof_via_load(built_wheel, tmp_path):
+    """The capstone: `raincloud.load('synth')` in a [build] venv drives load →
+    cache miss → mirror absent → build-fallback subprocess (file:// fetch +
+    fetch→…→convert) → adopt → vortex materialization. End-to-end, hermetic."""
+    manifest, _csv, expected_rows = _write_synth_manifest(tmp_path)
+    venv = _make_venv(tmp_path, built_wheel, extras="[build]")
+    env = _clean_env(
+        RAINCLOUD_MANIFEST=str(manifest),
+        RAINCLOUD_HOME=str(tmp_path / "home"),
+        RAINCLOUD_CACHE=str(tmp_path / "cache"),
+    )
+    cp = _run_py(
+        venv,
+        (
+            "import raincloud\n"
+            "ds = raincloud.load('synth')        # default vortex; convert.vortex=True\n"
+            "tbl = ds.to_arrow()\n"
+            f"assert tbl.num_rows == {expected_rows}, tbl.num_rows\n"
+            "assert tbl.column_names == ['a', 'b']\n"
+            "print('ok')\n"
+        ),
+        env=env,
+    )
+    assert cp.returncode == 0, f"stdout:\n{cp.stdout}\nstderr:\n{cp.stderr}"
+    assert "ok" in cp.stdout
+    # The build wrote real artifacts under $RAINCLOUD_HOME/outputs/v1/synth/
+    outputs = tmp_path / "home" / "outputs" / "v1" / "synth"
+    assert (outputs / "parquet" / "synth.parquet").exists()
+    assert (outputs / "vortex" / "synth.vortex").exists()