@ak--47/dungeon-master 1.6.5 → 1.8.0

package/.claude/skills/verify-dungeon/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: verify-dungeon
-description: Use when a dungeon's hooks need verification before pushing data to Mixpanel — runs the dungeon at full scale, evaluates the dungeon's `stories` export with the mechanical story runner (verify-stories.mjs), validates schema integrity (catches flag-stamping), and reports per-hook NAILED/STRONG/WEAK/NONE/INVERSE verdicts. LLM investigation is reserved for failures and duckdb-type assertions.
-argument-hint: [dungeon path(s), e.g. dungeons/vertical/gaming/gaming.js or dungeons/vertical/fintech/fintech.js]
+description: Use when a dungeon needs verification before import or warehouse deployment, including standaloneEvents cadence streams and warehouseMetrics tables. Runs full-scale story checks, schema validation, and automatic warehouse audits even without stories. Reports per-hook NAILED/STRONG/WEAK/NONE/INVERSE verdicts; investigates failures and duckdb assertions.
+argument-hint: '[dungeon path(s), e.g. dungeons/vertical/gaming/gaming.js or dungeons/vertical/fintech/fintech.js]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -35,10 +35,10 @@ Read the dungeon at `$ARGUMENTS`. If it's a bare filename (no `/`), check `dunge
 
 For each hook/pattern, catalog:
 - Hook number and name (e.g., "Hook #1: Compass users have 3x quest completion")
-- Hook type (`event`, `everything`, `funnel-pre`, `funnel-post`, `user`, `scd-pre`)
+- Hook type (`event`, `everything`, `funnel-pre`, `funnel-post`, `user`, `scd-pre`, `standalone`, `warehouse`)
 - Mechanism — what the code actually does
 - Expected signal — specific, measurable outcome (e.g., "compass_user=true events should have ~1.5x reward_gold")
-- Which output file the signal lives in (events, users, groups)
+- Which output file the signal lives in (user events, users, groups, standalone cadence shards, warehouse tables)
 - Mixpanel report instructions — flag missing/vague ones for the report
 
 ### Step 2: Run the dungeon
@@ -59,16 +59,25 @@ node scripts/verify-runner.mjs dungeons/vertical/gaming/gaming.js verify-gaming
 Full-fidelity runs can take minutes (50K+ user dungeons). Plan accordingly — kick off the run, do other reading, return when the file lands. If a run takes longer than your budget, report that as a finding ("dungeon too large to verify in current session") rather than falling back to `--small`.
 
 **Expected output files** (in `./data/`, prefixed by `<run-name>`):
-- `<run-name>-EVENTS.json` — all events (JSONL)
+- `<run-name>-EVENTS.json` — user events only (JSONL)
 - `<run-name>-USERS.json` — user profiles
 - `<run-name>-*-GROUPS.json` — group profiles (if dungeon has groups)
 - `<run-name>-*-SCD.json` — SCD data (if dungeon has SCDs)
+- `<run-name>-STANDALONE*.json` — `standaloneEvents` cadence records, separate from users
+- `<run-name>-WAREHOUSE-<metric>.*` — `warehouseMetrics` tables; use manifest paths and formats
+- `<run-name>-WAREHOUSE-MANIFEST.json` — table columns, grain, paths, SQL, and deployment metadata
+
+Use local disk output, `format: 'json'`, `gzip: false`, and sending disabled
+(`token: ''`) for this verification path. The existing runner supplies these
+overrides. Record the exact prefix, for example `data/verify-gaming`, and pass
+it explicitly to every downstream command. Preserve table files and their
+matching manifest for `/warehouse-metrics`; do not regenerate silently.
 
 For batched output (>2M events), the runner writes `<run-name>-EVENTS-part-*.json`. See [sql-recipes.md "Multi-part EVENTS files"](references/sql-recipes.md#multi-part-events-files-batch-mode).
 
 ### Step 3: Run the story runner (primary mechanical check)
 
-For any dungeon with a `stories` export, the runner — not the LLM — computes the verdicts:
+Run this for any dungeon with a `stories` export or `warehouseMetrics`:
 
 ```bash
 node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name>
