@call-me-sensei/toonlab 0.3.1 → 0.4.20

package/agents/references/runtime-entry-points.md

@@ -0,0 +1,175 @@
+# ToonLab Runtime Boundary
+
+ToonLab is recommended for stylizing and populating supplied anime-game
+scene content. Prefer focused imports from these production-oriented areas:
+
+- `toon`, `toon-settings`, `character`
+- `environment`, `ground-shader`, `rock-shader`
+- `vegetation`, `vegetation-shaders`, `grass`, `grass-palettes`
+- `water`, `water-settings`
+- `lighting`
+- `post`, `post-processing`
+- `rockgen`, `texgen`, `assetlib`
+- `styles`, `asset-policy`, `loaders`
+
+`sky` and `cloud` are public because they are owned by the live Sky, Cloud, and
+Sky & Cloud Labs. Weather, climate, debris, ambient-effects, fauna, debug, and
+root terrain/world helpers are not package entry points in this release.
+Repository examples may exercise them locally, but package users must not
+import them.
+
+For characters, prefer `createCharacterRuntime()` from `./character`. It owns
+format loading, texture readiness, foot-origin fitting, toon conversion,
+humanoid rig resolution, native clips or packaged locomotion fallback, mixer
+updates, VRM updates, and disposal. The host still owns movement intent,
+dynamic physics, ground contact, and camera behavior. The walkable runtime
+automatically consumes the static collision service bound by
+`createSceneStyleRuntime()`. Do not recreate this pipeline inside individual
+scenes or Labs.
+
+The selected style bundle coordinates visual settings and supported scene-look
+systems; it does not construct or classify a scene. Lighting is a supported
+bundle domain through `createSceneStyleRuntime()`. VFX, camera behavior,
+game-feel behavior, and renderer configuration remain unsupported bundle
+domains owned by the host game.
+When a project-local implementation changes the selected anime treatment,
+treat it as a custom adapter and record it in the custom-gap report.
+
+The `grass` entry owns two deterministic first-party Call Me Sensei clump
+recipes, three generated LODs per variant, the procedural material, and the
+async-compatible `createCallMeSenseiGrassField()` default factory. It ships no
+mesh or texture files. `RetainedGrassClumpField` remains the generic container
+for caller-supplied, properly licensed geometry and materials.
+
+The default factory resolves the `call_me_sensei_clump` meadow preset: 40
+upright overlapping primary blades, full ground-field adoption, watercolor
+lift and translucent stroke layering, and a final LOD without an implicit hard
+cull. Sparse generic blades and repository comparison media are not equivalent
+fallbacks.
+
+Applying the Call Me Sensei bundle resolves the same grass field response. The
+scene style runtime creates and updates the ground-field pass automatically, so
+grass roots sample the actual labeled Ground Shader output without host-side
+color duplication.
+
+The `environment` entry accepts the same explicit style/scenario routing used
+by the preset registry:
+
+```js
+await applyEnvironmentShader(root, {
+  preset: 'call_me_sensei',
+  scenario: 'exteriorDay',
+});
+```
+
+This is equivalent to spreading
+`resolveEnvironmentPreset('call_me_sensei', 'exteriorDay')` into the adapter.
+Named preset values establish the baseline; explicit `settings`, `features`,
+`parameters`, and `materialLook` overrides take precedence. Select the preset
+before authoring overrides instead of retyping its numeric fields.
+
+The `vegetation` entry's scatter helpers place across the ground heightfield —
+`scatterInRect`, `scatterGrassAround`, `scatterForest` — taking `(x, z)` and
+sampling `y` from a host `heightAt`. That contract cannot express a surface
+which is not single-valued in `y`, such as a cliff cap or a ledge with terrain
+both above and below it.
+
+For those, use `scatterOnSurface({ surfaces, density | count, minSpacing,
+mask, weightAt, normalBlend })`. Each surface is a disc in world space —
+`{ center, radius, normal?, seed? }`, the shape a rock or cliff module already
+publishes for its caps and ledges. Spacing is measured in 3D, so stacked caps
+do not reject each other's points. Each surface draws from its own
+deterministic stream, so adding or removing one does not reshuffle the others.
+Returned placements carry `normal`, `forward` and `yaw` alongside `x/y/z`, so
+an aligned field no longer has to derive orientation per placement. The
+existing `(x, z)` mask factories and `combineMasks` compose unchanged.
+
+The `ground-shader` entry also owns bounded transient print fields for sand,
+dirt, and sufficiently deep snow. Create a `GroundPrintLayer`, pass it as the
+material's `printLayer`, and emit contact events with `stamp()`. The portable
+Ground Shader document saves only `printResponse`; stamp history, snow depth,
+visibility, and recovery remain runtime state:
+
+```js
+const prints = createGroundPrintLayer({
+  bounds: geometry.boundingBox,
+  resolution: 1024,
+  recoverySeconds: 30,
+});
+
+const ground = createGroundShaderMesh({ geometry, field, layers, printLayer: prints });
+prints.stamp({
+  shape: 'boot-left',
+  position: footWorldPosition,
+  forward: characterForward,
+  size: [0.12, 0.28],
+});
+setGroundShaderSceneState(ground, { snowCover: 1, snowDepth: 0.12 });
+```
+
+This is a visual albedo, roughness, and normal response. Terrain geometry,
+precise/dynamic collision, navigation, character contact detection, and large-world print
+streaming remain host-owned.
+
+Pair it with `createCapEdgeWeight({ rimBias: 0.05, falloff, break })` for a
+radial weight that thins coverage toward a broken rim. `falloff` and `break`
+create the thinning; `rimBias` deliberately pushes coverage outward, so keep
+it near zero for a soil cap. A cap that stays dense to its edge reads as a flat
+disc stuck onto the rock rather than as soil.
+
+## Shared scene surface runtime
+
+Use `createSceneSurfaceRuntime()` from `@call-me-sensei/toonlab/runtime` when a
+scene combines an authored terrain heightfield with grounded props, meadow
+grass, characters, or shoreline water. The host supplies world bounds,
+`heightAt(x, z)`, and a water level once. The runtime then owns derived Y
+placements, bounds grounding, water masking, the shoaling/nearshore/shore-state
+connection, source-texture continuity checks, and fail-closed composition
+readiness.
+
+```js
+const surface = createSceneSurfaceRuntime({ bounds, heightAt, waterLevel: 0 });
+const grass = await surface.createGrassField({ count: 12000, min, max });
+const water = surface.createWaterSurface({ width: 80, depth: 50, position: { z: -25 } });
+surface.place(tree, { x: 4, z: 8 });
+surface.place(bench, { anchor: 'bounds', x: 2, z: 5 });
+
+// After the package shadow pass has updated:
+surface.assertReady({
+  camera,
+  styleRuntime,
+  requireShadowDomains: ['character', 'manufactured.surface', 'vegetation.tree'],
+});
+```
+
+Do not hand-author grass Y values, independently offset a shoreline water
+plane, or infer readiness from `castShadow` flags when this contract applies.
+
+The live `cloud` entry is a raymarched volumetric deck, not painted sources
+placed by a composition. The
+painted pipeline (`createCloudSourceDocument`, `createCloudCompositionDocument`,
+`createCloudField`, `createCloudShaderSettings`) was replaced outright and no
+longer exists. Parameters are six groups on a `toonlab/sky-params` document, and
+the whole sky is one system:
+
+```js
+const sky = await SkySystem.create({ renderer, scene, camera, quality: 'high' });
+await sky.applyPreset({
+  cloud: {
+    shape: { altitude: 1400, coverage: 0.55, thickness: 2800 },
+    lighting: { powderStrength: 0.7, scatteringAlbedo: 0.82 },
+    wind: { heading: 135, speed: 8 },
+  },
+});
+sky.update(delta);  // once per frame, before the scene pass
+```
+
+`applyPreset` fully replaces sky state: anything the object omits falls back to
+the schema default rather than to what is on screen. `sky.toParams()` is its
+inverse and round-trips. This is a focused sky/cloud authoring and runtime
+contract; final scene composition and art direction remain host
+responsibilities.
+
+Use the package README and exported functions/settings as the runtime source
+of truth. Labs, internal comparison fixtures, local asset paths, and repository
+documentation outside `agents/references/` are not installed public APIs.

