@call-me-sensei/toonlab 0.3.1 → 0.4.20

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

@@ -0,0 +1,74 @@
+---
+name: scene-style-application
+description: Inspect, plan, apply, and verify ToonLab style bundles on labeled scenes without copying Lab or showcase code.
+---
+
+# Scene style application
+
+Ask the developer whether application should be **strict** or **advisory** before
+changing the scene. Strict mode stops on unlabeled, invalid, or unsupported
+targets. Advisory mode applies valid labeled targets and reports every gap.
+
+Use the package contract in this order:
+
+1. Label host-owned objects with `createStyleTargetLabel()` and
+   `labelStyleTarget()` from `@call-me-sensei/toonlab/styles`.
+   For every newly modeled, generated, or imported renderable, assign a stable
+   material ID and at least one valid semantic material role to **every material
+   slot** in the label's versioned `materials` contract. A root domain label by
+   itself is incomplete for a multi-material object. Split incompatible surface
+   regions or provide an explicit material-ID mask; never guess a production
+   role from names or RGB values.
+   For an imported manufactured asset, call
+   `proposeManufacturedStyleTargetLabel()` first. Review every generic,
+   conflicting, or low-confidence entry, supply explicit `materialOverrides`,
+   then call `applyManufacturedStyleTargetLabelProposal()`. Never lower the
+   confidence threshold merely to make strict application pass.
+2. Run `toonlab inspect`, `toonlab audit`, then `toonlab plan` against a portable
+   `toonlab/scene-style-manifest` document. The OSS MCP tools with the same names
+   are equivalent when MCP is available.
+3. Show the plan, including unsupported domains and custom-material exemptions.
+4. Run `toonlab apply` only after the strict/advisory choice is known.
+5. Run `toonlab verify`, the consumer build, and visual checks for every camera,
+   renderer, quality profile, and scenario affected.
+
+When the scene combines ground-bound content with shoreline water, use one
+`createSceneSurfaceRuntime()` from `@call-me-sensei/toonlab/runtime` before
+creating grass, water, or derived object Y positions. Its `createGrassField()`,
+`createWaterSurface()`, and `place()` methods are the default integration path.
+After rendering the shared shadow pass, its strict readiness audit must pass;
+do not hand off a page that merely built or set shadow flags.
+
+For a package-generated `StylizedTree`, preserve an authored `trunkMap`; when
+it is absent, let Call Me Sensei select `call-me-sensei-bark-v1` or choose an
+explicit registered ID from `getTreeSurfaceProfileOptions()`. Never leave bark
+flat because no one chose a texture. Verify every trunk is both a shared-pass
+caster and receiver. `trunkSurfaceProfile: 'none'` is a deliberate opt-out,
+not a fallback.
+
+Do not hand off an authored 3D object while any render material is absent from
+the contract. In strict mode, missing material IDs/roles or a mixed atlas
+without a split/mask is a blocking failure; fix the asset metadata before
+applying the bundle. In advisory mode, report the same gap explicitly and do
+not describe the object as style-bundle-ready.
+
+`applyStyleBundle({ mode: 'strict' })` reconciles the declared material
+contract against the live material slots before mutation. Keep the broader
+scene audit as the reporting gate, but do not bypass a direct strict rejection
+by calling a lower-level shader adapter.
+
+Never import from a ToonLab `labs/` directory, copy a showcase scene, or depend
+on a retained reference-scene implementation. Labs are authoring/test clients;
+public package exports are the runtime authority. If a needed behavior is not a
+public export, record the package gap rather than copying private code.
+
+The host owns authored XZ layout, terrain shape/sampler, gameplay, dynamic
+physics, navigation, and content identity. The shared surface runtime owns
+derived ground heights and terrain/water coordination. The scene style runtime
+owns conservative static collision for labeled manufactured, rock, prop, and
+tree targets unless the label declares another policy. Call
+`styleRuntime.collision.assertReady()` before handoff and report its per-target
+plan. Do not add scene-local tree/rock/bench blocker lists. Use explicit
+`none`, `blockers`, `convex`, or `trimesh` metadata when bounds are wrong; use
+`createRapierCollisionAdapter()` for an existing Rapier world. A style bundle
+owns visual treatment and package-managed systems.

