@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/agents/skills/claude/visual-verification/SKILL.md

@@ -1,136 +1,62 @@
 ---
 name: visual-verification
-description: How to prove a ToonLab scene actually looks right — settling the scene before screenshotting, isolating a subsystem to attribute a defect, measuring colour against sampled targets with CIEDE2000, scanning the scene graph for outliers, and running an adversarial critic loop. Use whenever judging, reviewing, or iterating on a rendered scene, and before reporting that any visual defect is a ToonLab limitation.
+description: Verify ToonLab rendered output and gameplay with settled frames, relevant camera views, subsystem isolation and measurable evidence. Use for visual reviews or diagnosing a suspected rendering defect.
 ---
 
-# Verifying that it looks right
+# Verify rendered output
 
-A passing build is not visual approval, and a screenshot is not evidence unless
-you know what was in the frame when it was taken. This skill is the measurement
-discipline that turns "it looks wrong" into "this surface, this value, this
-owner".
+References beginning `agents/` resolve from the installed ToonLab package root.
+A passing build does not establish visual correctness. Choose checks that match
+the requested change, the art direction and the cameras the game actually uses.
 
-## Settle the scene before you screenshot
+## Readiness and capture
 
-ToonLab subsystems keep resolving work **after their factory returns** — GLB
-loads, render-target passes, texture uploads. Screenshotting on a fixed frame
-count produces frames with whole subsystems missing while your manifest happily
-reports them as present.
+Await every readiness promise exposed by the host, render through its real
+pipeline, and check required objects/textures have loaded. For static fixtures,
+stable drawable counts across frames are a necessary signal, not proof of GPU
+compilation or successful rendering. Animated/procedural scenes may legitimately
+change counts; use their explicit readiness signals instead.
 
-Observed: the same command produced 273,520 triangles with the entire lagoon
-absent on one run and 606,056 on the next.
+Inspect pixels from the output (a small `readPixels` grid or the captured image).
+Check that intended surfaces are visible, with useful coverage and valid alpha.
+Do not hardcode black as the only empty-frame value; an empty scene may match a
+sky-colored or transparent background. Check relevant console/network errors
+and failed textures. Do not dismiss a failed required resource because the rest
+of the scene renders. Record the camera, readiness signals and capture path.
 
-So: await every readiness promise the host exposes, render through the real
-pipeline, and re-read the scene graph until triangle and drawable counts are
-**unchanged across several consecutive reads**. Treat count stability as a
-necessary signal, not proof that GPU compilation, render targets, or external
-loads succeeded. Then screenshot. Report `settled`, the readiness signals, and
-a non-zero rendered frame count in the capture manifest, and **fail the
-capture** if any required signal is wrong. A black or half-built frame must
-never be able to pass as a render.
+## Diagnose before attributing a defect
 
-Before accepting the final frame, inspect pixels from the real output (a
-small `readPixels` grid or the captured image). Fail when nearly every sample
-matches the renderer clear/background color, when useful RGB variance or
-non-background coverage is effectively zero, or when alpha is invalid. Do not
-hardcode black as the only empty-frame value: sky blue, transparent, and custom
-clear colors can hide the same failure. Record the distinct-color count or
-coverage ratio with the capture.
+Isolate the suspect subsystem while retaining its lighting and required passes.
+Compare with and without post-processing when appropriate. Keep camera, pose,
+exposure, lighting and source textures fixed for before/after comparisons.
+Inspect world-space bounds, scale and material contracts when an object has an
+unexpected silhouette, repeated pattern or stretched surface.
 
-Also fail on any browser console error. A texture that failed to decode is a
-defect, not a warning.
+For palette-matching tasks, sample corresponding material regions and compare
+small patches in a perceptual color space such as CIEDE2000. Confirm the probe
+hits the intended surface. For ordinary feature work, clear visual inspection
+and targeted telemetry are enough; do not invent numeric color gates without a
+reference or require measurement tools unrelated to the requested result.
 
