@call-me-sensei/toonlab 0.2.0 → 0.3.1

package/AGENTS.md

@@ -94,11 +94,134 @@ Every cluster has a `default` and a studio-managed `call_me_sensei` preset.
 
 ## Subpath imports
 
-`/toon` `/environment` `/water` `/vegetation` (incl. scatter helpers +
-`StylizedForest`) `/sky` `/post` `/character` `/loaders` `/rockgen`
-`/debrisgen` `/debug`; root adds `createStylizedTerrain`,
+`/toon` `/environment` `/lighting` `/weather` `/water` `/vegetation` (incl. scatter helpers +
+`StylizedForest`) `/vegetation-shaders` `/grass-palettes` `/sky` `/post` `/character` `/loaders` `/rockgen`
+`/debrisgen` `/pathgen` `/debug`; root adds `createStylizedTerrain`,
 `createStylizedWorld`, `createWorldCollision`, `createWorldMinimap`,
-`resolveWorldPreset`.
+`resolveWorldPreset`, `createStylizedPaths`.
+
+Authoring scope: Character/Vegetation/Environment Shader Labs save reusable
+IP-wide material treatments; Tree/Flower/Grass and other Asset Labs save asset
+identity and geometry; Water/Sky Labs save complete runtime-system presets
+with their shader controls embedded, so do not create separate Water Shader or
+Sky Shader documents. Current lighting, weather, camera, and interactions
+remain host-owned.
+
+Sky and Water keep authored and current-scene state separate. `.settings` is
+the portable authored baseline; `.renderedSettings` is the composition after
+named transient layers. Lighting, Weather, and other owners must use unique
+ids with `setSceneOverrideLayer`, clear only their own id with
+`clearSceneOverrideLayer`, and never persist the composed result. The manual
+`setSceneOverrides`/`clearSceneOverrides` pair owns only the `scene` layer;
+`clearAllSceneOverrideLayers` is for explicit host teardown.
+
+`lighting.attachWorld(world)` owns the world sun adapter plus private
+priority-100 Sky/Water layers. If Weather is present it also installs Lighting
+as Weather's sun/ambient/fog bridge: Lighting remains the sole writer, Weather
+provides modulation and private priority-200 Sky/Water layers, and either
+system removes only its own state on detach/dispose.
+The adapter is `world.setSun({ direction, color, sky })`; it aligns the real
+light/shadows with Grass, Flower, Forest, Ambient FX, Sky, and Water inputs.
+For a standalone custom Weather coordinator, supply paired `getSun`/`setSun`
+and baselines for any write-only cloud/surface adapters so teardown is exact.
+
+Sky documents contain exactly 46 portable art fields; constructor-only radius
+and quality are excluded. Sky quality is compile-time (`low`/`medium`/`high`
+= 2/3/4 cloud octaves, or custom `{ cloudOctaves: 1..5 }`), and
+`sky.setQuality()` rebuilds the material while preserving authored/layered
+state. Water quality is selected when constructing `WaterSurface`; a tier
+change requires replacing/rebuilding the surface, never `applySettings()`.
+
+Lighting (`/lighting`) owns portable, versioned recipes and looks rather than
+a replacement renderer. Use `createLightingManager({ scene, camera, renderer,
+recipe, quality })`, call `update()` as the focus/camera moves, and save JSON
+with the recipe/look serializers. Luminaire, rig, look, and quality presets
+come from `getLightingPresetOptions(kind)`. Disc/tube area lights, IES, tag
+linking, and Unreal Engine 5.8 MegaLights/Lumen are explicit adapter intent;
+the capability report and diagnostics state each runtime fallback. Author and
+stress-test them in `/lighting-lab/`.
+
+`createLightingManager` is the lower-level rig-realization API. For a composed
+world and day cycle, use `createLightingSystem(...)`, then call
+`lighting.attachWorld(world)` for the sun/Sky/Water ownership and Weather
+modulation bridge described above.
+
+Paths/roads/bridges: `createStylizedWorld({ paths: { seed, auto: { count: 4,
+styles: ['dirt', 'stone'] } } })` routes seeded trails around slopes, bridges
+water crossings, parts grass/trees around the ribbon, and feeds the flattened
+profile to `world.collision.groundHeight` — use that (not raw `heightAt`) for
+character ground so bridges carry the walk. Minimap: pass `paths: world.paths`
+to `createWorldMinimap` for the network overlay.
+
+Catalog (`@call-me-sensei/toonlab/catalog`): the whole procedural library,
+queryable and spawnable —
+`catalog.list({ tags, cluster, text })`, `catalog.get(id)`, and the headline
+`catalog.spawn(id, { seed })` → a PropAsset for any prop / building / tree /
+rock / debris entry (settings presets throw with their copy-paste snippet
+instead). `catalog.register(entry)` adds user assets;
+`catalog.addSource(url, { headers })` mounts remote registries (the pro
+seam). The browser Gallery at `/gallery/` searches third-party open assets;
+the procedural Catalog itself is a runtime API rather than a standalone lab.
+
+Villages (`/villagegen`): `createStylizedWorld({ pois: { seed, villages: 2,
+shrines: 1, pierHamlets: 1, size } })` → named settlements (seeded syllable
+names) with streets merged into the world path network, buildings facing
+their street behind picket fences, wells/lanterns/clutter by archetype, POI
+entries auto-connected by roads. `world.pois` feeds
+`createWorldMinimap({ markers })` labels. Fully-shadowed building facades
+need `parameters.sunShadowStrength ≈ 0.7` in worlds that run near-zero
+ambient (full-strength cast shadows crush large vertical masses to black).
+
+Fauna (`/fauna`) and ambient VFX (`/ambientfx`) are one option each:
+`createStylizedWorld({ fauna: { species: { birds: 40, fish: 80 } },
+ambientfx: { effects: { petals: true, fireflies: true } } })` — both join
+the world's fog/wind/cloud-shadow automatically.
+
+Weather (`/weather`) is a cross-system coordinator, not an environment
+catch-all: `createStylizedWorld({ weather: { preset: 'snow' } })`, then
+`world.setWeather('thunderstorm', { duration: 4 })`. Its 22 shared presets
+drive sky/sun/fog/cloud shadows, wind across vegetation/fauna/ambient FX,
+one-draw GPU rain/snow/sleet/hail/dust, water waves/ripples, lightning and
+thunder events. Surface `{ wetness, snowCover, ice }` values are host-facing
+outputs for custom terrain/prop/character materials. Labs should read
+`getWeatherPresetOptions()` rather than maintaining a private condition list.
+
+Gameplay VFX (`/vfxgen`): event-driven combat/movement effects, spawned at
+gameplay moments (not a world option) — `createVfxSystem({ seed, preset,
+heightAt })` then `vfx.spawn('slash' | 'impact' | 'fireball' | 'footstep' |
+'landing', { at | follow, power, look })` and `vfx.update(delta, camera)`
+per frame. All bursts share TWO draw calls; slash trails / fireball cores
+are pooled meshes. `vfx.setDistanceFog(...)` joins the height-fog layer;
+`vfx.setTimeScale(0)` is hit-stop. Weapons + moves are batteries-included:
+`createStylizedWeapon({ type: 'sword' | 'greatsword' | 'spear' | 'dagger'
+| 'hammer' })` + `createMoveController({ weapon, vfx })` →
+`attack.play('slash' | 'overhead' | 'thrust' | 'spin' | 'plunge')` — authored
+phase-based motions whose event tracks fire the VFX at the right beats
+(plunge = the full crouch→leap→dive→landfall decomposition); weapon weight
+scales timing and hit power. Design interactively in the VFX Lab
+(`/vfx-lab/`): weapon picker + move triggers + schema panels, exports a
+recipe (preset + seed + overrides) that drops straight into `createVfxSystem`.
+The `call_me_sensei` preset targets the reference action-RPG hit language
+(smooth gradient arcs, four-point star + shockwave circle per hit,
+hard-saturated pyro fireball). Demo loop: `examples/vfx-arena/`.
+
+Buildings (`/buildinggen`): seeded grammar exteriors —
+`buildingAsset({ type: 'cottage' | 'shed' | 'farmhouse' | 'watchtower' |
+'shrine', seed })` is a PropAsset (multi-circle footprint, buried foundation
+skirt for slopes ≤ ~20°, hi/lo LOD, `door` anchor with outward normal for
+street-facing placement). `createBuildingFromRecipe(recipe)` rebuilds
+deterministically; ≤ 6 draw calls per building.
+
+Props (`/propgen`): every placeable thing is a PropAsset —
+`createPropAsset({ asset: { type: 'lantern', variant: 'stoneToro', seed } })`
+or `propAssetFromObject(importedGlb)` (auto footprint + ground anchor).
+Place with ONE call: `placeAlongSpline({ asset, spline: world.paths.splines[0],
+spacing, offset, mask, heightAt: world.paths.heightAt, collision:
+world.collision, parent })` (fences/walls build continuously; point props
+instance with hi/lo LOD — call the returned `update(delta, camera)` per
+frame), or `scatterProps`/`placeProps`. Props added after `createStylizedWorld`
+need `applyEnvironmentShader(propsRoot, { parameters: { …fog } })` to join the
+look; pass a dry-land `mask` so dressing never marches into water.
 
 ## Symptom table — check before debugging blind
 