package/agents/skills/codex/style-presets/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: style-presets
+description: Explicitly select and record the intended ToonLab style or preset at every style-aware call site, distinguish neutral-default factories from Call Me Sensei-default factories, and audit overrides before reporting a custom integration note. Use before authoring environment, vegetation, grass, water, rock, ground, sky, cloud, or post settings, and whenever a subsystem looks unexpectedly unstyled.
+---
+
+# Name the preset
+
+This skill makes an individual call site explicit; it does not imply that every
+listed subsystem is part of a live Lab. Sky and Cloud focused authoring is live.
+Weather, Climate, and automatic full-world composition remain lower-level APIs
+for users who want to assemble those systems in their own application.
+
+Style-aware ToonLab factories take a `preset`, a `style`, or both. Some
+factories intentionally resolve a neutral/default treatment when the selector
+is omitted; Rock and Ground already default to Call Me Sensei, while
+Cloud has no named style at all since the volumetric rebuild retired them.
+Always pass the intended selector anyway so the call site and capture manifest
+are auditable. Never claim that every omitted selector falls back to neutral.
+
+Omitting a selector on the neutral-default factories is one of the most
+expensive mistakes a ToonLab agent can make. In one capability test it hit
+three independent subsystems, each investigated as a custom integration note when the
+actual cause was a missing selector or an overridden preset field.
+
+## The rule
+
+```js
+// WRONG for a Call Me Sensei scene — resolves the vegetation baseline.
+createVegetationShaderScopeSettings('tree', { foliage: { ... } });
+
+// RIGHT
+createVegetationShaderScopeSettings('tree', {
+  preset: 'call_me_sensei',
+  foliage: { ... },
+});
+```
+
+Do this for every domain, on the **first** call, not as a later refinement.
+
+## Where it bites
+
+| Factory | Name this | Actual default behavior |
+|---|---|---|
+| `applyEnvironmentShader` | `preset: 'call_me_sensei'`, plus the intended `scenario` | The adapter accepts the selectors directly and composes preset, `settings`, then explicit overrides. `resolveEnvironmentPreset` remains available when plain settings data is needed elsewhere. |
+| `createVegetationShaderScopeSettings` | `preset: 'call_me_sensei'` | Omitting it resolves the neutral vegetation baseline. |
+| `createGrassSettings` / grass fields | `preset: 'call_me_sensei_clump'` for the first-party meadow, or `'anime_clump'` for the short narrow tuft recipe | Omitting it resolves neutral grass settings. These presets differ in geometry/coverage, not only colour. `createCallMeSenseiGrassField` defaults to the meadow and honors an explicit alternate preset. |
+| `createWaterSettings` | `preset: <water body>` **and** `style: 'call_me_sensei'` | Omitting selectors resolves Lake with the default rendition. The Call Me Sensei style owns `colorTone: 'anime'`; any non-`classic` tone intentionally owns its palette/fade/reflection block, while `classic` leaves those per-key values authorable. |
+| `createRockShaderSettings` / `applyRockShader` | `preset: 'call_me_sensei'` | Already defaults to Call Me Sensei. Textures are optional: the fallback is first-party generated 256 px data and the application report identifies its source. |
+| `createGroundShaderSettings` | `preset: 'call_me_sensei'` | Already defaults to Call Me Sensei. |
+| `createSkySettings` | `style: 'call_me_sensei'`, plus the intended `scenario` | Omitting style resolves the default sky rendition. |
+| `createCloudParams` / `SkySystem.applyPreset` | no preset id | The volumetric rebuild retired the named cloud styles; the eight replacement looks are whole-sky presets. Omitting parameters resolves the published schema defaults. |
+| `createPostProcessingSettings` | `preset: 'call_me_sensei'` | Omitting it resolves `off`. |
+
+## Overriding a preset field is a deliberate act
+
+Changing one key of a first-party preset is indistinguishable, at the call site,
+from configuring an unstyled system. Real examples, all of which produced a bug
+report against ToonLab before the cause was found:
+
+- `groundAdoptStrength: 0.04` over the shipped meadow's `1` — grass then never adopted
+  the ground colour, and the *mechanism* was reported as broken.
+- `colorTone: 'classic'` over the studio `'anime'` — the lagoon deliberately
+  left the studio tone, after which its palette/fade/reflection values needed
+  explicit authorship.
+- A bare `createVegetationShaderScopeSettings()` plus ~25 hand-authored fields —
+  three revisions of look development on the wrong base.
+
+So: **before overriding a preset field, state why the shipped value is wrong for
+this scene**, in a comment, naming the scene fact the shared IP treatment cannot
+know — plane extent, bed depth, camera distance, a specific art-direction target
+with a measured value. If you cannot name one, do not override it.
+
+## When a subsystem looks wrong
+
+Before concluding that ToonLab lacks a capability, check, in this order:
+
+1. **Was a preset named?** Not "is a preset applied somewhere" — was one passed
+   to *this* factory, at *this* call site.
+2. **Was a preset field overridden?** Diff your options against the shipped
+   preset's settings in the package source.
+3. **Does the package or repository lab do it differently?** Inspect the
+   installed preset registry/source first. If working in a ToonLab repository
+   checkout, open the matching lab and compare the public API call and values it
+   boots. Labs are not present in the npm tarball and are never runtime imports.
+4. **Only then** record a custom integration note.
+
+Steps 1–3 take minutes. Skipping them cost, in one run, several days of agent
+time and produced register entries claiming gaps that did not exist.
+
+## Introspection is limited, so be explicit
+
+Not every resolved settings object records which preset produced it. Water and
+Rock retain selector identity, while scoped vegetation, Grass, Ground, and
+Cloud settings are normalized value objects. A few options are
+**compile flags** rather than settings and never appear on the resolved object
+at all — `groundField` on grass is one, so `'groundField' in settings` reports
+`false` in a fully working scene.
+
+Therefore: log the preset id you passed, at construction, next to the subsystem
+name. It is the only durable record, and it makes a wrong base obvious in the
+console instead of three revisions later in a render.

