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

package/.claude/skills/analyze-soup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: analyze-soup
 description: Use when investigating TimeSoup parameters, diagnosing event-distribution shape, or comparing soup configs — runs a dungeon locally and analyzes time distribution at week/day/hour/minute granularities, producing a soup-analysis.md diagnostic report.
-argument-hint: [dungeon path, e.g. dungeons/technical/simplest.js]
+argument-hint: '[dungeon path, e.g. dungeons/technical/simplest.js]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -10,6 +10,12 @@ effort: max
 
 Run a dungeon and analyze the time distribution of generated events to evaluate TimeSoup parameters.
 
+Analyze user `eventData` / EVENTS shards only. `standaloneEvents` runs on a
+fixed cadence before the user loop; `warehouseMetrics` materializes tables
+afterward. Neither measures TimeSoup. Report their cadence or table checks
+separately through `/verify-dungeon`, and preserve warehouse files for
+`/warehouse-metrics`. Never count standalone synthetic ids as people.
+
 **Dungeon file:** `$ARGUMENTS` (default: `dungeons/technical/simplest.js`)
 
 ## Step 1: Run the Dungeon
@@ -17,15 +23,20 @@ Run a dungeon and analyze the time distribution of generated events to evaluate
 Run the dungeon with forced local-only settings:
 
 ```bash
-npm run prune
-node -e "
+node --input-type=module -e "
 import generate from './index.js';
 import config from './$ARGUMENTS';
-const result = await generate({ ...config, writeToDisk: true, format: 'json', token: '', verbose: true, name: 'soup-analysis' });
+const result = await generate({ ...config, writeToDisk: true, gzip: false, format: 'json', token: '', verbose: true, name: 'soup-analysis' });
 console.log('Events:', result.eventCount, 'Users:', result.userCount);
 "
 ```
 
+Choose an unused run name before executing; `soup-analysis` below is an example.
+Record the explicit data prefix (`data/soup-analysis`) and use it in every query.
+If that prefix already exists, choose another and update the query paths. Do not
+prune or overwrite an earlier run. Use `<prefix>-EVENTS*.json` with
+`union_by_name=true` for batched output; never glob STANDALONE or WAREHOUSE into it.
+
 Wait for generation to complete. Note the event count and EPS.
 
 ## Step 2: Query with DuckDB
@@ -147,7 +158,7 @@ Create `soup-analysis.md` with the structure below. For a user dungeon
 (`dungeons/user/<name>/<name>.js`) write it into the dungeon's folder
 (`dungeons/user/<name>/soup-analysis.md`) — everything about a dungeon lives in
 its folder. Otherwise write it to the project root. (The generated
-`./data/soup-analysis-EVENTS.json` is throwaway verification data — leave it in
+`./data/soup-analysis-EVENTS.json` is retained verification data; leave it in
 `./data/`.) Contents:
 
 1. **Config**: The soup parameters used (peaks, deviation, mean, numDays)
