@call-me-sensei/toonlab 0.4.22 → 0.4.24

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.4.22 and does not require access to the source
+reference for version 0.4.24 and does not require access to the source
 repository.
 
 ## Install
@@ -67,13 +67,13 @@ release. A one-asset Node rock annotation compiler is also repository-only.
 The npm artifact contains four supported layers:
 
 1. The JavaScript runtime and TypeScript declarations for the public imports.
-2. Text-only agent guides, prompts, references, and paired Codex/Claude skills
+2. Text-only agent guides, prompts, references, a copyable game example, and paired Codex/Claude skills
    under `agents/`.
 3. The `toonlab` manifest audit CLI and `toonlab-mcp` local stdio MCP server.
 4. The local MCP database/catalog support required for Library and asset
    discovery workflows.
 
-It does not contain the ToonLab website, Lab application UIs, examples,
+It does not contain the ToonLab website, Lab application UIs, repository demo applications,
 screenshots, models, textures, or other binary media. Optional public fixtures
 are identified by immutable `https://assets.toonlab.io` metadata rather than
 being bundled. Authored tree recipes are assets too: the reviewed public tree
@@ -115,8 +115,12 @@ await look.apply(CALL_ME_SENSEI_STYLE_BUNDLE, {
 
 renderer.setAnimationLoop(() => {
   const delta = clock.getDelta();
+  sky?.update(delta);
   look.update(delta, camera);
-  renderer.render(scene, camera);
+  // Update host-owned grass/characters here if this scene uses them.
+  water?.update(delta, camera);
+  if (post) post.render(delta);
+  else renderer.render(scene, camera);
 });
 ```
 
@@ -124,10 +128,22 @@ The host application still owns renderer creation, geometry and XZ layout,
 cameras, controls, gameplay, dynamic physics, navigation, persistence, and the
 frame loop. ToonLab does not turn a prompt into a finished world.
 
+## Realistic rock surface generation
+
+The public `rockgen` entry includes `createNaturalRockMapData`,
+`createNaturalRockSurfaceSpecification`, `resolveNaturalRockProjection`,
+`NATURAL_ROCK_SURFACE_PROFILES`, and `NATURAL_ROCK_MAP_ROLES`.
+These are the same deterministic realistic material profiles used by the Rock
+Lab. They produce typed RGBA map data; the host creates textures and assigns
+material/projection settings. Saved library rocks retain their surface recipe.
+The published realistic GLB is also available through raw catalog acquisition.
+Composite lithologies require authored semantic regions; micro-height maps are
+surface detail, not displacement that replaces a geometric high-to-low bake.
+
 ## Load Nature Reference Rocks
 
-Version 0.4.22 understands both the original `rock-0001`–`rock-0480`
-identities and the `rock-c8-*` Nature Reference Rocks. Acquiring an asset
+Version 0.4.24 understands both the original `rock-0001`–`rock-0480`
+identities and the Nature Reference Rocks catalog. Acquiring an asset
 directly returns its realistic PBR GLB. The one-call placement path additionally
 loads that asset's reviewed geology maps and `call_me_sensei` material settings
 before applying the selected style bundle.
@@ -146,21 +162,24 @@ const provider = createOfficialCatalogProvider({
   transport: 'public-rock',
 });
 const assets = createOfficialCatalogAssetRuntime({ provider, renderer });
+const catalog = await provider.listAssets();
+const selectedRock = catalog.assets.find((asset) => asset.label.toLowerCase().includes('sandstone'));
+if (!selectedRock) throw new Error('Select an available sandstone rock from the catalog.');
 
 // Raw acquisition keeps the realistic PBR model.
-const realistic = await assets.acquireAsset('rock-c8-arch-sandstone');
+const realistic = await assets.acquireAsset(selectedRock.id);
 scene.add(realistic.root);
 
 // Placement loads the same rock's geology maps and applies Call Me Sensei.
 const stylized = await loadOfficialCatalogAsset({
-  assetId: 'rock-c8-arch-sandstone',
+  assetId: selectedRock.id,
   assetRuntime: assets,
   parent: scene,
   styleBundle: CALL_ME_SENSEI_STYLE_BUNDLE,
 });
 
 // Rock Lab/editor integrations receive the non-destructive authoring contract.
-const rockPackage = await assets.getRockPackage('rock-c8-arch-sandstone');
+const rockPackage = await assets.getRockPackage(selectedRock.id);
 const editorSource = createOfficialCatalogRockEditorDescriptor(
   rockPackage.asset,
   rockPackage,
@@ -177,32 +196,23 @@ when their scene lifetime ends.
 
 Everything in this section is present in the installed npm package.
 
-### Codex
-
-```bash
-cp node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md ./AGENTS.md
-mkdir -p .agents/skills
-cp -R node_modules/@call-me-sensei/toonlab/agents/skills/codex/* .agents/skills/
-```
+### Use the installed guide
 
-### Claude Code
+Add a reference to `node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md`
+in the project's existing instructions, or read it directly. Merge relevant
+guidance; do not replace an existing `AGENTS.md` or `CLAUDE.md`. Claude's optional
+wrapper is `agents/claude/CLAUDE.md`; Cursor's is `agents/cursor/toonlab.mdc`.
 
-```bash
-cp node_modules/@call-me-sensei/toonlab/agents/claude/CLAUDE.md ./CLAUDE.md
-mkdir -p .claude/skills
-cp -R node_modules/@call-me-sensei/toonlab/agents/skills/claude/* .claude/skills/
-```
-
-### Cursor
-
-```bash
-mkdir -p .cursor/rules
-cp node_modules/@call-me-sensei/toonlab/agents/cursor/toonlab.mdc .cursor/rules/
-```
+Copy only the feature skills you need into the client's skill directory, while
+preserving any existing skills with the same names. Shared `agents/...`
+references remain relative to the installed package root. Keep the package
+installed; copying a single skill does not copy its reference library.
 
-Use `agents/PROMPTS.md` for ready-to-paste prompts. Begin with `game-dev` for
-an existing scene and add `asset-sourcing` when Library, Gallery, or MCP asset
-discovery is involved.
+Start with `game-dev` for a new game or existing-scene integration, then add
+`asset-sourcing` for Library/Gallery work and the focused rendering skills as
+needed. `agents/PROMPTS.md` contains the prompt cookbook.
+`agents/examples/game-foundation.mjs` is a copyable, playable blockout example;
+it is application code, not an exported ToonLab game engine.
 
 ## Connect MCP
 
@@ -218,7 +228,8 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "@call-me-sensei/toonlab@0.4.22",
+        "--package=@call-me-sensei/toonlab@0.4.24",
+        "toonlab-mcp",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"
       ],
@@ -230,7 +241,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
 }
 ```
 
-This server provides the anime-game profile, runtime guide, live-Lab
+This server provides the anime-game profile, live-Lab
 contracts, deterministic document creation and mutation, policy validation,
 public Gallery search/retrieval, local Library operations, and optional
 provider-backed generation when the developer supplies server-side provider

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.4.22
+## Versioned expectation: 0.4.24
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -115,7 +115,7 @@ await inspector.setDomainEnabled(label.domain, false);
 **Run the labs locally** (this repo):
 
 ```bash
-git clone https://github.com/call-me-sensei/toonlab.git && cd toonlab
+git clone https://github.com/call-me-sensei-app/toonlab.git && cd toonlab
 npm install
 npm run setup
 npm run dev
@@ -125,7 +125,7 @@ Setup starts local Postgres with Docker Compose, applies schema migrations and
 official catalog seeds, and reports configured BYO-key providers. Set an
 external `DATABASE_URL` to use an existing Postgres service instead. Vite
 serves the labs at `http://127.0.0.1:5175`. See
-[Getting started](https://github.com/call-me-sensei/toonlab/blob/main/docs/getting-started.md) for a tour.
+[Getting started](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/getting-started.md) for a tour.
 
 ### Open the full documentation locally
 
@@ -153,7 +153,7 @@ Prerequisites:
 Install and configure:
 
 ```bash
-git clone https://github.com/call-me-sensei/toonlab.git
+git clone https://github.com/call-me-sensei-app/toonlab.git
 cd toonlab
 npm install
 cp .env.example .env
@@ -317,8 +317,8 @@ exported files; generate approved seeded recipes; and import assets into the
 project. Authored Gallery recipes are fetched with their public license and
 provenance instead of being copied into the npm package. The server uses stdio,
 requires no account or OAuth for public discovery, and keeps local work local.
-See [Local MCP and workspace](https://github.com/call-me-sensei/toonlab/blob/main/docs/mcp.md) and
-[Local database and public asset releases](https://github.com/call-me-sensei/toonlab/blob/main/docs/local-database-and-public-assets.md).
+See [Local MCP and workspace](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/mcp.md) and
+[Local database and public asset releases](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/local-database-and-public-assets.md).
 
 ## The labs
 
@@ -326,7 +326,7 @@ Lab UIs are development tools and are not published in the npm package. The
 Labs home (`/`) presents the 15 live user-facing Labs by the artifact they
 author. Every Lab can save and reopen its documented portable creation type;
 preview cameras, stages, lights, playback, and comparison helpers remain
-preview-only. See [The 15 live ToonLab Labs](https://github.com/call-me-sensei/toonlab/blob/main/docs/live-labs.md).
+preview-only. See [The 15 live ToonLab Labs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/live-labs.md).
 
 Focused ToonLab shaders, water, vegetation, generated assets, texture recipes,
 Gallery assets, and metadata are intended for supplied scene content. Complete
@@ -336,7 +336,7 @@ construction remain host responsibilities.
 Every lab also uses one shared 24-hour preview harness with Dawn, Day, Sunset,
 and Night captures. The Day reference must visibly show Call Me Sensei's
 cool/blue shadow response. See the
-[universal preview contract](https://github.com/call-me-sensei/toonlab/blob/main/docs/lab-preview-environment.md).
+[universal preview contract](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/lab-preview-environment.md).
 
 - **Shaders** — Character, Tree, Grass, Flower, Rock, Ground, Manufactured
   Surface, Water, Sky, Cloud, and integrated Sky & Cloud authoring.
@@ -345,8 +345,8 @@ cool/blue shadow response. See the
 
 Every card links to a working editor. Integration examples are documented as
 examples rather than additional Labs. See
-[Lab responsibilities](https://github.com/call-me-sensei/toonlab/blob/main/docs/lab-architecture.md) for scope rules and
-[Getting started](https://github.com/call-me-sensei/toonlab/blob/main/docs/getting-started.md) for current direct routes.
+[Lab responsibilities](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/lab-architecture.md) for scope rules and
+[Getting started](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/getting-started.md) for current direct routes.
 
 Sky, Cloud, and Water Labs author reusable rendering artifacts. Your application
 still supplies valid scene geometry, placement, current conditions, and the
@@ -362,7 +362,7 @@ retired after the verified commit. Static hosted builds
 fall back to browser storage. **Reset Lab** clears the current lab state.
 Point any model-aware lab at your own model with the Model URL input or
 `?model=` — see
-[Characters](https://github.com/call-me-sensei/toonlab/blob/main/docs/characters.md).
+[Characters](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/characters.md).
 
 ## What's inside
 
@@ -375,21 +375,21 @@ camera behavior, and game feel remain host-owned or pre-beta.
 
 | Cluster | Import | What you get |
 |---|---|---|
-| Styles and bundles | `@call-me-sensei/toonlab/styles` | Local, versioned style-bundle documents that coordinate domain profiles without storing asset identity or current scene state. Create, validate, serialize, parse, and resolve JSON with no account or database; hosts currently route explicitly labeled assets through each owning runtime. [Contract](https://github.com/call-me-sensei/toonlab/blob/main/docs/styles-and-bundles.md) |
-| Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/toon-shading.md) |
-| Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/environment.md) |
-| Water | `@call-me-sensei/toonlab/water` | Focused water treatment for a host-authored water footprint, continuous shore, and closed seabed: Gerstner waves, absorption color, refraction/caustics/foam, ripples, splashes, wakes, kelp, underwater treatment, and CPU buoyancy sampling. It does not design the coast or underwater habitat. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/water.md) |
-| Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, five leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md) |
-| Rock shader | `@call-me-sensei/toonlab/rock-shader` | Detailed, versioned rock-material profiles with projected detail, distance tint, normal fading, striping, moss and optional top layers, plus explicit source-albedo and vertex-color/AO integration. Call Me Sensei is the default. Geometry generation remains separate in `rockgen`. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/rock-shader.md) |
-| Ground shader | `@call-me-sensei/toonlab/ground-shader` | Splat-weighted anime terrain with slope/cliff detail, shoreline and weather response, HDR sun/shade controls, safe shadow defaults, and flat-albedo ground-field output for vegetation adoption. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/ground-shader.md) |
-| Sky | `@call-me-sensei/toonlab/sky` | Reusable atmosphere, palette, sun, moon, stars, and god-ray settings authored by Sky Lab and Sky & Cloud Lab. Your application coordinates final lighting and scene state. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/sky.md) |
-| Cloud | `@call-me-sensei/toonlab/cloud` | Reusable cloud shape, erosion, density, lighting, wind, cirrus, haze, fade, style, and hero-cloud recipe controls authored by Cloud Shader Lab and Sky & Cloud Lab. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/cloud-shader.md) |
-| Post-processing | `@call-me-sensei/toonlab/post` | Optional single-pipeline compositor: character-aware bloom, color grade, LUT, vignette, screen outline, depth cue — schema-driven, preset-serializable. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/post-processing.md) |
-| Procedural textures | `@call-me-sensei/toonlab/texgen` | Seamless CPU-baked PBR texture generator: 25 tileable pattern/noise generators, layered detail + colored overlays (moss, rust, grime), five-stop cel-capable color ramp, cavity/sheen hand-painted read, derived normal/AO/roughness/metalness/height/ORM/emissive maps, 60+ presets, and a natural-language recipe mapper (offline keywords or BYO-key Gemini/OpenAI). [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/texture-lab.md) |
-| Character pipeline | `@call-me-sensei/toonlab/character` | High-level load/style/rig/animate lifecycle runtime, bone-role adapters for VRM/MMD/Mixamo/Rigify rigs, native-or-packaged locomotion fallback, and procedural freestyle swim. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/characters.md) |
+| Styles and bundles | `@call-me-sensei/toonlab/styles` | Local, versioned style-bundle documents that coordinate domain profiles without storing asset identity or current scene state. Create, validate, serialize, parse, and resolve JSON with no account or database; hosts currently route explicitly labeled assets through each owning runtime. [Contract](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/styles-and-bundles.md) |
+| Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/toon-shading.md) |
+| Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/environment.md) |
+| Water | `@call-me-sensei/toonlab/water` | Focused water treatment for a host-authored water footprint, continuous shore, and closed seabed: Gerstner waves, absorption color, refraction/caustics/foam, ripples, splashes, wakes, kelp, underwater treatment, and CPU buoyancy sampling. It does not design the coast or underwater habitat. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/water.md) |
+| Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, eight leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/vegetation-sky.md) |
+| Rock shader | `@call-me-sensei/toonlab/rock-shader` | Detailed, versioned rock-material profiles with projected detail, distance tint, normal fading, striping, moss and optional top layers, plus explicit source-albedo and vertex-color/AO integration. Call Me Sensei is the default. Geometry generation remains separate in `rockgen`. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/rock-shader.md) |
+| Ground shader | `@call-me-sensei/toonlab/ground-shader` | Splat-weighted anime terrain with slope/cliff detail, shoreline and weather response, HDR sun/shade controls, safe shadow defaults, and flat-albedo ground-field output for vegetation adoption. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/ground-shader.md) |
+| Sky | `@call-me-sensei/toonlab/sky` | Reusable atmosphere, palette, sun, moon, stars, and god-ray settings authored by Sky Lab and Sky & Cloud Lab. Your application coordinates final lighting and scene state. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/sky.md) |
+| Cloud | `@call-me-sensei/toonlab/cloud` | Reusable cloud shape, erosion, density, lighting, wind, cirrus, haze, fade, style, and hero-cloud recipe controls authored by Cloud Shader Lab and Sky & Cloud Lab. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/cloud-shader.md) |
+| Post-processing | `@call-me-sensei/toonlab/post` | Optional single-pipeline compositor: character-aware bloom, color grade, LUT, vignette, screen outline, depth cue — schema-driven, preset-serializable. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/post-processing.md) |
+| Procedural textures | `@call-me-sensei/toonlab/texgen` | Seamless CPU-baked PBR texture generator: 25 tileable pattern/noise generators, layered detail + colored overlays (moss, rust, grime), five-stop cel-capable color ramp, cavity/sheen hand-painted read, derived normal/AO/roughness/metalness/height/ORM/emissive maps, 60+ presets, and a natural-language recipe mapper (offline keywords or BYO-key Gemini/OpenAI). [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/texture-lab.md) |
+| Character pipeline | `@call-me-sensei/toonlab/character` | High-level load/style/rig/animate lifecycle runtime, bone-role adapters for VRM/MMD/Mixamo/Rigify rigs, native-or-packaged locomotion fallback, and procedural freestyle swim. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/characters.md) |
 | Scene surface runtime | `@call-me-sensei/toonlab/runtime` | One strict heightfield contract for grounded props/characters, terrain-aware meadow scatter, shoreline water bed/phase/state wiring, source-texture continuity, and actual labeled shadow-coverage readiness. The host still authors terrain and XZ layout. |
 | Scene collision runtime | `@call-me-sensei/toonlab/runtime` | Automatic reversible collision discovery for labeled static solids, lightweight walkable blockers by default, strict readiness diagnostics, and public Rapier/custom-adapter integration. |
-| Model loaders | `@call-me-sensei/toonlab/loaders` | Optional GLB/glTF, VRM 0+1, PMX/PMD, FBX, OBJ, and text-USDZ loading helpers. Kept off the root import so apps that do not load models avoid loader dependencies. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/characters.md) |
+| Model loaders | `@call-me-sensei/toonlab/loaders` | Optional GLB/glTF, VRM 0+1, PMX/PMD, FBX, OBJ, and text-USDZ loading helpers. Kept off the root import so apps that do not load models avoid loader dependencies. [Docs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/characters.md) |
 
 The main `vegetation` barrel exposes the complete runtime. Smaller consumers
 can import the same bindings from
@@ -573,7 +573,8 @@ Use the domain-specific runtimes below to implement each `apply` callback.
 Asset identity stays in project/library sourcing configuration; it is never
 embedded in the style bundle. Custom adapters and custom assets must be
 recorded in `.toonlab/reports/style-asset-gaps.json` and
-`TOONLAB_ASSET_GAPS.md`.
+`.toonlab/reports/asset-gaps.md`. These generated review records stay local and are
+excluded from source control.
 
 ### Individual clusters
 
@@ -622,42 +623,42 @@ stack, with WebGL2 fallback through the same TSL path.
   MCP setup, the prompt cookbook, and the full settings reference. Hosted
   features are marked "Pro"; the extended hosted docs live at
   [toonlab.io/docs](https://toonlab.io/docs).
-- [Lab responsibilities](https://github.com/call-me-sensei/toonlab/blob/main/docs/lab-architecture.md) — the finalized artifact,
+- [Lab responsibilities](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/lab-architecture.md) — the finalized artifact,
   production-method, editor/library, and preview-state boundaries.
-- [The 15 live ToonLab Labs](https://github.com/call-me-sensei/toonlab/blob/main/docs/live-labs.md) — each user-facing editor, saved artifact, runtime, and generation workflow.
-- [Universal lab preview environment](https://github.com/call-me-sensei/toonlab/blob/main/docs/lab-preview-environment.md) —
+- [The 15 live ToonLab Labs](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/live-labs.md) — each user-facing editor, saved artifact, runtime, and generation workflow.
+- [Universal lab preview environment](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/lab-preview-environment.md) —
   shared 24-hour controls, four-state regression matrix, and required cool/blue
   daylight-shadow verification.
-- [Rock shader](https://github.com/call-me-sensei/toonlab/blob/main/docs/rock-shader.md) — the separate generator/material
-  architecture, 58-field public configuration, import policy, and bundle use.
-- [Styles, style bundles, and asset routing](https://github.com/call-me-sensei/toonlab/blob/main/docs/styles-and-bundles.md) —
+- [Rock shader](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/rock-shader.md) — the separate generator/material
+  architecture, schema-defined public configuration, import policy, and bundle use.
+- [Styles, style bundles, and asset routing](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/styles-and-bundles.md) —
   rendering domains, required asset labels, fallback policy, bundle ownership,
   OSS application boundaries, and the shader/lab migration contract.
-- [Open asset library and scene coverage](https://github.com/call-me-sensei/toonlab/blob/main/docs/open-asset-library.md) —
+- [Open asset library and scene coverage](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/open-asset-library.md) —
   measurable scene-kit coverage, curated stylized generator base sets,
   CC0/CC-BY provenance, gallery routing, and generation fallback policy.
-- [Getting started](https://github.com/call-me-sensei/toonlab/blob/main/docs/getting-started.md) — clone, run, tour the labs,
+- [Getting started](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/getting-started.md) — clone, run, tour the labs,
   load your own models.
-- [Current capability status](https://github.com/call-me-sensei/toonlab/blob/main/docs/capability-status.md) — recommended
+- [Current capability status](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/capability-status.md) — recommended
   existing-scene, Gallery, MCP, and focused-authoring workflows versus
   experimental scene-construction claims.
-- [Toon character shading](https://github.com/call-me-sensei/toonlab/blob/main/docs/toon-shading.md)
-- [Manufactured environment materials](https://github.com/call-me-sensei/toonlab/blob/main/docs/urban-prop-surface-roles.md) —
+- [Toon character shading](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/toon-shading.md)
+- [Manufactured environment materials](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/urban-prop-surface-roles.md) —
   the layered classify-once contract for props, vehicles, buildings,
   interiors, and reusable material-aware shaders.
-- [Environment shading](https://github.com/call-me-sensei/toonlab/blob/main/docs/environment.md)
-- [Styles and bundles](https://github.com/call-me-sensei/toonlab/blob/main/docs/styles-and-bundles.md) — apply coordinated treatments to explicitly labeled scene targets.
-- [Current release notes](https://github.com/call-me-sensei/toonlab/blob/main/docs/release-notes.md)
-- [Water](https://github.com/call-me-sensei/toonlab/blob/main/docs/water.md)
-- [Sky system](https://github.com/call-me-sensei/toonlab/blob/main/docs/sky.md)
-- [Cloud shader](https://github.com/call-me-sensei/toonlab/blob/main/docs/cloud-shader.md)
-- [Vegetation](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md)
-- [Post-processing](https://github.com/call-me-sensei/toonlab/blob/main/docs/post-processing.md)
-- [Texture Lab and texgen](https://github.com/call-me-sensei/toonlab/blob/main/docs/texture-lab.md)
-- [Characters and animation](https://github.com/call-me-sensei/toonlab/blob/main/docs/characters.md)
-- [Settings reference](https://github.com/call-me-sensei/toonlab/blob/main/docs/settings-reference.md) — every tunable field,
+- [Environment shading](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/environment.md)
+- [Styles and bundles](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/styles-and-bundles.md) — apply coordinated treatments to explicitly labeled scene targets.
+- [Current release notes](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/release-notes.md)
+- [Water](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/water.md)
+- [Sky system](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/sky.md)
+- [Cloud shader](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/cloud-shader.md)
+- [Vegetation](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/vegetation-sky.md)
+- [Post-processing](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/post-processing.md)
+- [Texture Lab and texgen](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/texture-lab.md)
+- [Characters and animation](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/characters.md)
+- [Settings reference](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/settings-reference.md) — selected runtime and repository settings,
   generated from the schemas (`node scripts/generate-settings-reference.mjs`).
-- [Shader constants](https://github.com/call-me-sensei/toonlab/blob/main/docs/shader-constants.md) — the deliberately unexposed
+- [Shader constants](https://github.com/call-me-sensei-app/toonlab/blob/main/docs/shader-constants.md) — the deliberately unexposed
   constants and where they live.
 
 ## Build with an AI coding agent
@@ -667,14 +668,14 @@ Cursor, …). The recommended setup has three parts: give the agent the ToonLab
 skills, connect whichever ToonLab OSS local or ToonLab Pro remote MCP surface
 the developer has, then start from a goal prompt and iterate. The npm package
 ships runtime source and the small text-only `agents/` guidance bundle. It
-ships no models, textures, labs, examples, review fixtures, or other binary or
-visual assets.
+includes a copyable playable blockout in `agents/examples/game-foundation.mjs`;
+models, textures, Lab apps, repository demos and review media are not bundled.
 
 ### 1. Install the ToonLab skills in your game project
 
 The skills teach the agent the runtime boundary, asset-discovery order,
 frame-loop contract, and each focused subsystem API. Start with `game-dev` for
-integration into an existing scene and `asset-sourcing` for Gallery/MCP work.
+new-game development or integration, and `asset-sourcing` for Gallery/MCP work.
 Experimental whole-world, natural-cliff, Weather/Climate, camera, game-feel,
 and gameplay-VFX skills are intentionally not included in the npm artifact.
 
@@ -714,7 +715,7 @@ the public tree collection—those recipes are not npm built-ins:
   "mcpServers": {
     "toonlab-local": {
       "command": "npx",
-      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"],
+      "args": ["-y", "--package=@call-me-sensei/toonlab@latest", "toonlab-mcp", "--workspace", "/absolute/path/to/your-game/.toonlab"],
       "env": { "TOONLAB_LEGACY_WORKSPACE": "1" }
     }
   }

package/agents/PROMPTS.md

@@ -1,7 +1,21 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.4.22 runtime, agent skills, and MCP workflows.
+0.4.24 runtime, agent skills, and MCP workflows.
+
+## New playable game
+
+```text
+Use the installed ToonLab game-dev skill to build the game described in my
+request. Implement the host gameplay, input, camera, UI and level structure;
+use ToonLab's public APIs for the supported visual and runtime systems. Start
+with a playable slice that has movement, collision, one objective and restart,
+then replace placeholders and apply the selected style. Use the installed
+version's export map, preserve asset/material identities, assign one update
+owner per system, and verify actual keyboard/pointer input, resize and teardown.
+Do not invent package APIs or describe the result as polished before inspecting
+it at the gameplay camera. Report remaining limitations concretely.
+```
 
 ## Existing-scene integration
 
@@ -71,8 +85,8 @@ species engine.
 ```text
 Using the ToonLab rockgen and rock-ground-shaders skills, create or edit the
 requested rock asset with @call-me-sensei/toonlab/rockgen and style it with
-@call-me-sensei/toonlab/rock-shader. Keep geometry identity, seed, LOD,
-collision, and baked channels in the rock document; keep reusable appearance in
+@call-me-sensei/toonlab/rock-shader. Preserve geometry identity, seed, surface recipe, authored masks, LOD,
+collision, and bake provenance; keep reusable appearance in
 the rock shader profile. Validate the portable documents and verify the result
 from multiple useful views. Do not deep-import repository compilers or test
 fixtures.

package/agents/README.md

@@ -4,7 +4,8 @@ These are downloadable AI coding agent resources for developers using ToonLab
 runtime features in their own apps. They are not maintenance instructions for
 this repository.
 
-The recommended agent workflow starts from an existing scene: apply the
+For a new game, implement a playable host-game slice and then apply ToonLab.
+For an existing scene, preserve its authorized layout and systems: apply the
 focused character, manufactured, ground, rock, vegetation, water, sky, cloud,
 lighting, and post runtimes; find assets through Gallery or MCP; and author
 bounded portable outputs. The package does not promise reliable one-shot scene
@@ -22,12 +23,14 @@ Layout:
   runtime-boundary, sourcing-policy, and custom-gap contracts used by every
   agent integration.
 
-Recommended feature skills (start with `game-dev` for existing-scene
+Recommended feature skills (start with `game-dev` for new-game development or existing-scene
 integration and `asset-sourcing` for Gallery/MCP work):
 
 - `asset-sourcing`
 - `environment`
 - `game-dev`
+- `lighting`
+- `scene-style-application`
 - `post-processing`
 - `rock-ground-shaders`
 - `rockgen`
@@ -42,7 +45,7 @@ artifact. This includes whole-world construction, natural cliff formation,
 Weather/Climate composition, camera behavior, game feel, and gameplay VFX.
 
 These text-only resources ship with the npm package beside the runtime source.
-The package does not include ToonLab lab applications, examples, review
+The package does not include ToonLab lab applications, repository demo applications, review
 fixtures, models, textures, or other redistributed visual/media assets.
 First-party grass geometry and materials are generated by runtime code; the
 optional CC0 mannequin resolves from immutable public R2 rather than npm.
@@ -52,3 +55,10 @@ root needs a stable target ID/domain, and every material slot needs a stable
 material ID plus semantic role in the versioned ToonLab material contract.
 Root-only labels do not make multi-material assets bundle-ready. Strict mode
 blocks incomplete assets; advisory mode must report them as incomplete.
+
+References beginning `agents/` resolve under the installed package root. Do not
+copy the shared guide over an existing game instruction file: add a reference
+to it, or merge only relevant guidance. Individual skills copied to an agent's
+skill directory still read shared references from the installed package.
+See `references/game-lifecycle.md` for update ownership and
+`examples/game-foundation.mjs` for a copyable, verified playable blockout.

package/agents/claude/CLAUDE.md

@@ -2,6 +2,9 @@
 
 ## Claude Code
 
+- Resolve `agents/` references from the installed package root.
+- Use the `game-dev` skill for new games and integration; host-owned input,
+  gameplay and layout are part of requested game development.
 - Use `agents/skills/claude/` as the user-facing usage guides for ToonLab
   runtime features.
 - Keep this file short; shared guidance belongs in `agents/codex/AGENTS.md`.