package/agents/skills/codex/toon-shading/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: toon-shading
+description: Help developers use ToonLab character toon shading, toon settings, presets, material roles, outlines, shadows, highlights, fur, or stickers.
+---
+
+# Toon Shading
+
+Use this skill when a developer wants ToonLab character toon materials, toon
+settings, preset documents, material-role handling, outlines, hair highlights,
+rim light, shadows, stickers, glitter, fur, or debug views in their app.
+
+Public imports:
+- `@call-me-sensei/toonlab/toon`
+- `@call-me-sensei/toonlab/toon-settings`
+
+Read first:
+- `agents/references/anime-art-direction.md`
+- `agents/references/style-bundles.md`
+- `agents/references/runtime-entry-points.md`
+
+Developer guidance:
+- Apply toon shading to app-owned Three.js character roots and meshes.
+- The host app owns character loading, animation, input, camera, persistence,
+  and asset URLs.
+- The optional CC0 qualification mannequin is not bundled in npm. Load the
+  immutable public-R2 URL and provenance from `TOONLAB_MANNEQUIN_ASSET` in
+  `@call-me-sensei/toonlab/character`, or use the host project's own mannequin.
+  Never substitute a repository `public/characters/mannequin.glb` path when
+  testing an installed package. After downloading, verify its byte count,
+  SHA-256, and 46 clips before applying the toon shader.
+- Use settings and preset documents for portable looks instead of lab HUD
+  state.
+- Use ToonLab's TSL/NodeMaterial path; do not advise raw GLSL or
+  `ShaderMaterial` forks for ToonLab toon features.
+- Do not rely on `assets-local/` or lab-only model discovery.
+
+Verify:
+- Run the consumer app's normal build and inspect the character under at least
+  one lit and one shadowed view.
+- Record `applyToonShader()`'s converted mesh count, material-role summary,
+  shader mode, and selected preset. A loaded GLB is not proof that cel shading
+  was applied.
+- Toggle the relevant setting or preset to confirm the app is not hard-coded to
+  lab defaults.