@@ -77,6 +86,26 @@ node scripts/verify-stories.mjs <dungeon-path> --data-prefix <run-name> --json
 
 The runner streams the shards from Step 2, evaluates every assertion against its declared `target` / `floor` / `minCohort`, substitutes `{{PREFIX}}` into `duckdb`-type assertions and shells them out, enforces hook coverage (every numbered hook in the HOOK STORIES comment block must be targeted by at least one story), and prints a five-tier verdict table. Exit code is non-zero when any story lands WEAK / NONE / INVERSE or coverage is incomplete.
 
+When the dungeon declares `warehouseMetrics`, the runner also performs an automatic warehouse shape audit even if the dungeon exports no `stories`: it checks declared-column integrity, dense-gap absence, monotonic time ordering, empty numeric cells, sparse repeated-value suppression, and row-count sanity against the dataset window. Audit failures are reported alongside story verdicts and fail the CLI.
+
+Warehouse stories support `warehouse` row assertions and `warehouse-stats`
+summary assertions in the story schema. Automatic audits do not replace engineered story
+assertions, and an audit-only dungeon must not be reported as having passing stories.
+
+If a request calls these checks `rawStats`, translate that intent into supported
+`warehouse-stats` fields or disk DuckDB. There is no `rawStats` breakdown type
+in the local story schema or dispatcher. Inspect `lib/verify/warehouse.js` and
+`lib/verify/story-runner.js` for the available summary fields; never invent one.
+
+For `standaloneEvents`, use disk-backed `duckdb` assertions with
+`read_json_auto('{{PREFIX}}-STANDALONE*.json', union_by_name=true, sample_size=-1)`.
+The CLI's emulator input contains user EVENTS shards only. `--in-memory` skips
+disk-only DuckDB assertions; it cannot prove standalone stories. The disk CLI
+also requires nonempty user EVENTS shards. For a standalone-only artifact set
+without those shards, run the same SQL directly and report that CLI limitation.
+A standalone-only config without stories does not receive an automatic cadence
+audit; perform the explicit schema, tick, dimension, and identity checks below.
+
 **Verdicts are computed, not judged.** They include the population floor: a cohort smaller than the assertion's `minCohort` caps at WEAK — a 12-user cohort can no longer score NAILED regardless of how clean its ratio looks. See [report-format.md "Verdict criteria"](references/report-format.md#verdict-criteria-5-tier) for the mechanical definitions.
 
 **What the LLM investigates after this step — and nothing else:**
@@ -90,6 +119,15 @@ Do NOT re-derive verdicts the runner already computed as passing. `hook-results.
 
 Catches hooks that introduce undeclared columns (flag stamping). For each unique event type, compare actual columns against config-declared properties. See [sql-recipes.md "Schema validation queries"](references/sql-recipes.md#schema-validation-queries) for the SQL and the expected-schema source table.
 
+Keep schemas separate. User-event checks use `events[]`, superProps, and enabled
+SDK fields. Standalone checks use only core `event`, `time`, `insert_id`,
+`distinct_id`, plus that spec's dimensions and properties. Require no `user_id`
+or `device_id`; synthetic ids never count as people. Check one row per cadence
+tick and dimension tuple unless a documented hook intentionally changes it.
+Warehouse checks use the manifest's fixed columns and the metric's time column,
+group keys, value column, and declared extras. Never apply user superProp or
+identity requirements to cadence records or warehouse rows.
+
 **Schema verdicts:**
 - **SCHEMA-PASS** — added column appears on 100% of events of this type (uniform enrichment, acceptable)
 - **SCHEMA-FAIL** — added column appears on <100% (flag stamping; conditional property creates inconsistent schema)
@@ -121,6 +159,9 @@ Applies only to the investigation targets from Step 3 — failing stories, `duck
 | Identity-model invariants | DuckDB |
 | Experiment invariants | DuckDB |
 | True bespokes (no emulator analysis fits) | DuckDB |
