@call-me-sensei/toonlab 0.3.1 → 0.4.20

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

@@ -0,0 +1,100 @@
+---
+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.
+---
+
+# Integrating ToonLab into an Anime-Style Game
+
+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.
+
+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`
+
+## Assembly order
+
+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.
+
+## Runtime boundary
+
+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.
+
+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.
+
+## Definition of done
+
+- 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.

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

@@ -0,0 +1,44 @@
+---
+name: post-processing
+description: Help developers use ToonLab post-processing, bloom, color grade, LUT, vignette, outlines, depth cue, or motion blur.
+---
+
+# Post Processing
+
+Use this skill when a developer wants ToonLab's optional post-processing
+pipeline, settings, preset documents, bloom, color grading, LUTs, vignette,
+screen outlines, depth cue, motion blur, or character-aware bloom.
+
+Public imports:
+- `@call-me-sensei/toonlab/post`
+- `@call-me-sensei/toonlab/post-processing`
+
+Read first:
+- `agents/references/anime-art-direction.md`
+- `agents/references/style-bundles.md`
+- `agents/references/runtime-entry-points.md`
+
+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.
+- Ship the resolved preset in the app; keep the recipe only if runtime
+  re-rolling is a feature.
+
+Developer guidance:
+- Keep the post stack optional and controlled by the host app.
+- Wire ToonLab outputs into the app's render loop deliberately; the app owns
+  renderer lifecycle, resize handling, and scene/camera management.
+- Use documented settings and preset documents for portable looks.
+- Provide depth, masks, or character pass textures only when using features
+  that need them.
+- Do not assume ToonLab lab UI state or sample routing exists in the consumer
+  app.
+
+Verify:
+- Run the consumer app's normal build and a before/after visual smoke check.
+- Confirm disabling the post stack returns control to the app's normal render
+  path.

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

@@ -0,0 +1,134 @@
+---
+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.
+---
+
+# Rock and ground shaders
+
+Use this skill when terrain, cliffs, catalog rocks, beaches, or grass-ground
+blending are being built or reviewed. These two systems are separate public
+APIs and must share scene state deliberately.
+
+## Rock assets and material application
+
+Find rock geometry through ToonLab asset discovery. Feature-detect the surface:
+ToonLab OSS provides local catalog tools such as `search_assets({ source:
+'official' })`; ToonLab Pro provides the public gallery equivalent. Inspect
+`dimensionsMeters`, taxonomy, geology, structural role, and delivery metadata
+before download. Never render an asset merely to discover its size.
+
+Apply the package shader to compatible rock meshes:
+
+```js
+import {
+  applyRockShader,
+  setRockShaderSceneState,
+} from '@call-me-sensei/toonlab/rock-shader';
+
+const report = applyRockShader(rockRoot, { preset: 'call_me_sensei' }, {
+  textures: authoredRockMaps, // omit deliberately to use first-party generated maps
+});
+if (report.applied === 0) throw new Error('No rock mesh received the shader');
+if (report.usedGeneratedTextures) {
+  console.info('Using ToonLab first-party generated rock maps');
+}
+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.
+
+`applyRockShader` sets `castShadow` and `receiveShadow` true by default.
+Override them only for an explicit rendering reason. It reports whether
+provided textures or first-party generated maps were used; never call the
+fallback an authored catalog texture.
+
+The Call Me Sensei preset includes a macro projection plus a metre-scale near
+detail octave, HDR exposure, an indirect floor for down-facing overhangs, and
+a water-level wet band. Tune `projection.nearDetailScale`,
+`projection.nearDetailStrength`, `lighting.exposure`,
+`lighting.ambientFloor`, `lighting.skyFillStrength`,
+`lighting.skyFillTint`, and `shoreline.*` through the portable preset
+instead of adding example-local material overrides. Camera-visible rock must
+retain readable detail at close range, a lit/shade split, non-black overhangs,
+and wet response where it meets water.
+
+Call Me Sensei uses a controlled imported-map blend by default. Preserve clean
+UV-authored rock albedo, normal, and ORM inputs; verify
+`report.retainedSourceTextures` and the material's texture-lineage metadata.
+Do not set `preserveTextures: false` or switch to Replace merely to silence a
+surface audit. Use Replace only when an import audit proves the source maps are
+unusable.
+
+## Ground creation and shared scene state
+
+Prefer the safety wrapper:
+
+```js
+import {
+  createGroundShaderMesh,
+  setGroundShaderSceneState,
+} from '@call-me-sensei/toonlab/ground-shader';
+
+const ground = createGroundShaderMesh({
+  geometry,
+  field,
+  layers,
+  settings: { preset: 'call_me_sensei' },
+});
+scene.add(ground);
+setGroundShaderSceneState(ground, {
+  sunColor,
+  sunDirection,
+  skyColor,
+  waterLevel,
+  wetness,
+  snowCover,
+});
+```
+
+The wrapper defaults `castShadow`, `receiveShadow`, and
+`userData.groundFieldWrite` to true and disables unsafe frustum culling for
+custom/displaced bounds. The Call Me Sensei ground preset exposes
+`lighting.sunIntensity` for HDR sun-facing headroom and retains triplanar
+rock detail when optional maps are absent. Optional authored albedo, normal,
+and packed surface maps are still preferred for hero terrain and beaches.
+
+When grass adopts ground color, prefer `createSceneStyleRuntime()` with labeled
+`terrain.ground` and `vegetation.grass` targets. The bundle marks writers and
+  owns the environment ground-field pass. In a manual subsystem integration,
+  create and update the pass after writers exist, assert `pass.writerCount > 0`
+  and `pass.ready`, and call `pass.invalidate()` whenever a writer repaints without changing
+  transform. The field publishes unlit surface albedo; consumers apply their own
+lighting. Do not publish camera-lit ground color into the field.
+
+## Lighting and shadow verification
+
+A material flag is not visual proof. Enable the renderer shadow path, use a
+directional light that casts shadows, fit its camera to the visible world, and
+run the ToonLab environment sun-shadow pass on the node backend. Inspect:
+
+- sun-facing and away-facing ground and rock;
+- cast shadows from trees, rocks, characters, and the cliff mass;
+- self-shadow acne and detached/peter-panning shadows;
+- close rock detail and distant macro continuity;
+- ground-field color adoption without double lighting;
+- wet rock, beach, and shoreline continuity at the current water level.
+
+Reject flat untextured walls, black overhangs, missing trunk/cliff shadows,
+silent generated-map use, or a grass/ground color jump. Record the package
+version, preset, texture source, scene-state wiring, shadow backend, and
+inspection cameras in release evidence.

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

@@ -0,0 +1,30 @@
+---
+name: rockgen
+description: Help developers use ToonLab procedural rock, cliff, heightfield, erosion, SDF, mesh, preset, sculpt, or GLB export tools.
+---
+
+# Rockgen
+
+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.
+
+Public imports:
+- `@call-me-sensei/toonlab/rockgen`
+
+Read first:
+- `README.md` feature table for the exported rockgen surface.
+
+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.
+
+Verify:
+- In consumer apps, regenerate with the same preset/seed and compare the asset
+  shape or exported file the app expects.

package/agents/skills/claude/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/claude/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/claude/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.