HardYards/docs/MANUAL.md

HARD YARDS — dev manual & cookbooks

Written at Sprint 13 integration, distilled from THREADS. The canon docs (DESIGN.md, PLAN3D.md) say what the game IS; this says HOW to work on it. When this file and a lane's THREADS entry disagree, THREADS wins — fix this file.

The tool map — what answers what

question	tool	notes
does everything still work?	web/world/selftest.html	must be N/0/0; the count is the per-lane sum
is this yard rig-able by mouse?	web/world/dev_rigging.html	N switches yards; __laneB.switchSite(i)
what does the sky/storm look like at t=X?	web/world/dev_skyfx.html	scrubbable clock; flies debris; warning: it aims you SOUTH
player anims/movement	web/world/dev_player.html
is this site winnable, at what price?	tools/site_audit/ (audit.html browser, audit.mjs node)	funnel state printed in the header — check it
does rigging save the garden here?	tools/garden_bench/ + tools/site_audit/gardenfly.js	garden outcomes, separation targets, margin rule
per-anchor wind exposure over a storm	tools/storm_envelope/	the storm-side second harness
regenerate all canon GLBs	blender -b -P tools/blender/build_yard_assets.py	deterministic; --only <name> for one asset
does this asset LOOK right?	tools/assetcheck/look.html?a=name1,name2	the game's renderer + the 1.7 m capsule; the only check that answers "wrong shape"
job-sheet/invoice design preview	tools/jobsheet/index.html?v=...	E's design-ahead handover pattern
deploy to partly.party/hardyards	sh tools/deploy_hardyards.sh	ships web/ ONLY; self-verifies

Adding an asset (a prop, a structure, a thing in the yard)

House rules first (PLAN3D §0): the runtime asset is always .glb, committed in web/world/models/. Raw .blend/.fbx never enter the repo (gitignored). Two legitimate routes in:

Route 1 — the factory (canon assets). Add a builder to tools/blender/build_yard_assets.py, re-run, commit the GLBs. Nothing is hand-edited after export; the factory must produce byte-identical output across runs (this is asserted — three full runs, same hashes). This is Lane E's lane.

Route 2 — vendored external (John's hand-built / MeshGod / library assets). Precedent exists: models/debris/* is copied verbatim from the 3D-STORE library. Drop the GLB in web/world/models/, then wire it (below). If it's a one-off, say in THREADS where it came from; if it'll be regenerated, it belongs in the factory instead.

Wiring a prop — the gnome pattern (~5 lines + data, one commit). There is deliberately no generic props: [] — every prop is a named top-level key in the site JSON, wired explicitly, so a site says what it contains. The bike (Sprint 12) is the worked example — copy its diff:

1. Put bike_kid_01_v1.glb in web/world/models/.
2. Site JSON gains a key: "bike": { "x": -7, "z": 9.69, "rotYDeg": 180 }.
3. world.js loader: one entry in the Promise.all + a placement block (position via heightAt(x,z), rotation from the JSON).
4. Optional collateral: bake collateral / collateral_value extras in the GLB as the proposal; the site JSON's number is canonical (the carport's collateralValue: 180 pattern). Nothing is billed until collateralFor() can resolve it — an unpriced collateral returns null and reads as "not scored", never as free… and never as billed either (the gutter was a free failure for two sprints).
5. Wrecks: same origin, same footprint, mesh-for-mesh swap on world.wreckStructure(id) — build the wreck variant from a shared helper so intact/wrecked can't drift (E's _house_facade() pattern).
6. An assert that can actually fail, negative-control-proven (E rebuilt the bike at lean 0° to watch the suite go red before trusting it).

Conventions the loader reads (bake as GLB extras / node names):

• rating_hint (float) on anchor nodes — effective failure = hw.rating × ratingHint. Unset ⇒ 1 at adoption; the sim reads the anchor, live.
• collateral (string) on anchor nodes — what breaks when this anchor's corner blows. collateral_key on ANY asset that carries a price, naming which collateral string that price answers to. Not just the odd ones out (house → "gutter"): the carport went five sprints resolving only because site_02 happens to id its structure "carport", and a second carport placed in the editor would have been a free failure.
• tie_off: false on an *_anchor node that is NOT a tie-off (a carry point, a light hint, a stand position). Silence is not neutral here — adoptAnchor does rating_hint ?? 1, so an unrated anchor node is the best steel in the game the moment a site names it. Three e.test.js rules enforce this class of honesty across every GLB: no silent anchors, no collateral string nobody prices, no anchor_type outside ANCHOR_TYPE.
• Named nodes matter: pickup_anchor (where carried items sit), the fascia_anchor_* family, etc. Check world.js adoptAnchor before renaming anything.

