@ak--47/dungeon-master 1.6.2 → 1.6.4

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

@@ -315,9 +315,22 @@ function printSummary() {
 		// Defensive: the API's `added`/`skipped` entries may be objects, strings, or
 		// null. Never let summary formatting throw — it would swallow real warnings.
 		const fmt = (g) => (g == null ? null : typeof g === 'string' ? g : (g.property_name || g.name || null));
-		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean).join(', ') || '(none)';
-		console.log(`group keys:     added [${added}]  skipped [${skipped}]`);
+		const added = (groupKeyResult?.added || []).map(fmt).filter(Boolean);
+		const skipped = (groupKeyResult?.skipped || []).map(fmt).filter(Boolean);
+		// `added`/`skipped` are not always populated (a create that lands via a
+		// different code path can return both empty), which made a perfectly good
+		// provision print "added [(none)] skipped [(none)]" and read as a failure.
+		// `all_group_keys` is the authoritative post-state, so report against that
+		// and only fall back to the deltas when it's absent.
+		const all = (groupKeyResult?.all_group_keys || []).map(fmt).filter(Boolean);
+		if (all.length) {
+			const present = groupKeys.map((g) => g.property_name).filter((p) => all.includes(p));
+			const missing = groupKeys.map((g) => g.property_name).filter((p) => !all.includes(p));
+			console.log(`group keys:     in project [${present.join(', ') || '(none)'}]${missing.length ? `  MISSING [${missing.join(', ')}]` : ''}`);
+			if (missing.length) warnings.push(`group keys missing after addGroupKey: ${missing.join(', ')}`);
+		} else {
+			console.log(`group keys:     added [${added.join(', ') || '(none)'}]  skipped [${skipped.join(', ') || '(none)'}]`);
+		}
 	}
 	console.log(`business ctx:   ${content.length} chars uploaded (source: ${ctxSource})`);
 	console.log(`credentials:    ${wroteBack ? 'written back into dungeon ✓' : 'NOT written (see warnings)'}`);

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