-## Isolate before you blame
+## View and interaction coverage
 
-Render subsystems alone to attribute a defect — and include the light rig, or
-you get a black frame and learn nothing.
+Use gameplay cameras first. For 3D assets or formations, choose relevant views
+from hero, wide, close, flyover, top-down; include angles that expose seams or
+repetition. A fixed-camera UI change does not need a five-camera asset audit.
+Check near/far and lit/shadowed behavior when LOD or lighting is affected.
 
-A "flowing water" texture smeared over every cliff was investigated as a
-waterfall bug for two review cycles. One isolated capture of terrain plus its
-lighting settled it in a minute: the ground shader was painting it.
+For a game slice, exercise movement, collision, interaction, success/failure and
+restart where present. Test resize, focus loss/resume and teardown when changing
+lifecycle ownership. Confirm post-processing is the final render path when used.
 
-Support a query flag that takes a **list** (`?only=terrain,lighting,sky`), and a
-flag that bypasses post. Most attribution questions collapse to two captures.
+## Review and report
 
-## Measure colour, do not argue about it
+Take a separate review pass against the requested acceptance criteria. When
+active tools and developer authorization permit an independent agent/thread,
+that reviewer should capture fresh evidence. Otherwise review locally; do not
+spawn agents or create user tasks without authorization.
 
-Sample the frame at fixed points and compare against your target values in
-**CIEDE2000**, not by eye and not by RGB distance. Average a small patch rather
-than a single pixel so dithering does not decide the answer.
-
-Two disciplines that matter more than the metric:
-
-- **Probe the right surface.** A probe that lands on terrain when you think it
-  is on rock will report a rock defect that does not exist. Prove it: change the
-  suspected material's value and re-measure. If the probe does not move, it is
-  not on that material. This exact check revealed that two "rock" probes were
-  reading the ground shader.
-- **Probe where the reference has that material.** A probe placed at coordinates
-  the reference fills with sky, on a frame where your scene has a cliff, measures
-  a composition difference and reports it as a colour failure.
-
-Keep a second sampler for arbitrary points, so a question like "is the shaded
-wall darker than the lit one, and by how much" is one command.
-
-## Scan the scene graph for outliers
-
-Traverse for meshes above a size threshold and print path, world-space extent
-and position. This catches the things nobody sees because they read as
-background:
-
-- a 104 m slab lying across a 72 m channel, damming it;
-- "cliff-top caps" built at 70–90 m across when the tower crown is 20 m.
-
-Both survived several visual reviews. A ten-line traversal found each in
-seconds.
-
-Audit transforms the same way. Report per-role mean and max uniform scale and
-the worst axis ratio; a mean scale of 6× with a max of 22× is a stretched
-surface, and it is visible long before anyone can articulate why.
-
-## Judge from every approved camera
-
-A formation can read as one coherent mass from the hero camera and as a kit row
-from above. Fix a small set of cameras — hero, wide, close, flyover, top-down —
-and require all of them before approving a change. Never approve from one view.
-
-## Run an adversarial critic
-
-Separate the builder from the judge. When the active tool surface and developer
-authorization permit an independent agent/thread, have that critic capture its
-**own** fresh evidence rather than trusting the builder's screenshots. Otherwise
-perform a separate critic pass after clearing builder assumptions. Read the
-module source and return structured blockers: region, expected, actual, fix,
-owner.
-
-Make the critic's standard a specific shipped frame, not "good". Give it the
-sampled palette and an explicit auto-fail list, and require a verdict field that
-is hard to fudge — a boolean like `readsAsOneMass` forces a judgement that a
-score can blur.
-
-Then feed the blockers back to the builder with instructions not to argue but to
-disprove with a capture if it disagrees. Loop until the critic passes it.
-
-In the qualifying run, independent critics scored subsystems 1.5–3.0 out of 10
-with 9–11 blockers each and drove the useful visual fixes. Code inspection
-still found contract defects; rendered evidence determined whether they were
-visible and whether a correction actually improved the target frame.
-
-## Keep the harness honest under parallelism
-
-If several agents capture at once:
-
-- give each run its own port, or they fight over a fixed one;
-- serialise the browser through a small semaphore — GPU-backed browsers
-  exhaust WASM memory a few instances in, and the failure surfaces to an agent
-  as a broken module rather than as machine pressure;
-- expect transient failures from another agent's mid-edit file, and retry rather
-  than "fixing" a module you do not own.
-
-## Record the measurement, not the conclusion
-
-Write down the number and the command that produced it. "The wall is too blue"
-ages badly; "left wall `#4B6E97` L105 against target `#93A9C6` L168, from
-`capture --view hero` then a point sample at 300,250" can be re-checked after
-the scene has moved on — and it repeatedly turned out that the conclusion was
-wrong while the measurement was still useful.
+Describe concrete defects with location, expected result, observed result and
+likely owner. Fix them and repeat affected checks. Report evidence and remaining
+limitations without treating every host-owned feature as a ToonLab limitation.
+Use a standalone fixture to support claims about package defects.