@@ -163,10 +174,9 @@ its folder. Otherwise write it to the project root. (The generated
 - **Last day spike**: < 1.5x average = PASS, < 2x = WARN, > 2x = FAIL
 - **Hourly pattern**: Should show visible peaks but no single hour > 5x average
 
-## Step 4: Cleanup
-
-```bash
-npm run prune
-```
+## Step 4: Preserve artifacts
 
-Remove `soup-analysis.md` only if the user asks. It's meant to persist for comparison across runs.
+Record the prefix and files in the report. Keep warehouse tables and the matching
+manifest until deployment completes. Cleanup requires user consent and an explicit
+list of this run's files. Never run blanket prune. Keep `soup-analysis.md` for
+comparison across runs unless the user asks to remove it.

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

@@ -1,7 +1,7 @@
 ---
 name: create-dungeon
-description: Use when authoring a new dungeon-master config from an app description — designs events, funnels, properties, identity model, and macro/soup. SCHEMA ONLY; engineered story trends + hooks are added separately by write-hooks.
-argument-hint: [free-text app description, e.g. "AI meeting assistant" or "B2B logistics platform"]
+description: Use when authoring a new dungeon-master config from an app description, including standaloneEvents cadence streams and warehouseMetrics source tables. Designs events, funnels, properties, identity model, and macro/soup. SCHEMA ONLY; engineered story trends and hooks are added separately by write-hooks.
+argument-hint: '[free-text app description, e.g. "AI meeting assistant" or "B2B logistics platform"]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -87,9 +87,9 @@ import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc.js";
 dayjs.extend(utc);
 import "dotenv/config";
-import * as u from "../../lib/utils/utils.js";
+import * as u from "../../../lib/utils/utils.js";
 import * as v from "ak-tools";
-/** @typedef {import("../../types").Dungeon} Config */
+/** @typedef {import("../../../types").Dungeon} Config */
 
 // ── OVERVIEW ──
 /*
@@ -133,8 +133,8 @@ const config = {
   numUsers: NUM_USERS,
   avgEventsPerUserPerDay: EVENTS_PER_DAY,
   format: "json",
-  gzip: true,
-  writeToDisk: false,
+  gzip: false,
+  writeToDisk: true,
   concurrency: 1,
   macro: "flat",   // optional — see "Trend shape" below
   soup: "growth",  // optional
@@ -319,7 +319,40 @@ group attributes. Skip for B2C apps.
 Slowly-changing dimensions for plan tier, role, etc. JSDoc on `SCDProp` covers
 type/frequency/timing/values/max.
 
-### 7. Hook function — DO NOT WRITE
+### 7. Metric data surfaces (v1.8.0)
+
+Author these schemas here when the app needs system telemetry or warehouse tables.
+Requests that call these surfaces "v2" still target v1.8.0; do not bump the version.
+
+| Surface | Required design | Time settings | Output |
+|---|---|---|---|
+| `standaloneEvents` | `event`, declared `dimensions` and `properties`; optional `distinctIdFrom` naming a dimension | `cadence: 'hour'`, `'day'`, or `'week'` | `result.standaloneEventData`, `-STANDALONE*.json`; imports as events |
+| `warehouseMetrics` | `name`, `type: 'additive'` or `'point-in-time'`, `source`; declare extra `columns` | `grain: 'day'`, `'week'`, or `'month'`, optional `history` bucket count | `result.warehouseMetricData`, `-WAREHOUSE-*` tables and `-WAREHOUSE-MANIFEST.json`; separate deploy |
+
+`standaloneEvents` generates before the user loop. Each cadence tick emits one
+record per dimension cross-product row. Its synthetic `distinct_id` identifies a
+series, never a person. Do not put these events in funnels, retention, identity
+stitch checks, or people counts. They do not inherit user metadata or superProps.
+
+Standalone property functions receive `{ time, config, dimensions, tickIndex,
+tickCount, cadence, event }`, with `time` in milliseconds. Guard `tickCount <= 1`
+before dividing by `tickCount - 1`. Declare every property and dimension here.
+
+Warehouse sources reference only user `events[]`, including names in both
+`source.event` (plus) and optional `source.minus`. A `standaloneEvents` stream
+cannot be a warehouse source. Declare `source.property` and every `source.groupBy`
+key on every plus and minus event, or in `superProps`. `sum` and `avg` require
+`source.property`; point-in-time disallows `avg` and `dau`. Use at most two group
+keys. `sparse: true` applies only to point-in-time metrics.
+
+Warehouse materialization runs after the user loop. Extra column functions receive
+`{ value, row, time, bucketIndex, bucketCount, grain, isBackfill, seriesKey, spec,
+config }`. `time` is milliseconds. `history` adds synthetic pre-window buckets;
+it does not create historical user events. Keep `timeColumn`, `valueColumn`, group
+keys, and extra `columns` distinct and declared. Read `dungeons/technical/warehouse.js`
+and the warehouse interfaces in `types.d.ts` before choosing measures or backfill.
+
+### 8. Hook function — DO NOT WRITE
 
 Skip the `hook:` field entirely (engine defaults to pass-through). The
 `write-hooks` skill picks this up and engineers the trends.
@@ -620,10 +653,16 @@ This keeps `dungeons/user/` organized — EVERYTHING about this dungeon lives in
 the same folder: `hook-results.md` + `hook-query-log.txt` +
 `<name>-verifications.sql` (from `verify-dungeon`), `soup-analysis.md` (from
 `analyze-soup`), briefs, schema CSV/JSON, example data. The only thing kept
-outside is the throwaway verification data the runs write to `./data/` (cleaned
-after).
+outside is the verification data the runs write to `./data/`. Preserve the exact
+run prefix and its files until verification and warehouse deployment are complete.
 
 Do NOT inject hooks. Do NOT use `subscription`, `attribution`, `geo`,
 `features`, or `anomalies` (the engine will silently strip them and warn).
 
-When done, tell the user the next skill to run.
+When done, hand off to `/write-hooks` when trends are needed, then `/verify-dungeon`.
+For artifact generation use local `writeToDisk: true`, `format: 'json'`,
+`gzip: false`, and an explicit unique run name. Verification runs must disable
+sending with a top-level `token: ''` override. Provision with `/create-project`
+after verification. If `warehouseMetrics` exists, route to `/warehouse-metrics`
+with the verified disk artifact prefix after project provisioning. Keep those
+files; ordinary event import does not deploy warehouse tables.

package/.claude/skills/create-project/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: create-project
 description: Use when an existing dungeon needs a real Mixpanel project provisioned before sending data — creates the project, sets timezone UTC, mints a scoped service account, adds the dungeon's group keys, uploads business context (AI context), and writes the resulting credentials back into the dungeon so it "just runs". Follows create-dungeon / write-hooks / verify-dungeon.
-argument-hint: [dungeon path, e.g. dungeons/user/shopstream/shopstream.js]
+argument-hint: '[dungeon path, e.g. dungeons/user/shopstream/shopstream.js]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -25,7 +25,7 @@ in order:
 1. **createProject** — name derived from the dungeon's `OVERVIEW` (`NAME:` line), region `US`, timezone `UTC` (set as a follow-up by the endpoint).
 2. **mintServiceAccount** — `admin`, expires `+30 days`, scoped to the new project. This is what the dungeon uses to **send** data.
 3. **addGroupKey** — one per `groupKeys` entry in the dungeon (`property_name` + a titleized `display_name`). Skipped if the dungeon has no group keys.
-4. **setBusinessContext** — markdown built from the dungeon's `OVERVIEW` comment block plus the `stories` named export (per story: `narrative` + `mixpanelReport` + intentional deviations); dungeons without stories fall back to the `HOOK STORIES` comment scrape (via the package's `extractComments`). Plus an events/funnels/props/group-keys summary, capped at 50k chars. The dry-run plan prints which source was used.
+4. **setBusinessContext** — markdown built from the dungeon's `OVERVIEW` comment block plus the `stories` named export (per story: `narrative` + `mixpanelReport` + intentional deviations); dungeons without stories fall back to the `HOOK STORIES` comment scrape (via the package's `extractComments`). Plus an events/funnels/props/group-keys summary and separate standalone-event and warehouse-metric summaries, capped at 50k chars. The dry-run plan prints which source was used.
 5. **write-back** — replaces the dungeon's `credentials: { … }` block with `{ token, projectId, serviceAccount, serviceSecret, region }`.
 
 **Always creates a fresh project.** Re-running mints a new project and overwrites
@@ -83,7 +83,26 @@ run command:
 node scripts/run-dungeon.mjs <dungeon-path>
 ```
 
-## Error handling
+## Metric handoff (v1.8.0)
+
+Verify `standaloneEvents` and `warehouseMetrics` locally before provisioning.
+Keep the verified run's disk files and record its explicit prefix. Cadence events
+import through the normal send path; their synthetic `distinct_id` values must
+never become people counts or identity-model evidence.
+
+After credentials are written, route `warehouseMetrics` to `/warehouse-metrics`
+with that prefix and `credentials.projectId`. Require local uncompressed table
+files (`writeToDisk: true`, `gzip: false`) and the matching warehouse manifest.
+Review the deploy dry run before obtaining consent for live writes. Project
+provisioning alone does not load BigQuery tables or save warehouse metrics.
+
+The pure `context.mjs` helper summarizes cadence, dimension keys and cardinalities,
+property names, and synthetic identity separately from person events. Warehouse
+summaries include sources, measures, grain, type, point-in-time baseline, history,
+dimension and output columns, aggregation, and the separate deployment handoff.
+It does not evaluate property functions or include config credentials.
+
+## Provisioning errors
 
 - **Missing `BEARER_TOKEN` / `ORG_ID`** — orchestrator exits; have the user fix `.env`.
 - **`createProject` fails** — nothing is provisioned; surface the power-tools error (`{ error }` or `{ errors:[{param,message}] }`) verbatim and stop.

package/.claude/skills/create-project/context.mjs

@@ -0,0 +1,89 @@
+export function buildContext(name, config, comments, groupKeys, stories) {
+	const parts = [`# ${name}`, ''];
+	if (comments.overview) parts.push(comments.overview, '');
+
+	if (stories?.length) {
+		parts.push('## Engineered Behaviors', '');
+		parts.push(`${stories.length} machine-verified story patterns (from the dungeon's \`stories\` export):`, '');
+		for (const s of stories) {
+			const arch = s.archetype ? ` — ${s.archetype}` : '';
+			parts.push(`### ${s.id}${arch}`, '');
+			if (s.narrative) parts.push(String(s.narrative).trim(), '');
+			if (s.mixpanelReport && typeof s.mixpanelReport === 'object') {
+				parts.push('How to see it in Mixpanel:');
+				for (const [k, v] of Object.entries(s.mixpanelReport)) {
+					parts.push(`- **${k}**: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
+				}
+				parts.push('');
+			}
+			if (Array.isArray(s.intentionalDeviations) && s.intentionalDeviations.length) {
+				parts.push('Notes:', ...s.intentionalDeviations.map((d) => `- ${d}`), '');
+			}
+		}
+	} else if (comments.hookStories) {
+		parts.push('## Engineered Behaviors', '', comments.hookStories, '');
+	}
+
+	parts.push('## Schema', '');
+	const events = config.events || [];
+	parts.push(`### Events (${events.length})`);
+	for (const e of events) {
+		const props = e.properties ? Object.keys(e.properties).join(', ') : '';
+		const weight = e.weight != null ? ` (weight ${e.weight})` : '';
+		parts.push(`- ${e.event}${weight}${props ? ` — ${props}` : ''}`);
+	}
+	parts.push('');
+
+	const funnels = config.funnels || [];
+	if (funnels.length) {
+		parts.push(`### Funnels (${funnels.length})`);
+		for (const f of funnels) {
+			const seq = (f.sequence || []).join(' → ');
+			const rate = f.conversionRate != null ? ` (${f.conversionRate}%)` : '';
+			parts.push(`- ${f.name || '(unnamed)'}: ${seq}${rate}`);
+		}
+		parts.push('');
+	}
+
+	if (groupKeys.length) {
+		parts.push('### Group keys', ...groupKeys.map((g) => `- ${g.property_name} (${g.display_name})`), '');
+	}
+
+	const standaloneEvents = config.standaloneEvents || [];
+	if (standaloneEvents.length) {
+		parts.push(`### Standalone events (${standaloneEvents.length})`);
+		parts.push('Cadence streams use the normal event send path. Their synthetic distinct_id values are never people counts or identity-model evidence.', '');
+		for (const stream of standaloneEvents) {
+			const dimensions = Object.entries(stream.dimensions || {}).map(([key, values]) => `${key} (${values.length} values)`);
+			const properties = Object.keys(stream.properties || {});
+			const identity = stream.distinctIdFrom ? `dimension ${stream.distinctIdFrom}` : 'event name';
+			parts.push(`- ${stream.event}: cadence ${stream.cadence ?? 'day'}; dimensions ${contextList(dimensions)}; properties ${contextList(properties)}; synthetic distinct_id from ${identity}`);
+		}
+		parts.push('');
+	}
+
+	const warehouseMetrics = config.warehouseMetrics || [];
+	if (warehouseMetrics.length) {
+		parts.push(`### Warehouse metrics (${warehouseMetrics.length})`);
+		parts.push('Sum adds buckets; LastValue reads the latest snapshot.', '');
+		parts.push('Separate /warehouse-metrics deployment is required; provisioning and sendToMixpanel do not load warehouse tables or save warehouse metrics.', '');
+		for (const metric of warehouseMetrics) {
+			const type = metric.type ?? 'additive';
+			const source = metric.source;
+			const aggregation = type === 'point-in-time' ? 'LastValue' : 'Sum';
+			parts.push(`- ${metric.name}: type ${type}; grain ${metric.grain ?? 'day'}; history ${metric.history ?? 0} periods before the event window; sparse ${metric.sparse ?? false}; Mixpanel aggregation ${aggregation}`);
+			if (type === 'point-in-time') parts.push(`  baseline ${metric.baseline ?? 0} (point-in-time starting level)`);
+			parts.push(`  source events ${contextList(source.event)}; minus ${contextList(source.minus)}; measure ${source.measure ?? 'count'}; property ${source.property ?? '(none)'}; where ${source.where ? 'present (function, not evaluated)' : '(none)'}`);
+			parts.push(`  columns: time ${metric.timeColumn ?? 'date'}; value ${metric.valueColumn ?? 'value'}; groupBy ${contextList(source.groupBy)}; extra ${contextList(Object.keys(metric.columns || {}))}`);
+		}
+		parts.push('');
+	}
+
+	let md = parts.join('\n');
+	if (md.length > 50000) md = md.slice(0, 49900) + '\n\n…(truncated to 50,000 chars)';
+	return md;
+}
+
+function contextList(value) {
+	return (Array.isArray(value) ? value.join(', ') : value) || '(none)';
+}

package/.claude/skills/create-project/provision.mjs

@@ -32,6 +32,7 @@ import path, { dirname, resolve } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import dotenv from 'dotenv';
 import { loadFromFile, extractComments } from '../../../index.js';
+import { buildContext } from './context.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(__dirname, '../../../');
@@ -204,66 +205,6 @@ function isoInDays(days) {
 	return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
 
-function buildContext(name, config, comments, groupKeys, stories) {
-	const parts = [`# ${name}`, ''];
-	if (comments.overview) parts.push(comments.overview, '');
-
-	// Preferred source: the stories export — each story's narrative is the
-	// human-readable behavior and mixpanelReport (free-form object) points at
-	// the report where it shows. Comment scrape is the fallback for dungeons
-	// without stories (schema-only or pre-1.6).
-	if (stories?.length) {
-		parts.push('## Engineered Behaviors', '');
-		parts.push(`${stories.length} machine-verified story patterns (from the dungeon's \`stories\` export):`, '');
-		for (const s of stories) {
-			const arch = s.archetype ? ` — ${s.archetype}` : '';
-			parts.push(`### ${s.id}${arch}`, '');
-			if (s.narrative) parts.push(String(s.narrative).trim(), '');
-			if (s.mixpanelReport && typeof s.mixpanelReport === 'object') {
-				parts.push('How to see it in Mixpanel:');
-				for (const [k, v] of Object.entries(s.mixpanelReport)) {
-					parts.push(`- **${k}**: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
-				}
-				parts.push('');
-			}
-			if (Array.isArray(s.intentionalDeviations) && s.intentionalDeviations.length) {
-				parts.push('Notes:', ...s.intentionalDeviations.map((d) => `- ${d}`), '');
-			}
-		}
-	} else if (comments.hookStories) {
-		parts.push('## Engineered Behaviors', '', comments.hookStories, '');
-	}
-
-	parts.push('## Schema', '');
-	const events = config.events || [];
-	parts.push(`### Events (${events.length})`);
-	for (const e of events) {
-		const props = e.properties ? Object.keys(e.properties).join(', ') : '';
-		const weight = e.weight != null ? ` (weight ${e.weight})` : '';
-		parts.push(`- ${e.event}${weight}${props ? ` — ${props}` : ''}`);
-	}
-	parts.push('');
-
-	const funnels = config.funnels || [];
-	if (funnels.length) {
-		parts.push(`### Funnels (${funnels.length})`);
-		for (const f of funnels) {
-			const seq = (f.sequence || []).join(' → ');
-			const rate = f.conversionRate != null ? ` (${f.conversionRate}%)` : '';
-			parts.push(`- ${f.name || '(unnamed)'}: ${seq}${rate}`);
-		}
-		parts.push('');
-	}
-
-	if (groupKeys.length) {
-		parts.push('### Group keys', ...groupKeys.map((g) => `- ${g.property_name} (${g.display_name})`), '');
-	}
-
-	let md = parts.join('\n');
-	if (md.length > 50000) md = md.slice(0, 49900) + '\n\n…(truncated to 50,000 chars)';
-	return md;
-}
-
 function writeBackCredentials(p, creds) {
 	let src = readFileSync(p, 'utf-8');
 	const block =

package/.claude/skills/headless-build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: headless-build
 description: Use after a dungeon's data is loaded into a real Mixpanel project — builds the full demoable environment with mixpanel-headless (dashboards, charts, Lexicon, cohorts, custom properties, behaviors/metrics/formulas, annotations) targeted at that dungeon's engineered stories, then verifies the stories still read live. Final step after create-dungeon / write-hooks / verify-dungeon / create-project.
-argument-hint: [dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]
+argument-hint: '[dungeon path, e.g. dungeons/user/nyc-dcp/nyc-dcp.js]'
 model: claude-opus-4-6
 effort: max
 ---
@@ -14,6 +14,23 @@ Last step of the pipeline:
 /create-dungeon → /write-hooks → /verify-dungeon → /create-project → /headless-build
 ```
 
+For `warehouseMetrics`, insert `/warehouse-metrics` after verification and project
+provisioning, before this build. Use the verified local disk artifact prefix.
+Ordinary event import loads `standaloneEvents` but does not deploy warehouse tables.
+
+Keep cadence and warehouse metrics separate from people analyses. Synthetic
+standalone `distinct_id` values identify series; never count them as users or
+include them in funnels, retention, or identity stitching. Build aggregate reports
+from their declared numeric properties and dimensions.
+
+For warehouse-backed charts, read the manifest and saved metric ids from the
+warehouse handoff. `history` may extend the metric window before the user-event
+window; preserve that range and label synthetic backfill. Check saved definitions
+and `previewWarehouseMetric` results before narrating values. A successful
+`refreshWarehouseMetric` only invalidates cache; it does not execute the query.
+Use the existing `/macro/setup-bq-warehouse` flow through `/warehouse-metrics`
+for source setup. Do not reimplement source creation or IAM grants in build code.
+
 The project already has data. This skill builds everything a human sees: themed
 dashboards whose narrative is computed from the live data, an annotated Lexicon,
 saved cohorts and custom properties, saved behaviors/metrics/formulas, and

package/.claude/skills/powertools/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: powertools
 description: Use when any task needs the Mixpanel Power Tools API ("use powertools") — schema export (get-schema), event volumes, project CRUD, query methods, macros, or snapshotting a prod project's schema to copy it into a dungeon. Companion to create-project (which handles provisioning specifically).
-argument-hint: [what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]
+argument-hint: '[what to do, e.g. "get schema for project 12345" or "copy project 12345 into a dungeon"]'
 ---
 
 # Power Tools API
@@ -43,6 +43,25 @@ node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token
 
 ## Endpoint catalog (the useful subset)
 
+### Warehouse handoff (v1.8.0)
+
+For a dungeon with `warehouseMetrics`, use `/warehouse-metrics` after local
+verification produces disk tables and a manifest, and `/create-project` writes
+the project id. Pass the explicit verified `--data-prefix`; preserve those files.
+That skill owns load, source setup, SQL preview, and metric create-or-skip.
+Reuse `/macro/setup-bq-warehouse` through `pt.mjs`; do not reimplement its
+source creation, GCP IAM grant, or dataset ACL handling here.
+
+Warehouse metric endpoints include `getWarehouseMetrics`, `previewWarehouseMetric`,
+`createWarehouseMetric`, and `refreshWarehouseMetric` in the `/crud` family.
+Read endpoint docs before live use. Preview executes the read query; create does
+not validate SQL, and refresh only invalidates cache. A docs-route 404 uses the
+warehouse skill's manual-setup fallback; other errors must surface.
+
+`standaloneEvents` imports as a separate event stream through the ordinary sender.
+Its synthetic ids are series keys, so schema snapshots and dashboard counts must
+distinguish cadence telemetry from user `events[]`. It is not a warehouse source.
+
 GET the path for full docs. Full list: GET `/` and GET `/macro`.
 
 **crud** — 187 endpoints. GET `/crud` for the full list.

package/.claude/skills/release-check/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: release-check
+description: "Use before a dungeon-master release to audit versioned docs, skills, tests, determinism, package contents, and Git state; report release blockers and prepare an explicitly authorized PR and merge handoff."
+argument-hint: "[version, e.g. 1.8.0] [optional base branch]"
+---
+
+# Release check
+
+Check the current checkout before release. Read `AGENTS.md`, `package.json`,
+the target changelog entry, and its upgrade guide. Default to validation only.
+Never publish to npm unless the user gives explicit authorization for npm publishing.
+An instruction to merge a PR is not permission to publish a package.
+
+## Establish the release scope
+
+1. Inspect `git status --short`, the current branch, remotes, and recent history.
+   Preserve unrelated changes. Never reset or clean the worktree to make checks pass.
+2. Confirm the requested version matches `package.json`, the lockfile, changelog,
+   and guide. Do not invent a release date or bump a version without authorization.
+3. Compare the release diff against the base branch. Check exports, dependencies,
+   config defaults, compatibility notes, examples, and migration instructions.
+4. Inspect test setup before running it. This repo's suite prunes `data/` and `tmp/`.
+   If pending deployment artifacts exist, preserve them outside those directories
+   or obtain consent before running the suite. Do not silently delete verified inputs.
+
+## Run executable gates
+
+Use `set -o pipefail` for every piped command. Keep all Vitest output behind
+`2>&1 | tail -50`; a successful tail command alone is not passing evidence.
+
+```bash
+set -o pipefail
+npm test 2>&1 | tail -50
+npm run typecheck
+git diff --check
+npx vitest run tests/unit/engine-shape-canary.test.js 2>&1 | tail -50
+RUN_FULL_SWEEP=1 npx vitest run tests/e2e/engine-shape-full-sweep.test.js 2>&1 | tail -50
+node tests/engine/smoke-test-all.mjs
+npm pack --dry-run --json
+```
+
+Run commands separately or chain with `&&` so a failure cannot disappear behind
+a later success. Record exit codes, pass/skip counts, and the tested commit/diff.
+The smoke script discovers vertical dungeons only. Verify changed technical or
+customer fixtures separately with the existing verification runners.
+
+For generation changes, require the event-stream determinism test. Compare runs
+with the same seed, pinned window, and `concurrency: 1`; strip only `insert_id`.
+Use sequential test cases because the RNG is shared. Include warehouse noise in
+warehouse determinism checks. Never accept an unrun or failing determinism gate.
+
+## Audit docs and skills
+
+- Run `tests/e2e/skills-contract.test.js`. Parse YAML frontmatter rather than
+  guessing from appearance: names match folders, descriptions are strings, and
+  `argument-hint` is a quoted string.
+- The canonical skills live in `.claude/skills`. Verify `.agents/skills` and
+  `.github/skills` resolve to that directory. Do not duplicate skill content.
+- Check README, HOOKS, type comments, changelog, and guide against actual code.
+  Do not carry stale test counts, old skill paths, or historical operational
+  failures forward as current release claims.
+- Follow the complete handoff: author, optional hooks, verify, provision,
+  generate/import, optional `/warehouse-metrics`, then headless build.
+- Distinguish user events, identity-less `standaloneEvents`, and warehouse rows.
+  Synthetic IDs are not people. Standalone hooks return retained records;
+  warehouse hooks mutate rows and ignore returns. Preserve deployment artifacts.
+- If API integrations changed, read the current endpoint docs and local handback.
+  Distinguish docs discovery, mocked execution, dry-run, and live verification.
+  Live writes require explicit authorization. Never claim an endpoint GET proves
+  authenticated write permission or end-to-end deployment.
+
+## Inspect the package and internal files
+
+Read the file list from `npm pack --dry-run --json`. Confirm new runtime modules,
+dependencies, scripts, and canonical skill files ship. Reject credentials,
+customer data, `plans/`, `research/`, `.superpowers/`, or obsolete skill paths.
+Check symlink handling in the package separately from workspace discovery.
+
+Verify `git ls-files .superpowers` is empty and `.gitignore` covers the directory.
+Ignoring an already tracked file does not untrack it. Obtain authorization before
+removing index entries; preserve local reports. Archive completed plan folders
+whole under `plans/archived/`; leave active or ambiguous work in place.
+
+## Report and optional shipping handoff
+
+Report blockers first, then evidence, skipped checks, compatibility changes,
+and remaining operational limits. Do not fix unrelated failures or weaken tests.
+
+Only when explicitly requested: inspect all staged files for secrets, commit the
+authorized changes, push the feature branch, create or reuse its PR, and inspect
+CI and mergeability. Require successful completed checks for the current PR head
+before squash merge. If no CI checks are configured, report that explicitly and
+use recorded local release gates; do not describe absent CI as passing. A failed
+release gate requires investigation and an explicit operator decision before shipping.
+Never bypass protections or use admin merge
+to hide a failing check. Confirm the PR is merged before switching local branches.
+Fetch, switch to `main`, and pull with `--ff-only`; stop rather than discard local
+changes or divergent commits. Report the PR URL, merge SHA, current branch, and
+working-tree status. Leave npm publishing to the operator unless separately authorized.