@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/sdk.md

@@ -1,6 +1,8 @@
 # @hypersoniclabs/helix-sdk
 
-The HELIX Instant SDK. Worlds running on HELIX Instant use it for player identity today, and multiplayer / voice / wallet / inventory in upcoming versions. It is the **only** way a world talks to the platform — worlds never call platform APIs or internal services directly.
+The HELIX Instant SDK. It is the **only** way a world talks to the platform — worlds never call platform APIs or internal services directly.
+
+Shipped namespaces: `Helix.auth` · `Helix.avatar` · `Helix.emotes` · `Helix.multiplayer` (see the multiplayer hub via `get_started({ kind: "multiplayer" })`) · `Helix.voice` · `Helix.wallet` · `Helix.marketplace` · `Helix.purchases` (what a sale granted — see `read_doc({ name: "purchases" })`) · `Helix.inventory` · `Helix.dataStore` · `Helix.leaderboard` · `Helix.achievements` · `Helix.camera` · `Helix.presence` · `Helix.notify` · `Helix.prompts` · `Helix.device` · `Helix.analytics`.
 
 > This document is the SDK contract. It is written to be sufficient for an AI agent to integrate a world without reading the SDK source.
 
@@ -12,10 +14,10 @@ npm install {{SDK_INSTALL_SPEC}}
 
 ## Core concepts
 
-1. **Your world runs in a sandboxed iframe** inside the HELIX shell (the portal play page, or the `helix dev` shell during local development). The SDK talks to the shell via `postMessage`; the shell talks to the platform.
+1. **Your world runs in a sandboxed iframe** inside a HELIX shell — the portal play page in production, or the **simulated** shell `helix dev` serves on your own machine (see *Local development* at the end of this doc). The SDK talks to the shell via `postMessage`; the shell talks to the platform.
 2. **Identity is granted, not taken.** Your world receives a short-lived, world-scoped session that only unlocks the permissions declared in your `helix.json` manifest. You never see the player's platform credentials.
 3. **Login UI belongs to the shell.** Your world cannot render a login form — it *requests* login, and the shell overlays its own UI. This is deliberate (anti-phishing) and means you never handle passwords.
-4. **Standalone mode.** When the world is opened directly (e.g. `vite dev` without a shell), `init()` resolves with `embedded: false` and all identity APIs return `null`/`false`. Your world should still run — treat identity as an enhancement.
+4. **Standalone (preview) mode.** When the world is opened directly (`vite dev`, `vite preview` — no shell), `init()` resolves with `embedded: false`, identity APIs return `null`/`false`, and the rest of the platform surface degrades to neutral: saves no-op, purchases refuse, entitlements read empty. The SDK says so out loud, once per method — ``[Helix] dataStore.set() did nothing — not embedded in a HELIX shell. Run `helix dev` to exercise this locally.`` Your world should still run (treat identity as an enhancement), but a clean preview run is **never** evidence that a save, a sale or a board works — run `helix dev` for that.
 
 ## Quick start
 