package/agents/skills/claude/water/SKILL.md

@@ -3,6 +3,10 @@ name: water
 description: Help developers use ToonLab water materials, waves, ripple simulation, breakers, splashes, rain, kelp, or water settings.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Water
 
 Use this skill when a developer wants WaterSurface, water material settings,
@@ -65,8 +69,8 @@ Developer guidance:
   composition. Live scene owners use unique `setSceneOverrideLayer` ids and
   clear only their own id; they must not write composed values back to a preset.
 - In a composed world, let the host game own lighting and pass current light
-  state through Water's explicit scene adapters. Lighting is not a stable
-  public package or bundle domain.
+  state through Water's explicit scene adapters. The public lighting slot and `createSceneStyleRuntime()` coordinate the
+  supported lighting and shared-shadow contract.
 - Preserve the host renderer's depth convention. Water supports both standard
   and reversed depth; qualify contact foam and refraction using the host's
   actual `reversedDepthBuffer` setting rather than silently changing it.

package/agents/skills/codex/asset-sourcing/SKILL.md

@@ -3,6 +3,10 @@ name: asset-sourcing
 description: Help agents source anime-game-ready models, textures, and presets through policy-aware ToonLab MCP discovery, provenance, supported shaders, and explicit custom-gap reporting.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Asset Sourcing
 
 Use this skill when a developer needs an asset — a model, texture, HDRI,
@@ -66,7 +70,7 @@ scene-kit role.
    Never regenerate or re-download something already available.
 3. **Use an approved procedural family only when policy permits it.** Discover
    approved families through MCP, then use their focused runtime such as
-   `@call-me-sensei/toonlab/vegetation`, `rockgen`, `debrisgen`, or `texgen`.
+   `@call-me-sensei/toonlab/vegetation`, `rockgen` or `texgen`.
    This is the direct route only when the requested family has an approved,
    versioned stylized base set and passes the policy/review gate described in
    `agents/references/asset-sourcing-policy.md`. Preserve base-set version, generator version,
@@ -97,9 +101,8 @@ scene-kit role.
    generation capability, polling, and save tools; follow the advertised schema.
 6. **Author stable visual profiles in code.** Post profiles can be generated
    deterministically through `@call-me-sensei/toonlab/post`; other stable
-   shader profiles resolve through the selected style bundle. Lighting, VFX,
-   camera, and game-feel generation are host-owned or pre-beta in the public package and
-   are not advertised by the packaged MCP server.
+   shader profiles resolve through the selected style bundle. Lighting is a supported public runtime and bundle slot. VFX, camera and
+   game-feel implementations remain host-owned; do not invent package APIs.
 
 Persist anything worth keeping with `save_creation` (or write the JSON into
 the repo); `.toonlab/creations/` is the shared surface labs and later