+| Standalone cadence values, dimensions, tick counts | Disk DuckDB on `{{PREFIX}}-STANDALONE*.json` |
+| Warehouse value stories | `warehouse` or `warehouse-stats` assertion |
+| Warehouse schema, gaps, ordering, numeric cells | Automatic warehouse audit, with or without stories |
 
 The emulator now covers lifecycle, flows, sessions, event breakdowns, formulas, and compounded retention — DuckDB's remit is schema / identity / experiment invariants plus true bespoke shapes. If a "bespoke" check is really a funnel, frequency, path, or breakdown in disguise, it belongs in the emulator.
 
@@ -142,9 +183,9 @@ generated artifacts into `dungeons/user/<name>/`:
 - `hook-query-log.txt` (Step 6)
 - `<name>-verifications.sql` (Step 7b)
 
-The ONLY exception is the throwaway verification data the run writes to
-`./data/` (`verify-*` event/user files) — that stays in `./data/` and is
-deleted in Step 8.
+The exception is run data under `./data/`, including cadence shards, warehouse
+tables, and the manifest. Keep it under its explicit prefix until verification
+and deployment finish. Step 8 requires consent before any scoped cleanup.
 
 For non-user dungeons (technical/vertical) or batch runs across many dungeons,
 fall back to `./research/` for `hook-results.md` / `hook-query-log.txt`.