@@ -96,6 +98,72 @@ character recipe §8 and the `hangout` template §3a. **Gate on `skeleton === 'h
 character assets load — the body is bind-once. In multiplayer, remote players' avatars arrive on room state
 (`player.avatarUrl`, `''` = none) — you never look up another user's avatar yourself.
 
+**Changing the avatar is not an SDK call.** Use `mp.changeAvatar(inventoryItemId | null)` on the character
+system's `CharacterMultiplayer` — the one avatar change (placeholder → persist → swap → every player sees it).
+`Helix.avatar.updateLoadout` still exists as published contract, but do not use it to change the body: it
+skips the placeholder and is not the contract agents and worlds share. See the character recipe §8.
+
+### `Helix.emotes` — the player's carried emote wheel
+
+`getEquipped(): Promise<{ emotes: EquippedEmote[] } | null>` — the local player's equipped emotes
+(`{ slot, itemId, clip, playback, audio?, label? }`; `slot` is `r0`..`r7` for the eight radial petals plus
+`sit` / `lie`). `null` for guests / standalone / any failure; an **empty array is a real answer** — this
+player carries none. `onChanged(cb)` fires after the platform's customizer closes. `openCustomizer():
+Promise<boolean>` raises that customizer over the world and resolves `false` when the player is signed out
+or the host mounts no editor — "it did not open" is a normal outcome, not an exception.
+
+**Most worlds should not call any of this.** The character system's native avatar runtime reads the same
+loadout off the shell channel itself and drives the wheel, the tap-replay, the posture lane and the
+Customize door with no world code — see the character recipe §8g, which also covers how to refuse those
+features if your world does not want them. Reach for this namespace only when you are drawing your own
+emote UI in place of the native wheel.
+
+### `Helix.voice` — voice chat (LiveKit under the hood)
+
+Player voice for multiplayer worlds — **the platform default: every multiplayer world should ship voice**
+(scaffolds and templates already include it; a deliberately silent world opts out by removing the permission
+and the join block). Requires: a `voice.proximity` or `voice.room` **permission** in the manifest (each
+implies `multiplayer`), a logged-in player, and a **joined multiplayer room** (the voice room pairs 1:1 to
+the game room instance). The heavy voice client is dynamically imported only when a world calls `join()` —
+no-voice worlds pay zero bundle cost.
+
+```ts
+// After Helix.multiplayer.joinRoom() succeeds (mp.room != null with the facade):
+try {
+  if (await Helix.voice.join()) mp.attachVoice(Helix.voice, manifest.multiplayer.voice);
+} catch (err) {
+  console.info('voice unavailable:', err); // fail-soft — the world stays fully playable
+}
+```
+
+- **`join(options?): Promise<boolean>`** — fetches the voice grant and connects. Resolves `false` (never
+  throws) when voice is off for this world/environment, so it is safe to call unconditionally. Options:
+  `pttKey` (default `'n'`), `channel` (initial channel), `roomId`/`apiBaseUrl` overrides. `n` is a
+  platform-reserved key (the character system's `capabilities.reservedKeys`) — if your world needs **N**
+  for gameplay, repoint `pttKey` here; never bind a game action over the PTT default. (The default moved
+  from `'b'` — KeyB now belongs to the `point` standard action.)
+- **`leave(): Promise<void>`** — releases the mic and disconnects. Safe when not joined.
+- **`setPttDown(down: boolean)`** — programmatic push-to-talk, the pad/touch leg. You normally never call
+  it: `mp.attachVoice` auto-registers the `voicePTT` standard action (hold modifier + right bumper, global
+  context — keeps working under menus) and forwards it here. Only 'ptt' mic mode opens the mic, and the
+  hot-mic safeties (blur/hidden tab) release a programmatic hold too.
+- **Mic behavior belongs to the PLAYER, not the world**: mode (push-to-talk **N**, pad: hold
+  modifier+RB / open / muted), device,
+  volumes, sensitivity, and per-player mutes are set from the platform tablet's Voice tab and pushed to the
+  SDK by the shell. A world never renders mic UI.
+- **Channels (exclusive semantics):** every player is in exactly ONE voice space — the ambient world or a
+  named channel. `setChannel(id)` switches (a walkie-talkie frequency, a private call); `setChannel(null)`
+  returns to ambient. Ids are free-form — dynamic ids (e.g. `` `call:${[a,b].sort().join(':')}` ``) need no
+  declaration and render flat; channels declared in the manifest's `multiplayer.voice.channels` can opt into
+  proximity render. Readers: `channel()`, `channelOf(userId)`.
+- **Rendering is the engine's job:** `mp.attachVoice(Helix.voice, manifest.multiplayer.voice)` drives
+  per-player volume (ambient proximity falloff or flat, per-channel policies) off synced positions, feeds
+  the directional pan when the manifest sets `"spatial": true` (ambient voices heard from where the speaker
+  stands; channels stay center-panned), and lights the nameplate mic glyphs. Pass the manifest block straight
+  through — one source of truth.
+- Speaking/participant events for custom UI: `onSpeakingChanged(cb)`, `onParticipantsChanged(cb)`,
+  `participantIds()` (all keyed by platform userId, which is also `PlayerState.userId` on room state).
+
 ## Manifest requirements
 
 Your bundle root must contain a `helix.json` manifest (see `@hypersoniclabs/helix-manifest`). To use the identity APIs, declare the permission:
@@ -112,6 +180,257 @@ Your bundle root must contain a `helix.json` manifest (see `@hypersoniclabs/heli
 
 Calling an API whose permission is not declared returns an error — permissions are enforced server-side on the session token, not just in the SDK.
 
