@genex-ai/cli-demo 0.7.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -15,14 +15,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsup",
-    "prepack": "pnpm build",
-    "start": "node src/index.ts",
-    "dev": "node --watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test test/*.test.ts"
-  },
   "keywords": [
     "cli",
     "claude",
@@ -46,5 +38,12 @@
   "bugs": {
     "url": "https://github.com/me-ai-org/genex-demo/issues"
   },
-  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme"
-}
+  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme",
+  "scripts": {
+    "build": "tsup",
+    "start": "node src/index.ts",
+    "dev": "node --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  }
+}

package/templates/README.md

@@ -1,15 +1,16 @@
 # Genex workspace
 
-These files were installed into your `~/.claude` directory by `genex init`.
-They give your coding agent a starter workspace for making 3D games in the
-browser.
+These files were installed by `genex init` into your coding agent's workspace —
+Claude Code (`~/.claude`), Codex (`~/.codex/skills`), and Cursor
+(`~/.cursor/skills`), whichever it detected. They give your agent superpowers
+for making 3D games in the browser.
 
 Genex is built around agent superpowers for browser games: Three.js skills,
-one-click publishing, multiplayer-ready architecture, and team workflows. The
-installed files are yours to edit, extend, and keep with each project.
+one-click publishing, multiplayer-ready architecture, and team workflows.
 
-Existing files are never overwritten. Re-running `genex init` only adds files
-you do not already have.
+Files whose names start with `genex-` are managed by Genex: re-running
+`genex init` refreshes them to the latest version. Anything you add yourself is
+never touched.
 
 - `skills/` - reusable Genex skills for 3D game creation.
 - `agents/` - example subagent definitions.

package/templates/skills/genex-ai-model/SKILL.md

@@ -54,8 +54,8 @@ i.e. "looking forward"). A hero whose nose points sideways reads as broken at a
 
 ## Load it into the scene
 
-Use Three.js `GLTFLoader` with the **relative** path (so it works under the
-published subpath `https://<user>.github.io/<slug>/`):
+Use Three.js `GLTFLoader` (the game serves at the domain root
+`https://<slug>.genex.technology/`, so relative or absolute paths both work):
 
 ```ts
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
@@ -73,12 +73,12 @@ To place many copies, `model.clone()` per instance. For animated GLBs, drive
 
 ## Publish checklist (so players see the model)
 
-- Reference assets with **relative** paths (`./assets/...`), never absolute
-  (`/assets/...`) — GitHub Pages serves the game at a subpath.
+- Reference assets with **relative** paths (`./assets/...`); absolute
+  (`/assets/...`) also resolves since the game serves at the domain root.
 - Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
   prompt's publish step).
 - Keep generated assets under `public/assets/` — Vite only ships files under `public/`
-  (or files you `import`); `npx genex publish` commits and pushes that folder with the game.
+  (or files you `import`); `npx genex publish` ships that folder with the game.
 
 ## Options
 

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -56,7 +56,7 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 ## Publish checklist
 
 - Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; files live under
-  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
+  `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
 
 ## Troubleshooting
 

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -61,10 +61,10 @@ texture.dispose; // (dispose the PMREM source later if you stop using it)
 
 ## Publish checklist
 
-- Use the **relative** path `./assets/skybox/...` (GitHub Pages serves at a subpath).
+- Use the **relative** path `./assets/skybox/...` (absolute `/assets/...` also works — the game serves at the domain root).
 - `base: "./"` in `vite.config.ts` before `npm run build`.
 - Generated files live under `public/assets/` so Vite ships them; `npx genex publish`
-  commits and pushes that folder with the game.
+  ships that folder with the game.
 
 ## Troubleshooting
 

package/templates/skills/genex-ai-texture/SKILL.md

@@ -68,7 +68,7 @@ scene.add(ground);
 ## Publish checklist
 
 - Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; files live under
-  `public/assets/` so Vite ships them; `npx genex publish` commits and pushes them.
+  `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
 
 ## Troubleshooting
 

package/templates/skills/genex-getting-started/SKILL.md

@@ -23,12 +23,14 @@ are never touched).
 
 Start with `$genex-threejs-skill-router` for broad game or graphics requests.
 It routes the agent to focused skills for cameras, procedural geometry,
-materials, atmosphere, water, VFX, post-processing, and visual validation.
+materials, atmosphere, water, weather, VFX, post-processing, and visual
+validation.
 
 ## Generating real assets
 
 Beyond procedural code, Genex can generate **real, AI-made assets** from a prompt
-and drop them into `./assets/` (committed when you publish):
+and drop them into `public/assets/` (shipped with your published game; load them
+as `./assets/...` — the `public/` prefix is stripped when served):
 
 ```bash
 npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)