package/agents/references/style-bundles.md

@@ -0,0 +1,71 @@
+# Style Bundles and Shader Routing
+
+A style bundle selects coordinated visual treatments and supported system
+behavior. It never selects model identity, species, placements, current
+weather, or current time.
+
+Use `CALL_ME_SENSEI_STYLE_BUNDLE` as the first-party anime-game reference.
+Use `auditStyleBundleApplication()` before `applyStyleBundle()`. Production
+targets need a stable `id` and an explicit `domain`. Supported domains use
+package adapters automatically; custom renderers need an explicit adapter. Do
+not classify from object names, texture colors, or scene parenting.
+
+| Target domain | Bundle slot |
+| --- | --- |
+| `character`, `equipment`, `prop` | `toon` |
+| `manufactured.environment` | `environment` |
+| `vegetation.tree` | `treeShader` |
+| `vegetation.grass` | `grassShader` + `grass` field response |
+| `vegetation.flower` | `flowerShader` |
+| `terrain.ground` | `groundShader` |
+| `natural.rock` | `rock` |
+| `natural.debris` | `debris` |
+| `water` | `water` |
+| `sky` | `sky` |
+| `cloud` | `cloud` |
+| `lighting` | `lighting` |
+| `post` | `post` |
+
+Prefer `createSceneStyleRuntime({ renderer, scene, sky, water })` for a complete
+bundle application. It owns one stable lighting rig and automatically enables
+the environment ground-field pass when the grass slot requests ground-color
+adoption. Call `runtime.update(delta, camera)` before the scene render. Never
+recreate those passes in each playground or scene.
+
+Strict application preflights every target before the first mutation. Missing
+slots, unknown domains, mixed material roles without an ID mask, unsupported
+renderers, and undocumented custom adapters are failures. Advisory mode may
+apply valid targets, but it must return every skipped target and gap.
+
+## Mandatory authored-asset labeling
+
+Agents that model, generate, convert, or import a 3D object must finish its
+style metadata before handoff. Every renderable root needs a stable target ID
+and explicit domain. Every material slot beneath it needs a stable material ID
+and at least one semantic role in the versioned `materials` contract. A root
+domain label does not substitute for per-material classification.
+
+If one atlas crosses incompatible physical or shader roles, split the draw
+materials or author a material-ID mask. Strict mode must fail incomplete
+material coverage. Advisory mode may continue only while recording the gap;
+the agent must not call the asset style-bundle-ready.
+
+The minimum public-API shape is:
+
+```js
+material.userData.toonlabMaterialId = 'BenchWood';
+labelStyleTarget(root, createStyleTargetLabel('manufactured.surface', {
+  targetId: 'scene/bench-1',
+  materials: createStyleMaterialContract('manufactured.surface', {
+    assignments: { BenchWood: { roles: ['primaryMass'] } },
+  }),
+}));
+```
+
+Repeat the assignment for every distinct render material. The IDs belong in
+the asset/export manifest as well as the runtime object so reimport does not
+silently erase routing.
+
+Style bundle v2 is visual-only and includes anime art-direction metadata.
+Parsing a v1 document returns migration warnings for old asset selections;
+move those decisions to scene configuration or an asset-sourcing policy.

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