package/agents/skills/codex/vegetation-sky/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: vegetation-sky
+description: Help users apply ToonLab grass, flowers, trees, Tree/Grass/Flower shader profiles, and the live Sky/Cloud authoring surfaces to an existing scene.
+---
+
+# Vegetation, Sky, and Cloud
+
+Use these focused systems on an existing scene with host-supplied placements,
+terrain, lighting coordination, and current conditions. The Sky and Cloud Labs
+are live authoring tools; they do not replace whole-scene composition.
+
+Public imports:
+- `@call-me-sensei/toonlab/vegetation`
+- `@call-me-sensei/toonlab/vegetation-shaders`
+- `@call-me-sensei/toonlab/grass-palettes`
+- `@call-me-sensei/toonlab/sky`
+- `@call-me-sensei/toonlab/cloud`
+- `@call-me-sensei/toonlab/grass`
+
+Read first:
+- `agents/references/anime-art-direction.md`
+- `agents/references/style-bundles.md`
+- `agents/references/runtime-entry-points.md`
+
+User guidance:
+- Add vegetation and sky objects to app-owned scenes, terrain, and render loops.
+- Produce `placements` with the scatter helpers rather than by hand. Across the
+  ground heightfield use `scatterInRect`, `scatterGrassAround` or
+  `scatterForest`. For a surface that is **not single-valued in y** — a cliff
+  cap, a ledge, a shelf, a rock platform, anything with terrain both above and
+  below it — those cannot express the placement at all; use
+  `scatterOnSurface({ surfaces, density | count, minSpacing, mask, weightAt,
+  normalBlend })`. Surfaces are discs in world space,
+  `{ center, radius, normal?, seed? }`, which is the shape a rock or cliff
+  module already publishes for its caps. Spacing is measured in 3D so stacked
+  caps do not starve each other, each surface has its own deterministic stream
+  so adding one does not reshuffle the rest, and the returned placements carry
+  `normal`, `forward` and `yaw` so an aligned field does not have to derive
+  orientation itself. The `(x, z)` mask factories and `combineMasks` compose
+  with it unchanged.
+- Pair it with `createCapEdgeWeight({ rimBias: 0.05, falloff, break })`. A cap that
+  stays dense all the way to its rim reads as a flat green disc stuck onto the
+  rock; real soil caps thin toward a broken, slightly overhanging edge. Keep
+  `rimBias` near zero for soil: high values push coverage into an outer annulus
+  and work against the edge falloff. Use `falloff` and `break` for the ragged
+  transition.
+- Use async `createCallMeSenseiGrassField({ placements, variant })` for
+  ToonLab's first-party procedural grass. `primary` is the accepted default;
+  `secondary` is the denser alternate. Both generate deterministic LOD0/1/2
+  geometry and the material directly from package code. They have no GLB,
+  image, or package-owned URL dependency. The returned default is a
+  `StylizedGrassClumpField`; use `RetainedGrassClumpField` only when the caller
+  deliberately supplies custom geometry or material.
+- Keep the field's package-default spatial frustum culling enabled for outdoor
+  scenes. It chunks placements, rejects offscreen chunks/records, and compacts
+  visible records into the existing three LOD buffers. Read `cullingStats` for
+  visible/culled counts; tune `chunkSize` or `cullPadding` only for a measured
+  world-scale need. Never set `frustumCulling: false` as a meadow default.
+- Keep the factory's default `call_me_sensei_clump` preset unless the developer
+  explicitly requests another style. It is the accepted meadow preset: 40
+  upright overlapping blades per primary clump, full ground-field adoption,
+  texture-free watercolor lift, translucent stroke layering, and three LODs
+  without an implicit terminal hard cull. Do not replace it with a generic
+  single-blade field, a repository asset, or example-local material settings.
+  Reject dark or dirty roots, isolated patches, tangled silhouettes,
+  bare-ground pinholes at normal density, and straight coverage boundaries.
+  Compare both composition and grass-close views against the frozen controlled
+  source mode.
+- Preserve ground hue in the Call Me Sensei default. Its neutral
+  `groundAdoptTint` may lift exposure uniformly, but `tipHueShift` and
+  `tipDesaturation` remain zero: green ground produces only shades of green.
+  Hue shifts remain public profile parameters for explicitly authored styles.
+  LOD0/1/2 reduce 40/14/6 primary blades and widen retained strokes to keep
+  integrated coverage within 2% of LOD0. Reject any camera-distance change
+  that makes the terrain appear to change color.
+- Ground-field sampling is a compile option; the source is the shared
+  environment ground-field pass. Prefer `createSceneStyleRuntime()` and label
+  terrain `terrain.ground` plus grass `vegetation.grass`; the bundle then marks
+  writers and owns the pass automatically. For a manual subsystem integration,
+  create the pass after all writer meshes exist, call its `update()` every frame before grass, require
+  `writerCount > 0` and `ready`, and call `invalidate()` after repainting a
+  writer without a transform change.
+- In the public package, use `LEGACY_TREE_PRESETS` and `createLegacyTree()` for the 12
+  supported pre-species silhouettes. Use `BranchTree` when the developer wants
+  recursive branching, five broadleaf silhouettes, leaf color/texture plus a
+  portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
+  color/texture, authored trunk bend/twist/taper, roots, portable documents,
+  and the shared Tree Shader. `branches.children` counts lateral children;
+  the generator also continues the leader so the trunk does not end in a stump.
+  `BranchTree` is the focused portable wrapper around `StylizedTree` with
+  `skeleton.generator: 'branching'`; choose the normal blob-crown tree when a
+  solid anime foliage mass matters more than a visible recursive skeleton.
+  Its current crown is tip-driven: `canopyWidth`, `canopyDepth`, and
+  `leafPlacement` are fixed by the wrapper, while `coverageScale` remains the
+  supported density control. Use `StylizedTree` directly when the crown
+  geometry itself must be authored; do not pass ignored BranchTree options.
+  Preserve an authored `trunkMap`. If it is absent, the Call Me Sensei preset
+  and bundle select `call-me-sensei-bark-v1` automatically. Use
+  `getTreeSurfaceProfileOptions()` when the developer asks the agent to choose
+  another registered bark surface; never leave the trunk bare by accident,
+  and use `trunkSurfaceProfile: 'none'` only for a deliberate flat-color art
+  direction. Verify every trunk both casts and receives in shared-pass
+  coverage telemetry.
+  Do not select, invent, or claim support for a botanical species. The large
+  taxonomy/species roster visible in repository labs is experimental and is
+  not a package API.
+- Author and route the independent `TREE_SHADER_PROFILE`,
+  `GRASS_SHADER_PROFILE`, and `FLOWER_SHADER_PROFILE` through the bundle's
+  `treeShader`, `grassShader`, and `flowerShader` slots. They share a renderer
+  family and semantic material contract, but serialize and apply independently.
+  Keep asset albedo and legacy/BranchTree geometry/material inputs separate from all
+  three shader treatments.
+- Grass palettes update base, tip, and shadow tint together; they do not change
+  shadow strength, wind, or current weather.
+- Use the public versioned Grass, vegetation-shader, legacy/BranchTree/flower recipe, and Sky
+  preset document APIs for portable data; do not copy lab-local validators.
+- Treat Sky as one integrated World System, not a separate Shader Lab. Its
+  shader, sun, clouds, stars, and procedural motion form one system preset with
+  exactly 46 portable art fields; dome radius and quality are not in it.
+- Cloud is a raymarched volumetric deck. The painted source/composition/card
+  pipeline was replaced outright: `createCloudSourceDocument`,
+  `createCloudCompositionDocument`, `createCloudField` and
+  `createCloudShaderSettings` no longer exist. Build the sky with
+  `SkySystem.create({ renderer, scene, camera })` and author it with
+  `applyPreset(skyParams)`, whose `cloud` block is the six groups shape,
+  lighting, wind, cirrus, haze and fade. `applyPreset` fully replaces sky
+  state; omitted fields fall back to the schema default, not to what is on
+  screen.
+- `sky.settings` is the authored baseline and `sky.renderedSettings` is the
+  current named-layer composition. Give Lighting, Weather, and other scene
+  owners unique `setSceneOverrideLayer` ids and clear only their own id.
+- For world integration, let the host game own the sun/light adapter. Lighting
+  is not a stable public package or bundle domain; coordinate project-local
+  lighting through explicit Sky, Weather, Water, and vegetation adapters.
+- The composed-world sun adapter is `setSun({ direction, color, sky })`; it
+  keeps the real light/shadows and Grass, Flower, Forest, Ambient FX, Sky, and
+  Water scene inputs aligned without changing their portable presets.
+- Sky quality is compile-time: low/medium/high compile 2/3/4 cloud octaves,
+  custom `{ cloudOctaves: 1..5 }` is supported, and `sky.setQuality()` rebuilds
+  the material while preserving authored settings and active layers.
+- Keep current wind, wetness, snow, interaction targets, weather, lighting,
+  camera, and export destinations owned by the host app.
+- **Start from a public package preset or a portable Lab export.** The browser
+  Labs author and preview settings, while the package registry and imported
+  documents are the runtime sources of truth. Never import Lab UI code into an
+  application. Water and Sky keep their controls inside their complete system
+  documents rather than requiring hidden companion settings.
+- **Always name the preset.** `createVegetationShaderScopeSettings(scope, {...})`
+  with no `preset` silently resolves an anonymous `default` — not the studio
+  look — and does not warn. Pass `preset: 'call_me_sensei'` explicitly on the
+  first call. See the `style-presets` skill; this single omission has taken a
+  whole vegetation look onto the wrong base for several revisions.
+- Grass presets differ in **shape**, not only colour: `call_me_sensei_clump` is
+  the wide dense meadow clump, while `anime_clump` is the shorter narrow six-
+  blade tuft with a far smaller clump radius. Choose deliberately when coverage
+  and silhouette matter. `createCallMeSenseiGrassField()` defaults to the
+  meadow and honors an explicit alternate `preset`; verify the resolved id in
+  `field.userData.callMeSenseiGrass.preset`.
+- Do not rely on repository sample meshes, textures, or generated manifests.
+  A clean npm tarball contains no grass media files; test the generated
+  topology, blade attributes, LOD counts, and material in a clean consumer.
+
+Verify:
+- Run the consumer app's normal build and inspect near/far vegetation plus sky
+  under the target camera.
+- For exported trees, reload the generated asset in the consumer app or asset
+  pipeline.

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

