@hypersoniclabs/helix-mcp 0.2.1

package/docs/character-world.md

@@ -0,0 +1,493 @@
+# HELIX Instant — Character World Recipe (v0.2)
+
+Follow this when the world has a **player character**, in **any camera framing**: first-person,
+third-person, **3D top-down** (twin-stick / ARPG / MOBA), **2.5D / side-on** (platformer), an avatar
+that walks / runs / jumps, or behaviors like flying, swimming, or shooting. You build on the published
+**`humanoid-character` system** instead of hand-rolling a character — it gives you a physics-driven
+chassis, locomotion + animation, first/third-person cameras, and an ability host. Top-down and 2.5D
+are **not a different foundation** — they are camera + movement *config* on this same system
+(`camera.initialPitch` / `allowRotate:false` for a fixed top-down angle, `locomotion.movementAxis` to
+lock side-on movement to one axis — see §8a).
+
+> For a bare scene with no character (a spinning object, a data viz, a menu), use the **scene**
+> recipe instead: `get_started({ kind: "scene" })`.
+
+## 0. Discover what's published FIRST — don't assume
+
+The catalog grows. Before you design anything, **fetch the latest** so you reuse what already exists
+instead of rebuilding it:
+
+- `list_systems` — runtime frameworks a world can build on (today: `humanoid-character`).
+- `list_abilities` — installable behaviors that plug into a system (e.g. `fly`, `swim`, `gun-control`).
+  Filter by `system` to see only compatible ones: `list_abilities({ system: "humanoid-character" })`.
+- `get_package_manifest({ slug })` — the contract for one package before you pin it. For an ability
+  this includes its **`configSchema`** (the tunable surface, e.g. `fly.maxSpeed`), activation, and
+  actions. The manifest *is* the documentation — never guess a package's options or version.
+
+Map the user's request to abilities that already exist (a flying game → pin `fly`; underwater → `swim`;
+shooting → `gun-control`) before writing any custom behavior.
+
+## 1. Project layout
+
+```
+my-world/
+├── package.json
+├── vite.config.ts
+├── tsconfig.json
+├── index.html
+├── helix.lock.json            ← written by `helix install`; commit it
+├── public/
+│   ├── helix.json             ← the v0.2 manifest (pins); lands at dist/ root on build
+│   └── helix_modules/         ← written by `helix install` (code only); gitignored
+└── src/
+    ├── main.ts
+    ├── loading.ts              ← the loading screen (count-based progress bar); restyle/extend freely (§8b)
+    └── helix.runtime.ts        ← written by `helix install`; committed (do not hand-edit)
+```
+
+## 2. package.json
+
+`three` is a **devDependency**: it is external at runtime (the platform hosts the single shared
+instance), but Vite needs it at build time to bundle the GLTFLoader/KTX2Loader addons + for types.
+`@dimforge/rapier3d-compat` (the physics engine) bundles into the world.
+
+```json
+{
+  "name": "my-world",
+  "private": true,
+  "type": "module",
+  "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview", "typecheck": "tsc --noEmit" },
+  "dependencies": { "@dimforge/rapier3d-compat": "^0.14.0" },
+  "devDependencies": { "@types/three": "^0.172.0", "three": "^0.172.0", "typescript": "~5.7.3", "vite": "^6.0.0" }
+}
+```
+
+The system itself is NOT an npm dependency — `helix install` materializes it under
+`public/helix_modules/` and the alias below resolves it.
+
+## 3. vite.config.ts
+
+Externalize **only the bare `three`** so the world, the embedded system, and every ability share the
+one hosted instance (two copies of three break `instanceof` and silently corrupt rendering).
+`three/examples/jsm/...` is NOT externalized — Vite bundles the addons from your `node_modules` three.
+
+```ts
+import { defineConfig } from 'vite';
+import { fileURLToPath } from 'node:url';
+
+export default defineConfig({
+  base: './',
+  resolve: {
+    alias: {
+      '@helix/humanoid-character': fileURLToPath(new URL('./public/helix_modules/humanoid-character/index.js', import.meta.url)),
+    },
+  },
+  build: { target: 'es2022', rollupOptions: { external: ['three'] } },
+});
+```
+
+## 4. tsconfig.json
+
+Point the type path at the embedded system's declarations (installed alongside the code).
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"], "strict": true, "noEmit": true, "skipLibCheck": true,
+    "paths": { "@helix/humanoid-character": ["./public/helix_modules/humanoid-character/index.d.ts"] }
+  },
+  "include": ["src"]
+}
+```
+
+## 5. index.html
+
+Ship the `helix:three` import-map markers exactly as below — `helix install` rewrites the import map
+to the hosted three URL. Leave the placeholder; do not fill it by hand. The `#loading` overlay is the
+loading screen: it paints on HTML parse (before any JS), and `src/loading.ts` drives its progress bar
+(§8b). Keep the markers and the overlay; restyle the overlay freely.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My World</title>
+    <!-- helix:three:start -->
+    <script type="importmap">
+    { "imports": { "three": "" } }
+    </script>
+    <!-- helix:three:end -->
+    <style>
+      html, body { margin: 0; height: 100%; overflow: hidden; background: #14161a; }
+      /* Loading overlay — painted on HTML parse (before any JS downloads → no flash). The bar starts as a
+         CSS marquee (no JS); src/loading.ts switches it to a measured fill, then fades out. Restyle freely. */
+      #loading { position: fixed; inset: 0; z-index: 100; display: flex; align-items: center; justify-content: center;
+        background: #14161a; color: #cdd6e0; font: 13px/1.5 ui-monospace, monospace; opacity: 1; transition: opacity 0.4s ease; }
+      #loading.done { opacity: 0; pointer-events: none; }
+      #loading .card { width: min(360px, 76vw); text-align: center; }
+      #loading .eyebrow { font-size: 11px; letter-spacing: 0.18em; text-transform: uppercase; color: #6cc7ff; opacity: 0.75; }
+      #loading .title { margin: 6px 0 18px; font-size: 16px; font-weight: 600; color: #e6edf5; }
+      #loading .bar { height: 6px; border-radius: 3px; background: #232830; overflow: hidden; }
+      #loading #bar { width: 30%; height: 100%; border-radius: 3px; background: #6cc7ff; animation: helix-marquee 1.1s ease-in-out infinite; }
+      #loading.determinate #bar { animation: none; transition: width 0.25s ease; }
+      #loading.working #bar { animation: helix-pulse 1s ease-in-out infinite; }
+      #loading.error #bar { animation: none; width: 100% !important; background: #e5675e; }
+      #loading-text { margin-top: 12px; color: #9aa7b4; }
+      @keyframes helix-marquee { 0% { transform: translateX(-110%); } 100% { transform: translateX(370%); } }
+      @keyframes helix-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+    </style>
+  </head>
+  <body>
+    <div id="loading">
+      <div class="card">
+        <div class="eyebrow">HELIX Instant</div>
+        <div class="title">My World</div>
+        <div class="bar"><div id="bar"></div></div>
+        <div id="loading-text">Starting…</div>
+      </div>
+    </div>
+    <div id="hud"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+## 6. public/helix.json — pin what you discovered in step 0
+
+`helixVersion: "0.2"` opts into systems/abilities. Pin the system + every ability you want as
+`slug -> semver range` (use `^0.1` unless `get_package_manifest` shows a newer line). `helix install`
+resolves each range to an exact version and bakes it into `helix.lock.json`.
+
+```json
+{
+  "helixVersion": "0.2",
+  "title": "My World",
+  "slug": "my-world",
+  "entry": "index.html",
+  "maxPlayers": 1,
+  "permissions": ["auth.profile"],
+  "supportsMobile": true,
+  "contentRating": "everyone",
+  "systems": { "humanoid-character": "^0.1" },
+  "abilities": { "fly": "^0.1", "swim": "^0.1" }
+}
+```
+
+## 7. src/helix.runtime.ts — stub (helix install overwrites it)
+
+```ts
+// GENERATED by `helix install` — placeholders until you run it; do not hand-edit.
+export const THREE_VERSION = '';
+export const THREE_MODULE_URL = '';
+export const TRANSCODER_PATH = '/runtime/basis/';
+export const SYSTEM_ASSET_BASE = '';
+```
+
+## 8. src/main.ts — the flow
+
+`loadCharacterAssets` streams the body/face LOD + locomotion clips from the CDN (never bundled);
+`Character.create` drives the chassis; `LocomotionAbility` is the built-in movement; everything you
+pinned loads via `loadInstalledAbilities`.
+
+```ts
+import * as THREE from 'three';
+import { Character, loadCharacterAssets, loadInstalledAbilities, LocomotionAbility, RapierBody } from '@helix/humanoid-character';
+import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
+import { createLoadingScreen } from './loading';   // loading screen — hooks DefaultLoadingManager (§8b)
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.05, 200);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(innerWidth, innerHeight);
+document.body.appendChild(renderer.domElement);
+scene.add(new THREE.HemisphereLight(0xbfd4ff, 0x40382a, 0.9));
+
+// Mount the loading screen before any loader runs — it hooks THREE.DefaultLoadingManager so every asset
+// load below (character, abilities, any extra GLB you add) counts on the bar automatically. See §8b.
+const loading = createLoadingScreen();
+
+const { model, clips } = await loadCharacterAssets(SYSTEM_ASSET_BASE, { renderer, transcoderPath: TRANSCODER_PATH });
+scene.add(model);
+
+// Assets are in (bar ~90%); the rest is un-metered (Rapier WASM compile, character setup) → show the
+// indeterminate "Starting…" tail so the bar never looks frozen, then dismiss on the first frame.
+loading.working('Starting…');
+
+const body = await RapierBody.create({ position: { x: 0, y: 0.2, z: 0 } });
+body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 }); // floor
+
+const character = await Character.create({
+  model, camera, domElement: renderer.domElement, body,
+  // FIRST-PERSON: set the initial camera mode. Omit for the third-person default.
+  config: { character: { camera: { mode: 'first-person' } } },
+});
+character.abilities.register(new LocomotionAbility(clips));
+await loadInstalledAbilities('/helix_modules', character); // fly, swim, … from helix.json
+
+// First-person mouse-look needs pointer lock — request it from a click (browser gesture rule).
+renderer.domElement.addEventListener('click', () => character.services.input.requestLook());
+
+const clock = new THREE.Clock();
+let firstFrame = true;
+renderer.setAnimationLoop(() => {
+  character.update(Math.min(clock.getDelta(), 0.1));
+  renderer.render(scene, camera);
+  if (firstFrame) { firstFrame = false; loading.dismiss(); } // world on screen → fade the overlay
+});
+```
+
+## 8a. Configure the character — read the knobs from the manifest, NEVER guess
+
+**This is the step agents get wrong.** Speed, camera, spawn, slope, jump-feel — almost everything a
+game designer reaches for is already a **config value**, not a method on the TypeScript class. If you
+inspect the `Character` / `LocomotionAbility` class API and conclude "there's no setting for X", you
+looked in the wrong place: the tunable surface is the **published config**, and the authoritative list
+is in the manifest.
+
+> **Rule:** `get_package_manifest("humanoid-character")` → its **`config`** is the complete tunable
+> surface (every key with default, range, and description: `character.spawn.*`, `character.camera.*`,
+> `character.body.*`, `character.lod.*`, `locomotion.*`). Its **`capabilities`** lists input actions,
+> blackboard keys, the runtime **`api`** entry points, and the **`events`**. Each ability adds its own
+> `configSchema` (read its `get_package_manifest`). **Read it before you configure. Do not invent keys.**
+
+There are exactly two ways to set any config value, and one runtime API surface:
+
+**1. Initial — `Character.create({ config })`.** Nested under the namespace; merges over defaults.
+
+```ts
+const character = await Character.create({
+  model, camera, domElement: renderer.domElement, body,
+  config: {
+    character: {
+      spawn:  { x: 4, z: -2, facingDeg: 90 },     // where the player starts + which way they look (0 = +Z)
+      camera: { mode: 'third-person', initialYaw: 90, lookSensitivity: 1.4, fov: 70 },
+    },
+    locomotion: { runSpeed: 7, coyoteTimeMs: 120 },
+    // ability namespaces too, once pinned & installed:  fly: { maxSpeed: 14 }
+  },
+});
+```
+
+**2. Runtime — `character.config.set('ns.key', value)`.** Read live every tick; the change applies
+immediately. This is how you do timed buffs, difficulty changes, "look at the boss", etc.
+
+```ts
+// Timed speed boost (a pickup): boost, then restore after 4 s — no engine change, pure config.
+const base = 5.5;                                   // or read it: character.config.get('locomotion.runSpeed')
+character.config.set('locomotion.runSpeed', 11);
+setTimeout(() => character.config.set('locomotion.runSpeed', base), 4000);
+
+// Re-aim the camera (respawn / cutscene / face a target). yaw = boom azimuth, pitch = view (up +).
+// initialYaw/initialPitch are construct-time SEEDS — to re-aim a LIVE camera, call these, not config.set.
+character.camera?.setYaw(180);
+character.camera?.setPitch(-10);
+
+// Live difficulty / movement-lock changes (these keys re-apply on set):
+character.config.set('character.camera.allowRotate', false);
+character.config.set('character.camera.tp.distance', 15);
+character.config.set('locomotion.movementAxis', 'x');   // restrict planar movement to one axis (2.5D)
+```
+
+**Top-down / 2.5D recipe.** Set the fixed framing at create time (`initialPitch` is a seed); `allowRotate`,
+`tp.distance` and `movementAxis` can still be flipped live afterward.
+
+```ts
+// 3D top-down (twin-stick): camera looks straight down, no orbit, body faces the movement direction.
+config: { character: { camera: { mode: 'third-person', allowRotate: false, initialPitch: -80, tp: { distance: 15 } } },
+          locomotion: { facingMode: 'movement' } }
+
+// 2.5D side-on platformer: lock planar movement to the X axis (camera framing as you like).
+config: { locomotion: { movementAxis: 'x' } }
+```
+
+**Runtime APIs (from `capabilities.api`)** — for things config can't express:
+
+```ts
+character.services.body.teleport({ x, y, z });        // move now (runtime equivalent of spawn)
+character.services.body.applyImpulse({ x: 0, y: 8, z: 0 }); // jump pad / knockback / explosion
+character.respawn(/* optional checkpoint */);          // teleport + zero velocity + stand up + reface
+character.setEnabled(false);                           // hard pause (halts gravity/abilities/anim) — cutscenes
+character.camera?.addTrauma(0.6);                      // camera shake for a hit/landing (0..1)
+```
+
+**Events (subscribe via `character.events.on(name, cb)`):** `landed` (`{ impactSpeed, fallDistance,
+speed }` — `impactSpeed` is vertical, use it for fall damage), `fell`, `respawned`, `jumped`,
+`stateEntered`. The full list + payloads are in `capabilities.events`.
+
+### Lock the controls to the genre — disable what doesn't fit (don't ship every control everywhere)
+
+Every `allow*` gate **defaults to `true`** (all controls enabled). So you must **opt OUT** of the ones
+that don't belong, or the player keeps a control the game shouldn't have. The classic bug: a
+first-person game where pressing **T** still flips to third-person, because `allowModeToggle` was left
+on. **Match the gates to the genre when you configure the character — don't leave it to chance.**
+
+The gates (all `boolean`, default `true` — set `false` to remove the control; confirm names/defaults in
+the manifest `config`):
+
+| gate | removes |
+|---|---|
+| `character.camera.allowModeToggle` | first/third-person switch (the **T** action) |
+| `character.camera.allowRotate` | orbit / mouse-look (fixed camera angle) |
+| `character.camera.allowZoom` | scroll-wheel zoom |
+| `character.camera.allowShoulderSwap` | over-shoulder side swap (the **V** action) |
+| `locomotion.allowJump` / `allowCrouch` / `allowSprint` | the jump / crouch / sprint actions |
+
+Genre presets (set these at create time, then add the rest of your tuning):
+
+```ts
+// First-person ONLY — keep the player in FP; T must NOT switch to third-person.
+config: { character: { camera: { mode: 'first-person', allowModeToggle: false } } }
+
+// Third-person ONLY — lock to TP; no FP toggle, no shoulder-swap clutter.
+config: { character: { camera: { mode: 'third-person', allowModeToggle: false, allowShoulderSwap: false } } }
+
+// Top-down — fixed framing: no mode toggle, no orbit, no zoom (combine with the top-down recipe above).
+config: { character: { camera: { mode: 'third-person', allowModeToggle: false, allowRotate: false, allowZoom: false } } }
+
+// No-jump (walking sim / puzzle / point-to-move).
+config: { locomotion: { allowJump: false } }
+```
+
+You can also flip these live (e.g. disable controls during a cutscene): `character.config.set('character.camera.allowModeToggle', false)`.
+
+### First-person vs third-person (a slice of the camera config)
+
+- Initial mode: `config.character.camera.mode` = `'first-person'` or `'third-person'` (default).
+- Toggle at runtime: `character.services.camera?.setMode('first-person')` (or `.toggleMode()`).
+- Tune via config like everything else: `character.camera.fp.fov`, `character.camera.tp.distance`,
+  `character.camera.lookSensitivity`, `character.camera.minPitchDeg` / `maxPitchDeg`, … — see the manifest.
+
+## 8b. Loading screen — `src/loading.ts` (count-based progress, extensible)
+
+The `#loading` overlay in `index.html` paints on HTML parse (before any JS downloads → no flash).
+`src/loading.ts` then hooks **`THREE.DefaultLoadingManager`** — the SAME instance the engine's
+GLTFLoader/KTX2Loader use (one shared three via the import map) — so the character, every ability, and
+ANY extra three load you add count on the bar automatically, with no extra code. The bar climbs as
+assets stream, shows an indeterminate **"Starting…"** tail for the un-metered window (Rapier WASM
+compile, character setup), then fades on the first rendered frame. Ship this file verbatim; restyle freely.
+
+```ts
+import * as THREE from 'three';
+
+// Loading screen for this world. It hooks THREE.DefaultLoadingManager — the SAME instance the engine's
+// GLTFLoader/KTX2Loader use (one shared three via the import map) — so the character, every ability, and
+// ANY extra three load you add (a world GLB, a TextureLoader, …) count on the bar automatically, with no
+// extra code. For a NON-three asset (audio, a raw fetch), wrap it in loading.task(). The overlay markup
+// + CSS live in index.html so it paints before this module downloads (no flash). Restyle/extend freely.
+
+const BAND_MAX = 0.9;   // the measured climb fills [0, 0.9]; the last tenth is the post-load tail + first frame
+const QUEUE_MIN = 5;    // go indeterminate→measured only once a real wave is queued (total-loaded ≥ this), so the
+                        // brief body+face 2/2 blip can't fill the bar then snap backward when the 38 clips enqueue
+
+export interface LoadingScreen {
+  /** Fold a NON-three async asset into the bar (counts like one item). Call before the work; handle.done() when it resolves. */
+  task(): { done(): void };
+  /** Set the status line under the bar. */
+  label(text: string): void;
+  /** Enter the indeterminate "Starting…" tail — covers the un-metered window (Rapier WASM compile, character setup). */
+  working(text?: string): void;
+  /** One-shot fade + remove. Call AFTER the first renderer.render(), never on manager.onLoad (it fires early). */
+  dismiss(): void;
+  /** Switch to the error state (red bar + message). */
+  fail(message: string): void;
+}
+
+export function createLoadingScreen(): LoadingScreen {
+  const root = document.getElementById('loading');
+  const bar = document.getElementById('bar');
+  const textEl = document.getElementById('loading-text');
+  const noop = (): void => {};
+  if (!root || !bar || !textEl) return { task: () => ({ done: noop }), label: noop, working: noop, dismiss: noop, fail: noop };
+
+  const mgr = THREE.DefaultLoadingManager;
+  let determinate = false; // latched once a real queue appears; never reverts (no marquee↔fill flicker)
+  let tail = false;        // working() latched — ignore further manager ticks; the pulse owns the bar
+  let shown = 0;           // last rendered fraction — monotonic, never decreases
+  let extra = 0;           // open task() handles, folded into the denominator
+
+  const render = (loaded: number, total: number): void => {
+    if (tail) return;
+    const t = total + extra;
+    if (!determinate && t - loaded >= QUEUE_MIN) { determinate = true; root.classList.add('determinate'); }
+    if (!determinate) return;
+    const frac = Math.min(loaded / Math.max(t, 1), 1) * BAND_MAX;
+    shown = Math.max(shown, frac);
+    bar.style.width = `${(shown * 100).toFixed(1)}%`;
+  };
+
+  mgr.onStart = (_url, loaded, total) => render(loaded, total);
+  mgr.onProgress = (url, loaded, total) => {
+    render(loaded, total);
+    if (tail) return;
+    if (/anims\/.*\.glb(\?|$)/.test(url)) textEl.textContent = `Loading animations… ${loaded}/${total}`;
+    else if (/\.ktx2(\?|$)/.test(url) || /basis_transcoder/.test(url)) textEl.textContent = 'Decoding textures…';
+  };
+  // No mgr.onLoad: it fires on the transient body/face 2/2 before the clips queue. Dismissal is the world's
+  // job — a one-shot after the first rendered frame (see main.ts).
+
+  return {
+    task() { extra += 1; let closed = false; return { done() { if (!closed) { closed = true; extra -= 1; } } }; },
+    label(text) { textEl.textContent = text; },
+    working(text = 'Starting…') { tail = true; root.classList.add('determinate', 'working'); textEl.textContent = text; },
+    dismiss() {
+      if (root.classList.contains('done')) return;
+      root.classList.remove('working');
+      root.classList.add('determinate');
+      bar.style.width = '100%';
+      root.classList.add('done');
+      setTimeout(() => root.remove(), 450);
+    },
+    fail(message) { root.classList.add('error'); textEl.textContent = `ERROR: ${message}`; },
+  };
+}
+```
+
+**Add your own assets to the bar.** An extra three load is counted automatically — just load it on the
+default manager (`new GLTFLoader().loadAsync(...)`). For a NON-three asset (audio, a raw fetch), wrap it
+in `loading.task()`:
+
+```ts
+loading.label('Loading music…');
+const music = loading.task();                 // counts like one item; the bar waits for it
+const audio = new Audio(new URL('theme.mp3', document.baseURI).href);
+audio.addEventListener('canplaythrough', () => music.done(), { once: true });
+audio.load();
+```
+
+**Errors.** To surface a load failure on the overlay instead of a frozen bar, guard the awaited setup and
+call `loading.fail(...)`:
+
+```ts
+try {
+  // … loadCharacterAssets … Character.create … loadInstalledAbilities …
+} catch (err) {
+  loading.fail(err instanceof Error ? err.message : String(err));
+  throw err;
+}
+```
+
+## 9. Install, build, publish
+
+```bash
+npm install
+helix install            # resolve the pins → download code, write installed.json + lock, wire the
+                         #   three import map + src/helix.runtime.ts (re-run after editing pins;
+                         #   `helix install --update` re-resolves ranges to newer versions)
+npm run build            # vite build (three external; system + addons + rapier bundle)
+```
+
+Then `validate_world` on `dist/` (fix every problem — no `.glb`/`.ktx2` may ship; assets stream from
+the CDN), `whoami` to confirm login, and `publish_world` on `dist/` for the play link.
+
+## The rules that matter
+
+- **One three.** `three` is external everywhere (import map → hosted instance). Never bundle it.
+- **Assets always stream from the CDN.** Animation clips + textures are never downloaded or shipped
+  with the world. The build contains no `.glb`/`.ktx2`. `loadCharacterAssets` fetches them at runtime.
+- **Test with `build` + `preview`, not `dev`.** The dev server rewrites bare imports and hides whether
+  the import map is correct; preview serves the real built output the platform runs.
+- **Pins are locked.** A rebuild uses the versions in `helix.lock.json`; `helix install --update`
+  advances them. Commit the lock so rebuilds are reproducible.

package/docs/manifest.md

@@ -0,0 +1,25 @@
+# helix.json — Manifest Reference (v0.1)
+
+Declares a world's identity, entry point, and the platform capabilities it is allowed to use. Lives at the bundle root as helix.json.
+
+Required fields: `helixVersion`, `title`, `slug`, `entry`. Unknown fields are REJECTED.
+
+| Field | Type / allowed values | Default | Description |
+| --- | --- | --- | --- |
+| `helixVersion` | const `"0.1"` | — (required) | Manifest schema version. Determines which fields and permissions are available. |
+| `title` | `string` (1–80 chars) | — (required) | Display name shown on the world page and in listings. |
+| `slug` | `string` matching `^[a-z0-9](?:[a-z0-9-]{1,48})[a-z0-9]$` | — (required) | URL identifier (3-50 chars: lowercase letters, digits, hyphens; no leading/trailing hyphen). Globally unique; the world's play URL is /g/{slug}. |
+| `entry` | `string` matching `^(?!/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html$` | — (required) | Bundle-relative path to the HTML entry point (e.g. index.html). Must not be absolute or contain '..'. |
+| `maxPlayers` | `integer` (1–100) | `1` | Player slots per room. 1 = single-player. Only meaningful with the multiplayer permission (M2). |
+| `permissions` | array of `"auth.profile"` | `[]` | Platform capabilities the world requests, OAuth-scope style. Worlds get nothing by default. v0.1 defines: auth.profile (read the player's id, username, display name). Later versions add multiplayer, voice.*, wallet.*, inventory.*. |
+| `supportsMobile` | `boolean` | `false` | Whether the world is playable on mobile browsers. Surfaces as a compatibility tag. |
+| `requiresAuth` | `boolean` | `false` | When true, players must log in before playing — the shell's login overlay offers no guest option, and the world page shows an 'Account required' badge. Leave false (default) for instant guest play. |
+| `contentRating` | `"unrated"` / `"everyone"` / `"teen"` / `"mature"` | `"unrated"` | Self-declared content rating. Curated review may override. 'unrated' worlds may be restricted from public listing. |
+
+## Bundle rules (enforced at validate AND publish)
+
+- Max 200 files, 25 MB per file, 50 MB total, no empty files
+- Paths are bundle-relative: no leading `/`, no `..`
+- Allowed file extensions: html, js, mjs, css, json, map, wasm, png, jpg, jpeg, gif, webp, svg, ico, ktx2, glb, gltf, bin, mp3, ogg, wav, woff, woff2, ttf, txt, md
+- `entry` must exist in the bundle and end in `.html`
+- The manifest file itself must be at the bundle root as `helix.json`

package/docs/publishing.md

@@ -0,0 +1,42 @@
+# Publishing to HELIX Instant
+
+## The pipeline
+
+`publish_world` runs the full creator pipeline against the platform:
+
+1. **Local validation** — the bundle directory is checked with the exact rules the server enforces (manifest schema, slug format, entry exists, file types, size budget). `validate_world` runs the same check standalone.
+2. **World resolution** — the manifest `slug` is matched against your existing worlds; a new world is created on first publish. Re-publishing a slug creates the **next build** (builds are immutable; the newest finalized build is what players get).
+3. **Upload** — each file is uploaded to CDN storage via presigned URLs (size and content type are cryptographically pinned; a mismatched upload is rejected by storage itself).
+4. **Finalize** — the platform verifies every declared file landed byte-exact, then atomically activates the build. A draft world auto-publishes on its first successful build.
+5. You get back the **play URL** — shareable, instant, no install.
+
+## Login (human prerequisite)
+
+Publishing requires a creator account session. Agents cannot log in — the flow is interactive. If `whoami` says not logged in, ask the human to run:
+
+```bash
+npm i -g @hypersoniclabs/helix-cli   # NOT `npx helix` — that's an unrelated package
+helix login
+```
+
+Creator access is currently invite-only (curated launch); the account must have the creator flag.
+
+## Error semantics
+
+- Validation errors list every problem at once — fix all of them, rebuild, re-validate.
+- `409` on world creation: the slug is taken by another creator. Choose a different slug in `helix.json`.
+- "missing upload" / "size mismatch" at finalize: the build directory changed between validate and publish — rebuild and re-publish.
+- `401`/`403`: login expired or the account lacks the creator flag — back to the human.
+
+## After publishing
+
+- World page: `https://helix-instant-website-production.up.railway.app/w/<slug>`
+- Instant play: `https://helix-instant-website-production.up.railway.app/play/<slug>`
+- Title, content rating, mobile support, and `requiresAuth` on the world page all come from the manifest — re-publish to update them.
+
+## Keeping the toolchain current
+
+The `@helix` packages publish independently; call `check_for_updates` (or `helix doctor`) to see what's behind and get the exact update command.
+
+- **CLI and MCP** — run them via `npx -y @hypersoniclabs/helix-cli@latest` / `npx -y @hypersoniclabs/helix-mcp@latest` and they're always current (the MCP config already does this). A global install goes stale; refresh it with `npm i -g @hypersoniclabs/helix-cli@latest`.
+- **SDK** (`@hypersoniclabs/helix-sdk`, pinned in a world's `package.json`) — a `^0.x` range locks the minor, so a new minor isn't picked up by `npm update`. Bump the range and reinstall: `npm i @hypersoniclabs/helix-sdk@latest`.

package/docs/sdk.md

@@ -0,0 +1,105 @@
+# @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.
+
+> 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.
+
+## Install
+
+```bash
+npm install @hypersoniclabs/helix-sdk
+```
+
+## 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.
+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.
+
+## Quick start
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+
+const { embedded, user, world } = await Helix.init(); // call once, before anything else
+
+if (user) {
+  greet(user.displayName ?? user.username);
+}
+
+// React to login/logout at any time (e.g. update the HUD):
+Helix.auth.onAuthChanged((user) => updateHud(user));
+
+// Prompt login at a moment that makes sense in your world:
+saveButton.onclick = async () => {
+  try {
+    const user = await Helix.auth.requestLogin(); // shell overlay; no page reload
+    await saveProgress(user.id);
+  } catch {
+    // player dismissed the login — keep playing, nothing is lost
+  }
+};
+```
+
+## API
+
+### `Helix.init(): Promise<HelixInitResult>`
+
+Performs the shell handshake. **Must be called once before any other API.** Safe to call again (returns the same state). Resolves within ~3s even with no shell present.
+
+```ts
+type HelixInitResult = {
+  embedded: boolean;              // false when running standalone (local dev)
+  world: { id: string; slug: string; title: string } | null;
+  user: HelixUser | null;         // null when not logged in
+};
+```
+
+### `Helix.auth.getUser(): Promise<HelixUser | null>`
+
+The current player, or `null` when unauthenticated. Requires the `auth.profile` permission in your manifest.
+
+```ts
+type HelixUser = {
+  id: string;          // stable player id (UUID) — use this as your save key
+  username: string;    // unique handle
+  displayName: string | null;
+};
+```
+
+### `Helix.auth.isAuthenticated(): boolean`
+
+Synchronous check.
+
+### `Helix.auth.requestLogin(): Promise<HelixUser>`
+
+Asks the shell to show its login overlay. Resolves with the user on success. Rejects when: the player dismisses the overlay (`'dismissed'`), no shell is present (standalone), or the request times out. **The world keeps running throughout — there is no reload, and your state is preserved.** If already logged in, resolves immediately.
+
+### `Helix.auth.onAuthChanged(cb: (user: HelixUser | null) => void): () => void`
+
+Subscribes to login/logout. Fires with the user on login and `null` on logout. Returns an unsubscribe function.
+
+### `Helix.getSessionToken(): string | null`
+
+The raw world-scoped session token (JWT, `aud: helixb-world`). Most worlds never need this; later SDK modules use it internally.
+
+## Manifest requirements
+
+Your bundle root must contain a `helix.json` manifest (see `@hypersoniclabs/helix-manifest`). To use the identity APIs, declare the permission:
+
+```json
+{
+  "helixVersion": "0.1",
+  "title": "My World",
+  "slug": "my-world",
+  "entry": "index.html",
+  "permissions": ["auth.profile"]
+}
+```
+
+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
+
+`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.