@hypersoniclabs/helix-mcp 0.2.2 → 0.2.3

package/docs/publishing.md

@@ -10,12 +10,14 @@
 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)
+## Login (human-in-the-loop)
 
-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:
+Publishing requires a creator account session. The sign-in itself is human (browser + website), but you drive it: call `start_login` — the human's browser opens to the HELIX sign-in page (relay the returned URL if it doesn't) — then poll `check_login` until it reports success. The minted token is saved locally by the MCP process and never enters the conversation.
+
+Terminal alternative (same flow, human-run):
 
 ```bash
-npm i -g @hypersoniclabs/helix-cli   # NOT `npx helix` — that's an unrelated package
+npm i -g {{CLI_PKG}}   # NOT `npx helix` — that's an unrelated package
 helix login
 ```
 
@@ -30,13 +32,12 @@ Creator access is currently invite-only (curated launch); the account must have
 
 ## 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>`
+- The publish response returns the canonical **play URL** — share that link directly (don't construct portal URLs by hand; they differ per environment).
 - 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`.
+- **CLI and MCP** — run them via `npx -y {{CLI_PKG}}@latest` / `npx -y {{MCP_PKG}}@latest` and they're always current (the MCP config already does this). A global install goes stale.
+- **SDK** (`@hypersoniclabs/helix-sdk`, pinned in a world's `package.json`) — a version pin isn't picked up by `npm update`. `check_for_updates` returns the exact per-package update command for this environment — use those commands verbatim (don't hand-write them; on non-production lanes the dependency value is an npm alias).

package/docs/sdk.md

@@ -7,7 +7,7 @@ The HELIX Instant SDK. Worlds running on HELIX Instant use it for player identit
 ## Install
 
 ```bash
-npm install @hypersoniclabs/helix-sdk
+npm install {{SDK_INSTALL_SPEC}}
 ```
 
 ## Core concepts
@@ -82,7 +82,19 @@ Subscribes to login/logout. Fires with the user on login and `null` on logout. R
 
 ### `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.
+The raw world-scoped session token (JWT, `aud: helix-instant-world`). Most worlds never need this; later SDK modules use it internally.
+
+### `Helix.avatar.getEquipped(): Promise<EquippedAvatar | null>`
+
+The local player's equipped **universal avatar** — the single character a world renders for them.
+`EquippedAvatar = { source: 'equipped' | 'auto' | 'default', itemId, glbUrl, skeleton }`. Resolves `null` for
+guests / standalone / any failure — the world falls back to the default body, never breaks. Feed it to
+`loadCharacterAssets`'s `avatar` option (single-player) or the `AvatarModelCache` (multiplayer) — see the
+character recipe §8 and the `hangout` template §3a. **Gate on `skeleton === 'helix-humanoid'`** (the
+`UNIVERSAL_AVATAR_SKELETON` export): only a converted avatar can be driven by the platform clips; the
+`loadCharacterAssets` `avatar` option does this gate for you. Call **after `Helix.init()`** and **before**
+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.
 
 ## Manifest requirements
 

package/docs/world-recipe.md

@@ -27,7 +27,7 @@ my-world/
     "build": "vite build"
   },
   "dependencies": {
-    "@hypersoniclabs/helix-sdk": "^0.1.0",
+    "@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}",
     "three": "^0.172.0"
   },
   "devDependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersoniclabs/helix-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "HELIX Instant MCP server — gives AI coding agents the platform contract: world recipes, manifest schema, validation, catalog discovery, and publishing.",
   "type": "commonjs",
   "main": "dist/server.js",
@@ -17,7 +17,7 @@
     "test": "node scripts/smoke.mjs"
   },
   "dependencies": {
-    "@hypersoniclabs/helix-cli": "^0.1.1",
+    "@hypersoniclabs/helix-cli": "^0.1.5",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   },