@@ -0,0 +1,136 @@
+---
+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.
+---
+
+# Verifying that it looks right
+
+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".
+
+## Settle the scene before you screenshot
+
+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.
+
+Observed: the same command produced 273,520 triangles with the entire lagoon
+absent on one run and 606,056 on the next.
+
+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.
+
+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.
+
+Also fail on any browser console error. A texture that failed to decode is a
+defect, not a warning.
+
+## Isolate before you blame
+
+Render subsystems alone to attribute a defect — and include the light rig, or
+you get a black frame and learn nothing.
+
+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.
+
+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.
+
+## Measure colour, do not argue about it
+
+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.

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

@@ -0,0 +1,105 @@
+---
+name: water
+description: Help developers use ToonLab water materials, waves, ripple simulation, breakers, splashes, rain, kelp, or water settings.
+---
+
+# Water
+
+Use this skill when a developer wants WaterSurface, water material settings,
+Gerstner waves, CPU buoyancy mirrors, ripple simulation, refraction, foam,
+breakers, wakes, splashes, rain, kelp, underwater view, or water preset
+documents.
+
+Public imports:
+- `@call-me-sensei/toonlab/water`
+- `@call-me-sensei/toonlab/water-settings`
+
+Read first:
+- `agents/references/anime-art-direction.md`
+- `agents/references/style-bundles.md`
+- `agents/references/runtime-entry-points.md`
+
+Developer guidance:
+- Add water surfaces and update hooks to the host app's scene and render loop.
+- For a standalone controlled coast, construct `WaterSurface` with a world-space
+  `bedHeight(x, z)` sampler so shoaling and shoreline depth use the same beach
+  geometry, enable `shoreState` when wet-sand/foam memory is under test, keep
+  the surface axis-aligned, and call `water.update(renderer, scene, camera,
+  delta)` before the host render.
+- Cover the full water tile and every allowed camera footprint with closed
+  seabed geometry. Dress visible underwater areas with package `WaterKelpField`
+  vegetation and licensed/package rock clusters, including partially buried
+  and partially submerged transitions. An empty bed, visible terrain underside,
+  open world edge, or sky showing below the bed is a release failure.
+- Treat Water as one integrated World System. Surface shading, waves, foam,
+  reflections, interaction, and quality belong to the complete Water preset;
+  do not invent a separate Water Shader document or runtime dependency.
+- Keep `WaterSurface`'s default `underwaterAtmosphere` scene adapter enabled.
+  Its update restores the host's air-side background/fog for water capture
+  passes, then applies body-color fog and background when the camera is below
+  and inside the surface footprint. Its capture-excluded color veil also
+  grades ToonLab TSL materials that opt out of scene fog. Do not duplicate
+  Water Lab fog-swapping in a host app. Disable or override this adapter only
+  when a complete replacement underwater post stack owns the same transition.
+- Keep the three authored axes explicit: `preset` selects the body/motion
+  recipe (`coast`, `ocean`, `lake`, and so on), `style: 'call_me_sensei'`
+  selects the studio rendition, and `colorTone` selects `classic`, `anime`,
+  `teal`, `caribbean`, `lagoon`, or `deepOcean`. Do not replace a coast preset
+  with an "Anime" preset; Anime is a tone selected by the style.
+- A non-`classic` tone owns its coherent optical block:
+  `shallowColor`, `midColor`, `deepColor`, `depthFadeDistance`,
+  `deepFadeDistance`, `fresnelBias`, `fresnelColor`, `reflectionStrength`,
+  `reflectionSoftness`, `causticsStrength`, and `detailNormalStrength`.
+  Supplying those keys alongside a named tone does not override the tone.
+  Choose `classic` when the caller needs full per-key control instead.
+- Choose the tone from captures made with the real bed depth and approved
+  cameras, not from its label or palette table alone. Grazing views tend toward
+  `deepColor`; overhead shallow views expose more `shallowColor`.
+- `opacity` controls only the fallback path without a scene-color capture.
+  With the normal WaterSurface scene-color pass bound, the body composites as
+  the integrated refractive surface and that setting is intentionally inactive.
+- Keep interaction targets, camera mode, resize handling, and physics/buoyancy
+  integration owned by the app.
+- Use `water.settings` for the portable authored baseline and
+  `water.renderedSettings` when inspecting the current Lighting/Weather
+  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.
+- 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.
+- Choose Water's compile-time quality when constructing `WaterSurface`.
+  Changing low/medium/high or custom quality requires replacing/rebuilding the
+  surface; `applySettings()` edits authored art/simulation values, not quality.
+- Use documented settings and presets for portable water looks.
+- When using buoyancy, sample or mirror the same wave configuration the visible
+  water uses.
+- Treat ToonLab playground scenes as examples, not runtime dependencies.
+- Size finite water surfaces from the union of every approved camera frustum's
+  intersection with the water plane, then add margin for orbit, shake, and
+  wave displacement. A visible rectangular boundary is a release failure;
+  increasing width and depth is the correction.
+
+Verify:
+- Run the consumer app's normal build and inspect calm, moving, and interaction
+  states relevant to the game.
+- If buoyancy is used, check that objects match the visible water height closely
+  enough for the app's camera distance.
+- Inspect the water from the cliff camera, a low shore camera, and a downward
+  reveal. Verify the shoreline has no hovering terrain, dry gaps, hard surface
+  edge, or water slivers, and record `nearshorePhaseStatus` plus the ship's
+  sampled `getHeightAt()` result when a vessel is present. Treat an inactive
+  nearshore phase as diagnostic, not automatically as a shader failure: the
+  mild-slope path cannot activate on a vertical wall or deep gorge that never
+  presents a qualifying bank to the bed sampler.
+- Add two underwater inspections: one looking up through the surface and one
+  looking across the floor toward the shore. Verify real above-water
+  transmission, readable depth tint/haze, a continuous closed bed, caustic or
+  light response, submerged rocks, moving vegetation, and no hollow terrain.
+  Assert `water.underwaterAtmosphereState.active` in both submerged views and
+  verify that the original host background/fog return above the surface.
+- When the host uses reversed depth, inspect the foam debug view as well:
+  open water must remain dark and contact foam must stay localized to shore
+  and piercing objects.