Skip to content

Official Codebase of 3DCodeVerse

Python

skills: the scene-graphics recipe port — atmosphere, water, night, materials (R25-R28)

gaoypeng7797b375d236
diff --git a/harness/codeverse/skills/cv3d-scene-atmosphere/SKILL.md b/harness/codeverse/skills/cv3d-scene-atmosphere/SKILL.md
new file mode 100644
index 00000000..67cfba4b
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-atmosphere/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: cv3d-scene-atmosphere
+description: "Use when a scene_threejs env, baseline or refine session builds the sky, the environment map, clouds or fog. The sky is not a backdrop: it is the light source every PBR material reflects. Gives the sky-dome shader, the equirect bake that turns it into scene.environment (with the one-line orientation bug that blackens water), the cloud recipes that read in a still frame, and the fog numbers that add depth instead of eating the scene."
+license: Apache-2.0
+compatibility: three r0.182, headless WebGL; renderer fixed at ACES Filmic tone mapping, exposure 1.0, sRGB output.
+metadata:
+ evidence: inherited-unverified
+ evidence_note: 'Recipes ported 2026-09-01 from the scene_multifile_graphics reference harness, where they carry measured origins: its audit found the equirect bake INVERTED in 4 of 9 delivered scenes (a Venice canal at patch RGB 35,27,18 went to 100,87,43 by flipping one line), and its PMREM note is from three.js source (cube size = width/4). Not yet A/B-validated on this harness; the sceneloop battery attaches our own numbers.'
+ verified: "2026-09-01"
+ target_metric: "env_bake_orientation_flags"
+ target_direction: "down"
+ target_unit: "inverted bakes per run (prospective census)"
+ target_measurable: "false"
+ target_baseline: "n=0 — no measured runs yet (2026-09-01); the sceneloop A/B battery sets it"
+---
+
+# Sky, environment and air — the frame's light source comes first
+
+Build the sky BEFORE any PBR material exists. `scene.environment` is what makes
+metal, glass, water and wet ground live; a scene assembled first and skied later
+has every reflective surface already born dead.
+
+## The sky dome
+
+A big sphere, `side: THREE.BackSide`, `depthWrite: false`, named `Sky`, with a
+ShaderMaterial over the view direction `d = normalize(vWorldPos)`:
+
+```glsl
+vec3 col = mix(horizonColor, zenithColor, pow(clamp(d.y, 0., 1.), 0.6));
+float sunAmt = max(dot(d, sunDir), 0.0);
+col += hazeColor * pow(sunAmt, 8.0) * 0.25; // mie halo
+col += sunColor * smoothstep(0.9993, 0.9998, sunAmt); // sun disk
+col = mix(col, horizonColor, pow(1.0 - clamp(d.y, 0., 1.), 8.0)); // haze band
+```
+
+* Sunset: sun low (`sunDir.y` around 0.1), horizon orange/rose, widen the halo
+ (`pow(sunAmt, 4.0) * 0.6`).
+* Night: zenith around #050a18, horizon #0d1626; stars by hashing the direction
+ (`vec3 c = floor(d*300.); step(0.9985, hash(c.xy + c.z))`, vary brightness);
+ a moon disk shaded with fbm and ONE slate-blue DirectionalLight.
+
+## Bake the SAME sky into `scene.environment`
+
+Mirror the sky function in JS and bake it into an equirect `DataTexture`, then
+`scene.environment = tex`. Rules that are bugs when broken:
+
+* **256x128 or larger.** three derives its PMREM cube size as `width / 4`; a
+ 64x32 bake gives 16-pixel cube faces — technically valid, visually useless.
+* **Bake WITHOUT the sun disk** — the disk doubles every specular highlight.
+* `tex.mapping = THREE.EquirectangularReflectionMapping;`
+ `tex.colorSpace = THREE.SRGBColorSpace;`
+* **The orientation bug that blackens water**: three samples v = 1 at the
+ ZENITH, and a `DataTexture` defaults to `flipY = false`, so ROW 0 IS STRAIGHT
+ DOWN. Fill with `const v = 1 - y / h;` (theta = v * PI from the zenith).
+ Inverted, the ground half sits where the sky belongs and every reflective
+ surface mirrors the dark half — the reference harness found this in 4 of 9
+ delivered scenes; its canal went from near-black to green-with-sun by
+ flipping that single line.
+* Keep dome and bake the same function, and paint the cloud shapes faintly into
+ the bake too, so reflections agree with the sky the camera sees.
+
+## Clouds that read in a still frame
+
+Billboard sprite puffs beat everything else per token:
+
+* ONE shared CanvasTexture: 4-8 overlapping white radial gradients on 128 px.
+* Per cloud: 6-15 `THREE.Sprite`s in a flattened ellipsoid (x-spread 2-3x the
+ y), scales 8-25 m, opacity 0.35-0.7, bottoms tinted darker,
+ `depthWrite: false`.
+* Overcast / cirrus: 1-3 huge planes at altitude with
+ `alpha = smoothstep(.5, .75, fbm(uv * k + t * dir))`, kept well above every
+ camera.
+* Raymarched volumetrics only when clouds ARE the subject of the brief.
+
+## Fog adds depth or eats the scene — nothing in between
+
+`FogExp2` density 0.002-0.01 outdoors, always in the sky's hue family. Fog that
+softens the far hills sells the depth; fog that hides the mid-ground kills the
+frame, and the frame gate reads it as washed out. The shader-trap skill covers
+the fog uniforms custom shaders must honour; this one only sets the numbers.
+
+## Order of operations
+
+1. Sky dome + sun direction. 2. JS mirror -> equirect bake ->
+`scene.environment`. 3. Lights (see cv3d-scene-lighting). 4. Only THEN
+materials, water, assets — they are all downstream of the environment.
+
+## Verify before you finish
+
+Render one frame and look at a reflective surface: water or glass mirroring a
+BRIGHT sky half means the bake is upright; mirroring darkness at midday means
+row 0 went to the zenith. `references/exotic-space.md` holds the validated
+black-hole / nebula / planet recipes for space briefs.
diff --git a/harness/codeverse/skills/cv3d-scene-atmosphere/references/exotic-space.md b/harness/codeverse/skills/cv3d-scene-atmosphere/references/exotic-space.md
new file mode 100644
index 00000000..b6e79e33
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-atmosphere/references/exotic-space.md
@@ -0,0 +1,58 @@
+# Exotic space recipes (black hole, wormhole, nebula, planet)
+
+Ported 2026-09-01 from the scene_multifile_graphics reference ledger; the black
+hole recipe was validated live there (mf36_blackhole, 2026-07-29) including two
+measured failure modes quoted below. Everything is raw three.js + GLSL.
+
+## Black hole — one shader, not meshes
+
+Scene-graph rings read as neon toys. The Interstellar look is ONE
+ShaderMaterial on a shell — `SphereGeometry(2.5 * r_out)`, `side: BackSide`,
+`transparent: true`, `depthWrite: false` — centred on the hole, raymarched in
+the fragment shader with bent rays. Camera-independent: ray origin from the
+built-in `cameraPosition` uniform.
+
+* FAST-FORWARD the ray to the hole first — `float toHole = dot(-ro, rd);
+ ro += rd * max(0.0, toHole - 1.5 * r_out);` — or a distant camera exhausts
+ the step budget before the disk and the hole renders as a bare ring
+ (steps x dt must exceed ~3x r_out of REMAINING path, never camera distance).
+* Step 30-40 times: `vec3 g = -p * strength / pow(dot(p,p), 1.5);
+ rd = normalize(rd + g*dt); p += rd*dt;`
+* Disk accumulation wherever the bent ray crosses the equatorial plane inside
+ [r_in, r_out]: temperature ramp white-hot -> orange -> deep red by radius,
+ x azimuthal fbm streaks sheared Keplerian (`phi + t / pow(r, 1.5)`),
+ x Doppler boost `1.0 + 0.6 * dot(diskTangent, -rd)`.
+* Sample the disk as a THIN SLAB, not only on sign crossings:
+ `bool crossed = (pn.y > 0.) != (p.y > 0.); bool inSlab = abs(pn.y) < 1.5;`
+ accumulate on either (slab samples weighted ~0.22). Crossing-only sampling
+ makes the disk VANISH edge-on — rays parallel to the plane never flip sign
+ (measured live in the reference run).
+* Rays spiralling inside ~1.4 r_s terminate BLACK with alpha 1 — the shader
+ paints its own shadow; remove any solid black sphere mesh or it occludes the
+ fold. Scale `dt ~ r_out / 20` so ~90 steps cross the shell (a dt tuned on a
+ small test hole renders a big one invisible).
+* The far-side fold over/under the horizon and the photon ring come free from
+ the bending — never model them as geometry. Background lensing: the
+ starfield sphere's fragment offsets its sample direction toward the hole by
+ `strength / b2` outside the shadow radius.
+
+## Wormhole
+
+Camera-facing open `TubeGeometry` along a curved spine (`side: BackSide`),
+polar-uv fbm palette scrolling toward the far end, bright rim at the mouth,
+radial streaks converging inward; a DIFFERENT star pattern visible through the
+throat is what sells it.
+
+## Nebula and starfield
+
+10-30 large additive fbm-canvas billboards (alpha = fbm^2, magenta/cyan/orange)
+plus a few near-black NORMAL-blended dust-lane sprites. Starfield: `Points`
+5-10k with power-law brightness (`pow(rand(), 3.0)`), slight colour spread,
+3-5 hero stars with cross-flare sprites.
+
+## Planet
+
+Sphere with canvas-baked fbm continents + bumpMap; atmosphere rim = 1.03x
+sphere, `side: BackSide`, additive fresnel (`pow(1. - dot(N, V), 3.5)`); cloud
+shell at 1.01x. Space background is never pure #000 (additive blending clips) —
+use #020208.
diff --git a/harness/codeverse/skills/cv3d-scene-materials/SKILL.md b/harness/codeverse/skills/cv3d-scene-materials/SKILL.md
new file mode 100644
index 00000000..171716ea
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-materials/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: cv3d-scene-materials
+description: "Use in every scene_threejs build or refine session that authors surfaces - terrain, buildings, props, vegetation. The strongest 'plastic toy' tell is a flat albedo; the second is identical twins. Gives the photographic checklist: procedural variance on every large surface, per-instance jitter, roughness as the realism dial, bevels near the camera, the tight shadow camera, domain-warped terrain with banded colour, and scatter that is intentional instead of uniform."
+license: Apache-2.0
+compatibility: three r0.182, headless WebGL; ACES tone mapping, GTAO + soft bloom supplied by the renderer.
+metadata:
+ evidence: inherited-unverified
+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger (its 18-reviewer audit of 137 scenes; flat walls and duplicated assets are among its most-cited defects, and trees/rocks its two weakest measured classes). Not yet A/B-validated here; the sceneloop battery attaches our numbers.'
+ verified: "2026-09-01"
+ target_metric: "flat_albedo_surfaces"
+ target_direction: "down"
+ target_unit: "large surfaces with zero value variance (prospective census)"
+ target_measurable: "false"
+ target_baseline: "n=0 — no measured runs yet (2026-09-01); the sceneloop A/B battery sets it"
+---
+
+# Surfaces that read as a place, not a render
+
+The renderer supplies ambient occlusion, soft bloom and ACES tone mapping.
+What still separates a photograph from a toy is AUTHORED: material variance
+and light contrast.
+
+## Never ship a flat albedo
+
+One constant `color` per large surface is the strongest plastic tell. Give
+every large surface a subtle procedural map: a CanvasTexture of low-contrast
+fbm (use the shared noise block from cv3d-scene-water) as `map` multiplied
+into the tint, or as `roughnessMap`; `repeat` scaled so one texel is 2-5 cm at
+walking distance. Stone, plaster, soil and wood all read instantly better with
+5-15% value noise.
+
+## Vary per instance
+
+Copies of one asset get +-6% hue and +-10% lightness jitter — clone the
+material once per VARIANT, not per instance — plus scale 0.7-1.3, random
+Y-rotation and a tiny tilt. Identical twins read as duplicated geometry;
+slight variance reads as a place.
+
+## Roughness is the realism dial
+
+Real surfaces are rarely uniform. Working numbers: wet stone 0.25, dry stone
+0.85, painted wood 0.6, weathered wood 0.9, glass 0.05 with `envMapIntensity`
+1.5, brushed metal 0.35 with metalness 0.8, foliage 0.75 with slight sheen.
+Push a `roughnessMap` (same noise) so highlights break up instead of forming
+perfect ovals.
+
+## Bevel what the camera approaches
+
+Razor 90-degree edges catch light unnaturally and read as CAD. Anything within
+a few metres of a camera gets `ExtrudeGeometry` with `bevelEnabled` or an
+equivalent chamfer. Background boxes can stay sharp.
+
+## Terrain that is landscape, not noise blob
+
+Heightfield: `PlaneGeometry(W, D, N, N)` displaced by 5-octave fbm with DOMAIN
+WARP and a power curve — that pair is what separates hills from static:
+
+```js
+const y = Math.pow(fbm(x + 30 * fbm2(x * .008, z * .008), z), 1.6);
+```
+
+Recompute vertex normals AFTER displacing. Colour by slope and height bands
+via vertexColors: rock where `normal.y < 0.65`, else sand -> grass -> rock ->
+snow with smoothstep blends and +-5% hue jitter — never one flat green.
+
+## Scatter intentionally
+
+Uniform random scatter reads as noise. Jittered grid (spacing = the mean
+distance you want, +-40% jitter), times a clump mask so groves and clearings
+form (threshold the shared low-frequency noise at 0.5), times slope/height
+rejection. Every instance: y from the SHARED height function, sunk 0.1 m so nothing
+hovers on a blade of grass — the placement gate measures floaters.
+
+## The tight shadow camera
+
+One key light (sun) at intensity 2.5-4 with `castShadow`, a dim
+`HemisphereLight` 0.3-0.6 fill with a ground-bounce colour, and no third light
+without a reason. Then TIGHTEN `light.shadow.camera.left/right/top/bottom` to
+the extent the cameras can actually see, `mapSize` 2048-4096: a shadow map
+stretched over two kilometres has metre-wide pixels and every shadow is mush.
+
+## Ground the frame
+
+A low, wide gradient patch of darker ground colour under big structures, plus
+the slight darkening where verticals meet the ground, anchors everything the
+AO pass does not reach.
+
+## Verify before you finish
+
+Zoom one frame to a large wall or the terrain: if the surface is one flat
+value, it needs the noise map. Find two copies of the same asset: if you
+cannot tell them apart, jitter is missing. Look at one shadow edge: mush means
+the shadow camera is too wide.
diff --git a/harness/codeverse/skills/cv3d-scene-materials/references/terrain-and-scatter.md b/harness/codeverse/skills/cv3d-scene-materials/references/terrain-and-scatter.md
new file mode 100644
index 00000000..22241d25
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-materials/references/terrain-and-scatter.md
@@ -0,0 +1,48 @@
+# Terrain and scatter — the deeper cut
+
+## Domain warp, in full
+
+Plain fbm terrain reads as static. Warping the INPUT coordinates by another
+noise breaks the isotropy into ridgelines and valleys:
+
+```js
+function height(x, z) {
+ const wx = x + 30 * fbm(x * 0.008, z * 0.008);
+ const wz = z + 30 * fbm(x * 0.008 + 100, z * 0.008 + 100);
+ return Math.pow(fbm(wx * 0.02, wz * 0.02), 1.6) * H_MAX;
+}
+```
+
+* The warp amplitude (30) is in METRES — scale it with the scene.
+* The power curve (1.6-2.2) flattens lowlands and steepens peaks; without it
+ everything is rolling dough.
+* This function is THE height authority: terrain mesh, water shoreline, every
+ scattered instance's y, and building foundations all call it. Two height
+ sources = floating trees, drowned paths (the placement gate measures both).
+
+## Colour bands with jitter
+
+Vertex colours, blended by smoothstep over height with a slope override:
+
+ slope: normal.y < 0.65 -> rock gray
+ height < shore + 1 -> wet sand
+ < treeline -> grass (hue-jittered +-5%)
+ < snowline -> rock
+ else -> snow
+
+Jitter every band's colour per-vertex by a high-frequency noise at +-5% value;
+band edges get a 2-4 m smoothstep overlap, never a hard line.
+
+## Scatter masks
+
+Three multiplied gates, in order of visual weight:
+
+1. Clump mask: low-frequency noise thresholded at ~0.5 — groves and clearings.
+2. Slope rejection: no trees where normal.y < 0.75; no rocks on cliffs
+ steeper than ~55 degrees (they roll off in the viewer's head).
+3. Jittered grid: spacing = target mean distance, +-40% uniform jitter — the
+ Poisson look without the Poisson cost.
+
+Per instance: y from the height authority sunk 0.1 m, random Y rotation, scale
+0.7-1.3, tilt up to ~4 degrees along the slope normal, hue/lightness jitter
+from the materials checklist. InstancedMesh for anything over ~40 copies.
diff --git a/harness/codeverse/skills/cv3d-scene-motion/SKILL.md b/harness/codeverse/skills/cv3d-scene-motion/SKILL.md
index c9abd6c2..15789bdd 100644
--- a/harness/codeverse/skills/cv3d-scene-motion/SKILL.md
+++ b/harness/codeverse/skills/cv3d-scene-motion/SKILL.md
@@ -187,6 +187,24 @@ move the mover into frame. Do not ship on the strength of having written the
code — and if nothing at all moved, run `scene_probe` first: a frozen scene is
more often a thrown `update` than a small amplitude.
+## People, vehicles, weather
+
+* **A walking figure**: hierarchy person -> hips -> legs, torso -> arms,
+ pivots AT the joints, posed from t: `ph = t*3.2 + seed*6.283;
+ legL.rotation.x = sin(ph)*0.6; legR = -legL;` arms opposite-phase at 0.4x;
+ bob hips by `abs(cos(ph))*0.04`. Per-person seed on phase and speed
+ (+-20%) prevents lockstep; frozen mid-stride reads perfectly.
+* **Paths**: people and vehicles ride a `CatmullRomCurve3` —
+ `getPointAt((t*speed/len + u0) % 1)`, face the tangent; distinct `u0`
+ offsets space the traffic; wheels spin `t*speed/wheelR`.
+* **Rain is streaks, not dots**: `LineSegments` pairs `[p, p+vec3(.1,-1.4,0)]`
+ at opacity 0.3-0.5 — elongation IS the motion cue. Snow: soft-sprite
+ `Points` with per-flake sine sway. Every particle gets a random phase so a
+ frozen frame is mid-motion, never at a synchronized extreme.
+* **Fire additive, smoke normal** — never swap: fire is crossed planes
+ scrolling fbm through a flame mask (`AdditiveBlending`) plus a flickering
+ orange PointLight; smoke is gray soft sprites, NORMAL blending.
+
## Depth
`references/motion_recipes.md` — the sway pivot, the recycling particle field,
diff --git a/harness/codeverse/skills/cv3d-scene-night/SKILL.md b/harness/codeverse/skills/cv3d-scene-night/SKILL.md
new file mode 100644
index 00000000..f97ef8c1
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-night/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: cv3d-scene-night
+description: "Use when a scene_threejs brief says night, dusk, evening, neon, lamplit or moonlit. Night scenes fail two ways: black frames (the gate catches those) and the CHRISTMAS-TREE look - every window a flat glow, light shafts like white tents, twelve competing hues. Gives the emissive-window recipe, glow without postprocessing, fake light pools, the measured shaft opacity, wet-road numbers, and the discipline of two light temperatures."
+license: Apache-2.0
+compatibility: three r0.182, headless WebGL; ACES tone mapping, exposure 1.0.
+metadata:
+ evidence: inherited-unverified
+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger; the shaft-opacity ceiling is its measured finding (a normal-blended shaft at 0.3+ rendered as a solid white tent and buried the scene). Pair with cv3d-scene-lighting, whose linear-vs-hex table is the other half of every night failure. Not yet A/B-validated here; the sceneloop battery attaches our numbers.'
+ verified: "2026-09-01"
+ target_metric: "overbright_shaft_findings"
+ target_direction: "down"
+ target_unit: "solid-reading light shafts per run (prospective census)"
+ target_measurable: "false"
+ target_baseline: "n=0 — no measured runs yet (2026-09-01); the sceneloop A/B battery sets it"
+---
+
+# Night light — few sources, believable glow, no tents
+
+The frame gate stops black frames; this skill is about the opposite failure:
+night scenes lit like a fairground. Real night is ONE or TWO light temperatures
+and a lot of dark. Read cv3d-scene-lighting's linear-vs-hex section first —
+half of "my night scene is black" is an albedo 40x darker than its neighbour.
+
+## Emissive windows (buildings at night)
+
+Per building ARCHETYPE (not per building), one CanvasTexture: dark facade,
+window grid, ~35% of the rects lit warm with jitter, a few TV-blue. Use it as
+`map` AND `emissiveMap`, `emissiveIntensity` 1-2. Emissive does NOT illuminate
+anything else — pair each big lit facade or sign with one dim matching
+PointLight so the street below agrees with the window above.
+
+## Glow without postprocessing
+
+Two layered additive sprites per source: a small bright core plus a large faint
+halo at ~0.15 opacity, both `depthWrite: false`; the bulb mesh itself is
+`MeshBasicMaterial` (a lit bulb does not shade). One sprite reads as a sticker;
+the two-layer stack is what reads as bloom.
+
+## Street lamps — fake the pool, budget the real lights
+
+The pool of light on the ground is an additive radial-gradient disc ON the
+ground plus a faint gradient cone for the shaft. Real `PointLight`s (decay 2)
+are a budget: 4-8 for foreground lamps, no more — WebGL forward lighting costs
+per-fragment per-light, and thirty real lights is both slow and flat.
+
+## Light shafts are barely there
+
+Additive blending, opacity 0.03-0.08, alpha fading along the cone. The
+reference harness measured the failure: a NORMAL-blended shaft at 0.3+ opacity
+renders as a solid white TENT and buries the scene behind it. If the shaft
+reads clearly in a thumbnail, it is too strong.
+
+## Wet road (the night city's best friend)
+
+Near-black road, `roughness 0.12-0.25`, `metalness ~0.8`, and a night
+environment bake whose LOWER half carries the window/neon colours (the road
+mirrors what is above it — see cv3d-scene-atmosphere for the bake). Puddles:
+a few irregular darker planes at `roughness 0.03`. Without the coloured bake
+the wet road has nothing to mirror and just goes black.
+
+## Discipline: two temperatures
+
+Pick 1-2 dominant temperatures — sodium orange + cool white is the classic —
+plus RARE neon accents. Every additional hue divides the frame's coherence.
+The moon is one slate-blue DirectionalLight, not a second sun.
+
+## Verify before you finish
+
+One frame: count the distinct light colours (more than 3 is a fairground);
+check one lamp's ground pool exists; check no shaft reads as a solid; check
+the road mirrors colour, not blackness.
diff --git a/harness/codeverse/skills/cv3d-scene-night/references/window-canvas.md b/harness/codeverse/skills/cv3d-scene-night/references/window-canvas.md
new file mode 100644
index 00000000..185cd755
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-night/references/window-canvas.md
@@ -0,0 +1,24 @@
+# The emissive window canvas — exact construction
+
+One CanvasTexture per building ARCHETYPE. 256x256 canvas:
+
+1. Fill the facade colour first — near-black warm gray (#141210), not #000.
+2. Window grid: compute rows/cols from storey height (~3 m) and window pitch
+ (~1.8 m) so the texture's repeat over the building gives plausible storeys.
+3. Per window rect (inset ~30% of the cell): lit with probability ~0.35.
+ Lit colour: warm white base (#ffd9a0) with per-window jitter of +-8% hue and
+ +-15% lightness; roughly 1 in 12 lit windows TV-blue (#9fc4ff) at lower
+ alpha. Unlit windows: slightly darker than the facade, never pure black.
+4. A faint 1-px sill line under each window sells the relief at distance.
+
+Use the SAME canvas as `map` and `emissiveMap`; `emissiveIntensity` 1-2;
+`roughness` 0.9 on the facade so the windows, not the wall, carry the light.
+
+Pair each large lit facade with ONE dim warm PointLight at street level in
+front of it (intensity ~0.3, decay 2, distance ~2 storeys): emissive maps do
+not light the street, and the missing bounce is what makes fake buildings
+float in the dark.
+
+Distant buildings: skip geometry relief entirely — a box with this texture
+reads correctly past ~80 m. Near buildings: model the ground floor for real
+(doors, awnings) and let the texture carry storeys 2+.
diff --git a/harness/codeverse/skills/cv3d-scene-water/SKILL.md b/harness/codeverse/skills/cv3d-scene-water/SKILL.md
new file mode 100644
index 00000000..e4e1a83e
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-water/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: cv3d-scene-water
+description: "Use when a scene_threejs session builds water in any form - pond, lake, harbor, river, ocean, pool, canal, waterfall or fountain. Water is a dielectric, not a mirror: the single most common water bug is metalness, and the second is an environment bake it has nothing to reflect. Gives the material numbers, the shared noise block that keeps terrain, shoreline and scatter agreeing, the Gerstner ocean, and foam that reads."
+license: Apache-2.0
+compatibility: three r0.182, headless WebGL; ACES tone mapping, exposure 1.0.
+metadata:
+ evidence: inherited-unverified
+ evidence_note: 'Ported 2026-09-01 from the scene_multifile_graphics reference ledger, which shipped the metallic-water mistake once and documented the fix, and whose equirect audit showed dark water is usually the ENVIRONMENT bake, not the water (see cv3d-scene-atmosphere). Not yet A/B-validated here; the sceneloop battery attaches our numbers.'
+ verified: "2026-09-01"
+ target_metric: "metallic_water_planes"
+ target_direction: "down"
+ target_unit: "water materials with metalness above 0.3 (prospective census)"
+ target_measurable: "false"
+ target_baseline: "n=0 — no measured runs yet (2026-09-01); the sceneloop A/B battery sets it"
+---
+
+# Water — a dielectric with something to reflect
+
+Two facts produce almost every convincing water plane: water reflects the
+ENVIRONMENT (build cv3d-scene-atmosphere's bake first), and water is a
+DIELECTRIC — it reflects ~2% head-on and ~100% at grazing angles. That fresnel
+ramp is why real water is dark at your feet and mirror-bright at the horizon.
+
+## The material (lake, harbor, pond, pool)
+
+Flat plane + `MeshPhysicalMaterial`:
+
+* `metalness: 0` and `ior: 1.333` — NON-NEGOTIABLE. Metallic water is a
+ uniformly tinted mirror at every angle: the dirty-chrome-puddle look. Do not
+ raise metalness to "make it reflective"; reflectivity comes from the
+ environment map through the fresnel ramp.
+* `roughness: 0.05-0.15`, base colour a DARK blue-green (the environment
+ supplies the brightness).
+* Motion: a small fbm normal `DataTexture` (RepeatWrapping), scrolled as TWO
+ copies at different scales and directions via `onBeforeCompile` (two layers
+ kill tiling), driven by the shared `uTime`.
+* Bias the water plane ~0.02 BELOW the shore ground, or the shoreline
+ z-fights.
+
+## The shared noise block (one source of truth for height)
+
+Terrain height, water shorelines, foam and scatter masks must AGREE, so ship
+value-noise + fbm ONCE in GLSL and mirror it exactly in JS:
+
+```glsl
+float hash(vec2 p){ return fract(sin(dot(p, vec2(127.1,311.7))) * 43758.5453); }
+float noise(vec2 p){ vec2 i = floor(p), f = fract(p); f = f*f*(3.-2.*f);
+ return mix(mix(hash(i), hash(i+vec2(1,0)), f.x),
+ mix(hash(i+vec2(0,1)), hash(i+vec2(1,1)), f.x), f.y); }
+float fbm(vec2 p){ float v = 0., a = .5;
+ for (int i = 0; i < 5; i++){ v += a * noise(p); p *= 2.03; a *= .5; } return v; }
+```
+
+One height function `h(x, z)` sampled by the terrain mesh, the shoreline foam,
+tree placement and building foundations is the single biggest coherence win a
+scene can buy.
+
+## Shoreline foam beats crest foam
+
+In the water fragment shader, foam from DEPTH against the shared height —
+`1. - smoothstep(0., 1.2, waterLevel - h(x, z))`, multiplied by noise — hugs
+the banks and reads instantly. Crest foam on open water is harder and pays
+less.
+
+## Open ocean — Gerstner, not scrolling normals
+
+ShaderMaterial vertex shader summing 3-4 Gerstner waves:
+`k = 2.*PI/L; f = k*dot(D, p.xz) - sqrt(9.8*k)*t;` displace xz by
+`Q*A*D*cos(f)`, y by `A*sin(f)`. Keep the sum of Q*A*k below 1 (above it the
+crests loop over). Grid 256x256 or denser; get normals by finite-differencing
+the DISPLACED surface, not from the flat plane. Fragment side: fresnel mix to
+the horizon colour (`pow(1. - dot(N, V), 5.)`).
+
+## Waterfall and fountain
+
+Waterfall: a curved plane whose fragment shader scrolls vertical fbm streaks,
+thresholded to white over translucent blue; mist is a cluster of soft sprites
+at the base. Fountain: `THREE.Points` where each particle's position is a pure
+ballistic arc of `fract(seed + t * rate)` — frozen mid-flight it still reads.
+
+## Verify before you finish
+
+One rendered frame: water should be DARKER looking straight down than toward
+the horizon (fresnel working), and it should carry the sky's colour (bake
+upright — if it mirrors darkness at midday, fix the atmosphere skill's
+orientation bug first, not the water).
diff --git a/harness/codeverse/skills/cv3d-scene-water/references/gerstner-and-foam.md b/harness/codeverse/skills/cv3d-scene-water/references/gerstner-and-foam.md
new file mode 100644
index 00000000..c96e0d6b
--- /dev/null
+++ b/harness/codeverse/skills/cv3d-scene-water/references/gerstner-and-foam.md
@@ -0,0 +1,40 @@
+# Gerstner waves and shoreline foam — the deeper cut
+
+## Why Gerstner and not displaced noise
+
+Noise-displaced water bobs; Gerstner water TRAVELS. Each wave moves vertices in
+a circle — horizontally toward the crest, vertically over it — which is what
+sharpens crests and flattens troughs like real deep-water waves.
+
+Per wave i, with direction D_i (unit, xz), wavelength L_i, amplitude A_i,
+steepness Q_i:
+
+ k = 2*PI / L
+ c = sqrt(9.8 / k) // deep-water phase speed, m/s
+ f = k * dot(D, p.xz) - k*c*t
+ xz += Q * A * D * cos(f)
+ y += A * sin(f)
+
+* Sum 3-4 waves: one long swell (L 18-40 m, A 0.4-0.8), two mid chops at
+ 30-60 degrees off the swell, one short ripple. Randomize phases.
+* STABILITY: sum of Q*A*k must stay below 1.0, or crests loop into
+ self-intersecting curls. Budget Q per wave as Q_total / n_waves.
+* Normals: finite-difference the DISPLACED positions (sample the full sum at
+ p+dx and p+dz). Analytic normals from one wave look wrong the moment you sum.
+* Grid: 256x256 minimum for L >= 18 m; halve the wavelength, double the grid.
+
+## Foam, ranked by payoff
+
+1. SHORELINE foam (best): needs the shared height function. In the fragment
+ shader, `shore = 1. - smoothstep(0.0, 1.2, waterLevel - h)` then multiply by
+ scrolling fbm and add as near-white. Hugs banks, islands, piers.
+2. Contact foam around obstacles: same trick with distance to the obstacle's
+ footprint circle.
+3. Crest foam (skip unless asked): threshold on the Jacobian of the Gerstner
+ displacement; expensive to get right, subtle in stills.
+
+## Frozen-frame checks
+
+At the fixed capture time the surface must show asymmetric crests (travel
+direction readable), no through-floor dips at the shore (bias the plane down
+0.02), and foam only where geometry explains it.
diff --git a/harness/codeverse/skills/registry.py b/harness/codeverse/skills/registry.py
index b2b38720..6af25ba5 100644
--- a/harness/codeverse/skills/registry.py
+++ b/harness/codeverse/skills/registry.py
@@ -235,6 +235,21 @@ ROUTES: tuple[Route, ...] = (
findings=(GL_MOTION_OR_DETAIL,), why="the frame gate saw no motion or no detail"),
Route("R24-opengl", "cv3d-opengl-pipeline", 90, tracks=("graphics",), languages=("opengl_python",),
findings=(GL_MOTION_OR_DETAIL,), why="the frame gate saw no motion or no detail"),
+ # R25-R28 (2026-09-01): the graphics-recipe port from the scene_multifile_graphics
+ # reference (docs/EVAL.md sceneloop entry). Atmosphere and materials ride every
+ # env/baseline build; water and night only when the plan's own words ask for them.
+ Route("R25", "cv3d-scene-atmosphere", 70, tracks=("scene",), languages=("scene_threejs",),
+ kinds=("baseline", "env", "refine"),
+ why="the sky bake is the light source every PBR surface reflects; 4/9 reference scenes shipped it inverted"),
+ Route("R26", "cv3d-scene-water", 85, tracks=("scene",), languages=("scene_threejs",),
+ kinds=("baseline", "env", "zone", "compose", "refine"), requires_any=("wants_water",),
+ why="the plan's own words ask for water; metallic water is the reference's most-shipped material mistake"),
+ Route("R27", "cv3d-scene-night", 85, tracks=("scene",), languages=("scene_threejs",),
+ kinds=("baseline", "env", "zone", "compose", "refine"), requires_any=("wants_night",),
+ why="the plan's own words ask for night; shafts/emissive discipline is measured in the reference ledger"),
+ Route("R28", "cv3d-scene-materials", 65, tracks=("scene",), languages=("scene_threejs",),
+ kinds=("baseline", "zone", "compose", "refine"),
+ why="flat albedo and identical twins are the reference audit's most-cited surface defects"),
)
#: every skill the table can attach — the Author phase's contract for which bundles must exist
@@ -253,6 +268,12 @@ _SHADER_WORDS = ("shader", "glsl", "onbeforecompile", "shadermaterial", "custom
"raymarch", "postprocess", "post-process")
+_WATER_WORDS = ("water", "pond", "lake", "river", "ocean", "sea", "harbor", "harbour",
+ "canal", "pool", "waterfall", "fountain", "shore", "beach", "koi")
+_NIGHT_WORDS = ("night", "neon", "dusk", "evening", "moonlit", "moonlight", "lamplit",
+ "midnight", "nocturnal", "starlit")
+
+
def plan_signals(plan: Any | None) -> dict[str, Any]:
"""Route-relevant facts about a plan. Tolerant by design: a missing/partial plan
yields all-false signals rather than raising, because a planner failure must not
@@ -277,6 +298,10 @@ def plan_signals(plan: Any | None) -> dict[str, Any]:
"has_joints": bool(joints),
"joint_types": sorted({str(getattr(j, "type", "")) for j in joints if getattr(j, "type", "")}),
"has_custom_shader": bool(effects) or any(w in text for w in _SHADER_WORDS),
+ # scene-content signals (2026-09-01, the graphics-recipe port): matched against the
+ # plan's own words so the water/night recipes ride only when the brief wants them
+ "wants_water": any(w in text for w in _WATER_WORDS),
+ "wants_night": any(w in text for w in _NIGHT_WORDS),
}
diff --git a/harness/codeverse/skills/targets.py b/harness/codeverse/skills/targets.py
index b562e8cc..a13d1f93 100644
--- a/harness/codeverse/skills/targets.py
+++ b/harness/codeverse/skills/targets.py
@@ -240,6 +240,60 @@ TARGETS: tuple[Target, ...] = (
why="every gl_frames finding in the whole graphics corpus (3 flicker, 1 low detail) came "
"from opengl_python, and flicker is trap 1 (a sampled solver) showing up in pixels",
),
+ # ------------------------------------------------------------- 2026-09-01 recipe port
+ # The four bundles ported from the scene_multifile_graphics reference carry that
+ # harness's measured findings; OUR baselines attach when the sceneloop A/B lands.
+ # Until then the honest target is the same frame-gate family the recipes serve.
+ Target(
+ skill="cv3d-scene-atmosphere",
+ metric="env_bake_orientation_flags",
+ direction=DOWN,
+ unit="inverted bakes per run (prospective census)",
+ source=SRC_ARTIFACT,
+ languages=("scene_threejs",),
+ measurable=False,
+ why="the sky bake IS the scene's light source; the reference audit found the bake "
+ "inverted in 4 of 9 delivered scenes and every reflective surface went dark",
+ caveat="ported claim: reference-harness evidence, our own A/B pending (sceneloop).",
+ ),
+ Target(
+ skill="cv3d-scene-water",
+ metric="metallic_water_planes",
+ direction=DOWN,
+ unit="water materials with metalness above 0.3 (prospective census)",
+ source=SRC_ARTIFACT,
+ languages=("scene_threejs",),
+ measurable=False,
+ why="dielectric water against a live environment bake is the reference's most-shipped "
+ "material fix; no deterministic gate measures water quality yet",
+ caveat="NOT yet measurable here: judged quality only. The sceneloop A/B attaches numbers; "
+ "a water-specific instrument (fresnel/metalness census) is a candidate follow-up.",
+ ),
+ Target(
+ skill="cv3d-scene-night",
+ metric="overbright_shaft_findings",
+ direction=DOWN,
+ unit="solid-reading light shafts per run (prospective census)",
+ source=SRC_ARTIFACT,
+ languages=("scene_threejs",),
+ measurable=False,
+ why="night briefs are the dark_or_flat gate's richest source; the bundle is the "
+ "reference's measured shaft/emissive discipline plus our linear-luminance table",
+ caveat="ported claim: reference-harness evidence, our own A/B pending (sceneloop).",
+ ),
+ Target(
+ skill="cv3d-scene-materials",
+ metric="flat_albedo_surfaces",
+ direction=DOWN,
+ unit="large surfaces with zero value variance (prospective census)",
+ source=SRC_ARTIFACT,
+ languages=("scene_threejs",),
+ measurable=False,
+ why="flat albedo and identical twins are the reference audit's most-cited surface "
+ "defects; no deterministic gate measures material variance yet",
+ caveat="NOT yet measurable here: judged quality only. A variance census (per-material "
+ "value spread over sampled texels) is the candidate instrument.",
+ ),
)
BY_SKILL: dict[str, Target] = {t.skill: t for t in TARGETS}
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 725af960..fd1915c9 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -125,7 +125,7 @@ This is the difference between a metric and a number that would have read 100% f
| `cv3d-cadquery-forms` | any | cadquery | **inherited-unverified** | 82 | 1,482 | R10 |
| `cv3d-threejs-forms` | static_object | threejs | **inherited-unverified** | 120 | 1,929 | R11 |
-**All thirteen ship OFF** (`CV3D_SKILLS` unset). Zero have a measured effect; see
+**All seventeen ship OFF** (`CV3D_SKILLS` unset). Zero have a measured effect; see
`docs/SKILLS_LEDGER.md` §5 for why that is the honest default and what flips one on.
Shipping a subset needs no new machinery — `CV3D_SKILLS_ONLY` restricts the library before
routing, so `CV3D_SKILLS=1 CV3D_SKILLS_ONLY=<names>` is the vehicle when a bundle earns it.
@@ -409,7 +409,7 @@ line in a long markdown file plus a generic `read_file`.
— **cannot be cleared by anything on this rig at n = 8**: the A/A of two identical arms
fails it, twice over (−0.038, −0.206).
3. The deterministic readouts are not an escape hatch either (below).
-4. Two of thirteen bundles have no graded runs behind them at all and are already routed off.
+4. Two of the original thirteen bundles have no graded runs behind them at all and are already routed off; the four 2026-09-01 scene-graphics ports are `inherited-unverified` by construction until the sceneloop A/B grades them.
Nothing here says the library is wrong. The CLI evidence says the opposite. It says the
delivery mechanism for `api-agent` is a pointer nobody follows, and that is fixable.
diff --git a/harness/docs/SKILLS_LEDGER.md b/harness/docs/SKILLS_LEDGER.md
index 1043f541..6f6ca740 100644
--- a/harness/docs/SKILLS_LEDGER.md
+++ b/harness/docs/SKILLS_LEDGER.md
@@ -5,7 +5,9 @@ the maintenance surface: **one row per bundle**, naming the single deterministic
claims to move, the direction, the number it has to beat, and what it owes before it can be
called earned.
-**Library: 13 bundles.** All 13 ship **OFF** (`CV3D_SKILLS` unset). Zero have a measured
+**Library: 17 bundles** (13 + the 2026-09-01 scene-graphics port: atmosphere, water,
+night, materials — routes R25-R28, evidence `inherited-unverified` from the
+scene_multifile_graphics reference ledger). All 17 ship **OFF** (`CV3D_SKILLS` unset). Zero have a measured
effect. §5 says why that is the honest default and what would change it.
Three files hold it up:
@@ -274,7 +276,7 @@ The library does **not** have to share one switch. `CV3D_SKILLS_ONLY` restricts
CV3D_SKILLS=1 CV3D_SKILLS_ONLY=cv3d-part-contact,cv3d-bbox-contract # the vehicle
```
-**Today that list is empty, and all 13 bundles default OFF.** Not for lack of a mechanism,
+**Today that list is empty, and all 17 bundles default OFF.** Not for lack of a mechanism,
and not because the wave ran out of time — because **zero bundles have a measured effect**,
and every candidate default-on is a token cost per session against an unmeasured benefit.