@@ -0,0 +1,275 @@
+---
+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.
+---
+
+# Asset Sourcing
+
+Use this skill when a developer needs an asset — a model, texture, HDRI,
+prop, tree, rock, building, material, or a saved look/behavior preset.
+
+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/custom-gap-report.md`
+
+**The boundary:** ToonLab targets anime-style games and environments. The npm package is the worker for approved procedural
+families, style presets, and texture baking. The gallery is optional. Route
+through MCP only where it adds something beyond the package: external
+discovery, curation/moderation policy, download provenance, shared workspace
+state, or explicitly requested managed generation. Do not use MCP tools as a
+proxy for package functions. ToonLab Pro may author and review stylized base
+sets; their approved documents, recipes, labels, seeds, and provenance must
+remain portable so OSS runtimes can use them without a database.
+
+## Select the connected MCP surface
+
+Feature-detect tools before making a call. ToonLab OSS local MCP is identified
+by `get_workspace_info`, `search_cc0_assets`, `get_cc0_asset`, and
+`import_cc0_asset`. ToonLab Pro remote MCP is identified by
+`get_runtime_guide`, `search_public_gallery`, and `get_toonlab_asset`. Either
+surface is sufficient and both may be connected. Shared names such as
+`search_assets`, `get_asset`, `list_my_creations`,
+`validate_asset_candidate`, and `record_asset_gap` have surface-specific
+schemas; qualify them by MCP server when both are present and use the schema
+advertised by that server. Read `agents/references/mcp-asset-discovery.md` for
+the exact OSS and Pro sequences.
+
+## Decision order
+
+Choose the first route that is both available and accepted for the requested
+scene-kit role.
+
+1. **Load policy and ask when missing.** Call the available server's
+   `get_anime_game_profile`, load
+   the selected bundle, and locate the project's sourcing policy. If no policy
+   exists, ask the developer; until answered, use library-first advisory mode
+   and report the unresolved decision. Validate every candidate before use.
+2. **Reuse what exists.** In OSS, earlier imports, saved presets, and exports
+   live in `.toonlab/`; call local `list_my_creations` and `search_assets` with
+   `source: 'workspace'`, `'workspace-storage'`, `'library'`, or `'builtin'`.
+   If those do not close the role, use local `search_assets` with
+   `source: 'official'` for the complete released Gallery catalog and follow
+   `nextOffset` until null.
+   In Pro, call cloud `list_my_creations`, then `search_public_gallery`; use
+   `source: 'toonlab'` plus the appropriate catalog for first-party assets and
+   follow `nextOffset`. For rocks on either surface, shortlist from positive
+   `dimensionsMeters` width/height/depth plus family/profile, scale class,
+   category/subcategory, geology, and surface; never render a GLB merely to
+   discover its size. Call `get_asset` (OSS) or `get_toonlab_asset` (Pro) only
+   for finalists that need full recipe, lineage, and file metadata. When both are connected,
+   search the local project/library before the Pro cloud library and gallery.
+   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`.
+   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,
+   recipe, seed, domain/material labels, and golden-seed verification. Do not
+   treat every legacy catalog entry as approved merely because it can spawn.
+4. **Search curated open sources when policy permits and generation is not
+   approved or is not the best fit.** In OSS, use
+   `search_cc0_assets({ query, kind, provider })`, `get_cc0_asset`, then
+   `import_cc0_asset` to download selected files into `.toonlab/imports/` with
+   a provenance manifest. In Pro, use Pro `search_assets` and `get_asset`;
+   Pro does not expose `search_cc0_assets` or `import_cc0_asset`. This route
+   stays on MCP because it carries the network fetch, the owner curation
+   policy, and licensing provenance —
+   selection is by name/tags only, so always preview imports in-scene before
+   committing to them. Prefer CC0. Accept CC-BY only through a source path that
+   exposes the exact creator, asset URL, license/version/URL, provider credit,
+   and modification notice; do not assume a tool named `search_cc0_assets`
+   returns CC-BY.
+5. **Use managed generation for a named remaining gap through the connected surface.**
+   First record why accepted
+   assets, approved procedural families, and curated open candidates were
+   inadequate. Check generation capabilities and rights for the input image.
+   Treat output as a candidate that still needs topology, UV, texture, scale,
+   collision, LOD, semantic-label, and Call Me Sensei review. OSS keeps
+   `generate_asset` for deterministic recipes and exposes provider-backed work
+   separately as `generate_ai_asset` when local keys are configured. Pro uses
+   credit-spending `generate_asset` with hosted workers. Both surfaces expose
+   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.
+
+Persist anything worth keeping with `save_creation` (or write the JSON into
+the repo); `.toonlab/creations/` is the shared surface labs and later
+sessions read. Every reusable saved object must include up to ten concise
+lowercase slug tags. Cover its semantic role, material or asset family,
+location or biome when relevant, project, and lifecycle state; never save an
+object with only a filename or generic `asset` tag. Follow `nextOffset` until
+null when checking for an existing saved object before creating a duplicate.
+
+For every completed asset request, update or report the scene family, kit
+role, selected route, license/provenance, rendering domain, material roles,
+support level, collision/LOD status, Call Me Sensei verification, and coverage
+gap that was closed. State explicitly when gallery search was skipped because
+an approved generator owned the role.
+
+## Manufactured environment material contract
+
+For generated or imported props, vehicles, buildings, furniture, and interior
+assets, classify each material once with glTF extras / Three.js
+`userData.urbanMaterial`. Author the versioned object with these axes:
+
+- `baseMaterial`: `metal`, `mineral`, `wood`, `polymer`, `rubber`, `glass`,
+  `ceramic`, `textile`, `leather`, `paper`, `composite`, `fluid`, or
+  `genericDielectric`.
+- `finish`: `raw`, `painted`, `varnished`, `clearCoated`, `polished`,
+  `brushed`, `glazed`, `anodized`, `mirror`, or `matte`.
+- `renderMode`: `opaque`, `alphaCutout`, `translucent`, `transmissive`, or
+  `unlit`.
+- `structuralRole`: `primaryMass`, `secondaryStructure`, `trim`, `fastener`,
+  `cavity`, `window`, `graphic`, or `lightEmitter`.
+- `contentFlags`: any of `graphic`, `display`, and `emissive`.
+
+Preserve source color and every available PBR map. Classification supplies
+stable meaning and fallback priors; it never replaces albedo, roughness,
+metalness, normal, AO, emissive, clearcoat, transmission, opacity, or UV data.
+
+- Put classification on the material when a mesh has multiple materials. A
+  node classification is a default for every material below it.
+- Split materials or provide a material-ID mask when one atlas spans
+  incompatible classes such as masonry, wood, metal, and window glass.
+- Keep wear, dirt, rust, chipped coating, wetness, burn, snow, and similar
+  conditions in continuous masks rather than inventing material classes.
+- Never encode pastel amount, palette overrides, cel thresholds, reflection
+  strength, or time-of-day values in the model.
+- Never reclassify a model to suit a shader. Custom shaders consume the stable
+  axes and define global settings plus sparse per-axis profiles.
+- Accept the old `urbanSurface` IDs only through the documented compatibility
+  map; do not author `lid`, `roof`, or `trim` as physical material classes.
+- Reload the exported GLB and inspect classifications, fallback warnings, and
+  mixed-atlas boundaries before judging only a beauty render.
+- Run `analyzeManufacturedAsset(root)` as the code-first audit. Names, PBR
+  slots, alpha/transmission, emission, and metalness can cover clean assets;
+  never guess material identity from RGB alone. Use visual analysis only as
+  offline assistance for mixed/anonymous atlases and approve its proposal into
+  a material split, ID mask, or explicit assignment.
+- Use `proposeManufacturedStyleTargetLabel(root)` to turn safe classifications
+  into stable material IDs and a versioned `manufactured.surface` label.
+  Generic fallback, low-confidence, and shared-role-conflict issues block the
+  proposal. Supply reviewed `materialOverrides`, then call
+  `applyManufacturedStyleTargetLabelProposal(root, proposal)`. Report automatic
+  and assisted results separately; an explicit repair is not an automatic hit.
+- For FBX, OBJ/MTL, USDZ, VRM, PMX/PMD, third-party GLB, and other sources
+  that cannot safely carry custom properties, write a versioned
+  `*.toonlab-materials.json` sidecar and apply it after loading. The runtime
+  classification layer never edits geometry, UVs, or texture pixels.
+- Review and temporarily switch tags in the Manufactured Material Lab; export
+  its sidecar to make the result durable.
+
+## Sample and compare (vision-capable agents)
+
+For surfaces that dominate the look (terrain, floors, walls, hero props),
+don't take the first hit — produce 2–3 candidates across routes and look at
+them before choosing:
+
+- **Generated**: texgen is part of the npm package, not an MCP tool — bake
+  candidates headlessly with a short node script:
+  `evaluateTextureMaps(createTextureSettings(findTexturePreset(id).settings),
+  { size: 256 })` (async, ~50 ms) returns raw RGBA maps; encode the albedo
+  to PNG and write it next to the imports.
+- **Discovered in OSS**: when the connected surface exposes
+  `import_cc0_asset`, it leaves real image files in `.toonlab/imports/`.
+  ToonLab Pro instead returns approved immutable download URLs and provenance;
+  do not prescribe the OSS import tool on that surface.
+
+View the swatches side by side, judge fit against the game's stylized look,
+then confirm the winner in-scene (toon shading changes how a texture reads).
+If you cannot view images, fall back to the routing heuristics and rely on
+the in-scene verify step. This costs extra tokens — reserve it for hero
+surfaces and take the first good match for incidental materials.
+
+## Which source for which asset
+
+Stable routing (the source list itself grows — treat the registry, not this
+table, as the source of truth):
+
+- Seamless PBR material sets (brick, wood, ground …) → ambientCG.
+- Photoscanned props, HDRIs, high-end texture sets → Poly Haven.
+- Stylized/toon-ready models, vegetation, buildings → the built-in
+  procedural catalog first only for families that passed the base-set
+  reliability gate; otherwise compare curated external candidates.
+- Stylized *seamless textures* → `@call-me-sensei/toonlab/texgen` in code
+  (60+ presets); the catalog has no texture entries, so this route is a
+  package import, not an MCP call.
+- Audio, fonts, adjacent media → not automated; link the developer to the
+  source and import the downloaded file.
+
+Sources carry their own metadata (`kinds`, `goodFor`, `qualityTier`,
+`enabled`) in the registry (`src/assetlib/sources.js`, surfaced through the
+asset tools). New sources appear over time; query rather than assume.
+
+## Loading first-party catalog models
+
+Some first-party catalog GLBs declare `KHR_texture_basisu` in
+**`extensionsRequired`**, so a KTX2 transcoder is mandatory for those assets.
+Supply `decoderBasePath` and `renderer`, and stage the Basis and Draco decoder
+files where that path resolves.
+
+**Share one transcoder set across the whole catalog.** A transcoder is expensive
+and is not automatically pooled. Use the public loader contract:
+
+```js
+import {
+  createModelAssetTranscoders,
+  loadModelAsset,
+} from '@call-me-sensei/toonlab/loaders';
+
+const transcoders = createModelAssetTranscoders({ decoderBasePath, renderer });
+const asset = await loadModelAsset(url, { transcoders });
+// Reuse transcoders for every model, then dispose once after loading finishes.
+transcoders.dispose();
+```
+
+Constructing decoder resources per asset can spin up a WASM instance per asset,
+and a catalog-scale scene can fail with
+
+```
+RuntimeError: Aborted(RangeError: WebAssembly.instantiate():
+Out of memory: Cannot allocate Wasm memory for new instance)
+```
+
+long before it finishes loading. Cache each parsed asset/geometry by immutable
+asset URL as well, so a repeated id is one decode and upload rather than two.
+
+Note also that a catalog rock's `material-config.json` may name textures with
+paths that do not resolve from the delivery origin. Do not block on them: the
+rock shader's own projection is the safe fallback. Call Me Sensei normally
+blends clean UV-authored albedo/normal/ORM detail and reports retained texture
+lineage; use `assetIntegration.sourceAlbedoMode: 'replace'` only when an import
+audit proves those source maps unusable.
+
+## Licensing and curation rules
+
+- Enabled sources are owner-curated to the project quality bar; disabled
+  ones are pending review. Do not bypass the tools with ad-hoc downloads
+  from other sites — moderation and provenance exist for a reason.
+- CC0 clears copyright, not trademarks, logos, or personality rights
+  visible in scans. If an asset shows a brand or a person, flag it instead
+  of importing.
+- Every imported ref keeps `source` + attribution provenance. Preserve it;
+  some sources (e.g. Poly Haven's API terms) want credit even though the
+  assets are CC0. Surface attribution in the app's credits.
+- CC-BY additionally requires appropriate creator credit, the license link,
+  the source link when supplied, and an indication of modifications. Preserve
+  those fields through conversions, bundles, scenes, and exports.
+
+## Verify
+
+- For every selected first-party rock, record the catalog ID and original
+  `dimensionsMeters`; after authored scaling, record the resulting scene size.
+  Reject missing, zero, negative, or axis-ambiguous dimensions before download.
+- Preview imported GLBs/textures in the consumer app's actual scene and
+  toon/environment shading — reference-realistic assets can clash with a
+  stylized look.
+- For procedural assets, pin the `seed` and confirm the app regenerates the
+  identical asset.

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

@@ -0,0 +1,59 @@
+---
+name: environment
+description: Help developers use ToonLab environment shading, lighting rigs, ambient probes, reflections, fog, cloud shadows, or vertex AO in an app.
+---
+
+# Environment
+
+Use this skill when a developer wants stylized scene materials, material-role
+classification, sun/lamp rigs, time-of-day, ambient probes, planar reflections,
+BVH vertex AO, fog, cloud shadows, or environment presets.
+
+Public imports:
+- `@call-me-sensei/toonlab/environment`
+
+Read first:
+- `agents/references/anime-art-direction.md`
+- `agents/references/style-bundles.md`
+- `agents/references/runtime-entry-points.md`
+- the exported `environment` material-role schema and guidance below.
+
+Developer guidance:
+- Apply environment materials to app-owned meshes and scenes.
+- Keep asset loading, texture hosting, renderer setup, and scene routing in the
+  host app.
+- Use documented settings and presets for material roles, lighting, fog, cloud
+  shadows, probes, and reflections.
+- Consume the versioned `urbanMaterial` classification: base material,
+  finish, render mode, structural role, and content flags. Put style choices
+  in global shader settings and sparse per-axis profiles; do not relabel assets
+  when the shader changes. Accept legacy `urbanSurface` only through the
+  documented migration map.
+- Use `analyzeManufacturedAsset` for the automatic code-first import audit.
+  Apply durable corrections with `applyManufacturedMaterialManifest`; do not
+  infer semantic material from base-color pixels alone. A visual model is an
+  optional offline assistant for mixed atlases, never a runtime dependency.
+- For an imported hero vehicle or ship, preserve the complete pre-conversion
+  audit and the `applyEnvironmentShader()` classification report. Report every
+  generic fallback, low-confidence assignment, transparent surface, and mixed
+  atlas; do not call the result contract-ready until a reviewed sidecar or
+  embedded material contract removes those warnings.
+- Treat global environment settings as the catch-all, then resolve sparse
+  `materialLook` profiles by base material, finish, render mode, structural
+  role, content flags, object class, and stable asset id. Do not implement a
+  shader fork per base material; only incompatible render modes need distinct
+  shader families.
+- Use the same post-load classification for GLB, FBX, OBJ/MTL, USDZ, VRM,
+  PMX/PMD, and procedural `Object3D`s. Prefer glTF extras for owned GLBs and a
+  `*.toonlab-materials.json` sidecar for formats that do not preserve custom
+  metadata reliably.
+- Treat BVH vertex AO as optional; apps that do not use it should not need
+  `three-mesh-bvh`.
+- Do not rely on ToonLab sample app URLs, sample asset paths, or generated local
+  manifests.
+
+Verify:
+- Run the consumer app's normal build and visual smoke check.
+- For a vessel, inspect above-water, shoreline, and reflected/refracted views;
+  verify sails/windows keep their intended render mode and the hull crosses the
+  waterline without being excluded from required water scene passes.