package/agents/skills/codex/environment/SKILL.md

@@ -3,6 +3,10 @@ name: environment
 description: Help developers use ToonLab environment shading, lighting rigs, ambient probes, reflections, fog, cloud shadows, or vertex AO in an app.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Environment
 
 Use this skill when a developer wants stylized scene materials, material-role

package/agents/skills/codex/game-dev/SKILL.md

@@ -1,100 +1,76 @@
 ---
 name: game-dev
-description: Starting point for integrating ToonLab into an existing anime-style game or scene, including focused runtime routing, Gallery/MCP sourcing policy, and experimental/host-owned boundaries.
+description: Build a new playable game or integrate ToonLab into an existing Three.js game using public rendering, character, surface, collision, and asset workflows.
 ---
 
-# Integrating ToonLab into an Anime-Style Game
+# Develop a game with ToonLab
 
-Use this skill when an existing game, level, character, or scene spans more
-than one ToonLab system. Do not use it to promise a complete polished world
-from one prompt.
+Use this for game development and integration spanning several ToonLab systems.
+For a single shader or asset edit, use its focused skill. References beginning
+`agents/` are relative to the installed `@call-me-sensei/toonlab` package root.
 
-Read first:
-- `agents/references/anime-art-direction.md`
-- `agents/references/style-bundles.md`
-- `agents/references/mcp-asset-discovery.md`
-- `agents/references/asset-sourcing-policy.md`
-- `agents/references/runtime-entry-points.md`
+Read `agents/references/runtime-entry-points.md` for supported APIs. Read
+`agents/references/game-lifecycle.md` when wiring the renderer, movement,
+update loop, or teardown. Read art-direction/style references when applying a
+look, and `asset-sourcing` when asset discovery or generation is needed.
 
-## Assembly order
+## New game
 
-1. Inventory the supplied scene, approved cameras, existing asset/library
-   content, and the exact targets the developer wants ToonLab to change. Treat
-   layout, terrain, coastline, biome, lighting, camera, and gameplay
-   as protected host work unless the developer requests an experiment.
-2. Load the selected v2 bundle and its `artDirection`; use
-   `CALL_ME_SENSEI_STYLE_BUNDLE` when no other approved bundle is selected.
-3. Locate the asset-sourcing policy. Ask the developer when it is missing;
-   continue library-first in advisory mode only while reporting that decision.
-4. Feature-detect ToonLab OSS local and/or ToonLab Pro remote MCP. Reuse the
-   project/library first, search the released Gallery for named gaps, validate
-   finalists, then download only selected assets with provenance.
-5. Let the host game retain its renderer, scene layout, cameras, controls,
-   animation, physics, storage, and loading pipeline. When the same scene has
-   terrain-bound objects, grass, or shoreline water, create one
-   `createSceneSurfaceRuntime({ bounds, heightAt, waterLevel })`. The host owns
-   authored XZ layout and the terrain sampler; the surface runtime owns every
-   derived Y placement, bounds-grounding, water bed/shore wiring, and its
-   readiness audit. Never independently assign those values.
-   Label only the requested character, manufactured, tree, grass, flower,
-   ground, rock, water, and post targets.
-   When creating or modifying 3D content, also inventory every render material:
-   each slot needs a stable material ID and valid semantic role in the target's
-   versioned material contract. A root label alone never makes a multi-material
-   model bundle-ready.
-   Imported manufactured models should go through
-   `proposeManufacturedStyleTargetLabel()` and a reviewed proposal; every
-   low-confidence or generic entry needs an explicit override before
-   `applyManufacturedStyleTargetLabelProposal()` writes durable metadata.
-   Create one `createSceneStyleRuntime()` for the scene. Its default collision
-   runtime makes labeled manufactured, rock, prop, and tree targets solid;
-   generated trees use trunk geometry. Do not write parallel blocker arrays.
-6. Run `auditStyleBundleApplication()` and resolve every missing label, mixed
-   material, unsupported renderer, missing slot, or custom adapter before the
-   first mutation. Then call atomic `applyStyleBundle()`.
-7. Add focused procedural grass with `surface.createGrassField()`, ground
-   objects with `surface.place()`, and create shoreline Water with
-   `surface.createWaterSurface()`. This makes terrain sampling, water masking,
-   shoaling, nearshore phase, and persistent shore state the default. Do not
-   silently redesign the level to make a subsystem fit.
-8. Run `styleRuntime.collision.assertReady()`, report every target plan, and
-   probe representative tree, rock, and manufactured objects. Use explicit
-   collision metadata when bounds are inappropriate and the public Rapier
-   adapter when the host already owns a Rapier world. Then run
-   `surface.assertReady({ camera, styleRuntime, requireShadowDomains })`
-   after the shared shadow pass has rendered. A build, `castShadow` flag, or
-   target count is not proof of grounding, texture preservation, shoreline
-   wiring, or actual caster coverage. Then inspect the developer-supplied cameras plus relevant
-   close/far and lit/shadowed views. Iterate one material or asset family at a
-   time and report every remaining host or experimental gap.
+Implement the requested host game: input, camera, rules, HUD, level layout,
+dynamic physics or lightweight movement, and persistence if requested.
+Host-owned does not mean forbidden. Use ToonLab for the capabilities it
+actually exports; do not promise that a package call generates a finished world.
 
