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

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)
@@ -158,15 +169,23 @@ its folder. Otherwise write it to the project root. (The generated
 6. **Assessment**: Overall quality judgment and recommendations
 
 ### Quality Criteria
+
+These thresholds are diagnostic heuristics, not alignment acceptance criteria.
+Interpret them against the configured macro, soup, resolved window, and intentional
+hook effects. Read the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md)
+for proof scope. Report insufficient observations separately from shape failures.
+Include empty buckets and identify partial buckets before computing distribution
+statistics; the SQL above reports observed buckets only. Sparse or partial buckets
+alone do not establish a distribution defect.
+
 - **Daily CV**: 0.2-0.6 is ideal (some variation, not flat or spiky)
 - **Max-to-avg ratio**: < 2.0 at daily level, < 3.0 at hourly level
 - **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
 ---
@@ -35,11 +35,12 @@ In scope here:
   - `credentials: { token, region, serviceAccount, serviceSecret, projectId }`
   - `switches: { hasLocation, hasCampaigns, hasSessionIds, hasAvatar,
     hasIOSDevices, hasAndroidDevices, hasDesktopDevices, hasBrowser,
-    isAnonymous, alsoInferFunnels, hasAdSpend, hasAttributionFlags }`
+    isAnonymous, alsoInferFunnels, hasAdSpend }`
   - `identity: { avgDevicePerUser, sessionTimeout }`
 
   Old top-level keys keep working (verbose warn nudges migration), but new
   dungeons should ship the sub-object shape.
+  `hasAttributionFlags` is derived from `events[].isAttributionEvent`; do not set it.
 - Surviving advanced entities: `personas`, `worldEvents`, `engagementDecay`,
   `dataQuality` — use sparingly
 
@@ -64,6 +65,7 @@ see `HOOKS.md` at the project root.
 
 Before writing any code, scan:
 
+- [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md) - report definitions, neutral controls, and proof limits.
 - `types.d.ts` — the complete API reference. Every Dungeon field, EventConfig
   flag, Funnel option, AttemptsConfig, and Hook meta interface is documented
   with full JSDoc. **Treat this as the source of truth.**
@@ -87,9 +89,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 +135,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
@@ -234,8 +236,8 @@ When using experiments, include `$experiment_started` in the events array with
 
 - First funnel: includes `isFirstEvent` AND has `isAuthEvent: true` on the
   identity-transition step.
-- Usage funnels: ordinary sequences without `isFirstFunnel`. Optionally use
-  `attempts` for repeat-usage modeling (abandon-cart pattern).
+- Usage funnels: ordinary sequences without `isFirstFunnel`. Volume and funnel
+  selection control repetitions; `attempts` applies only to born-user first funnels.
 - Pick `conversionRate` between 30 and 80; `timeToConvert` in hours.
 
 Funnel `props` stamp constant properties on all events in that funnel run.
@@ -267,9 +269,9 @@ consumed standalone instances as funnel matches. Set `isStrictEvent: false`
 explicitly only when you intend mixed funnel/standalone semantics for that
 event.
 
-**Mark hook-readable funnel-step events with `isStrictEvent: false`.** When a hook reads `event === 'X'` and `X` is also a funnel step, the validator's auto-promote turns it into `isStrictEvent: true` and the engine stops emitting standalone occurrences — cohort goes empty. Identify these candidates at schema time so `write-hooks` doesn't have to re-thread the schema. Common candidates: login, page view, search, add to cart, swap, deposit — anything that's both a funnel step AND a recurring user behavior hooks will likely cohort on.
+**Use `isStrictEvent: false` when a cohort needs standalone occurrences.** Auto-promotion removes standalone traffic but leaves funnel-generated occurrences readable. Declare the opt-out at schema time only when that extra traffic is part of the intended behavior; a hook reading an event name alone does not require it.
 
-**Funnels representing loops need `reentry: true`.** Any funnel named "X loop" / "X cycle" / "session" / per-instance recurring behavior must declare `reentry: true`. Without it, the engine emits one sequence per user and downstream "power user" / "daily active" cohorts have no behavioral signal to bin on.
+**`reentry` is verifier-only.** Usage volume, funnel selection, and the event budget control generated repetitions. Set `reentry: true` only when the intended report counts repeated histories. It does not generate loops; local totals also default to `reentry: false`.
 
 **Structural trend engineering — duplicate funnels instead of reaching for
 hooks.** Not every trend needs a hook: initial conditions can raise or lower
@@ -294,20 +296,19 @@ to architect a comparison directly into the schema:
 Prefer structure when the story is a *between-path comparison* (this path
 converts worse / slower than that one). Reach for hooks when the story is a
 *within-cohort behavior* (these users do more of X over time, this segment's
-values differ). Structural trends are cheaper to verify — the knob IS the
-expected value.
+values differ). Structural trends still need report-level proof: competing
+histories, saturation, and finite budgets can change the observed effect.
 
 ### 3. SuperProps (2–3)
 
 Properties present on EVERY event. Common picks: `Plan`, `Region`, `Platform`,
-`App Version`. Values must come from same enumerations used in `userProps` for
-consistency.
+`App Version`. Matching `userProps` enumerations only shares a value domain.
+Use `stickyEventProps` for values that must match each user's profile.
 
 ### 4. UserProps (4–8)
 
-User profile properties. Set once per user. Use enumerations whose values
-match `superProps` for any overlapping keys (so per-event Region matches per-user
-Region).
+User profile properties. Set once per user. Declare overlapping event keys in
+`superProps` and use `stickyEventProps` when profile/event equality is required.
 
 ### 5. Groups (0–2)
 
@@ -319,7 +320,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.
@@ -384,9 +418,9 @@ Typical ranges:
 
 - Direct-acquisition first funnels: `{ min: 0, max: 0 }` (single attempt) or omit
 - Shared-link / friction-heavy onboarding: `{ min: 0, max: 2 }` (some retry)
-- Re-engagement / abandon-cart usage funnels: `{ min: 0, max: 3 }`
+- Usage funnels do not consume this retry plan; model their repetitions through usage selection and volume.
 
-When set, `attempts.conversionRate` (optional) overrides `funnel.conversionRate`
+For a born user's first funnel, `attempts.conversionRate` (optional) overrides `funnel.conversionRate`
 on the FINAL attempt. Failed prior attempts truncate before the first
 `isAuthEvent` step (no stitch fires for those attempts).
 
@@ -471,12 +505,12 @@ intra-day rhythm). Only override when you have a specific reason:
 
 ### Macro × born% / bias compatibility (strict clamps)
 
-When you set `macro` AND `percentUsersBornInDataset` explicitly, the validator
-clamps born% to the macro's preset value: flat=12, steady=12, growth=30,
-viral=55, decline=5. Same for `bornRecentBias` outside `[-0.5, 0.5]`. If you
-need higher born% (e.g., "this app launched mid-window — every user is in the
-dataset"), switch macros first (flat → growth → viral) instead of pushing the
-preset's value. Setting born% without a macro keeps legacy behavior (no clamp).
+The per-preset born% cap applies only to a named preset (`macro: 'growth'` or
+`macro: { preset: 'growth', ... }`) with explicit `percentUsersBornInDataset`:
+flat=12, steady=12, growth=30, viral=55, decline=5. A custom macro object without
+`preset` has no per-preset cap; own and verify its shape. The global born% clamp
+to [0,100] still applies. Explicit `bornRecentBias` is separately clamped to
+[-0.5,0.5], with compound protection for high born% and bias. Preset bias is exempt.
 
 The clamp warning explains why and points to safe alternatives — read it.
 
@@ -541,18 +575,19 @@ Top-level optional knob. Shape retention via log-linear interpolation
 between waypoints. Independent of `engagementDecay`.
 
 ```js