@@ -171,22 +212,25 @@ Write to `dungeons/user/<name>/hook-results.md` for a user dungeon, else `./rese
 
 When verifying a dungeon in `dungeons/user/`, also write a standalone DuckDB SQL file alongside the dungeon in its folder at `dungeons/user/<name>/<name>-verifications.sql`. Vertical dungeons already have their SQL co-located at `dungeons/vertical/<name>/<name>.sql`. Format: see [report-format.md "Verification SQL file"](references/report-format.md#verification-sql-file-mandatory-for-user-dungeons).
 
-### Step 8: Cleanup
+### Step 8: Preserve artifacts and hand off
 
-```bash
-rm -f ./data/verify-* ./verify-*
-```
+Record the exact verified prefix and retained files in the report. If warehouse
+tables are present, provision with `/create-project`, then hand off to
+`/warehouse-metrics` using `--data-prefix <verified-prefix>`. Provisioning and
+ordinary event import do not deploy these tables.
 
-Remove ALL files matching `verify-*` in `./data/` and project root. Also remove any temporary runner scripts.
+Do not run blanket prune or delete `verify-*` globs. Only after deployment is
+complete, list files for this exact run and obtain user consent for scoped
+cleanup. Keep reports and reproducible SQL. Do not delete files during an audit.
 
 ## Hook execution model
 
 Per user, hooks fire in this order:
 
 1. `"user"` — profile created (mutate in-place; return ignored)
-2. `"scd-pre"` — SCD entries created (mutate in-place OR return new array)
+2. `"scd-pre"` — SCD entries created (mutate in-place; return ignored)
 3. For each funnel: `"funnel-pre"` → `"event"` (per step) → `"funnel-post"`
-4. `"event"` — for non-funnel standalone events (return value REPLACES the event)
+4. `"event"` — for non-funnel user events from `events[]` (return value REPLACES the event)
 5. `"everything"` — array of ALL the user's events (return array to replace)
 6. **Storage phase** — data written to disk. Hooks for `event`, `user`, `scd` do NOT re-fire (already applied above). Hooks for `mirror`, `ad-spend`, `group`, `lookup` fire only in storage.
 
@@ -195,6 +239,15 @@ Return-value behavior:
 - `everything` hook: return value IS used if it's an array (replaces event list)
 - `user`, `scd-pre`, `funnel-post`: return value IGNORED — only in-place mutations work
 - `funnel-pre`: return value IGNORED — mutate the `record` object in-place (e.g., `record.conversionRate = 0.9`)
+- `standalone`: runs before the user loop. Return an object or array; `undefined`
+	drops the record. `meta.spec` and `meta.config` describe the cadence stream.
+- `warehouse`: runs after the user loop. Mutate the row; return value is ignored.
+	Meta includes `spec`, `config`, `metricName`, bucket fields, `grain`,
+	`seriesKey`, `isBackfill`, and `raw` source aggregates.
+
+Neither `standalone` nor `warehouse` receives person metadata or passes through
+`everything`. Their generation phases differ even though both hooks fire on
+storage push. Other storage-only types return objects or arrays to retain rows.
 
 ## Final output
 
@@ -204,5 +257,7 @@ Tell the user:
 3. Query log path (if written): alongside the report (`dungeons/user/<name>/hook-query-log.txt`, else `./research/hook-query-log.txt`)
 4. Verdict counts from the story runner (per dungeon if batch mode), plus which stories needed LLM investigation
 5. One-line summary of the most interesting finding
+6. Separate standalone checks and `warehouseAudits`, including audit-only runs,
+   skipped assertions, retained artifact prefix, and warehouse deployment handoff
 
 If hooks failed, note that `hook-results.md` can be used as context for fixing them: "read hook-results.md and fix the failing hooks in <dungeon-file>".

package/.claude/skills/verify-dungeon/references/counting-semantics.md

@@ -1,3 +1,17 @@
+# v1.8.0 metric streams
+
+The user-event emulator receives EVENTS and profiles. `standaloneEvents` writes
+separate STANDALONE shards; verify these with disk `duckdb` assertions on
+`{{PREFIX}}-STANDALONE*.json`. The CLI's `--in-memory` mode skips disk-only SQL.
+Standalone synthetic `distinct_id` values identify series, never people, so
+exclude them from funnels, retention, lifecycle, identity stitching, and user counts.
+
+`warehouseMetrics` reads only user `events[]` sources. It materializes after
+the user loop and supports `warehouse` and `warehouse-stats` assertions.
+Automatic warehouse audits run even without stories. Its history buckets can
+precede the user-event window; sparse point-in-time tables intentionally omit
+unchanged rows. Do not apply cadence or user-population counting rules to them.
+
 # Counting Semantics — Mixpanel-Accurate Verification
 
 Mixpanel does NOT count the way naive SQL does. The verifier (and any DuckDB query you write) must match Mixpanel's rules.

package/.claude/skills/verify-dungeon/references/report-format.md

@@ -4,6 +4,23 @@ Templates and conventions for writing `hook-results.md` and per-dungeon verifica
 
 ## Verdict criteria (5-tier)
 
+Every report records the exact data prefix and retained artifact paths. Separate
+user EVENTS/USERS, standalone cadence shards, and warehouse tables/manifest.
+Keep deployment inputs until `/warehouse-metrics` completes; cleanup needs
+consent and must name this run's files only.
+
+Report standalone schema, cadence counts, dimension coverage, numeric values,
+and absence of person ids separately from user schema and identity checks.
+Name the disk DuckDB assertions and flag any skipped in-memory checks. Synthetic
+standalone ids never contribute to users, funnels, or retention.
+
+Render `warehouseAudits` from the runner JSON in a separate pass/fail table,
+including declared columns, gaps, ordering, numeric cells, sparse repeats, and
+row-count checks. Report these even without stories. Label an audit-only run
+"no stories declared"; do not invent NAILED/STRONG story verdicts. Distinguish
+warehouse history backfill from the user-event date window and record the
+project-provisioning and `/warehouse-metrics` handoff status.
+
 Verdicts are **mechanical** — computed by `scripts/verify-stories.mjs` from each story assertion's declared `target` / `floor` / `minCohort` (see the `StoryVerdict` typedef in `types.d.ts`), not eyeballed percentages:
 
 - **NAILED** — observed within ±10% of `target`.
@@ -206,7 +223,7 @@ Follow the format in `dungeons/vertical/<name>/`:
 -- USAGE:
 --   1. node scripts/verify-runner.mjs dungeons/user/<name>/<name>.js verify-<name>
 --   2. duckdb < dungeons/user/<name>/<name>-verifications.sql
---   3. rm -f verify-<name>-*
+--   3. Preserve this prefix through deployment; cleanup requires explicit consent.
 -- ============================================================================
 
 -- HOOK N: NAME (TYPE)

package/.claude/skills/verify-dungeon/references/sql-recipes.md

@@ -60,6 +60,41 @@ If any event type has SCHEMA-FAIL, flag it prominently and include specific reme
 
 ## Standard identity-model invariants
 
+### Metric artifacts use separate schemas
+
+The expected-schema table above applies only to user EVENTS. For `standaloneEvents`,
+expect `event`, `time`, `insert_id`, `distinct_id`, plus the matching spec's
+dimension and property keys. User superProps, session ids, and SDK flags do not
+apply. Check undeclared columns explicitly; the story CLI's user schema pass
+does not cover standalone shards.
+
+Use a `duckdb` story assertion with this source, filtering the declared event:
+
+```sql
+SELECT event, count(*) AS records, min(time::TIMESTAMP) AS first_tick,
+       max(time::TIMESTAMP) AS last_tick
+FROM read_json_auto('{{PREFIX}}-STANDALONE*.json',
+  union_by_name=true, sample_size=-1)
+GROUP BY event;
+```
+
+Compare the count with cadence ticks times the dimension cross-product size.
+Check duplicate `(event, time, <dimension keys>)` tuples and undeclared keys,
+and assert that `user_id` and `device_id` are absent. Synthetic `distinct_id`
+values identify series, never people. Do not union these shards into EVENTS
+for funnels, retention, stitching, or user counts. Substitute `{{PREFIX}}`
+with the exact artifact prefix when running SQL outside the story CLI.
+
+For `warehouseMetrics`, use the matching `-WAREHOUSE-MANIFEST.json` to resolve
+each table file and schema. Read JSONL with `read_json_auto` or CSV with
+`read_csv_auto` according to that manifest. Check the declared `timeColumn`,
+group keys, `valueColumn`, and extra `columns`; no identity fields are required.
+Use `warehouse` or `warehouse-stats` assertions for stories. The
+automatic warehouse audit runs even without stories. Account for `history`
+backfill and `sparse` point-in-time rows before judging counts or time coverage.
+
+### User-event identity checks
+
 Run these for every dungeon that uses the identity model (`isAuthEvent` + `attempts` + `identity.avgDevicePerUser`), BEFORE per-pattern checks:
 
 ```sql
