@call-me-sensei/toonlab 0.3.1 → 0.4.20

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

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