-## Runtime boundary
+Start with a playable vertical slice: move, collide, interact with one objective,
+and restart. Use simple host-authored geometry until the loop works. Replace
+placeholders with accepted assets and the chosen style incrementally. Record
+performance and visual checks at the gameplay camera, not just a flyover.
+The copyable `agents/examples/game-foundation.mjs` demonstrates a small
+host-authored loop with public ToonLab labeling, styling and static collision;
+it is an example, not a new package API or a full physics controller.
 
-The host render loop advances gameplay and explicitly installed scene systems,
-then renders once. Do not invent undocumented ToonLab imports. One-shot world
-generation; terrain/biome/coast/cliff formation; automatic set dressing;
-current Sky/Cloud composition; and full Lighting, Weather, Climate, VFX,
-camera, game-feel, navigation, physics, and streaming composition are
-experimental or host-owned.
+## Existing game
 
-Asset identity never belongs in a v2 style bundle. Strict tree and rock tests
-accept only project/ToonLab libraries or the ToonLab gallery. A similar-looking
-external or generated replacement is still denied under that policy.
+Inventory the existing renderer, loop, cameras, physics, loading and cleanup
+paths. Preserve them unless the task authorizes replacement. Integrate only the
+requested targets and avoid starting another animation loop. Use adapters for
+the host physics world and existing controllers rather than parallel systems.
 
-## Definition of done
+## Integrate the supported runtime
 