@@ -775,7 +810,7 @@ Choice depends on whether the JSDoc's stated ranges are load-bearing for the dun
 If you edit a hook then query the existing data files, you'll get STALE results. The verifier must re-run the dungeon AND wait for full completion before re-querying:
 
 ```bash
-rm -f ./data/verify-<NAME>-*
+# Keep this run's files for verification and deployment; cleanup needs explicit consent.
 node scripts/verify-runner.mjs dungeons/vertical/<NAME>.js verify-<NAME>
 # Wait for the {"mode":"full","eventCount":...} JSON to print before querying
 ```

package/.claude/skills/warehouse-metrics/GAPS-template.md

@@ -0,0 +1,34 @@
+# Warehouse Metric CRUD Gap Report
+
+Dungeon: {{DUNGEON_PATH}}
+Warehouse dir: {{WAREHOUSE_DIR}}
+Dataset: {{DATASET}}
+Source id: {{SOURCE_ID}}
+
+Note: {{NOTE}}
+
+## Desired Powertools Contract
+
+All under `/crud`, POST to execute, GET for docs, standard `client_id` / `region` body convention.
+
+| Endpoint | Required | Notes |
+|---|---|---|
+| `createWarehouseMetric` | `project_id`, `source_id`, `name`, `sql`, `value_column` | Optional: `metric_type`, `time_column`, `aggregation`, `refresh`, `description` |
+| `getWarehouseMetrics` | `project_id` | |
+| `getWarehouseMetric` | `project_id`, `metric_id` | |
+| `updateWarehouseMetric` | `project_id`, `metric_id`, `payload` | `source_id` is immutable; delete and recreate to rebind |
+| `deleteWarehouseMetric` | `project_id`, `metric_id` | |
+| `refreshWarehouseMetric` | `project_id`, `metric_id` | Cache invalidation only; does not execute the query |
+| `previewWarehouseMetric` | `project_id`, `source_id`, `sql` | Returns rows; use before save because create does not validate SQL |
+
+## Manual Notes
+
+- `value_column` is required for every warehouse metric, including numeric ones.
+- `source_id` must come from the actual `/macro/setup-bq-warehouse` response.
+- `previewWarehouseMetric` rejects raw SQL containing `DROP`, `DELETE`, `TRUNCATE`, `ALTER`, `CREATE`, `INSERT`, or `UPDATE` as substrings.
+- `created_at` and `updated_at` therefore fail preview unless the blocked text is removed from the query entirely.
+- `refreshWarehouseMetric` invalidates cache only; it does not execute the query.
+
+## Per-table Checklist
+
+{{TABLE_CHECKLIST}}