-retentionCurve: [
-  { day: 0,  retention: 1.0 },
-  { day: 1,  retention: 0.80 },
-  { day: 7,  retention: 0.50 },
-  { day: 30, retention: 0.20 },
-]
+retentionCurve: {
+  type: 'logarithmic',
+  day1: 0.80,
+  day7: 0.50,
+  day30: 0.20,
+}
 ```
 
-Each born-in-dataset user's events get filtered based on the interpolated
-retention at the event's age-from-first-event-day. Use when you want a
-declarative retention shape at config level (analytical-style D1/D7/D30
-targets) instead of writing hook logic.
+Use `type: 'logarithmic'` (default) or `'linear'`, with `dayN` active-day
+weights; day 0 is implicitly 1. The curve weights the active-day plan and takes
+precedence over `avgActiveDaysPerUser`. It does not directly filter each event
+or guarantee report D1/D7/D30 percentages. Verify mature cohorts and account for
+funnel spill and finite event budgets.
 
 ### `userSeed` (separate distinct_id RNG seed, v1.5+)
 
@@ -568,16 +603,15 @@ userSeed: "users-v1", // user-pool RNG (stable across versions)
 
 ## SuperProp consistency rule
 
-If `superProps` and `userProps` both define a property like `Plan`, the
-enumeration must match exactly. Otherwise users with `userProps.Plan = 'pro'`
-will fire events with `superProps.Plan = 'free'` — Mixpanel will see broken
-breakdowns.
+Matching enumerations do not guarantee profile/event equality: independent draws
+can differ. Declare both keys and project the profile values with `stickyEventProps`.
 
 ```js
 const PLANS = ["Free", "Free", "Free", "Pro", "Pro", "Enterprise"];
 // ...
 superProps: { Plan: PLANS, Region: REGIONS },
 userProps:  { Plan: PLANS, Region: REGIONS, Role: ROLES, ... },
+stickyEventProps: ['Plan', 'Region'],
 ```
 
 ## Verification
@@ -620,10 +654,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
 ---
@@ -16,6 +16,12 @@ This is the step after a dungeon is authored, reviewed, and tweaked. It turns a
 local dungeon into one you can actually send to Mixpanel by creating the project
 and stamping `credentials` back into the file.
 
+Follow the [1.8.1 verification contract](../verify-dungeon/references/alignment-contract.md)
+when carrying verification claims into business context. Preserve the actual report
+definition and explicit counting options. Local evidence is selected source-derived
+verification, not live Mixpanel parity. Provisioning is a separately authorized
+handoff; never run it automatically during offline verification.
+
 ## What it does
 
 All work runs through the orchestrator `provision.mjs` (this skill's directory),
@@ -25,7 +31,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 +89,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 =