-- Every requested supported treatment routes to an explicit labeled target;
-  unused or experimental bundle slots are not a completion requirement.
-- Every render material on every created/imported target has a stable ID and
-  semantic role; incompatible atlas regions are split or carry an ID mask.
-- No raw PBR material escapes without the selected anime treatment.
-- Every used asset has stable ID, source class, provenance, license, anime-fit
-  review status, and a policy decision.
-- Supplied verification cameras pass the requested material, asset, vegetation,
-  water, shadow, and LOD checks without changing protected host composition.
-- `.toonlab/reports/style-asset-gaps.json` and `TOONLAB_ASSET_GAPS.md` exist
-  when custom work was required, and state what feedback is requested.
-- The consumer build and a real gameplay smoke test pass.
-- The shared scene-surface audit passes with no off-surface grass/objects,
-  disconnected water bed, missing shore state, lost source texture inputs,
-  invalid review camera, or incomplete required shadow domain.
+1. Resolve the installed package version, export map, and selected style bundle.
+   Call Me Sensei's bundle ID is `call-me-sensei`; domain selectors can differ.
+2. Create or reuse the host scene and renderer. Use `createCharacterRuntime()`
+   for supported loaded characters, and the walkable runtime when its movement
+   integration fits. Keep host input, movement intent and camera separate.
+3. If terrain placement and shoreline systems share a heightfield, provide its
+   world bounds and `heightAt(x, z)` once to `createSceneSurfaceRuntime()`.
+   Use its placement, grass and water helpers for that coordinated scene.
+   Ordinary rooms or flat arenas do not need a surface runtime.
+4. Assign stable target IDs, rendering domains, material IDs and roles. Use
+   `proposeManufacturedStyleTargetLabel()` and explicit reviewed corrections
+   for ambiguous imported materials; persist the accepted contract.
+5. Create one `createSceneStyleRuntime()` for the scene, then call its `apply()`
+   with the chosen bundle and labeled targets/discovery in strict mode. This
+   coordinates the renderer, lighting, ground field, shadows and static
+   collision. Resolve strict failures before application; do not bypass them
+   by calling an adapter directly.
+6. Use its default labeled static blockers and explicit collision metadata
+   where bounds are inappropriate. Prefer `createRapierCollisionAdapter()`
+   when integrating with an existing Rapier world. Do not maintain a second
+   blocker list for the same assets. Test real movement, not just flags.
+7. Assign one update owner per system and one final render owner. See the
+   lifecycle reference: style updates do not replace Sky, Water, grass or
+   character updates. When post is active, render through its documented path.
+8. Run `styleRuntime.collision.assertReady()`. For heightfield scenes, also run
+   `surface.assertReady({ camera, styleRuntime, requireShadowDomains })` after
+   the shared passes have rendered, scoped to the domains actually present.
+
+## Completion
+
+The requested gameplay loop, controls, camera, UI and restart work. Applicable
+build/type checks pass. Targets have complete material contracts; assets retain
+provenance and editable recipes. Inspect lit/shadowed and near/far views where
+relevant, and exercise startup, resize, pause/resume and disposal. Report
+remaining defects honestly. Do not require every optional ToonLab domain in a
+scene that does not use it, or treat user-approved host code as a package defect.

package/agents/skills/codex/lighting/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: lighting
+description: Integrate ToonLab's public lighting and scene-style runtime, diagnose shared shadows and sky alignment, and coordinate host-owned local lights.
+---
+
+# Lighting and shared shadows
+
+References beginning `agents/` resolve from the installed ToonLab package root.
+Read `agents/references/runtime-entry-points.md` and the selected bundle's
+art direction. Public imports are `@call-me-sensei/toonlab/lighting` and
+`@call-me-sensei/toonlab/styles`.
+
+Prefer `createSceneStyleRuntime({ renderer, scene, sky, water, post })` and
+`styleRuntime.apply(bundle, ...)` for a coordinated game scene. The public
+lighting bundle slot owns the supported sun/fill/probe settings; scene-style
+updates coordinate lighting, shared shadows and the ground field. Do not add
+an independent default directional rig that doubles the package key light.
+
+The host owns the time progression, authored local lights, camera and gameplay
+conditions. Use `styleRuntime.setTimeOfDay(hour)` to synchronize supported
+bound systems. Choose unique named override layers for independent live owners,
+and remove only the layer that owner created. Do not serialize composed state
+back over authored presets.
+
+Every relevant caster/receiver must participate in the shared shadow contract.
+Label targets, preserve cast/receive flags, and inspect the actual shared-pass
+coverage. Native `renderer.shadowMap` alone does not feed every ToonLab TSL
+receiver. If the host integrates focused APIs without scene-style ownership,
+explicitly wire the same light direction, shadow pass and scene-state adapters.
+
+Check the visible sky sun against the shadow direction, key/fill balance,
+near-white clipping, dark-material readability and relevant indoor/outdoor
+views. Frame shadow coverage around the area the game actually uses. Tune
+quality/resolution against a measured frame budget. Use additional coastal or
+underwater checks only when water is present. Record an integration gap only
+when the supported contract cannot meet the requested treatment.