package/.claude/skills/warehouse-metrics/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: warehouse-metrics
+description: 'Use when a completed warehouse dungeon needs its warehouse tables loaded into BigQuery and saved as Mixpanel warehouse metrics. Triggers: "deploy warehouse metrics", "load warehouse tables", "connect warehouse metric source", "save warehouse metrics", after a dungeon has already run.'
+argument-hint: '[dungeon path, e.g. dungeons/user/acme/acme.js]'
+model: claude-opus-4-6
+effort: max
+---
+
+# Deploy Warehouse Tables and Metrics
+
+Load the generated warehouse tables for a dungeon into BigQuery, connect the dataset to Mixpanel with the existing powertools macro, preview each metric SQL, and save the warehouse metrics when the CRUD endpoints are available.
+
+**Dungeon file:** `$ARGUMENTS`
+
+## What it does
+
+The orchestrator is `.claude/skills/warehouse-metrics/deploy.mjs`. It works from the warehouse manifest emitted by a completed dungeon run.
+
+1. Loads the dungeon with the package loader and requires `warehouseMetrics`.
+2. Finds the latest warehouse manifest and table files, or uses `--data-prefix` when supplied.
+3. Normalizes the BigQuery dataset name to `dm_<dungeon_name>`, unless `--dataset` overrides it.
+4. Writes per-table SQL files under the dungeon's sibling `warehouse/` directory with `{{DATASET}}` already substituted for the dataset id. The metric SQL itself is fully qualified to `mixpanel-gtm-training.<dataset>.<table>`.
+5. Runs a non-destructive `bq ls` preflight first so missing CLI or ADC fails before any write.
+6. Probes `GET /crud/getWarehouseMetrics` first and, when available, lists metrics before any BigQuery writes so malformed list payloads or upstream 500s fail early.
+7. Loads the tables into BigQuery with explicit schemas from the manifest, then reuses `.claude/skills/powertools/pt.mjs` to call `/macro/setup-bq-warehouse`. Do not reimplement that flow here. Only the macro performs the GCP-side IAM grant.
+8. If the docs route 404s, the script still completes the BigQuery load and source setup, then writes `warehouse/GAPS.md` from the template for manual metric setup.
+9. When the endpoint exists, it dedupes by `name`, previews SQL with `previewWarehouseMetric`, then saves new metrics with `createWarehouseMetric`.
+
+## Flags
+
+```bash
+node .claude/skills/warehouse-metrics/deploy.mjs <dungeon-path> [--dataset dm_name] [--data-prefix path/prefix] [--dry-run]
+```
+
+- `--dataset`: override the normalized `dm_<name>` dataset.
+- `--data-prefix`: explicit run artifact prefix, for example `/tmp/run/warehouse-demo` for `/tmp/run/warehouse-demo-WAREHOUSE-MANIFEST.json`.
+- `--dry-run`: prints the full `bq ls`, docs probe, metric list, load, source, preview, and create plan without executing commands or requiring credentials. It still writes the SQL files and renders `warehouse/GAPS.md` for review.
+
+## Preflight
+
+- The dungeon must have passed `/verify-dungeon` and produced local warehouse
+	files with `writeToDisk: true` and `gzip: false`. Use the exact verified
+	`--data-prefix` and its matching `-WAREHOUSE-MANIFEST.json`; preserve all table
+	files referenced by the manifest. Do not use blanket prune before deployment.
+- Live mode requires `.env` `BEARER_TOKEN` for powertools.
+- Live mode requires working `bq` / gcloud ADC.
+- The dungeon must already have `credentials.projectId` from `/create-project`.
+- The Power Tools runtime principal needs `roles/resourcemanager.projectIamAdmin`
+	to grant project-level `roles/bigquery.jobUser`, and `roles/bigquery.admin`
+	(or equivalent permissions) for dataset creation and ACL changes. The macro
+	grants the Mixpanel principal `roles/bigquery.dataViewer` on the source dataset.
+	Keep these prerequisites; do not describe IAM as currently blocked. The operator
+	confirms the grant is fixed. Local Power Tools revision `7ae78aa` records the
+	successful one-shot live path and legacy `READER`/`WRITER`/`OWNER` ACL fix.
+	This audit used local evidence only and made no live calls.
+
+## Warnings
+
+- `bq load --replace` overwrites the destination table contents. Treat live execution as destructive for existing warehouse tables and get explicit user confirmation before running it.
+- `createWarehouseMetric` does not validate SQL. This skill previews every query first so the summary means something.
+- `source_id` is immutable on update. This flow is create-or-skip by metric name; it does not try to update a metric onto a new source.
+- `refreshWarehouseMetric` only invalidates cache. It does not execute the query.
+
+## Preview gotcha
+
+`previewWarehouseMetric` rejects raw SQL containing `DROP`, `DELETE`, `TRUNCATE`, `ALTER`, `CREATE`, `INSERT`, or `UPDATE` as plain substrings. That means `created_at` trips `CREATE` and `updated_at` trips `UPDATE`.
+
+This skill fails clearly in that case. It does not pretend preview succeeded. It also does not auto-rewrite the SQL. Aliasing only helps if the blocked text disappears from the query entirely. If the generated table uses one of those names, rename the column or finish the metric manually.
+
+## Typical flow
+
+### 1. Show the plan
+
+```bash
+node .claude/skills/warehouse-metrics/deploy.mjs <dungeon-path> --data-prefix <verified-prefix> --dry-run
+```
+
+Review the printed commands, the emitted SQL files, and the rendered `warehouse/GAPS.md`.
+
+### 2. Confirm live execution
+
+Live mode writes or replaces BigQuery tables and saves metrics into a real Mixpanel project. Confirm with the user before running it.
+
+### 3. Run live
+
+```bash
+node .claude/skills/warehouse-metrics/deploy.mjs <dungeon-path> --data-prefix <verified-prefix>
+```
+
+### 4. Report
+
+Relay:
+
+- dataset loaded
+- source id returned by `/macro/setup-bq-warehouse`
+- metrics saved vs skipped by name
+- SQL file paths
+- whether `warehouse/GAPS.md` was written or an older one was intentionally left in place
+
+## Error handling
+
+- A missing manifest or missing warehouse files is a hard stop. Tell the user to run `node scripts/run-dungeon.mjs <dungeon>` first, or pass `--data-prefix`.
+- A `GET /crud/getWarehouseMetrics` 404 is the only fallback. The script still loads tables and connects the source, then writes `warehouse/GAPS.md` instead of pretending metrics were saved.
+- Any other docs probe error, `bq` failure, preview failure, or create failure surfaces immediately. No catch-and-continue.
+- Existing `warehouse/GAPS.md` is never deleted silently. If a new one is written, the script says so. If CRUD is now available, the old file is left in place and reported as stale.