-## Coming in later versions
+**There are exactly five permissions**, and most SDK namespaces need none of them:
+
+| Permission | Available in | Gates |
+| --- | --- | --- |
+| `auth.profile` | v0.1+ | `Helix.auth` — the player's id, username, display name |
+| `multiplayer` | v0.3 | joining the world's shared room. Forces `requiresAuth: true` |
+| `voice.room` / `voice.proximity` | v0.3 | `Helix.voice`. Each implies `multiplayer` |
+| `camera.capture` | v0.3 | `Helix.camera.savePhoto` — writing a photo to the player's gallery |
+
+`wallet`, `marketplace`, `purchases`, `inventory`, `dataStore`, `leaderboard`, `achievements`, `presence`, `notify`, `prompts`, `device` and `analytics` require **no additional manifest permission** — they ride the world-scoped session. Do not invent a permission string for them; the manifest schema is `additionalProperties: false` and an unknown permission is a validation error, not a warning.
+
+## `Helix.dataStore` — durable per-world storage
+
+The Roblox-DataStore analog, and the right place for anything that must survive a session: player progress, settings, world state. Scoped to THIS world. Free for every world; quotas and write rate limits apply, and a rejected write throws.
+
+**The single-key doctrine: a player's client-side save is ONE JSON document, at exactly `player:${user.id}`.** That is the only key a session may write — structure everything as *fields inside it* (`{ level, coins, settings, artifacts: […] }`) rather than spreading a save across `player:${id}:coins`, `player:${id}:settings`, … Sub-keys under a player, world-global keys and room state exist, but they are **server-written** (by the game room or by creator tooling); a session write outside its own exact key is refused with a 403 naming the rule it broke. Reads are open — any client can point-`get` any key in the world.
+
+```ts
+await Helix.dataStore.set(`player:${user.id}`, { level: 4, coins: 120, unlocked: ['cave'] });
+const save = await Helix.dataStore.get<{ level: number }>(`player:${user.id}`); // null when unset
+const { keys, nextCursor } = await Helix.dataStore.list('player:');             // keys only, never values
+if (nextCursor) { /* >100 keys match: pass { cursor: nextCursor } for the next page */ }
+await Helix.dataStore.delete(`player:${user.id}`);
+```
+
+**Optimistic concurrency** — read the version, hand it back on the write, and a losing race is refused instead of silently clobbering the other writer (two tabs, or the player's own client racing the game room):
+
+```ts
+const entry = await Helix.dataStore.getEntry<Save>(`player:${user.id}`);  // { value, version } | null
+const next = { ...(entry?.value ?? fresh), coins: (entry?.value.coins ?? 0) + 10 };
+await Helix.dataStore.set(`player:${user.id}`, next, { expectedVersion: entry?.version ?? 0 }); // 0 asserts create-only
+```
+
+A stale `expectedVersion` fails with code `version-conflict` (HTTP 409) — re-read with `getEntry` and re-apply, never retry blindly. `delete` accepts the same guard. Omit `expectedVersion` and the write is a last-writer-wins overwrite.
+
+**Refusal codes** — a rejected call throws a `HelixRequestError` carrying a machine-readable **`code`**, so branch on the code and not on the message prose (`catch (e) { if (e.code === 'rate-limited') …}`). It is `undefined` when the failure has no classification (or the shell predates the code), so always keep a generic fallback. The ones an agent actually meets:
+
+| `code` | Means |
+| --- | --- |
+| `session-foreign-key` | writing `player:{someoneElse}` — a session only ever writes its own key |
+| `session-sub-key` | writing `player:{you}:something` — put it in the one document instead |
+| `session-server-key` | writing a world/room key a session doesn't own (`world:*`, `mp:player:*`, free-form server keys) |
+| `platform-reserved` | the `helix:*` prefix — platform data, never world-writable |
+| `prefix-reserved` | a reserved-but-unbuilt prefix (`mail:*`, `mp:world`) or a route-owned one (`leaderboard:*`) |
+| `counter-server-only` | a session tried to increment a world counter — counters move through server rules only |
+| `leaderboard-self-only` | submitting a score for another player |
+| `leaderboard-cap` | a session minting a NEW board past the world's 8-board cap — declared boards come from the room/creator lane |
+| `version-conflict` | a stale `expectedVersion` — someone wrote first |
+| `rate-limited` | over the per-player or per-world write budget — back off, don't hammer |
+
+**There is no multi-key transaction.** Two keys cannot be updated atomically — design so no two keys must move together, or keep the coupled values in one key. In preview mode (opened directly, no shell) `get`/`getEntry` return null, `list` returns an empty page, and writes no-op with a console warning — a no-op `set` is exactly what makes "I verified persistence in preview" a false positive, so test saves under `helix dev`, which persists them and enforces the same key policy. Value-bearing writes should be made server-authoritatively.
+
+**Shared surfaces and artifacts (guestbooks, galleries, placements, ghosts).** The tempting shape is one key per contributor — `world:guestbook:{userId}` — and it is an **anti-pattern**: keys scale with *authority boundaries*, never with data cardinality. Every one of those entries shares one writer (the room) and one access rule (world-open), so they never earned separate keys — a thousand visitors would spend a thousand keys on one corkboard. Make the SURFACE the key instead: ONE bounded document (`world:guestbook` = `{ v, entries: […] }`) that the room rewrites via rules, bounded by design — one entry per author, or newest-N with a trim on every write. This is the same shape leaderboards use, for the same reason, and one point-`get` renders the whole thing. In a **single-player** world, per-author content lives as fields inside the author's own `player:{userId}` blob (a `builds` array, say — no new keys; other players can still point-`get` it and render). A `{userId}` in a key name is correct only when that user is the key's WRITER — their own save (`player:{id}`, `mp:player:{id}`) — and never for assembling a shared surface. Splitting a surface across keys is legitimate only when a single entry is too large to share a document (a multi-KB replay ghost against the 256 KB value cap); then key per thing, cap the count, and have the room delete beyond the cap. What you can never do, in any shape, is have one player write into another player's key.
+
+## `Helix.leaderboard` — per-world ranked boards
+
+Each board is one bounded document keeping its declared top `size` (up to 100), at most one entry per player; keep-best is the backend's atomic verdict, so a worse or below-cutoff score is a harmless no-op and resubmitting is always safe (`best` comes back `null` while you're off the board). Boards are declared per build (`multiplayer.leaderboards`, one named `main` — the world's default board) and are usually written by the game room's `submitScore` rule; the SDK is how a client reads them, and how a single-player world submits its own score.
+
+```ts
+const { best, updated } = await Helix.leaderboard.submit('bestTime', lapMs, { order: 'asc' });
+if (!updated) showToast(`Your record of ${best} stands`);  // updated:false = an existing better score won
+
+const { entries, truncated } = await Helix.leaderboard.top('bestTime', { limit: 10, order: 'asc' });
+for (const e of entries) addRow(e.displayName, e.score);   // { subject, displayName, score, source, updatedAt }
+```
+
+- `submit(board, score, { order? })` → `{ best, updated }`. The subject is taken from the session token, so a client can only ever score for **itself** (`leaderboard-self-only` otherwise). A board's shape (`order`/`size`) is fixed when the board is CREATED: a session's `order` (`'desc'` default, `'asc'` for times) counts only on the very first submit to a brand-new board — an established board is never re-ranked or trimmed by a session; only the room/creator lane reshapes it. A session may mint at most 8 boards per world (`leaderboard-cap` past that).
+- `top(board, { limit?, order? })` → `{ entries, truncated }`. `limit` ≤ 100; `truncated` is true when the board holds more than the page.
+- `entry.source` records **who wrote the row**: `'session'` = client-claimed (a player's own submit — trust it like any client input), `'room'` = the authoritative game room. Show a leaderboard players compete over from `'room'` submissions; a single-player board is necessarily `'session'`.
+- Both calls need a shell — in preview mode they reject rather than fake a board.
+
+## `Helix.achievements` — this world's badges, read-only
+
+Every achievement registered to THIS world plus the viewer's earned flags, for a trophy case / progress panel. **There is no award or claim call, deliberately**: a world runs in the player's own browser, so it can never attest that they earned anything. Grants come from the authoritative room's `awardAchievement` rule or from server-evaluated `criteria` — see `multiplayer-logic` §19 for both, and for the registration step every key needs first.
+
+```ts
+const { achievements, total, earned } = await Helix.achievements.list();  // all of them + the viewer's tally
+renderTrophyCase(achievements, `${earned}/${total}`);
+
+const { achievements: mine } = await Helix.achievements.mine();           // the earned-only subset
+```
+
+- Each entry is `{ id, key, name, description, points, hidden, earned, rarityTier, earnPct, iconUrl }`. `rarityTier` is `'unranked'` with a null `earnPct` until the backend has enough earns to rank it (`legendary` · `epic` · `rare` · `uncommon` · `common` otherwise); `description` and `iconUrl` may be null.
+- A **hidden** achievement the viewer has NOT earned arrives **redacted** — the shell replaces name + description with placeholders and blanks `key` + `iconUrl` (the slug spells the name, the icon shows the secret), so nothing identifying reaches world code. Identify such a row by `id`. Render it as the locked mystery slot it is; do not try to reconstruct it.
+- **World-scoped:** the shell supplies the world id, so a world can never enumerate the viewer's earns in other worlds. `mine()` is this world's earns only.
+- Guests read `earned: false` on everything and an empty `mine()`. In preview mode (no shell) both resolve neutral empties (`list()` → `{ achievements: [], total: 0, earned: 0 }`, `mine()` → `{ achievements: [] }`) rather than rejecting — this is display data and must never break the world loop.
+- **Not a notification.** Nothing pushes an unlock into a running world, and the platform raises no banner over it: a room award should `broadcast` its own event for the celebration, and a trophy case re-reads `list()` when it opens.
+
+## `Helix.wallet` / `Helix.marketplace` — LIX, Coins, and IWP
+
+```ts
+const { lix, coins } = await Helix.wallet.getBalance();
+const off = Helix.wallet.onBalanceChanged((b) => updateHud(b));   // returns an unsubscribe fn
+
+const result = await Helix.marketplace.purchaseProduct('coin-pack'); // stable world-product key
+const item = await Helix.marketplace.purchaseDistributionKey('postcard', { quantity: 2 });
+const listing = await Helix.marketplace.purchaseListing('listing-for-serial-12');
+if (item.completed) refreshInventory();                            // Granted | Claimed | AlreadyOwned
+```
+
+`PurchaseResult.status` is the canonical outcome: `Pending` · `Granted` · `Claimed` · `AlreadyOwned` · `InsufficientFunds` · `MaxPerUserReached` · `ProductInactive` · `ProductNotFound` · `NotInWorld` · `Unauthorized` · `RateLimited` · `Cancelled` · `Failed` · `Timeout` · `NotFound` · `PriceChanged`. `completed` is the convenience for the three that mean the player now owns it (`PriceChanged` is never completed: the displayed price went stale, nothing was charged, and the shell re-prompts at the fresh price). The shell raises the confirm popup and settles the purchase — the world reacts to the result and never handles money itself. `getListings(query?)` browses; `getPurchaseContext(ref)` returns product + live balance + eligibility (+ the product's `grants` effect list) in one call if you are building a custom confirm UI.
+
+### Register the product BEFORE you write the code that buys it
+
+A world can only sell what its creator **registered on it**: `helix.json` has no products block and nothing in world code can mint one, so `purchaseProduct` on a key nobody registered returns `ProductNotFound` at runtime. Register first — MCP `register_world_product`, or `helix product register <world-slug> --title … --type … --price … --key …` — then name that key in the world:
+
+```ts
+const result = await Helix.marketplace.purchaseProduct('speed_boost');  // buys pkey:speed_boost
+if (result.status === 'Granted') applySpeedBoost();                     // consumable: YOUR world applies the effect
+```
+
+- The **key is required and immutable** — a rename would break every build that names it — so choose it once at registration. A bare key is auto-prefixed `pkey:`. Internal product UUIDs are never purchase references.
+- **The price lives in the registry only.** `purchaseProduct` sends no amount, ever; the shell shows the confirm popup, charges the LIX and settles server-side. `priceLix: 0` is a legitimate registration — a free **Claim** the popup confirms without spending.
+- **Author a World Product's world-local fulfilment as `pass` and `currency` grants.** Several effects = a bundle; an empty array = a tip jar. World Products do not mint universal items. For portable ownership, publish an item and create a Marketplace/World distribution (`read_doc({ name: "items" })`). A permanent-pass-only product is capped at 1; add a timed pass or currency to make it genuinely re-buyable.
+- Registration does **not** require the world to be published — only the all-worlds creator listing filters to Published, so a product registered on a draft world exists and lists fine by slug. **Buying** does need a live world (Published or Unlisted): until then the product is registered and unbuyable.
+
+### `Helix.purchases` — read and spend what fulfilment granted
+
+```ts
+const ent = await Helix.purchases.getEntitlements();
+// { v: 1, passes: { vip: { since, expiresAt, active } }, balances: { coin: 740 }, owned: { 'starter-pack': 1 } }
+if (ent.passes.vip?.active) unlockLounge();
+
+const spent = await Helix.purchases.consume('potion', 1);   // server-atomic, floor-at-zero
+if (spent.applied) drinkPotion(); else offerShop(spent.balance);
+
+Helix.purchases.onEntitlementsChanged(async () => render(await Helix.purchases.getEntitlements()));
+```
+
+- **Server-held, backend-written.** Entitlements are the durable projection of every settled grants purchase in THIS world for THIS player. A world can read them and spend balances — it can never write them, so never mirror paid goods into client state you trust.
+- `consume(code, amount)` is **atomic and floor-at-zero**: `applied: false` with `reason: 'insufficient'` means the balance was left untouched. Each call is one spend (retries of the same call are replay-safe; a new call is a new spend).
+- `onEntitlementsChanged` fires after the shell settles a purchase — it carries no payload, re-read with `getEntitlements()`. Pass expiry is evaluated at read time via `active`.
+- Preview mode (no shell) resolves empty entitlements and an insufficient consume — display data never breaks the world loop.
+- **Multiplayer: the room reads the same entitlements, and a settled purchase reaches your rules.** The shell settles the sale, then the platform forwards the backend's receipt to the room the buyer occupies — **no world code**, including on the `getPurchase` recovery read after a reload — firing a `{"when":{"on":"purchase"}}` rule with `self` = the buyer and `purchase.productKey` / `purchase.purchaseId` readable inside it. One purchase fires it **exactly once**, platform-enforced: a re-forward, a rejoin, a tab that died mid-sale and a second instance of the world all collapse to one firing. Rules read the buyer's entitlement snapshot with `{"op":"hasPass","passKey":"vip","of":"self"}` / `{"op":"balanceOf","code":"coin","of":"self"}` (O(1), refreshed before that purchase rule runs) and spend with `{"do":"consume","code":"coin","amount":10,"player":"self"}` — the same atomic, floor-at-zero backend spend as the call above. Grammar + worked examples: `multiplayer-logic` §20.
+- **Entitlements are the durable truth for anything paid for** (passes, balances, owned). Read them where you need them — client or rule — and never copy one into client state, a playerVar or a roomVar: a session-scoped mirror resets while the entitlement does not, and the two then disagree about money.
+
+## `Helix.inventory`
+
+```ts
+await Helix.inventory.hasItem(itemId);      // works across worlds and creators — the VIP / season-pass basis
+await Helix.inventory.getQuantity(itemId);
+await Helix.inventory.getMyItems();         // InventoryItem[]
+await Helix.inventory.equipItem(itemId);    // owned cosmetics
+Helix.inventory.onInventoryChanged(() => refresh());
+```
+
+## `Helix.camera` — the world camera's cloud side
+
+```ts
+if (Helix.camera.available()) {                      // false in preview; capture still works, save no-ops
+  const blob = await Helix.camera.capture(canvas, { aspect: 'landscape' }); // render in the SAME tick
+  const photo = await Helix.camera.savePhoto(blob, { caption: 'Summit' });  // null in preview, never a fake success
+}
+```
+
+Photos land in the player's phone Gallery on every device, tagged with the world (the shell stamps the name authoritatively). Requires `camera.capture`. `captureCanvas` is re-exported for non-camera use.
+
+## `Helix.presence` — rich presence
+
+```ts
+await Helix.presence.setActivity({ state: 'Racing — lap 3/5', party: { current: 3, max: 8 } });
+```
+
+Enriches the baseline "In [World]" shown to the player's friends. Server-authoritative by design: it posts as the player's own session, so a world can only ever set activity for the local player, in the world they are actually in. Governed by the player's privacy settings; text is length-capped, rate-limited and moderated server-side. Returns `false` (never throws) for guests, outside a shell, or when rejected.
+
+## `Helix.notify` / `Helix.prompts` / `Helix.device` — shell UI
+
+```ts
+Helix.notify.success('Checkpoint reached');          // also .failure / .notification / .message
+Helix.prompts.set({ id: 'door', title: 'Open the vault', input: { key: 'E' }, state: 'available' });
+Helix.prompts.clear('door');
+Helix.device.openTablet();                            // or openPhone()
+Helix.device.getState();                              // { open, form? } — is the Helix OS overlay up?
+const off = Helix.device.onStateChanged((s) => {      // fires on open/close edges (replayed after handshake)
+  if (s.open) pauseAmbience(); else resumeAmbience(); // the supported way to duck/pause under the overlay
+});
+```
+
+These render in the platform's own chrome, so they look native and stay clear of your HUD. The device
+open/close pose also replicates automatically — every replica shows the phone-in-hand stance with no
+world code beyond passing `helix` into `CharacterMultiplayer.create`.
+
+## `Helix.analytics`
+
+```ts
+await Helix.analytics.track(eventName, { /* input */ });
+```
+
+Ships events to the platform collector. Use the platform's event vocabulary rather than minting your own strings.
+
+## Local development — `helix dev`, the simulated shell
+
+```bash
+npm run build                            # `helix dev` serves the BUILT bundle, not the vite dev server
+helix dev                                # ./dist inside a simulated shell — no login, no backend, no room
+helix dev ./my-world --port 4180 --fresh # another dir, another port, a brand-new simulated player
+```
+
+`helix dev [dir] [--port <n>] [--reset] [--fresh]` runs your world's built bundle (`<dir>/dist`) inside a HELIX shell simulated on your own machine, entirely offline. The shell page and the world are served from two local origins, so your world meets production's cross-origin `postMessage` semantics rather than an accidental same-origin pass. The page carries a permanent **SIMULATED** banner plus a debug menu, and every answer is console-logged with a `[helix dev · SIMULATED]` prefix. The mode is called **simulated**, never "test" — nothing here spends or earns anything real.
+
+**What it simulates** — the established World Product shell lane: `purchaseProduct`, listings/context, entitlements, consume, wallet and inventory. Its confirm dialog covers Buy/Claim, cancel, replay and injected failure states. Universal-item `purchaseDistributionKey` / `purchaseDistribution` / `purchaseListing` require the real shell until the simulator ships registered distribution fixtures; it must return a clear unavailable result rather than inventing supply, serials or receipts.
+
+**What it refuses**, with a clear error rather than a plausible fake: the four `Helix.avatar` methods and `Helix.camera.savePhoto` — ``<method> is not simulated in `helix dev` — it needs the real asset pipeline.`` Those ride real asset pipelines, and a fake would teach your world the wrong shape.
+
+**It enforces production's caps, loudly** — 30 data-store writes/min per player and 600/min per world (`rate-limited`), 120 consumes/min, 256 KB per value, and the real key-policy refusals (`session-foreign-key`, `session-sub-key`, `platform-reserved`, …). A world that trips a cap locally trips it live; a simulator more permissive than production only manufactures false positives.
+
+**State persists across reloads** — `.helix/dev-state.json` in the world dir (git-ignored) holds the simulated player, which is the only way a save is testable at all. `--fresh` mints a new player (the first-run path); `--reset` wipes. Products seed from an optional `.helix/dev-products.json`, shaped like the registration you will make for real:
+
+```jsonc
+{ "products": [
+  { "key": "coin-pack", "title": "Coin Pack", "priceLix": 25,
+    "grants": [{ "kind": "currency", "code": "coin", "amount": 500, "display": "wallet" }] }
+] }
+```
+
+**Achievements UNLOCK locally.** Seed them from an optional `.helix/dev-achievements.json`, registration-shaped and validated with the **same rules** `helix achievement register` / `create_achievement` applies (closed criteria vocabulary, the two datastore key templates, the dot-path `field`, `unlockMode` coherence) — a seed that boots is the same JSON you will register for real, and a row registration would refuse fails the boot instead of silently never unlocking:
+
+```jsonc
+{ "achievements": [
+  { "key": "summit-club", "name": "Summit Club", "points": 25,
+    "criteria": { "signal": "datastore", "op": "gte", "value": 3,
+                  "key": "player:{userId}", "field": "stats.summits" } },
+  { "key": "room-badge", "name": "Room Badge" }   // no criteria ⇒ unlockMode "room": debug-menu award only
+] }
+```
+
+Unlocking mirrors production's poke → re-derive model, per signal:
+
+| Signal | Locally fed by | Latency |
+|---|---|---|
+| `datastore` over `player:{userId}` | every `Helix.dataStore.set` — the real gameplay loop | ~3 s debounce, as production |
+| `datastore` over `mp:player:{userId}` | debug menu **Set MP player var** (writes the room's `{v, vars}` envelope by hand — no rules run) | immediate |
+| `iwp` (`count` \| `lix`) | Granted/Claimed settles of seeded world products (never `AlreadyOwned`, never marketplace listings) | ~3 s debounce |
+| `playtime` | accrues 15 s/15 s while the shell page is open, plus debug **Add 5 min playtime** | immediate on tick |
+| `analytics` | debug **Bump analytics event** ONLY — `Helix.analytics.track` never reaches a shell, so real events cannot flow locally | immediate |
+
+Measurement is **fail-closed** exactly as production's: a missing document or field, a stringified `"12"`, or an array in the dot-path measures `null` and never unlocks — `helix dev` is the first place you can actually watch a wrong-typed leaf fail. Earned is **add-only** (achievements are soulbound; deleting evidence never revokes), a boot-time pass mirrors the registration backfill (evidence that already qualifies unlocks immediately), and no event is pushed to your world — poll `Helix.achievements.list()` / `mine()` to observe an unlock, exactly as on the portal. The host page shows a SIMULATED unlock toast; the debug menu adds **Award achievement** (refuses a key outside the seeded registry), **Print achievement progress** (measured-vs-target per row), and **Reset earned achievements** for re-testing.
+
+**From the seed to the real registry.** After the local pass, register each row with `register_achievement` / `helix achievement register` — same values, two shape differences: the seed stores criteria NESTED (`criteria: { signal, op, value, key, field, metric }` — the stored shape the backend keeps), while the tool flattens `key`/`field` to `criteriaKey`/`criteriaField` (the CLI: `--criteria-key`/`--criteria-field`) because `key` is already the badge's own slug; and real registration REQUIRES a 2D icon file the seed never needs (generate one with `generate_image`; blank or sub-16px placeholders are refused). Products go the same way: the `.helix/dev-products.json` rows are `register_world_product` rows. Registration works against a Draft row (`create_world` first on a brand-new project) and **takes effect on a live world immediately — no republish**: products become buyable the moment the world is live, and achievement registration runs its backfill pass at once. Confirm with `list_world_products` / `list_achievements` — the only proof a key really exists.
+
+**Never import the dev shell in world code.** `@hypersoniclabs/helix-sdk/dev-shell` is the CLI's half of `helix dev`, not a world API — and `checkBundle` refuses to publish any bundle containing it, precisely so a simulated shell can never ship inside a world.
+
+**The debug menu is the reason to run it** — none of this is reachable against real services without hand-editing a database. *Grant All Entitlements* · *Grant One* · *Force Remove* · *Print Owned* · **Purchases Always Fail** (cycles `InsufficientFunds` → `PriceChanged` → a throw that leaves the purchase `Pending`) · *Reset Player Document* · **Force Save Failure** · *Exhaust Consume Fence* · a signed-in toggle · a wallet setter. Drive your world through each one: failure paths are where worlds actually break, and a happy-path pass never executes them.
+
+**Everything a world only READS has a debug-menu writer.** Several surfaces are written by the room or the backend in production, so with no room they would sit empty forever — each has a stand-in that writes it by hand, loudly: **Seed leaderboard score** (declared boards are room-written live; a world calling only `leaderboard.top` renders an empty board until you seed entries — any player name, `source: "server"`, board shape rules kept), **Set data-store doc** (ANY key including the ones a session may not write: world-global keys, `mp:world:*` shared room state, the reserved namespaces — the session-side key policy stays enforced for the world itself), **Set MP player var** (the `mp:player:{userId}` persistent-var envelope), **Award achievement**, and **Push shell event** (`avatar-changed`, `equipment-changed`, `overlay-open`/`overlay-closed`). If your world renders something and it stays blank under `helix dev`, find its writer in this list before suspecting your code.
+
+**What it cannot prove** — read this before trusting a green local run:
+
+- that a product or achievement is actually **registered**. Nothing local can: use `list_world_products` / `list_achievements` against the real backend, and `create_world` first if the world row does not exist yet.
+- that a purchase **settles** — no charge, no escrow, no fulfilment, no receipt.
+- anything **room-lane**: DSL rules, the `consume` / `save` / `saveRoom` verbs, persistent playerVars, the real `awardAchievement` effect, or multiplayer of any kind. `helix dev` simulates the shell lane only — the debug menu's award and MP-var controls stand in for two room-lane *outcomes* without running any rules.
+- achievement **rarity** (`rarityTier` is always `unranked`, `earnPct` null — no population to rank against), or that an `analytics` criteria's `eventName` is in the platform enum (backend-validated at registration only).
 
-`Helix.multiplayer` (instances), `Helix.voice`, `Helix.wallet`, `Helix.inventory`, `Helix.cloudSave`, `Helix.leaderboards`. The shapes follow the same pattern: capability declared in the manifest → granted on the session → exposed as a namespace.
+End-to-end settlement against real services still runs on the engine repo's dev stack (`dev-stack.mjs up iwp-shop`) — see `read_doc({ name: "purchases" })` §9. When `helix dev` and the dev stack answer differently, that is signal, not noise: one of them is wrong, and it is worth knowing which.