package/agents/skills/codex/post-processing/SKILL.md

@@ -3,6 +3,10 @@ name: post-processing
 description: Help developers use ToonLab post-processing, bloom, color grade, LUT, vignette, outlines, depth cue, or motion blur.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Post Processing
 
 Use this skill when a developer wants ToonLab's optional post-processing
@@ -22,9 +26,10 @@ Generating looks (no lab UI required):
 - `createPostGeneratorRecipe(id, { seed, locks, configuration })` defines an
   editable domain; `createGeneratedPostPresetDocument(recipe, { quality })`
   resolves it into a flat, portable preset deterministically per seed.
-- The packaged MCP server is reserved for asset discovery, provenance,
-  sourcing-policy decisions, and custom-gap records. Generate post profiles
-  in code and commit any resolved document that the project needs to retain.
+- MCP supports portable Lab document creation and mutation as well as asset
+  discovery. Inspect `get_lab_features` for the available Lab contract; use
+  code for procedural profile generation and keep any resolved document the
+  project needs to retain.
 - Ship the resolved preset in the app; keep the recipe only if runtime
   re-rolling is a feature.
 

package/agents/skills/codex/rock-ground-shaders/SKILL.md

@@ -3,6 +3,10 @@ name: rock-ground-shaders
 description: Apply, configure, and verify ToonLab rock and ground shaders in outdoor scenes, including textures, close detail, HDR sun response, cast/receive shadows, ground-field adoption, shoreline wet bands, and Call Me Sensei defaults.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Rock and ground shaders
 
 Use this skill when terrain, cliffs, catalog rocks, beaches, or grass-ground