package/ATTRIBUTION.md

@@ -8,9 +8,18 @@ Code is MIT-licensed by Hyperbond Studio PTE. LTD. (see LICENSE). The assets bun
 |---|---|---|---|
 | Mannequin character (45 embedded animation clips) | `public/characters/mannequin.glb` | CC0 1.0 | [Quaternius — Universal Animation Library](https://quaternius.com/packs/universalanimationlibrary.html), recolored to neutral grays. See `public/characters/LICENSE.md`. |
 | Landscape textures (grassy-land, land, mountain, rock, sand, tree-trunk) | `labs/shared/textures/` | CC0 1.0 | First-party (created by the toonlab authors), dedicated to the public domain. |
+| Water Lab sea fern model | `public/water-lab/cc0/quaternius/fern-1.glb` | CC0 1.0 | [Quaternius — Fern 1, Stylized Nature MegaKit](https://quaternius.itch.io/stylized-nature-megakit), selected through the [ToonLab catalog](https://toonlab.io/asset/quaternius:stylized-nature-megakit-fern-1). |
+| Water Lab Coast Sand 01 texture set | `public/water-lab/cc0/polyhaven/` | CC0 1.0 | [Rob Tuytel — Coast Sand 01, Poly Haven](https://polyhaven.com/a/coast_sand_01), selected through the [ToonLab catalog](https://toonlab.io/asset/polyhaven:coast_sand_01). |
+| City street models (buildings, roads, cars, street props — 28 models) | `public/props/cc0/kaykit-city/` | CC0 1.0 | [Kay Lousberg — KayKit City Builder Bits](https://kaylousberg.com). Attribution optional under CC0; credited with thanks. See the bundled `LICENSE.txt`. |
+| Furniture models (tables, chairs, couch, lamps, shelves — 17 models) | `public/props/cc0/kaykit-furniture/` | CC0 1.0 | [Kay Lousberg — KayKit Furniture Bits](https://kaylousberg.com). Attribution optional under CC0; credited with thanks. See the bundled `LICENSE.txt`. |
+| Environment Lab Wood Floor texture | `public/environments/cc0/polyhaven/wood-floor-diff-1k.jpg` | CC0 1.0 | [Dimitrios Savva — Wood Floor, Poly Haven](https://polyhaven.com/a/wood_floor) |
+| Environment Lab Painted Plaster Wall texture | `public/environments/cc0/polyhaven/painted-plaster-wall-diff-1k.jpg` | CC0 1.0 | [Amal Kumar — Painted Plaster Wall, Poly Haven](https://polyhaven.com/a/painted_plaster_wall) |
+| Environment Lab photoscanned furniture (Sofa 02, Modern Arm Chair 01, Round Wooden Table 01, Classic Console 01, Steel Frame Shelves 01, Potted Plant 04) | `public/environments/cc0/polyhaven/models/` | CC0 1.0 | [Poly Haven models](https://polyhaven.com/models) (1k glTF), per-asset credits on each asset page |
+| Environment Lab museum scans (baluster vase F1980.190-.194; Colonoware pot) | `public/environments/cc0/smithsonian/` | CC0 1.0 | [Smithsonian Open Access 3D](https://3d.si.edu), selected through the [ToonLab catalog](https://toonlab.io/gallery?src=smithsonian) |
+| Draco + Basis decoders (model decompression) | `public/draco/`, `public/basis/` | Apache 2.0 | [google/draco](https://github.com/google/draco), [BinomialLLC/basis_universal](https://github.com/BinomialLLC/basis_universal) — bundled three.js decoder builds |
 
 Everything else that renders — water, sky, grass, flowers, trees, foliage,
-splashes, post-processing — is procedural code, no asset files.
+splashes, post-processing — is procedural code.
 
 ## Not bundled (bring your own)
 
@@ -32,9 +41,38 @@ folder that is **not** part of this repository:
 
 ## Recommended free sources
 
+The machine-readable version of this list (license facts, integration level,
+quality tier, enable/disable flags) is `src/assetlib/sources.js`; the Asset
+Browser lab surfaces it.
+
 - [Quaternius](https://quaternius.com) — CC0 models + the Universal
-  Animation Library (v1 and v2 free tiers).
+  Animation Library (v1 and v2 free tiers); most of the catalog is
+  searchable via Poly Pizza.
 - [Poly Haven](https://polyhaven.com) — CC0 textures/HDRIs/models.
-- [Kenney](https://kenney.nl) — CC0 game assets.
+- [Kenney](https://kenney.nl) — CC0 game assets (no file API; manual import).
+- [KayKit](https://kaylousberg.com) — CC0 stylized low-poly packs (city,
+  furniture, dungeon, characters …) on GitHub; integrated in the Asset
+  Browser (disabled by default — below the platform quality bar).
+  Attribution optional; credited with thanks.
+- [Open Source 3D Assets](https://opensource3dassets.com) — keyless CC0
+  registry (Polygonal Mind collections); integrated, pending quality review.
+- [Poly Pizza](https://poly.pizza) — low-poly aggregator, CC0/CC-BY
+  (BYO free API key).
+- [Smithsonian 3D Open Access](https://3d.si.edu) — museum scans; only
+  records explicitly marked CC0.
+- [Sketchfab CC0 search](https://sketchfab.com/search?features=downloadable&licenses=cc0&type=models)
+  — download manually (their download API is per-user OAuth with branding
+  terms; deliberately not automated).
+- [The Base Mesh](https://thebasemesh.com) — CC0 base meshes (manual import).
+- [3DTextures.me](https://3dtextures.me) — CC0 stylized materials
+  (manual import).
+- [TextureCan](https://www.texturecan.com) — CC0 textures (manual import).
+- [ShareTextures](https://www.sharetextures.com) — CC0 files, but their
+  platform terms prohibit automated downloads/hotlinking — browse manually
+  only, never wire an adapter.
 - [OpenGameArt](https://opengameart.org) — filter by CC0/CC-BY.
+- [Openverse](https://openverse.org) — openly licensed images/audio
+  (per-record license).
+- [Freesound](https://freesound.org) — sounds; free API tier is
+  non-commercial.
 - [VRoid Hub](https://hub.vroid.com) — VRM avatars (check per-model terms).

package/README.md

@@ -4,8 +4,9 @@ ToonLab by Call Me Sensei is a stylized anime-style game starter kit and
 runtime library for [Three.js](https://threejs.org/). Its goal is to simplify
 Three.js game development: you get a better-looking anime/stylized game
 without having to develop shaders yourself, and procedurally generated assets
-(trees, rocks, grass, water, sky) reduce content complexity so you can focus
-on your core game logic instead. Clone it and a toon-shaded character is
+(trees, rocks, grass) plus integrated procedural world systems (water, sky)
+reduce content complexity so you can focus on your core game logic instead.
+Clone it and a toon-shaded character is
 walking and swimming through a fully stylized world: cel-shaded characters,
 painterly environments, interactive water, procedural vegetation and sky,
 post-processing, and a schema-driven tuning panel. Use it as a starter kit,
@@ -15,8 +16,8 @@ subpath exports per cluster).
 ## Quickstart
 
 **No install** — use the hosted labs at **[toonlab.io](https://toonlab.io)**:
-tune character and environment shaders, design trees and rocks, and export
-presets straight from the browser.
+define character, vegetation, and environment shaders; author stylized assets;
+tune water and sky systems; and export portable presets from the browser.
 
 **As a library** in your own Three.js app:
 
@@ -35,30 +36,77 @@ npm run dev
 Vite serves the labs at `http://localhost:5175`. See
 [Getting started](docs/getting-started.md) for a tour.
 
+**Building with an AI coding agent?** That is the fastest path through all of
+this — see [Build with an AI coding agent](#build-with-an-ai-coding-agent)
+for the recommended setup (skills + MCP) and ready-to-paste starting prompts.
+
+### Local MCP server
+
+Running the labs locally also creates a disk-backed `.toonlab/` workspace
+shared by the browser tools and the included MCP server. Open
+`http://localhost:5175/settings/` for a checkout-specific configuration you
+can paste into an MCP-compatible coding tool.
+
+```bash
+npm run dev
+# In an MCP client, use the command/config shown at /settings/.
+```
+
+The local server can search the built-in procedural catalog and public CC0
+sources, read your saved presets and exported files, generate seeded recipes,
+and import assets into the project. It uses stdio, requires no account or
+OAuth, and keeps work on disk. See [Local MCP and workspace](docs/mcp.md).
+
 ## The labs
 
-Runnable demos in `labs/` (not published to npm). Switch between them with
-the HUD Scene select:
-
-- **Shader Lab** (`/`) — character + environment shader tuning: every toon
-  and environment setting as a live control, preset export/import, debug
-  views.
-- **Playground** (`/playground/`) — third-person character controller
-  in gameplay scenes: calm lake, river crossing, ocean beach with breaking
-  waves, and an indoor room. Walk, jump, swim, splash.
-- **Rock Lab** (`/rock-lab/`) — procedural stylized rocks, cliffs,
-  heightfields, sculpt edits, and GLB export.
-- **Tree Lab** (`/tree-lab/`) — procedural stylized trees,
-  flowers, sketches, recipes, and GLB export.
-- **Outdoor World** (`/examples/outdoor-world/`) — the flagship example: a
-  seeded 1×1 km open world built entirely from the public library API —
-  generated terrain, forests, lakes, cliffs, a swimmable character, and a
-  click-to-travel minimap. Re-roll it from the URL:
-  `?seed=42&archetype=lakeland&water=0.4&islands=3`.
-
-Every URL parameter has a HUD control, lab state persists per lab in
-`localStorage`, and **Reset Lab** clears it. Point any lab at your own model
-with the Model URL input or `?model=` — see
+Lab UIs are development tools and are not published in the npm package. The
+Labs home (`/`) presents them by the artifact they author:
+
+- **Shader Labs** — Character Shader Lab (`/shader-lab/`), Vegetation Shader
+  Lab (`/vegetation-shader-lab/`), and Environment Shader Lab
+  (`/environment-lab/`) each save one reusable IP-wide material treatment.
+- **Asset Labs** — Rock, Tree, Flower, Grass, Debris, and Texture Labs author
+  geometry, material data, recipes, and exports for individual asset classes.
+  Grass color palettes coordinate base, tip, and shadow tint as one set.
+- **World Systems** — Water Lab (`/water-lab/`) authors waves, surface
+  shading, foam, reflections, interaction, and quality as one runtime preset;
+  Sky Lab (`/sky-lab/`) authors the gradient, sun, clouds, stars, and cloud
+  motion as one runtime preset. Their shader controls are embedded in the
+  complete system labs rather than duplicated as separate shader labs.
+- **Playgrounds & demos** — Playground, Water Playground, Outdoor World, VFX
+  Arena, Fauna Demo, and Ambient VFX Demo validate the authored artifacts in
+  interactive scenes.
+
+Supporting editors remain available by direct URL: Weather Lab
+(`/weather-lab/`) coordinates current atmosphere, wind, precipitation,
+lightning, and surface state; Lighting Lab (`/lighting-lab/`) authors light
+rigs and budgets; Gallery
+(`/gallery/`) searches supported open-asset sources. The procedural Catalog
+is exposed through `@call-me-sensei/toonlab/catalog`. See
+[Lab responsibilities](docs/lab-architecture.md) for the scope rules and
+[Getting started](docs/getting-started.md) for every direct route.
+
+Sky and Water are integrated runtime systems, not extra Shader Labs. Their
+`.settings` are authored preset data; current Lighting and Weather state is
+composed through named transient layers and exposed as `.renderedSettings`
+without changing exported presets. Create a `LightingSystem`, then call
+`lighting.attachWorld(world)` to own the Lighting layers and connect the
+world's Weather coordinator as modulation, so each system can detach only its
+own layer. The shared `world.setSun({ direction, color, sky })` adapter keeps
+the physical light/shadows, vegetation scene inputs, Sky, and Water aligned;
+Weather captures and restores every transient baseline it drives. Sky presets contain exactly 46
+portable art fields; dome radius and compile-time quality stay outside the
+document. Sky provides low/medium/high cloud graphs plus custom 1–5-octave
+quality and can rebuild its material with `setQuality()`. Water quality is a
+construction-time graph choice; switching it requires replacing/rebuilding
+the surface rather than calling `applySettings()`.
+
+Every URL parameter has a HUD control. In local development, lab state is
+mirrored into `.toonlab/` so the MCP server and browser share it; existing
+`localStorage` and IndexedDB data migrate on first run. Static hosted builds
+fall back to browser storage. **Reset Lab** clears the current lab state.
+Point any model-aware lab at your own model with the Model URL input or
+`?model=` — see
 [Characters](docs/characters.md).
 
 ## What's inside
@@ -67,14 +115,30 @@ with the Model URL input or `?model=` — see
 |---|---|---|
 | Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](docs/toon-shading.md) |
 | Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](docs/environment.md) |
-| Water | `@call-me-sensei/toonlab/water` | Fully procedural interactive water: Gerstner wave stack with a calm→storm dial, wave sets, plunging breakers you can surf, three-stop absorption color, refraction/caustics/foam, GPU ripple sim, splashes, wakes, rain, kelp, underwater view — with a CPU mirror of the whole spectrum for buoyancy. [Docs](docs/water.md) |
-| Vegetation | `@call-me-sensei/toonlab/vegetation` | Instanced grass and flower fields (wind, push-away, scene + cloud shadows, backlit translucency) and procedural stylized trees with a serializable recipe system. [Docs](docs/vegetation-sky.md) |
-| Sky | `@call-me-sensei/toonlab/sky` | Procedural gradient/sun/painterly-cloud/star dome that also shows up in water reflections. [Docs](docs/vegetation-sky.md) |
+| Lighting | `@call-me-sensei/toonlab/lighting` | Versioned lighting recipes and looks, physical/artistic intensity helpers, reusable luminaire/rig/look/quality presets, deterministic light and shadow budgets, capability diagnostics, runtime Three.js realization, and a data-only Unreal Engine 5.8 MegaLights/Lumen handoff. [Docs](docs/lighting.md) |
+| Weather | `@call-me-sensei/toonlab/weather` | Shared cross-system weather coordinator with 22 presets, smooth transitions, one-draw GPU precipitation (rain, snow, sleet, hail, dust), lightning/thunder events, and normalized wetness/snow/ice outputs. It drives sky, sun, fog, cloud shadows, wind, vegetation, water, fauna, and ambient effects through their public adapters. [Docs](docs/weather.md) |
+| Water | `@call-me-sensei/toonlab/water` | Fully procedural integrated water system: Gerstner wave stack with a calm→storm dial, wave sets, plunging breakers you can surf, three-stop absorption color, refraction/caustics/foam, GPU ripple sim, splashes, wakes, rain, kelp, underwater view, construction-time quality, and a CPU mirror of the whole spectrum for buoyancy. [Docs](docs/water.md) |
+| Vegetation | `@call-me-sensei/toonlab/vegetation` | Instanced grass and flower fields, procedural trees/flowers with serializable recipes, coordinated grass palettes (base, tip, and shadow tint), and one semantic-role `VegetationShaderProfile` shared across grass, foliage, flowers, bark, and stems. Asset identity and current wind/weather remain separate. [Docs](docs/vegetation-sky.md) |
+| Paths, roads & bridges | `@call-me-sensei/toonlab/pathgen` | Seeded path networks routed over any `heightAt`: cost-field router (slope/water aware), hand-drawn ribbon overlay in dirt/stone/planks, arched plank bridges with collision, stepped stone climbs, flattened `paths.heightAt` for walkability, scatter exclusion mask, minimap overlay. |
+| Asset placement | `@call-me-sensei/toonlab/propgen` | The universal placement pipeline (the PropAsset contract: grounded, collided, instanced, hi/lo LOD by true 3D distance). `propAssetFromObject` drops any imported GLB — e.g. a CC0 model found through MCP — into the pipeline. |
+| Fauna | `@call-me-sensei/toonlab/fauna` | Instanced GPU-animated ambient creatures: flocking birds that perch and flush, butterflies over flower masks, hovering dragonflies, schooling koi — staggered boids, hard population budgets, ≤ 1 ms CPU at defaults. |
+| Ambient VFX | `@call-me-sensei/toonlab/ambientfx` | One GPU particle backbone, five effects: falling petals and leaves, dusk fireflies, backlit pollen, shoreline mist — follow-window emission, shared wind with grass, time-of-day gates, 3 draw calls total. |
+| Asset catalog | `@call-me-sensei/toonlab/catalog` | Every recipe/preset as a searchable manifest with one headline call: `catalog.spawn(id, { seed })` → a placeable PropAsset for trees, rocks, and debris. `catalog.addSource(url)` mounts remote registries. |
+| Sky | `@call-me-sensei/toonlab/sky` | Integrated gradient/sun/painterly-cloud/star system with exactly 46 portable art fields, named live scene layers, compile-time quality tiers/custom 1–5 cloud octaves, meaningful built-in looks, and water-reflection compatibility. [Docs](docs/sky.md) |
 | Post-processing | `@call-me-sensei/toonlab/post` | Optional single-pipeline compositor: character-aware bloom, color grade, LUT, vignette, screen outline, depth cue — schema-driven, preset-serializable. [Docs](docs/post-processing.md) |
+| Camera | `@call-me-sensei/toonlab/camera` | Extensible camera operator stack, generated recipe/preset documents, follow/framing/collision/damping/noise/impulse behavior, and a director for blending reusable rigs. [Style domain docs](docs/style-labs.md#camera) |
+| Game feel | `@call-me-sensei/toonlab/game-feel` | Event-driven response scheduler for camera punches, hit-stop/time warp, squash, flashes, audio, and haptics through capability-safe adapters, extensible effect factories, and bounded concurrency. [Style domain docs](docs/style-labs.md#game-feel) |
+| Procedural textures | `@call-me-sensei/toonlab/texgen` | Seamless CPU-baked PBR texture generator: 25 tileable pattern/noise generators, layered detail + colored overlays (moss, rust, grime), five-stop cel-capable color ramp, cavity/sheen hand-painted read, derived normal/AO/roughness/metalness/height/ORM/emissive maps, 60+ presets, and a natural-language recipe mapper (offline keywords or BYO-key Gemini/OpenAI). [Docs](docs/texture-lab.md) |
 | Character pipeline | `@call-me-sensei/toonlab/character` | Bone-role adapters for VRM/MMD/Mixamo/Rigify rigs, native-clip conventions, Mixamo retarget helpers, and a procedural freestyle swim clip. [Docs](docs/characters.md) |
 | Model loaders | `@call-me-sensei/toonlab/loaders` | Optional GLB/glTF, VRM 0+1, PMX/PMD, FBX, OBJ, and text-USDZ loading helpers. Kept off the root import so apps that do not load models avoid loader dependencies. [Docs](docs/characters.md) |
 | Debug panel | `@call-me-sensei/toonlab/debug` | One-line schema-driven tuning GUI for any settings module — the same panel the labs use. [Docs](docs/debug-panel.md) |
 
+The main `vegetation` barrel exposes the complete runtime. Smaller consumers
+can import the same bindings from
+`@call-me-sensei/toonlab/vegetation-shaders` or
+`@call-me-sensei/toonlab/grass-palettes`; package verification asserts that
+the focused subpaths and root export reference the identical implementations.
+
 Zero texture assets in the library: water, sky, grass, flowers, trees, and
 splashes are all procedural. The one bundled model is a CC0 mannequin with 45
 embedded animation clips.
@@ -101,6 +165,7 @@ const world = await createStylizedWorld({
   renderer, scene, camera,
   terrain: { heightAt: terrain.heightAt, root: terrainRoot, size: terrain.meshExtent },
   water: { level: terrain.waterLevel },
+  weather: { preset: 'call_me_sensei' }, // 'snow' | 'hail' | 'thunderstorm' | ...
   followTarget: character, // your character root (optional): splashes, wakes, grass push
 });
 character.position.copy(terrain.spawn); // probed: walkable, near a shore
@@ -168,13 +233,27 @@ stack, with WebGL2 fallback through the same TSL path.
 
 ## Documentation
 
+- **In-browser docs** — with the labs running (`npm run dev`), open
+  `http://localhost:5175/docs/` for guided documentation: library usage,
+  MCP setup, the prompt cookbook, and the full settings reference. Hosted
+  features are marked "Pro"; the extended hosted docs live at
+  [toonlab.io/docs](https://toonlab.io/docs).
+- [Lab responsibilities](docs/lab-architecture.md) — the boundary between
+  Shader Labs, Asset Labs, World Systems, and preview-only scene state.
 - [Getting started](docs/getting-started.md) — clone, run, tour the labs,
   load your own models.
 - [Toon character shading](docs/toon-shading.md)
 - [Environment shading](docs/environment.md)
+- [Lighting](docs/lighting.md)
+- [Weather system](docs/weather.md)
+- [Generative style labs](docs/style-labs.md) — Post & Color, Camera, Motion,
+  UI Theme, Biome, Soundscape, and Game Feel; shared recipes, MCP authoring,
+  package runtimes, quality budgets, and engine design references.
 - [Water](docs/water.md)
-- [Vegetation and sky](docs/vegetation-sky.md)
+- [Sky system](docs/sky.md)
+- [Vegetation](docs/vegetation-sky.md)
 - [Post-processing](docs/post-processing.md)
+- [Texture Lab and texgen](docs/texture-lab.md)
 - [Characters and animation](docs/characters.md)
 - [Debug panel](docs/debug-panel.md)
 - [World scale and world presets](docs/world-scale.md) — the meters
@@ -185,11 +264,129 @@ stack, with WebGL2 fallback through the same TSL path.
 - [Shader constants](docs/shader-constants.md) — the deliberately unexposed
   constants and where they live.
 
-## AI coding agents
+## Build with an AI coding agent
+
+ToonLab is designed to be driven by a coding agent (Claude Code, Codex,
+Cursor, …). The recommended setup has three parts: give the agent the ToonLab
+skills, connect an MCP server for asset discovery, then start from a goal
+prompt and iterate. Everything the agent needs ships in this repo under
+`agents/` (not in the npm package — the package stays runtime-only).
+
+### 1. Install the ToonLab skills in your game project
+
+The skills teach the agent the assembly order, the frame-loop contract, and
+each subsystem's API so it wires ToonLab correctly on the first try. Start
+with `game-dev`; the other twelve cover individual features (water, weather,
+lighting, camera, game feel, …).
+
+```bash
+# Claude Code — feature skills + project guidance
+mkdir -p .claude/skills
+cp -R path/to/toonlab/agents/skills/claude/* .claude/skills/
+cat path/to/toonlab/agents/codex/AGENTS.md >> CLAUDE.md
+
+# Codex — shared guide + Codex-oriented skills
+cat path/to/toonlab/agents/codex/AGENTS.md >> AGENTS.md
+cp -R path/to/toonlab/agents/skills/codex path/to/your-game/docs/toonlab-skills
+
+# Cursor — rule file
+mkdir -p .cursor/rules
+cp path/to/toonlab/agents/cursor/toonlab.mdc .cursor/rules/
+```
+
+See [`agents/README.md`](agents/README.md) for the full layout.
+
+### 2. Connect MCP for asset discovery
+
+Two servers, and they compose:
+
+**Local (free, no account).** The stdio server included in this package
+searches the built-in procedural catalog and public CC0 sources, reads your
+saved presets and lab exports, generates seeded recipes, and imports assets
+into a disk-backed `.toonlab/` workspace:
+
+```json
+{
+  "mcpServers": {
+    "toonlab-local": {
+      "command": "npx",
+      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"]
+    }
+  }
+}
+```
+
+If you run the labs from a checkout (`npm run dev`), open
+`http://localhost:5175/settings/` for a ready-made config instead. See
+[Local MCP and workspace](docs/mcp.md).
+
+**ToonLab Pro (remote, OAuth).** [toonlab.io](https://toonlab.io) hosts a
+remote MCP server that adds an indexed CC0 asset search with ToonLab-styled
+previews, AI generation (concept art, seamless textures, image→3D model
+chaining) on credits, stored characters with reference-image consistency, and
+your cloud library of presets and style bundles. Requires a Pro or Team plan.
+
+```bash
+# Claude Code
+claude mcp add --transport http toonlab https://toonlab.io/mcp
+```
+
+Other clients: add `https://toonlab.io/mcp` as a remote MCP server and
+authorize in the browser. Full client-by-client setup and a tool reference
+live at [toonlab.io/docs/mcp](https://toonlab.io/docs/mcp).
+
+### 3. The first prompt
+
+Give the agent a goal, name the skill, and let it verify its own work:
+
+```text
+Using the ToonLab game-dev skill, set up a new Three.js + Vite project with
+@call-me-sensei/toonlab. Build a 1 km seeded open world (archetype
+"lakeland") with the bundled toon-shaded mannequin as the playable character,
+water, sky, the "call_me_sensei" weather preset, post-processing, and a
+follow camera with game feel. Follow the skill's assembly order and
+frame-loop contract, then run the dev server and fix issues until I can walk
+from spawn to the shoreline and swim.
+```
+
+### 4. Prompts for common jobs
+
+```text
+Use the ToonLab MCP server to find CC0 props for a small fishing village —
+lanterns, crates, a pier, a torii gate — then place every import with
+propAssetFromObject so they are grounded, collided, and LOD'd. Tell me what
+came from where with licenses.
+```
+
+```text
+Using the ToonLab water skill, make the ocean stormier as the player sails
+away from shore, and let them surf the plunging breakers near the reef.
+```
+
+```text
+Generate a seamless mossy stone texture with texgen and apply it to the
+shrine path. I want a hand-painted look with a five-stop cel ramp.
+```
+
+```text
+Using the ToonLab weather + lighting skills, add a day/night cycle with a
+thunderstorm that rolls in at dusk: wind picks up in the grass, rain streaks
+the water, lightning drives the sky and light rig.
+```
+
+```text
+Search my ToonLab library for the "sunset-festival" style bundle and apply
+it across toon shading, sky, water, and post so the whole game matches it.
+```
+
+```text
+Give the sword swing anime game feel: hit-stop, a camera punch, a trail
+ribbon and impact sparks from vfxgen, and a white flash on hit.
+```
 
-The GitHub repo includes downloadable runtime-usage guidance for Codex, Claude
-Code, Cursor, and other coding agents under `agents/`. These files help
-developers use ToonLab in their own apps and are not part of the npm package.
+A more extensive prompt cookbook — including the Pro generation and
+character-consistency workflows — is at
+[toonlab.io/docs/prompts](https://toonlab.io/docs/prompts).
 
 ## License