@@ -43,18 +45,20 @@ npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
 `$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
 
-Your existing files were left untouched. `genex init` only adds what is missing.
+Your own files were left untouched. `genex init` only adds missing files and
+refreshes the genex-owned ones.
 
 ## Re-running setup
 
-Safe to run any time; it never overwrites your files:
+Safe to run any time — genex-owned skills are refreshed to the latest version,
+and your own files are never touched:
 
 ```bash
 npx @genex-ai/cli-demo@latest init
 ```
 
-Use `--force` only if you intentionally want to overwrite installed templates
-with the latest versions.
+Use `--force` only if you intentionally want your own existing files overwritten
+by the bundled templates too.
 
 ## Authorization
 

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: genex-threejs-embed-auth
+description: Wire up signed-in identity for a Genex game via @genex-ai/embed-sdk. Load this UNCONDITIONALLY for every game, multiplayer or not, BEFORE writing any boot code — identity is required for play, saving progress, and multiplayer; there is no anonymous mode.
+---
+
+# Genex Three.js Embed Auth
+
+`@genex-ai/embed-sdk` is how a Genex game learns **who is playing it**. Every
+game needs it — there is **no anonymous play**: without a signed-in identity
+the game is not playable, cannot save progress, and cannot join multiplayer.
+The SDK handles both contexts with one `initEmbed(...)` call:
+
+- **Embedded in the Genex dashboard (an iframe):** a silent handshake with the
+  dashboard signs the player in within a couple of seconds — no login screen.
+- **Standalone (someone opens the game's link directly):** the SDK redirects
+  through Genex sign-in (first-time visitors sign up there) and returns to the
+  game automatically. This is a real page navigation, by design — game code
+  does not need to handle any of it.
+
+While identity is resolving (or missing) the SDK shows its own full-screen
+overlay over the game, so never build a separate "connecting" screen for auth.
+
+## Install
+
+```bash
+npm i @genex-ai/embed-sdk @sentry/browser
+```
+
+(`@sentry/browser` powers the crash reporting + session replay wiring below —
+it's an optional peer of the SDK, and every Genex game installs it. Already
+installed if you followed Step 3 of the scaffold; repeated here so this skill
+is self-contained.)
+
+## Bootstrap (required, every game)
+
+```ts
+// main.ts — the FIRST things in the boot sequence, before any other game code
+import { initGameSentry } from "@genex-ai/embed-sdk/sentry";
+import { initEmbed } from "@genex-ai/embed-sdk";
+import { GENEX } from "./genex.config";
+
+// Crash reporting + session replay FIRST — so even a failure inside the auth
+// boot below gets reported. One required field; never pass tokens to it.
+initGameSentry({ slug: GENEX.slug });
+
+initEmbed({
+  slug: GENEX.slug,
+  apiUrl: GENEX.apiUrl,
+  dashboardOrigins: GENEX.dashboardOrigins,
+});
+```
+
+Scene setup and asset loading may continue immediately after this call — auth
+never blocks rendering. Gate the **identity-dependent** parts (multiplayer
+connect, saving/loading progress, showing the player's name) on `waitForAuth()`:
+
+```ts
+import { waitForAuth, getColyseusAuth, getEmbedToken } from "@genex-ai/embed-sdk";
+
+const { user } = await waitForAuth();   // resolves when signed in; rejects if blocked
+// user.id / user.name are the real Genex identity
+```
+
+## API surface (exact — do not invent methods)
+
+- `initEmbed({ slug, apiUrl, dashboardOrigins })` — call once, first. All three
+  fields required (from `genex.config.ts`).
+- `waitForAuth()` → `Promise<{ user }>` — THE gate for `connect()` and `/state`
+  calls. Rejects if the session ends up blocked — catch it and let the SDK's
+  overlay handle the UX (don't build your own sign-in UI).
+- `isEmbedded()` → `boolean` — structural "is in an iframe" check; NOT the same
+  question as "is signed in".
+- `getAuthState()` → `"pending" | "authenticated" | "blocked"` — synchronous.
+- `getUser()` → `{ id, name, image? } | null` — non-null only when authenticated.
+- `getEmbedToken()` → `string | undefined` — for `Authorization: Bearer` on
+  `GET`/`PUT ${GENEX.apiUrl}/api/projects/${GENEX.slug}/state` (both REQUIRE it).
+- `getColyseusAuth()` → `{ embedToken } | undefined` — pass as `connect()`'s
+  `auth` option (REQUIRED — the relay rejects tokenless joins). Read it fresh
+  at every `connect()` call; tokens rotate automatically (~every 10 minutes).
+- `on(event, cb)` → unsubscribe fn. Events: `"authenticated"`, `"blocked"`,
+  `"error"`.
+
+From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
+
+- `initGameSentry({ slug, dsn?, environment? })` — call once, BEFORE
+  `initEmbed()`. Only `slug` is required; the shared Genex Sentry project DSN
+  is built in. Errors, tracing, and session replay all start here; the signed-in
+  user is attached automatically after auth (no code needed).
+- `sentryCanvasSnapshot(canvas)` — session replay records the DOM, not the 3D
+  canvas; call this once per frame at the END of the render loop so replays
+  show actual gameplay. Works for BOTH WebGL and WebGPU renderers; internally
+  throttled, so calling at 60fps is fine:
+
+```ts
+function animate() {
+  requestAnimationFrame(animate);
+  // ...game update...
+  renderer.render(scene, camera);
+  sentryCanvasSnapshot(renderer.domElement); // AFTER render, same frame
+}
+```
+
+## Crash reporting rules
+
+- `initGameSentry` has token scrubbing built in (the sign-in return-trip pass
+  in URLs is redacted automatically). Never wrap, reimplement, or bypass it —
+  and never add Sentry options that capture network request/response bodies.
+- Don't call `Sentry.init` yourself or add a second error reporter —
+  `initGameSentry` is the one entry point.
+- Manual capture is fine where a try/catch swallows a real bug:
+  `import * as Sentry from "@sentry/browser"; Sentry.captureException(err)`.
+
+## NEVER log the tokens
+
+**NEVER log the return value of `getEmbedToken()` or `getColyseusAuth()` — not
+to `console.log`, not to a crash-reporter or analytics breadcrumb.** The token
+is bounded (15 minutes, one game, one scope), but third-party logging-service
+retention can outlive that. Nothing in normal game code ever needs to print it.
+
+## Config wiring (already done — do NOT hand-write URLs)
+
+**`genex init` already wrote the config files** — do not create or edit them,
+and NEVER hardcode an environment URL anywhere in game code:
+
+- `src/genex.config.ts` — a static env-reader (production URL defaults,
+  overridable via `VITE_GENEX_*` env vars). Import `GENEX` from it as shown
+  above; treat the file as read-only.
+- `.env` — `VITE_GENEX_SLUG` (the game's identity; committed).
+- `.env.development.local` — present only when init ran against a local/dev
+  stack: URL overrides that apply in `npm run dev` ONLY. A production build
+  (`vite build`) always uses the production defaults, so localhost values can
+  never ship. Gitignored via `*.local` — never commit it.
+
+If `src/genex.config.ts` is somehow missing (e.g. it was deleted), re-run
+`genex init` in the project folder rather than writing one by hand.
+
+## Standalone behavior (what to expect, not something to code)
+
+Opening the game's link directly (not from the dashboard) bounces through the
+Genex sign-in page and back before the game becomes playable — including during
+your own local `npm run dev` checks (sign in once; the bounce is instant after
+that). The return trip carries a one-time pass in the URL that the SDK consumes
+and removes immediately. Don't code around any of this: no `?`/`#` URL params
+of yours will be affected, and `isEmbedded()` / the return-trip handling are
+internal SDK concerns.
+
+## Checklist
+
+- [ ] `initGameSentry({ slug: GENEX.slug })` is the very first call in `main.ts`.
+- [ ] `initEmbed(...)` follows it, with all three config fields.
+- [ ] `sentryCanvasSnapshot(renderer.domElement)` runs after `renderer.render()`
+      in the main loop (WebGL and WebGPU alike).
+- [ ] `genex.config.ts` includes `dashboardOrigins` (from `.genex/project.json`).
+- [ ] Everything identity-dependent awaits `waitForAuth()` (multiplayer `connect`,
+      `/state` load/save, player-name UI).
+- [ ] `/state` fetches send `Authorization: Bearer ${getEmbedToken()}`.
+- [ ] No token value is ever logged or sent to analytics.
+- [ ] No custom sign-in/anonymous-fallback UI — the SDK overlay + dashboard own that.
+
+## Troubleshooting
+
+- **Game loads then immediately navigates away (standalone/local dev)** — that's
+  the sign-in bounce working as designed. Sign in once in the browser; it
+  returns to the game automatically.
+- **`waitForAuth()` rejects / state is `"blocked"`** — the visitor declined or
+  failed sign-in, or the dashboard session ended. The SDK overlay (or the
+  dashboard, when embedded) shows the sign-in prompt; the game just stays
+  paused behind it. Don't retry in a loop.
+- **Multiplayer join rejected with 401** — `connect()` ran before
+  `waitForAuth()` resolved, without `auth: getColyseusAuth()!`, or with a stale
+  cached token on reconnect (read it fresh each call).
+- **`/state` returns 401/403** — missing `Authorization` header (401) or the
+  token belongs to a different game (403): `GENEX.slug` doesn't match this
+  project.