@@ -0,0 +1,324 @@
+---
+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]
+model: claude-opus-4-6
+effort: max
+---
+
+# Headless Build — turn a loaded project into a demo
+
+Last step of the pipeline:
+
+```
+/create-dungeon → /write-hooks → /verify-dungeon → /create-project → /headless-build
+```
+
+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
+annotations that explain the engineered moments. Then it re-measures the hook
+stories **against the live project** and fails if they no longer read.
+
+That last step is the point. Local story verification passes on the generated
+array in memory; it never sees what survived ingest. A build can render five
+perfect dashboards on top of a story that silently collapsed on the way in.
+
+## Scope
+
+In scope: dashboards + charts, Lexicon enrichment, cohorts, custom properties,
+behaviors/metrics/formulas, annotations, and live story verification.
+
+Out of scope: changing the dungeon, regenerating or re-sending data. If the data
+is wrong, fix the dungeon and re-run `/create-project` — do not paper over it
+with dashboard copy.
+
+## Prerequisites
+
+- The dungeon's `creds.json` / `credentials` block exists (`/create-project` ran).
+- Data is actually loaded — `00_auth_check.py` fails loudly if not.
+- `uv` available. `mixpanel_headless` is on PyPI, so it needs no local checkout:
+  `uv run --with mixpanel_headless python <script>`.
+
+## Step 0 — ask who creates the entities
+
+**Ask the user before building.** The answer changes who owns every asset:
+
+| Mode | Effect |
+|---|---|
+| **bearer** (recommended) | Entities are created by a real user via OAuth token (`BEARER_TOKEN` in the repo `.env`). They appear in that person's Mixpanel UI with owner access. |
+| **service** | Entities are created by the dungeon's service account. A human then sees **"Your access: None"**, and custom properties have no share endpoint — so it cannot be fixed from the UI at all. Only correct when no OAuth token exists. |
+
+Default to **bearer** whenever a token is available. To use it with
+`mixpanel_headless`, set `MP_OAUTH_TOKEN` and **unset `MP_USERNAME` / `MP_SECRET`** —
+the SDK prefers the service account whenever the full SA env set is present.
+Power-tools calls must use the same principal (`Authorization: Bearer …`), or
+entities created through that path land back under the service account.
+
+## Reference implementation
+
+`dungeons/user/nyc-dcp/build/` is the worked example — read it before writing a
+new one. (It is gitignored with the rest of `dungeons/user/`, so it lives only in
+the working copy.) Peloton's equivalent is
+`/Users/ak/code/mixpanel-headless/ak/customer_peloton/`.
+
+## Layout
+
+Create the build inside the dungeon's own folder:
+
+```
+dungeons/user/<name>/build/
+├── .env                    # MP_USERNAME / MP_SECRET / MP_PROJECT_ID / MP_REGION
+├── _common.py              # window detection, ws factory + retry, helpers, knobs, cohorts
+├── build_all.py            # one-shot orchestrator, --only / --internal / --from-date
+├── scripts/
+│   ├── 00_auth_check.py         # also prints WHO is authenticated
+│   ├── 01_reset_entities.py     # opt-in: delete this build's own entities
+│   ├── 02_custom_props.py
+│   ├── 03_cohorts.py
+│   ├── 04_lexicon.py
+│   ├── 05_dash_start_here.py    # built LAST — links the other boards by id
+│   ├── 06..09_dash_<story>.py   # one board per engineered story
+│   ├── 10_annotations.py
+│   ├── 11_behaviors_metrics.py  # via power-tools; headless lacks these
+│   ├── 13_render_check.py       # saved params must be RENDERABLE, not just queryable
+│   └── 99_verify.py
+└── results/                # entities.json registry, window.json, verification_*.json
+```
+
+## Steps
+
+### 1. Read the dungeon
+
+Pull out, from the dungeon file itself: the `stories` export, the HOOK STORIES
+doc block, the knob constants, the event/property schema, and the VALUE MOMENT.
+**Mirror the knob constants into `_common.py`** so dashboard copy quotes the
+designed value while the charts show the measured one. Never let narrative text
+hardcode a number no longer tied to a knob.
+
+### 2. Probe the project before designing
+
+Capabilities differ per project. Run a throwaway probe and design around what
+actually works. Verified on both NYC DCP and Peloton:
+
+- Insights `group_by` / `where` / saved-cohort filters: **work**.
+- Funnels `group_by`: **silently does not segment** — returns rows identical to
+  ungrouped. Use one funnel per segment with a `where` filter instead.
+- Day-granularity queries reject ranges **over 366 days**. `unit="hour"` works
+  fine, including with `group_by` — that is how you read hour-of-day, since the
+  App API rejects `hour(A)` in a custom-property formula as an unknown function.
+- Valid `displayOptions.chartType`: `bar`, `column`, `frequency-curve`,
+  `funnel-steps`, `funnel-top-paths`, `insights-metric`, `line`, `pie`,
+  `retention-curve`, `table`. There is no `stacked-area` — the API rejects it.
+
+**Filters and breakdowns fail SILENTLY, returning 0 rather than erroring.** Probe
+every one before a board depends on it. Verified on Square:
+
+| Intent | Wrong (returns 0 / "undefined") | Right |
+|---|---|---|
+| Profile property | `Filter.equals("plan", "Pro")` | `Filter.equals("plan", "Pro", resource_type="people")` |
+| Profile property breakdown | `group_by="plan"` | not supported — one query per segment with a user-scoped `where` |
+| Numeric event property | `Filter.equals("depth", 3)` | `Filter.equals("depth", "3")` — as a **string** |
+| Boolean event property | `Filter.equals("flag", True)` | `Filter.is_true("flag")` / `Filter.is_false(...)` |
+| Custom-property breakdown | `group_by="Ticket Band"` | `GroupBy(CustomPropertyRef(<id>))` |
+| Sum of a property | `math="sum"` (raises) | `math="total"` **with** `math_property` |
+| Flows, split by property | `query_flow(where=[Filter.equals(...)])` (raises `Invalid filter type: resourceType`) | cohort filters only — `query_flow(where=[Filter.in_cohort(...)])` |
+
+**Querying successfully is NOT evidence that a report renders.** The single most
+expensive bug in the Square build: `Filter.equals(..., resource_type="user")`
+instead of `"people"`. The SDK's type is `Literal["events", "people"]`, but the
+value is not validated, the query endpoint accepts it, and it returns byte-identical
+numbers — so the build printed correct figures, `99_verify.py` re-measured the story
+live and called it a MATCH, `query_saved_report` executed the saved bookmark without
+complaint, and `get_dashboard_erf` reported `is_valid_for_erf: true`. Six dashboard
+cards nonetheless rendered **"The client has issued a malformed request."** The
+defect only existed in what was *persisted*: `sections.filter[0].resourceType`.
+
+Two rules follow:
+
+- **Never invent an enum value.** If the SDK declares a `Literal`, use one of its
+  members even when another string is accepted and works.
+- **Ship a render check.** `scripts/13_render_check.py` in the Square build walks
+  every saved bookmark on every registered board and fails on any `resourceType`
+  outside `{events, people, user_profiles, cohort}`. It runs as the first step of
+  the `verify` phase, before `99_verify`. Inspect persisted params, not query
+  results — every query-based check passed while the boards were visibly broken.
+
+**Build the new board BEFORE deleting the old one.** The obvious `replace_dashboard`
+(delete by title, then create) means any interruption — and a rate-limit wall
+partway through a board's queries is routine — leaves the project with no board at
+all. Capture the old ids first, create the replacement, then retire the old ones
+(`existing_dashboard_ids` → `publish(..., supersedes=...)` in the Square `_common.py`).
+
+**Budget the per-hour query cap across the whole session, not per run.** Probing,
+building, and verifying all draw on the same hourly allowance. Interactive probes
+early in a session can exhaust it and strand a rebuild hours later. Boards with
+many segment-per-query funnels are the expensive ones — the Square activation board
+alone fires ~30.
+
+**Retention: cohort maturity will eat your effect.** `query_retention` pools every
+cohort in the range, including ones a fortnight old that cannot yet have failed to
+return in week 4, and there is no server-side way to restrict the cohort window.
+On Square the same attach-retention gap read **1.71x pooled and 2.98x** over cohorts
+with a fully observed horizon. Aggregate the frame yourself: weight buckets by cohort
+size, require each bucket to be observed END TO END (`(b+1)*unit - 1` days of history,
+not `b*unit`), and cap the cohort date. Put both numbers on the board — the diluted
+one is what the chart shows, and naming why is a better demo than hiding it.
+
+**Time-to-convert is a MEAN, and means are tail-dominated.** Funnel frames carry
+`avg_time` and `avg_time_from_start` (seconds; not monotonic across steps — each is
+over that step's own survivors). A dungeon knob expressed as a median ratio will not
+reproduce: Square's designed 13x median gap measured 1.95x as a mean over a 30-day
+window. Use the **speed curve** instead — run the same funnel at 1/3/7/14-day
+conversion windows and read what share of each segment's eventual conversions had
+landed by then. Same effect, expressed in a statistic Mixpanel actually computes.
+
+### 3. Auto-detect the data window
+
+Never hardcode dates. A regenerated dungeon lands on new ones and every chart
+silently clips. Probe wide at `unit="month"`, then resolve exact days inside the
+non-empty months (day charts cap at 366 days). Cache to `results/window.json`.
+
+### 4. Build entities, then boards
+
+Order matters: custom properties and cohorts first (boards break down by them),
+Lexicon, behaviors/metrics/formulas, annotations, then dashboards, with the
+"Start Here" board last so it can link the others by id.
+
+Keep a `results/entities.json` registry of every created id — the Start Here
+board and the verifier both read it.
+
+### 5. Write boards that argue, not just render
+
+The difference between a dashboard and a demo:
+
+- **Query first, then narrate.** Compute the numbers live, then interpolate them
+  into text cards. Never write a number by hand.
+- **One board per story**, plus a Start Here tour board.
+- **Normalize rates.** Raw totals carry population and activity; the claim is
+  almost always about intensity. Say which denominator you used and why.
+- **Name the confound.** If a chart could be read two ways, put the alternative
+  in the text card and say what rules it out.
+- **End each board with a "So what"** — the decision the board supports.
+- Text card HTML must be single-line (`" ".join(html.split())`) — TipTap mangles
+  newlines.
+
+**Board titles carry no app prefix.** The project is already the app; a
+`"<App> — "` prefix on every board is noise that eats the readable part of the
+name in the sidebar. Title them `Borough Equity & Access`, not
+`NYC DCP — Borough Equity & Access`.
+
+**Always label the legend.** By default a series reads
+`Data Export [Total Events]` — it names the event and the math, not the thing
+being measured. Mixpanel exposes this as **Rename** on a query block; on the
+wire it is `params.sections.show[i].name` plus `userNamed: true` (the flag is
+what stops the UI regenerating the label). Every insights report should pass a
+plain-English label: `Users`, `Exports`, `Comments Filed`.
+
+**Merge KPI cards into ONE multi-metric report.** Four big-number cards do not
+need four saved reports. Each report is another entity to create and another
+query to run, and the rate limit is the binding constraint on a full build.
+Concatenate the `sections.show` arrays of several single-metric queries into one
+params dict and keep `chart_type="insights-metric"` — Mixpanel still renders big
+numbers, one per metric. Only safe when the inputs share a time range and
+report-level filter, since `sections.filter` applies to the whole report; per-metric
+filters have to move into `show[i].behavior.filters`.
+
+**Share everything, and warm the cohorts.** Two separate failure modes:
+
+- *Unshared* — an entity is visible only to its creator. Call
+  `/crud/shareDash` (`view_only: false`) and `/crud/shareCohort`
+  (`can_edit: true`) for everything you create. There is no share endpoint for
+  custom properties, behaviors, or metrics — which is exactly why bearer auth
+  matters: get the owner right at creation, because you cannot fix it after.
+- *Unwarmed* — cohort membership computes **lazily**. A freshly created cohort
+  reports `count: 0` until something queries it, and a cohort showing 0 members
+  reads as broken in a demo. Run one cheap query per cohort after creating it.
+  Verify counts, not just existence.
+
+### 6. Verify against the live project
+
+`99_verify.py` does two checks:
+
+- **structure** — every registered entity still exists.
+- **stories** — re-measure each hook effect live and compare to the knob.
+
+Report MATCH / DIRECTIONAL / MISS per story and exit non-zero on any MISS.
+Use a wider tolerance than the dungeon's own ±10% bar (~25%): Mixpanel's cohort
+membership is computed over the whole window, not the dungeon's internal binning,
+so depth-band style cohorts will not line up exactly.
+
+### 7. Report
+
+Give the user the board URLs
+(`https://mixpanel.com/project/<pid>/view/<wsid>/app/boards/<id>`), the entity
+counts, and the story verdict table.
+
+## Gotchas that cost real time
+
+**Saved cohort ids, never inline definitions.** `Filter.in_cohort(CohortDefinition(...))`
+is accepted and applied, but every definition collapses to the same membership —
+three different cohorts return byte-identical numbers instead of erroring. Create
+cohorts first, then filter by id: `Filter.in_cohort(<saved_id>, "<name>")`.
+
+**`getCohorts` can report `count: 0` for every cohort** even when they hold thousands
+of members and filter queries correctly. Do not use the listing's count as the
+membership check in `99_verify.py` — run one cheap query per cohort instead. This is
+the same call that warms them, so it costs nothing extra.
+
+**`create_cohort` via headless 500s** on some projects; `CreateCohortParams.definition`
+also wants `.to_dict()`, not the builder object. Use `/crud/createCohort` — see the
+`powertools` skill for the payload shape and its limits (behavioral counts yes;
+profile-property and behavior-nested property filters no).
+
+**Rate limits will kill a full build midway.** A build fires several hundred
+queries; the cap trips after the first couple of boards and the rest fail,
+leaving a half-built project that still looks fine until you count the boards.
+The client must therefore:
+
+- **Issue one request at a time**, with a small fixed gap. Parallelism does not
+  help and actively hurts — the cap is request-rate based, so concurrency only
+  reaches the limit sooner and then every worker sits in backoff together.
+- **Back off hard and genuinely exponentially** on 429: start ~30s, double, cap
+  ~15 minutes, ~7 attempts. The cap is per-hour, so short retries just burn
+  attempts without letting the window refill. Retry transient 502s the same way.
+- **Be resumable.** Keep the entity registry on disk and reuse by name, so a
+  killed build picks up where it stopped instead of duplicating.
+
+On Mixpanel-internal projects `--internal` additionally sends the rate-limit
+bypass headers. It is a no-op elsewhere and does *not* remove the need for
+backoff — it supplements it.
+
+**Fewer entities is a rate-limit strategy, not just tidiness.** Merging four KPI
+cards into one multi-metric report removes three creates and three queries from
+every build. Prefer one report with N metrics wherever the chart allows it.
+
+**`ws._api_client` is lazy** — None immediately after construction. Force it via
+`ws._get_api_client()` before patching request headers.
+
+**Idempotency.** Dashboards: delete-by-title then recreate. Everything else:
+look up by name and reuse. Re-running must never duplicate.
+
+## Commands
+
+```bash
+cd dungeons/user/<name>/build
+set -a && . ./.env && set +a
+
+uv run --with mixpanel_headless python build_all.py --auth bearer        # recommended
+uv run --with mixpanel_headless python build_all.py --auth service       # SA-owned assets
+uv run --with mixpanel_headless python build_all.py --internal           # + rate-limit bypass
+uv run --with mixpanel_headless python build_all.py --only reset --apply # wipe this build's entities
+uv run --with mixpanel_headless python build_all.py --only dashboards verify
+uv run --with mixpanel_headless python build_all.py --skip-lexicon
+uv run --with mixpanel_headless python build_all.py --from-date 2026-04-18 --to-date 2026-08-17
+uv run --with mixpanel_headless python scripts/99_verify.py              # verify only
+```
+
+Phases: `auth`, `reset` (opt-in only), `customprops`, `cohorts`, `lexicon`,
+`entities`, `annotations`, `dashboards`, `verify`.
+
+`reset` is never part of the default order — it deletes entities, and only ever
+the ones this build created, matched by name. Use it when assets were created
+under the wrong principal and must be recreated (there is no way to re-own an
+existing custom property).

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

@@ -45,7 +45,27 @@ node .claude/skills/powertools/snapshot-project.mjs <project_id> --bearer <token
 
 GET the path for full docs. Full list: GET `/` and GET `/macro`.
 
-**crud** — `/crud/createProject`, `/crud/deleteProject`, `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/addGroupKey`, `/crud/setBusinessContext` (all used by the create-project skill's `provision.mjs`).
+**crud** — 187 endpoints. GET `/crud` for the full list.
+
+*Project lifecycle* (used by create-project's `provision.mjs`): `/crud/createProject`, `/crud/deleteProject` (**irreversible** — deletes the project and all its data; needs `org_id`), `/crud/getProjects`, `/crud/mintServiceAccount`, `/crud/deleteServiceAccount`, `/crud/addGroupKey`, `/crud/deleteGroupKey`, `/crud/setBusinessContext`.
+
+*Analysis entities* (used by the `headless-build` skill for what `mixpanel_headless` does not expose): `/crud/createCohort` + `getCohorts`/`getCohort`/`updateCohort`/`deleteCohort`, `/crud/createBehavior` + `getBehaviors`/`deleteBehavior`, `/crud/createMetric` + `getMetrics`/`deleteMetric`, `/crud/createFormula` + `getFormulas`/`deleteFormula`, `/crud/createDash`/`updateDash`/`pinDash`/`duplicateDash`, `/crud/makeInsightsReport`/`makeFunnelsReport`/`makeFlowsReport`/`makeRetentionReport`, `/crud/createCustomProp`, `/crud/createCustomEvent`, `/crud/createAnnotation`, `/crud/createLookupTable`.
+
+### Entity-CRUD response shapes (verified 2026-08-17 — these bite)
+
+Three different shapes across one API family. Assuming a flat list or a flat `results.id` silently yields `None`/empty rather than erroring:
+
+- **create** returns `{"status":"ok","results":{"<id>":{...}}}` — `results` is keyed BY id, so `results["id"]` is None. Take `next(iter(results.values()))["id"]`.
+- **list** (`getBehaviors`/`getMetrics`/`getFormulas`) returns numerically-keyed entries at the **top level** — `{"0":{...},"1":{...},"duration_ms":…}` — with nothing under `results`. Iterate `raw.values()` and keep dicts that carry a `name`+`id`.
+- `getMetrics` and `getFormulas` return the **same combined set** (metrics and formulas share one store), so dedupe by name if you call both.
+
+### Cohort payload limits (verified on project 4054934)
+
+`/crud/createCohort` accepts the native UI shape: `groups[]` of `cohort_group` (each `{type, event:{resourceType:"cohort",value:"$all_users"}, filters[]}`) plus `determiner: "all"|"any"`. What works and what does not:
+
+- ✅ behavioral counts — `customProperty.behavior` + `filterOperator: "is at least"|"is at most"`; multiple filters in one group give a RANGE; multiple groups give AND (`all`) / OR (`any`).
+- ❌ profile-property filters, and property filters nested inside a `behavior` — both fail with `Failed to resolve cohort references`. Express those as report `where` filters instead.
+- New cohorts report `count: 0` at creation; membership computes asynchronously.
 
 **query** — `/query/getTopEvents` (per-event counts, limit≤100 default), `/query/getEventNames`, `/query/getPropertyValues`, `/query/getTopProperties`, `/query/getSegmentation`, `/query/getFunnel`, `/query/listFunnels`, `/query/listCohorts`, `/query/runJQL`. Rate limits: 5 concurrent / 60 per hour; 1h response cache.
 

package/CHANGELOG.md

@@ -2,6 +2,176 @@
 
 All notable changes to `@ak--47/dungeon-master`.
 
+## 1.6.4 — 2026-09-01
+
+Answers the doc/type half of the DM4 v5 engine request
+(`dungeon-master-library-changes-requested.md`, 2026-09-01). Every claim in that
+document was checked against source; all were accurate except the three noted
+under "Already correct" below.
+
+This release is deliberately scoped to changes that cannot alter generated data:
+docs, types, one additive helper option, one additive config form, and one
+warning. The feature requests are tracked for 1.7.0 — see "Deferred to 1.7.0".
+
+No generated output changes. Verified: same seed, same config, `concurrency: 1`,
+pinned dataset window — 1.6.4 and 1.6.3 produce byte-identical events, user
+profiles, and group profiles.
+
+### Added
+
+- **`scaleEventCount(events, name, factor, { spreadDays })`.** Scatters clones
+  uniformly across the next N days instead of stepping 1 second at a time. The
+  default 1-second spread cannot create a new distinct active day and cannot open
+  a new session under Mixpanel's 30-minute gap rule, so a default call moves event
+  volume and nothing else — not active days, DAU, stickiness, sessions, frequency
+  bins, or retention. 33 dungeons in the DM4 corpus used the default and then
+  documented an active-day, session, frequency, or stickiness claim. All 33 were
+  wrong. The limitation is now stated in the helper's JSDoc, in HOOKS.md §2.1, and
+  in HOOKS.md gotcha #22. Clones that land past `FIXED_NOW` are still dropped by
+  the future-time guard. Default behavior is unchanged.
+- **Named-object form for `groupKeys`.** `{ key, cardinality, events? }` alongside
+  the positional tuple `[key, cardinality]` / `[key, cardinality, events]`. Both
+  forms may be mixed in one array. The validator normalizes to tuples, so hooks,
+  the generators, and the verifier still see exactly one shape. Added so a
+  form-driven config generator never has to emit an untyped positional tuple.
+  Bad input throws with the offending index.
+- **HOOKS.md §2.1.1 — "Cloned events MUST carry a fresh `insert_id`."** The
+  consequence was only in a source comment before. Four DM4 corpus files
+  hand-rolled `JSON.parse(JSON.stringify(e))` and had their entire engineered
+  surge deduped away by Mixpanel at ingest, with local verification still
+  reporting the surge as present. Includes the note that data generated this way
+  on 1.6.2 or earlier is wrong in-project and must be regenerated.
+- **README "one config surface, not two."** States that the `credentials` /
+  `switches` / `identity` sub-objects are the canonical form, that the flat
+  top-level keys are a back-compat alias, and that top-level wins when both are
+  set. Mirrored in CLAUDE.md and in the three sub-object JSDoc blocks.
+
+### Changed
+
+- **The `avgActiveDaysPerUser` + `engagementDecay` warning is no longer gated
+  behind `verbose`.** The combination silently returns an active-day count at or
+  below the configured value, never above. A config UI that shows the requested
+  number was lying about it. Documented in HOOKS.md §2.5 and in the
+  `avgActiveDaysPerUser` JSDoc.
+- **`retentionCurve` precedence is now documented.** When both `retentionCurve`
+  and `avgActiveDaysPerUser` are set, the curve wins and `avgActiveDaysPerUser` is
+  ignored entirely. Behavior is unchanged — only the docs were missing. Added to
+  the CLAUDE.md safe-range table, the README config table, HOOKS.md §2.5, and the
+  `avgActiveDaysPerUser` JSDoc.
+
+### Fixed (types and docs)
+
+- **`writeToDisk` doc was wrong.** It read "If true (default), writes output files
+  to ./data/". The runtime default is `false` (`config-validator.js`).
+- **`region` types disagreed.** Top-level `region` was `"US" | "EU"` while
+  `DungeonCredentials.region` allowed `"IN"`. Both now use a shared `Region` type
+  of `'US' | 'EU' | 'IN'`, which matches what `mixpanel-import` accepts.
+- **`hasAttributionFlags` was presented as a settable switch.** The validator
+  unconditionally overwrites it with `events.some(e => e.isAttributionEvent)`. It
+  is removed from `DungeonSwitches` and from the `switches` hoisting allowlist,
+  and marked `@internal` on `Dungeon`. Read it off `result.validatedConfig`;
+  setting it never did anything.
+- **`GroupEventConfig` / `config.groupEvents` removed from the public types.** A
+  declared-only stub — nothing in `lib/` ever read it, its own doc comment said
+  "not yet implemented", and no shipped dungeon set it. Removed from `types.d.ts`,
+  `lib/templates/abbreviated.d.ts`, `lib/templates/schema.d.ts`, and the `wrapFunc`
+  whitelist. To scope an event to a group, list it in that group key's `events`
+  array.
+
+- **The determinism claim was overstated.** README and CLAUDE.md both said "same
+  seed + same config + `concurrency: 1` = byte-identical output". That has been
+  false since 1.4.0: `insert_id` is a `randomUUID()`, so it differs on every run
+  by design — which is what keeps Mixpanel from deduping a re-import of the same
+  dataset. Found while verifying that this release changes no output. Everything
+  else is byte-identical; strip `insert_id` before diffing two runs. Both docs now
+  say so.
+
+### Already correct (no change needed)
+
+- `funnels[].reentry` and `funnels[].stepFilters` were reported as reading like
+  generation features. Their JSDoc already says "Verifier-only hint … Generator
+  behavior unchanged."
+- The dead persona fields (`churnRate`, `activeWindow`, `soupOverride`) were
+  reported as `verbose`-gated. Their warning already fires unconditionally, once
+  per process. They stay accepted and warned; removing them from the `Persona`
+  type is a 1.7.0 change because it is a type-level break.
+
+### Deferred to 1.7.0
+
+Everything below is new public surface or a behavior change, so none of it belongs
+in a patch. Per-item design lives in the maintainer's local `plans/1.7.0/SPEC.md`
+(the `plans/` tree is not published).
+
+| Request | Why not in 1.6.4 |
+|---|---|
+| `funnels[].conditions` operators (`in`, `gte`, `neq`, …) | New public surface. Also throws on function/array condition values, which is a break. |
+| Experiment variant stamped on the user profile | New profile property; needs a change to when variants resolve. |
+| `(ctx) => value` for property value functions | New signature. Requires an arity guard on the `choose` source-string cache first, or context-aware functions get frozen at their first evaluation. |
+| `stickyEventProps` | New surface. Also needs `lib/verify/schema-validator.js` taught about it, or `/verify-dungeon` reports every sticky prop as flag stamping. |
+| Stable per-user `location` under `hasLocation` | A real fix (`featureCtx.userLocation` is computed and never read), but it changes generated event geo. |
+| `personas[].ttcModifier` | New surface. |
+| Removing the three dead persona fields from the `Persona` type | Type-level break. |
+| `campaignPerUser` | New surface. |
+| `autoPowerLaw: false` and `{ __weights }` | New surface. |
+| `result.warnings[]` for clamps | New result surface. |
+| Ad spend derived from users acquired per campaign | Needs a new cross-user aggregate pass. Deferred past 1.7.0. |
+| Engine-side `conversionRate` saturation reporting | Depends on `result.warnings[]`. Note: the engine can report its own `Math.min(100, …)` clamps, but not a hook's own `Math.min(95, rate * 3)` — that cap belongs to the hook and the engine never sees the intended value. |
+
+## 1.6.3 — 2026-08-17
+
+### Fixed
+
+- **Cloned events no longer get deduplicated away by Mixpanel on ingest.** All
+  eight clone-producing helpers now give each clone a fresh `insert_id`:
+  `cloneEvent`, `scaleEventCount`, `injectAfterEvent`, `injectBetween`,
+  `injectBurst`, `injectOnNewDays`, `applyLifecycleWave`, and `applyPathBias`.
+  Four of them (`cloneEvent` and the three `injectAfterEvent`/`injectBetween`/
+  `injectBurst`) copied the template's id verbatim, so clones arrived as
+  byte-identical twins and Mixpanel deduped them server-side. The others deleted
+  the id, which is no safer: `mixpanel-import` runs with `fixData: true` and
+  synthesizes a missing id by content-hashing the record, so identical clones
+  collide into one anyway. Measured on an 8K-user dungeon: 608,081 events
+  generated, 598,555 landed. The loss fell entirely on the two events the hooks
+  clone, and an engineered 4x comment surge read as **1.17x** in the project while
+  local story verification still reported 4.14x — verification never inspects
+  `insert_id`. After the fix, all 608,081 ids are distinct and in-project counts
+  match sent counts exactly. Affects any dungeon whose hooks clone or inject
+  events. New shared helpers `stampFreshInsertId` / `cloneWithFreshId` in
+  `lib/hook-helpers/_internal.js`; every clone site honors an explicit
+  `insert_id` override uniformly. Swept by `tests/unit/clone-insert-id.test.js`,
+  which covers every clone site rather than the one that happened to break.
+- **The engine now guarantees unique `insert_id` across each user's final event
+  stream.** Fixing the clone helpers was not sufficient: hooks are documented to
+  inject events by spreading an existing one, and a spread copies `insert_id`
+  too — so any hand-rolled clone reintroduced the bug. Several shipped dungeons
+  (including `dungeons/technical/simple.js` and most of `dungeons/vertical/`) do
+  exactly that, and measured 160 duplicate ids in a 3,254-event sample. The user
+  loop now re-stamps any duplicate or missing `insert_id` after the `everything`
+  hook, alongside the existing auto-sort and future-time guards. A legitimate
+  stream never carries two events with the same id, so any collision at that
+  point is a clone. Pinned by `tests/integration/insert-id-uniqueness.test.js`.
+  CLAUDE.md's hook rule now points at `cloneEvent` while documenting that a bare
+  spread remains safe.
+- **`mixpanel-import` 3.5.1 → 3.6.1**, which fixes an undercount in the reported
+  user-profile success total (3.5.1 reported 196 profiles sent for a batch of
+  6,049 that had in fact all landed).
+- **`create-project` no longer reports a successful group-key add as a failure.**
+  The summary read `added [(none)] skipped [(none)]` even when the key was created
+  and ready, because the response's `added`/`skipped` arrays are not always
+  populated. It now reports against `all_group_keys`, the authoritative post-state,
+  and warns when a declared key is genuinely absent.
+
+### Added
+
+- **`/headless-build` skill** — final step of the pipeline (after `/create-project`).
+  Builds a demoable Mixpanel environment with `mixpanel_headless`: dashboards whose
+  narrative text is computed live from the project, Lexicon enrichment, saved
+  cohorts, custom properties, behaviors/metrics/formulas, and annotations — then
+  re-measures every hook story against the live project and fails on a miss.
+- **`powertools` skill: entity-CRUD index.** Documents the three inconsistent
+  response shapes across the create/list endpoints, the `createCohort` payload
+  contract, and which cohort filter types the API accepts.
+
 ## 1.6.2 — 2026-07-30
 
 ### Fixed