@call-me-sensei/toonlab 0.4.22 → 0.4.23

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.23 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.23 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.23",
+        "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.23
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -379,7 +379,7 @@ camera behavior, and game feel remain host-owned or pre-beta.
 | 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) |
+| 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/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) |
@@ -629,7 +629,7 @@ stack, with WebGL2 fallback through the same TSL path.
   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.
+  architecture, schema-defined 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) —
   rendering domains, required asset labels, fallback policy, bundle ownership,
   OSS application boundaries, and the shader/lab migration contract.
@@ -655,7 +655,7 @@ stack, with WebGL2 fallback through the same TSL path.
 - [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,
+- [Settings reference](https://github.com/call-me-sensei/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
   constants and where they live.
@@ -667,14 +667,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 +714,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.23 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`.

package/agents/codex/AGENTS.md

@@ -1,161 +1,114 @@
 # ToonLab Agent Guide
 
-Use this file when helping a developer build an anime-style game, character,
-or environment with ToonLab's runtime library in their own Three.js app.
-
-## Anime-Game Product Contract
-
-- ToonLab is specifically an anime-game toolkit, not a generic stylization
-  library. Read `agents/references/anime-art-direction.md` before making
-  visual, shader, material, or asset decisions.
-- Load the selected bundle's `artDirection` and treat it as authoritative.
-  Call Me Sensei is the first-party coordinated reference.
-- Never accept unintended photorealism, generic low-poly styling, undirected
-  cartoon rendering, or untreated PBR materials as a finished ToonLab result.
-- If supported shaders or approved assets are insufficient, document the
-  customization and why your project needs it.
-
-## Runtime Boundary
-
-- `@call-me-sensei/toonlab` is primarily a runtime library for applying
-  Three.js shaders, stylized materials, focused vegetation/water, settings,
-  and preset documents to supplied scene content.
-- Prefer public package imports such as `@call-me-sensei/toonlab/toon`,
-  `@call-me-sensei/toonlab/environment`, `@call-me-sensei/toonlab/water`,
-  `@call-me-sensei/toonlab/vegetation`, `@call-me-sensei/toonlab/post`,
-  `@call-me-sensei/toonlab/styles`,
-  `@call-me-sensei/toonlab/texgen`, and `@call-me-sensei/toonlab/rockgen`.
-- Use `@call-me-sensei/toonlab/sky` and `/cloud` for the live Sky, Cloud, and
-  Sky & Cloud Lab contracts. Weather, Climate, ambient effects, and fauna are
-  not public package entry points in this release.
-- Use `@call-me-sensei/toonlab/vegetation-shaders` and
-  `@call-me-sensei/toonlab/grass-palettes` when a consumer needs only those
-  focused contracts. They are the same bindings exposed by the vegetation and
-  root barrels.
-- Keep root imports lightweight in examples. Import only the feature subpath a
-  developer needs.
-- Public export status and product maturity are different. Toon,
-  Environment/Ground/Rock, Tree/Grass/Flower, Water on a host-authored
-  footprint/shore/bed, Post, Gallery/MCP asset workflows, loaders, portable
-  settings, Sky/Cloud, and qualified focused generators are the recommended
-  path. Whole terrain/biome/coast/cliff construction,
-  automatic set dressing, and cross-system world assembly are experimental.
-- ToonLab's labs, sample assets, local manifests, screenshots, captures, and
-  app routes are examples. Do not treat them as part of the runtime API or copy
-  their local asset assumptions into user apps.
-- The host app owns scene layout and major geometry, asset placement, cameras,
-  collision, asset loading, decoder hosting, storage, routing, persistence,
-  collaboration, and final art direction. Renderer construction stays
-  host-owned, while the public renderer helper and scene style runtime apply
-  reversible Call Me Sensei renderer, lighting, probe, and shadow settings.
-- VFX, camera, game-feel, and renderer selection are not style-bundle domains.
-  Treat project-local implementations as custom adapters and record a gap when
-  they affect the selected look. Lighting is a supported bundle domain.
-
-## Usage Rules
-
-- Use the README and docs pages first; feature skills in `agents/skills/codex/`
-  are short usage guides for public runtime APIs.
-- For existing-scene or multi-system integration, start with the `game-dev`
-  skill (boundary, frame-loop contract, task→skill routing). When sourcing or generating
-  assets, use the `asset-sourcing` skill. Feature-detect the connected ToonLab
-  OSS local and/or ToonLab Pro remote MCP surface before calling tools; their
-  overlapping tool names have different discovery roles and schemas.
-  First-party rock search must shortlist from meter dimensions and taxonomy;
-  do not load or render catalog GLBs merely to determine their size.
-- Whole-world and natural-cliff construction skills are not shipped in the npm
-  package. Prefer bounded work on an existing terrain, asset family,
-  vegetation field, or water body.
-- For any style-aware construction, use `style-presets` to record the intended
-  selector and distinguish neutral defaults from domains that already default
-  to Call Me Sensei. Before visual approval or reporting a package gap, use
-  `visual-verification` for readiness, isolation, multi-view, measurement, and
-  outlier checks. These routes apply to every agent integration, not only Codex
-  or Claude.
-- ToonLab materials are TSL/NodeMaterial-first for Three.js WebGPU with WebGL2
-  fallback through the same TSL path. Do not guide developers toward raw GLSL,
-  `ShaderMaterial`, or classic WebGL-only forks for ToonLab features.
-- Keep developer examples focused on documented settings, preset documents,
-  public constructors/helpers, and app-owned Three.js objects.
-- Keep artifact scope explicit: Shader Labs author IP profiles, Asset Labs
-  author geometry/material data, and Water Lab authors a focused runtime
-  system preset with embedded shader controls. Sky, Cloud, and Sky & Cloud are
-  live focused authoring surfaces. Vegetation is one shared
-  implementation family with separate Tree, Grass, and Flower shader profiles;
-  their Generation Labs own geometry/material data. The public package ships
-  tree construction and shader capability, not predefined tree assets. Search
-  reviewed authored tree recipes through MCP; use `StylizedTree` or
-  `BranchTree` to instantiate or deliberately author them. Repository species
-  work is experimental and must not be presented as supported. Ground is a
-  separate shader domain. Scene weather,
-  lighting, camera, interactions, and complete Sky/Cloud composition stay
-  host-owned or experimental.
-- For style-bundle, multi-shader, or arbitrary-asset work, read
-  `agents/references/style-bundles.md` first. A bundle selects coordinated treatments;
-  explicit asset labels select rendering destinations; scene state selects
-  current conditions. Inventory and label every renderable root and material.
-  Every newly modeled, generated, or imported material slot requires a stable
-  ID and valid semantic role in the versioned material contract. A root domain
-  label is not sufficient for a multi-material asset; missing roles and mixed
-  atlases without a split or ID mask block strict handoff.
-  Character anatomy, clothing, held weapons, and worn hero accessories
-  normally route to toon; manufactured props, vegetation, rocks/debris,
-  water/sky, and VFX retain their owning runtimes. For an imported manufactured
-  prop, call `proposeManufacturedStyleTargetLabel()` first, review every issue,
-  provide explicit `materialOverrides` for unresolved slots, then call
-  `applyManufacturedStyleTargetLabelProposal()`. Never collapse assisted
-  results into the automatic success rate.
-- Report unknown domains and material roles, mixed atlases without masks,
-  unsupported transparency, and custom-renderer exemptions. Never silently
-  infer a production-safe route from names, texture colors, or scene
-  parenting. Preserve asset identity and runtime conditions when changing
-  style.
-- Local style bundle creation, validation, serialization, parsing, and
-  resolution are OSS `/styles` APIs and require no database. Hosted storage
-  and `fetchStyleBundle` are optional. Scene discovery remains explicit;
-  manufactured assets have a conservative proposal/review/apply labeling path,
-  and strict bundle application reconciles declared roles against live slots
-  before the first mutation.
-- New bundles use `treeShader`, `grassShader`, `flowerShader`, and
-  `groundShader`. V1 `vegetationShader`, `tree`, `grass`, and `flowers`
-  selections are migration inputs only and never serialize into v2. Do not
-  serialize asset recipes, tree geometry, scatter, or live wind/weather
-  into shader slots.
-- Treat `call_me_sensei` as the first-party reference bundle. Optimize the
-  canonical domain implementations for the best coordinated result and apply
-  the completion gate in `agents/references/style-bundles.md`. Assigning the same
-  style id to every slot is not completion, and compatibility flattening for
-  incomplete assets must not define the signature look.
-- For sourcing or generation, read
-  `agents/references/mcp-asset-discovery.md` and
-  `agents/references/asset-sourcing-policy.md`. Reuse an
-  accepted asset first. If a procedural family has an approved stylized base
-  set and passed the reliability gate, generate directly and skip gallery
-  search. Otherwise use curated CC0, then properly attributed CC-BY; reserve
-  image-to-3D for a named remaining gap. Preserve base-set version, recipe,
-  seed, domain/material labels, license provenance, and the Call Me Sensei
-  verification result. Pro may author/review base sets; OSS consumes portable
-  artifacts without a database.
-- For Sky/Cloud and Water work, `.settings` is the portable authored baseline and
-  `.renderedSettings` is the current composition. Give Lighting, Weather, and
-  other transient owners unique `setSceneOverrideLayer` ids and clear only the
-  same id; never export composed scene state.
-- In a composed-world test, use the public Lighting bundle slot and scene style
-  runtime for the coordinated sun, sky probe, and shared shadow contract. Keep
-  host-owned Weather and any custom local-light adapters coordinated with Sky,
-  Water, and vegetation scene inputs.
-- Sky documents contain exactly 46 portable art fields. Radius and compile-time
-  quality are not portable: named tiers use 2/3/4 cloud octaves, custom quality
-  accepts `{ cloudOctaves: 1..5 }`, and `sky.setQuality()` rebuilds the material.
-  Water quality is chosen when constructing/replacing `WaterSurface`, not via
-  `applySettings()`.
-- Do not depend on ToonLab sample assets, generated manifests, or lab-only
-  model/environment discovery.
-- Keep these downloadable resources focused on runtime usage.
-
-## Developer Verification
-
-- For consumer apps, run that app's normal typecheck, test, build, and visual
-  smoke checks.
-- For generated rock assets, use a fixed seed and compare the output your app
-  expects.
+Use ToonLab's public runtime to develop the game the user requested. Build the
+host game systems when needed; “host-owned” means your application implements
+that part, not that the task must be refused or called an experiment. Preserve
+existing gameplay and layout unless the request authorizes changing them.
+
+## Find the installed contract
+
+Resolve `@call-me-sensei/toonlab` in this project and read its `package.json`
+version and export map. In this guide and the feature skills, `agents/...` and
+`NPM-LIBRARY.md` are relative to that package root, normally
+`node_modules/@call-me-sensei/toonlab/`, not the game repository root. In a
+workspace with hoisted dependencies, resolve the installed location first.
+
+Start with `NPM-LIBRARY.md`, `agents/references/runtime-entry-points.md`, and the
+`game-dev` skill. Read other skills only for the systems the task uses. The
+installed package has the supported guides and references; a source checkout,
+Lab UI, Pro account, and generative AI are not prerequisites for building a game.
+Do not overwrite the game's existing agent instructions when installing this guide.
+
+## Divide responsibilities correctly
+
+| Application work | ToonLab support |
+| --- | --- |
+| Game rules, input, camera, UI, objectives, spawning, scene layout, navigation, dynamic physics, networking, persistence | Host code composed with the runtime; do not invent ToonLab APIs for these |
+| Renderer construction, resize, frame loop, shutdown | `renderer` helpers and scene-style configuration; use Three's `WebGPURenderer` for TSL, including its WebGL2 fallback |
+| Character loading, rig/clips, conversion, animation update/disposal | `createCharacterRuntime()`; `createWalkableCharacterRuntime()` connects locomotion and grounding to host movement/physics |
+| Terrain-bound placement, grass, shore and water-bed coordination | `createSceneSurfaceRuntime()` when the host supplies a heightfield |
+| Labeled static blockers | `createSceneStyleRuntime().collision`; use explicit collision metadata or the Rapier adapter where needed |
+| Coordinated lighting, sky inputs, ground field and shared shadows | `createSceneStyleRuntime()` and the public `lighting` domain |
+| Materials, vegetation, water, sky/cloud, post and procedural assets | Focused exports listed in `agents/references/runtime-entry-points.md` |
+
+A hand-built level is valid application work. Reliable automatic world layout,
+terrain/geology synthesis, navigation, camera controllers, gameplay VFX and the
+experimental species engine are not promises of the npm package. Do not import
+repository-only implementations or turn a Lab route into a runtime dependency.
+
+## Build in useful increments
+
+For a new game, make a playable vertical slice first: controls, movement,
+collision, camera, one objective, and restart. Then apply the selected art
+direction and add assets. For an existing game, integrate the requested domains
+without replacing its renderer or update loop unnecessarily. The `game-dev`
+skill gives the integration order and the frame ownership contract.
+
+Use focused package imports. Choose the selected bundle's treatment explicitly;
+Call Me Sensei is the first-party default when the user has not chosen another.
+Its bundle ID is `call-me-sensei`; many domain preset/style selectors instead
+use `call_me_sensei`. Use the documented selector for each API.
+
+Use `style-presets` before style-aware construction.
+For anime treatment, read `agents/references/anime-art-direction.md` and
+`agents/references/style-bundles.md`. Preserve source PBR maps and material
+identity. Realistic rock maps are valid asset inputs and may also be the user's
+requested output; do not confuse them with an accidentally unstyled anime scene.
+
+Label style targets by domain and give every material slot a stable material
+ID and semantic role. A root-only label is incomplete for a multi-material
+asset. Strict mode blocks incomplete coverage. Use the manufactured-material proposal/review/apply
+helpers for imported props. Report automatic and assisted results separately.
+Do not infer a physical material solely from its color or filename. Split mixed
+atlases or supply the required mask. Strict style application must reject
+incomplete coverage before mutation; advisory results must disclose gaps.
+
+Apply scene-wide styles through `styleRuntime.apply(...)`. It manages the
+lighting, renderer, shadow, and collision integrations as well as material
+transactions. Use the lower-level `applyStyleBundle()` only when the app owns
+those integrations deliberately. A `createStyleTarget()` descriptor alone is
+not durable labeling: use `labelStyleTarget()` for scene-label discovery.
+
+## Assets and MCP
+
+Use `asset-sourcing` when discovering/importing assets or requesting generation.
+Inspect the connected server's tool schemas: local and Pro tools with the same
+name can mean different things. Follow the project's actual policy; the strict
+acceptance fixture is not a universal rule for every game.
+
+Reuse project/Library assets, shortlist Gallery results from metadata, then
+retrieve selected artifacts. Preserve IDs, license, provenance, dimensions,
+recipe and seed. First-party rock dimensions and taxonomy support shortlisting
+without rendering GLBs just to measure them. Use returned IDs and public labels;
+internal production identifiers are not product names.
+
+MCP also creates and mutates portable Lab documents. Call `list_live_labs`,
+`get_lab_features`, then `create_lab_document`; its result wraps the portable
+JSON in `document`. Save through the relevant Library tool when persistence is
+part of the task. A valid document does not guarantee its preview or generated
+asset has passed visual review.
+
+Local `generate_asset` is procedural; local provider work uses
+`generate_ai_asset` and the user's keys. Pro `generate_asset` spends separately
+purchased credits. A free Pro month grants MCP access without AI credits.
+Generation capability is not permission to spend; follow existing authorization
+and the server's sourcing-policy requirements. Keep provider keys out of source
+and portable documents.
+
+## Verify and hand off
+
+Test through the app's real input and render path. Run its applicable checks,
+wait for asset/render readiness, inspect the console, and capture the requested
+views. Test restart/teardown and verify that listeners, resources, and animation
+loops are not duplicated. Each system has one update owner and each frame has
+one final render owner. Read `visual-verification` for a visual review.
+
+For a heightfield scene, run the shared surface audit after the required passes
+have rendered. Run `styleRuntime.collision.assertReady()` before relying on its
+blockers. Test actual movement around representative obstacles. Include LOD,
+shadow and shoreline views only when those systems are used.
+
+Record missing package capabilities and material-policy exceptions when they
+matter to the requested result. Ordinary host gameplay code is not a ToonLab
+failure. Report what works, what was tested, and any remaining limitation;
+never describe a build alone as a finished or visually approved game.