⚠ THE AXIS TRAP (bitten every sprint since 3): the exporter maps Blender (x, y, z) → three.js (x, z, −y). A lean toward Blender +Y arrives leaning toward three.js −Z. Never write a docstring about orientation without measuring the exported GLB in three.js coords — E's bike comment lied about its own geometry and only a browser-coords assert caught the flip. Dims/tri-count verifies CANNOT catch a wrong shape or a flipped lean; look at the render — tools/assetcheck/look.html exists for exactly that, and the Blender contact sheet is NOT a substitute (its view transform rendered a #8C7FC0 canopy as near-white; a colour judgement made there is a judgement about Blender). Better still, bake the orientation claim as an extra and assert the claim against the geometry, so the note and the mesh can only lie together (swing_set_01.wreck_falls_toward).

Authoring a site (a "level")

Sites are data: one JSON in web/world/data/sites/. Top-level shape (see site_02_corner_block.json): id, name, blurb, yard, sun, gardenBed, structures, trees, posts, fence, wind, [props…], [separation], _design/_why. Anchors are not listed directly — they come from structures/trees/posts (and GLB nodes), typed against the checked ANCHOR_TYPE enum in contracts.js.

The authoring loop that works (Sprint 10–13 distilled):

1. Copy the nearest existing site JSON; keep _design/_why notes in-file — they're the level's design doc and the repo expects them.
2. validateSite runs at load and fails loud (types, wind block, enum). Boot with boot({site:'your_site', bank:N}) to jump straight to it.
3. Wind personality lives in the SITE (venturi axis/gain/throat, tree shelters), storm personality in the storm def. The venturi axis is site GEOMETRY (a line, mod π), not a wind heading — reconciled twice in THREADS before that sentence earned its place.
4. Every trap must be: visible before commit (the enum gives it its pre-rig read), priced (collateral), and mechanically real (rating_hint) — "the price is the trap" vs "the steel is the trap" is a ruling, not an accident.
5. Run the gauntlet before calling it a level: site_audit (winnable lines at $80, funnel ON — check the header), gardenfly/garden_bench (does rigging separate held-vs-bare? pin a separation block if this site makes that promise), storm_envelope (per-anchor exposure), then a cold playthrough by someone who didn't author it (Lane D's job) — Sprint 11's soft-lock shipped behind 296 green tests and was found in one minute of play.
6. The blurb and brief carry real design load (night 3's "plenty to tie off to" is the trap's cover story). Client/brief/pay live in week.js NIGHTS; a site without a night is only half real (boot({site}) seeks the night).

The earned gotchas (each cost a real sprint-day; receipts in THREADS)

• Measure through the real chain. Any garden/load number that didn't go through commit → attach → skyfx is suspect: session-level commit() bypasses attach and scores every rig as bare (D, S13); a 12 s pre-settle skews SailRig's internal storm clock (B catching A, S13).
• Site wind is built in ONE place: windForSite() in weather.js. Three harnesses independently rebuilt it wrong (funnel off ×2, frozen tree sway). Import the helper; never hand-wire venturi/shelters in a tool again.
• Margin rule: any bench corner within ~15% of its rating breaks in the real game (residual bench-vs-UI under-read, cause unfound). Marginal ≠ PASS.
• world.dress() needs the importmap — without it the bare-specifier throw is swallowed by callers' try/catch and every ratingHint silently becomes 1.0 (no carport trap, invincible house).
• setHardware() refuses over-budget quietly — check .ok or fly with budget: 9999 in tools (this ate four of C's measurements).
• Documentation cannot fail: an unchecked enum, a JSDoc contract, a comment about geometry — if nothing asserts it, expect it to be wrong someday.
• Two harnesses, one number. When they disagree, find the variable before tuning anything; the variable is usually the harness.
• One clone per lane; ports 8823 (integration) / 8824–8828 (A–E) via untracked .claude/launch.json (copy the example).
• Hidden tabs throttle rAF dead: drive with SHADES.step(dt) / .render(); hidden-canvas boot needs one resize before projections are sane.

Design canon quick-reference (ruled, don't relitigate casually)

• Business: HARD YARDS. ABN stays sequential (never make it realistic).
• Carport $180 / gnome $25 / gutter $90; bike deliberately unpriced until the sim can knock it over (tripwire assert enforces this).
• The wild night sells no clean line — the pyrrhic win is intended. Night 5's garden is beyond saving BY DESIGN and the brief says so. GARDEN_DRAIN does not move. 18–45 m² is an availability floor, not a ceiling.
• Hail is why sails matter (steep, blockable); rain walks under cloth (don't reopen the rain-angle argument).

Where knowledge actually lives

READ ORDER for anyone new: README → DESIGN.md → PLAN3D.md → THREADS from the last [I] entry backwards until you have context → the current SPRINTn.md. THREADS is append-only memory, not a reference — when you learn something from it the hard way, promote it into THIS file so the next person reads one page instead of 300 entries.