@@ -35,21 +39,12 @@ if (report.usedGeneratedTextures) {
 setRockShaderSceneState(rockRoot, { waterLevel });
 ```
 
-For the representative semantic hoodoo, validate before styling:
-
-```js
-import { inspectRockRegionBindings } from '@call-me-sensei/toonlab/rock-shader';
-
-const regions = inspectRockRegionBindings(hoodooRoot);
-if (regions.totalVertices !== 134981) throw new Error('Unexpected hoodoo binding');
-```
-
-The v1 binding is fixed to profile `hoodoo-caprock-normalized-height-v1` and
-channels `base/shaft/neck/cap`. Do not apply it to another family. Use only
-material styling (`detail: null`) on the annotated mesh; any position/topology
-edit requires semantic regeneration and rebaking. Prove repeated
-`applyRockShader()` / `restoreRockShader()` cycles restore exact material,
-texture, geometry, index, attribute, shadow, and user-data identities.
+For an asset with authored semantic regions, use `inspectRockRegionBindings()`
+and its matching versioned contract before styling. Do not copy region names
+or vertex-count assumptions from a single research fixture onto other rocks.
+Preserve authored masks and their geometry binding; topology/UV edits require
+updated bindings and any required rebakes. Qualify apply/revert cycles on the
+actual asset.
 
 `applyRockShader` sets `castShadow` and `receiveShadow` true by default.
 Override them only for an explicit rendering reason. It reports whether

package/agents/skills/codex/rockgen/SKILL.md

@@ -1,30 +1,61 @@
 ---
 name: rockgen
-description: Help developers use ToonLab procedural rock, cliff, heightfield, erosion, SDF, mesh, preset, sculpt, or GLB export tools.
+description: Create or edit ToonLab procedural rocks and portable rock recipes, including deterministic realistic surface maps, semantic masks, LOD, collision and export.
 ---
 
-# Rockgen
+# Procedural rocks and realistic surfaces
 
-Use this skill when a developer wants procedural rock, cliff, or heightfield
-generation; stylized erosion; SDF composition; surface-nets meshing; rock
-presets; sculpt edits; or GLB export.
+Use public `@call-me-sensei/toonlab/rockgen` for geometry and deterministic
+surface data, and `@call-me-sensei/toonlab/rock-shader` for reusable appearance.
+References beginning `agents/` resolve from the installed package root, even
+when this skill is copied. Read `agents/references/runtime-entry-points.md` and
+`rock-ground-shaders` for material application and shared shadow integration.
 
-Public imports:
-- `@call-me-sensei/toonlab/rockgen`
+## Geometry and sourcing
 
-Read first:
-- `README.md` feature table for the exported rockgen surface.
+Use the project's accepted sourcing policy. Strict anime sourcing admits
+library/gallery rocks; a newly generated procedural rock needs an explicitly
+permitted workflow. An explicit rock-authoring request is not a request for a
+complete terrain or automatic world builder. Keep the host's layout and game
+logic separate from the asset recipe.
 
-Developer guidance:
-- Use fixed seeds when an app needs repeatable generated assets.
-- Store app-specific presets or generated outputs in the host app's asset
-  pipeline, not in ToonLab sample folders.
-- Treat Rock Lab as an optional local authoring example, not a runtime
-  dependency.
-- Heightfield erosion is provided by ToonLab's first-party stylized erosion
-  path; do not advise developers to depend on the old terrain-editor fork or
-  third-party simulator.
+Use a fixed seed and stable asset ID. Preserve the geometry recipe, transforms,
+units, surface specification, LODs, collision and provenance in the host asset
+pipeline. Use MCP `get_lab_features` for the current portable document contract
+before `create_lab_document`; read the result's `document` field. Save to the
+Library when persistence is requested. Do not import Labs, repository compilers
+or fixture data into the consumer app.
 
-Verify:
-- In consumer apps, regenerate with the same preset/seed and compare the asset
-  shape or exported file the app expects.
+## Realistic material support
+
+The npm generator supports realistic rock surfaces without generative AI
+credits. Use `NATURAL_ROCK_SURFACE_PROFILES` to discover IDs and display labels,
+`createNaturalRockMapData` to produce deterministic channel data, and
+`createNaturalRockSurfaceSpecification` to persist its reproducible recipe.
+Display “Nature Reference Rocks” or the profile label, never internal production
+names. Do not replace a requested realistic finish with a stylized one.
+
+`result.maps` contains RGBA byte arrays for `baseColor`, `normalGL`, `roughness`,
+`ao`, `orm`, `smoothness` and `heightMicro`. The host constructs textures and
+assigns the projection: Base Color is sRGB, other maps are linear data. ORM is
+AO/roughness/metallic in R/G/B; metallic is zero. Preserve source UV mapping
+when applying baked maps. A shader profile alone does not load or bind maps.
+
+Homogeneous profiles need an explicit profile and seed. Mixed-material profiles
+also require authored semantic masks bound to the current geometry SHA-256.
+Persist the specification's encoded masks and hashes unchanged. Do not fabricate
+regions or discard masks on save, clone or MCP edits. Topology/UV changes need
+new bindings. Use 64–4096 maps for previews; production surface specifications
+require 1024–4096. Budget memory for all channels before choosing resolution.
+
+Micro-height describes material detail, not a signed high-to-low geometry bake.
+Geometry edits can invalidate LOD, collision, projection and bake provenance;
+regenerate affected outputs before declaring the variation ready.
+
+## Verify the asset
+
+Regenerate with the same recipe and compare shape/map hashes; save and reopen
+when persistence is part of the task. Inspect the requested finish, seams,
+silhouette, near/far transitions and shadows at relevant views. Check physical
+scale and collision by moving against the object. Use targeted runtime tests
+and rendered evidence; metadata alone is insufficient.

package/agents/skills/codex/scene-style-application/SKILL.md

@@ -3,6 +3,10 @@ name: scene-style-application
 description: Inspect, plan, apply, and verify ToonLab style bundles on labeled scenes without copying Lab or showcase code.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Scene style application
 
 Ask the developer whether application should be **strict** or **advisory** before