Reorganize docs into category folders and drop the retired head-review page

Group the top-level docs into docs/project, docs/design, docs/assets and docs/process, each with its own README index. Delete the superseded docs/screens/head-review page and sheets. Rewrite every markdown link, absolute docs path and tool/test reference to the new locations, fix the pre-existing broken anchors and remove the dead Joke Shop photo-board link. check_docs OK, Python tooling 167/167.
2026-11-06 20:13:03 +01:00
1 parent 045ed2a58f
commit 2ba40f3578
@@ -15,13 +15,13 @@ The map-optimization references for the El Capitan Entertainment Centre block
 (6840 Hollywood Blvd) are in
 [`hollywood_boulevard/README.md`](hollywood_boulevard/README.md). The real-site
 facts and game mapping are documented in
-[`../../venues.md`](../../venues.md#hollywood-boulevard).
+[`../../venues.md`](../../design/venues.md#hollywood-boulevard).

 ## The Joke Shop — Sunset Strip

 The current Joke Shop map is based on The Comedy Store at 8433 Sunset Blvd.
 The real-site mapping and simplifications are in
-[`../../venues.md`](../../venues.md#the-joke-shop); the frames are in
+[`../../venues.md`](../../design/venues.md#the-joke-shop); the frames are in
 [`joke_shop/README.md`](joke_shop/README.md).

 ![Joke Shop entrance in daylight](joke_shop/joke_shop_entrance_day.png)
@@ -4,7 +4,7 @@ AI-generated art-direction frames for the real El Capitan Entertainment Centre
 block at 6840 Hollywood Boulevard. They are generated with
 `tools/scene_concepts.py generate --group scene --only ...` and are not shipped
 game textures. The geometry mapping and source links are in
-[`../../../venues.md`](../../../venues.md#hollywood-boulevard).
+[`../../../venues.md`](../../../design/venues.md#hollywood-boulevard).

 ## Entrance — day

@@ -4,7 +4,7 @@ AI-generated art-direction frames for the fictional Joke Shop, based on the
 real Comedy Store block at 8433 Sunset Boulevard. They are generated with
 `tools/scene_concepts.py generate --group scene --only ...` and are not shipped
 game textures. The geometry mapping and source links are in
-[`../../../venues.md`](../../../venues.md#the-joke-shop).
+[`../../../venues.md`](../../../design/venues.md#the-joke-shop).

 ## Entrance — day, photo-anchored

@@ -1,68 +0,0 @@
-# Head rework — review page (2026-11-04)
-
-> **Historical page / changed source (2026-11-04).** The numbers below describe the
-> earlier decimated MakeHuman head (1,548-tri skin). The shared source
-> `assets/models/blender_src/makehuman_head.glb` now holds the higher-resolution
-> standalone prototype. The owner accepted the basic head; the automated vision gate
-> still records REJECT on the eye/lid region as deferred polish. See
-> [`../../makehuman-head-review.md`](../../makehuman-head-review.md). Re-run the
-> library head build before relying on the comparison counts below.
-
-This page is the review checkpoint for the NPC head rework. The goal was to replace the
-sphere-and-floating-primitive face with a head that has real nose / chin / jaw landmarks at
-portrait distance.
-
-## What changed
-
-The original procedural face is a head sphere plus separate nose, mouth, ear and eye primitives.
-The new head uses the **decimated MakeHuman head** (CC0, 1,573 tris) as the base shape and keeps
-the project's separate eyeballs, brow and mouth pieces on top. An AI judge was used to drive the
-decision: it scored the procedural rework at ~3/5 and then picked the MakeHuman head as the
-clearer silhouette.
-
-| | Source | Tris (head) | Read |
-| --- | --- | --- | --- |
-| **Before** | procedural `_face` (sphere + primitives) | ~1,900 | flat face, slit eyes |
-| **After** | overhauled MakeHuman head + project eyes/brows/mouth | ~1,880 | smooth nose/chin/jaw landmarks |
-
-The head source was overhauled 2026-11-04: the blocky decimated MakeHuman head was welded
-(merge-by-distance) and Laplacian-relaxed into one clean manifold shell (`makehuman_head.glb`,
-1,548 tris skin), then the project eyes/brows/mouth were added.
-
-## AI-generated target concept
-
-The rework was guided by two generated concept frames (front + profile, `bytedance-seed/seedream-4.5`).
-
-![concept](sheet_concept.jpg)
-
-## 1.85 m comparison (top = current, bottom = new)
-
-Left to right: front, three-quarter, profile.
-
-![1.85 m comparison](sheet_compare_1.85.jpg)
-
-## New head at 1.5 m (portrait)
-
-![1.5 m portrait](sheet_head_1.5.jpg)
-
-## Contract and checks
-
- `blender_assets.py inspect` on the assembled `npc_casual` with the new head: **14 bones,
-  skinned, no issues**.
- Source: `assets/models/blender_src/makehuman_head.glb` (CC0, attributed in `CREDITS.md`).
- Python 167/167, Godot 277/277, `check_docs` OK.
-
-## Remaining polish (known, not blockers)
-
-1. The hair cap still reads as a stepped block instead of hugging the skull.
-2. The brows weld to the face but can read as a slightly separate bar.
-3. The neck underside cap is plain; it is hidden by the body neck in the assembled character.
-4. The head skin is 1.5k tris (smooth but low-poly); a retopology pass could add resolution if a
-   portrait shows faceting.
-
-## Decision (2026-11-04, owner)
-
-The MakeHuman-head direction is approved for the basic human head. The remaining review is the
-assembled prototype's hair cap and full-body silhouette. After that, roll the head into the other
-11 variants (one asset family at a time) with a before/after sheet per batch, then re-run the
-24-NPC budget + AO bake.
@@ -76,8 +76,8 @@ committed here is the redacted copy, not the original.
 ## How the folder is used

 - Build the venue **three-up boards** (photo | concept | current capture) for the review verdicts.
- Link the board from the venue map document (`docs/venues.md#hollywood-boulevard`,
-  `docs/venues.md#the-joke-shop`) and from the local-map block notes.
+- Link the board from the venue map document (`docs/design/venues.md#hollywood-boulevard`,
+  `docs/design/venues.md#the-joke-shop`) and from the local-map block notes.
 - Cite the sidecar when a texture, proportion or signage decision is derived from a photo.
 - Refresh the board when a venue change makes an old reference misleading, and note the change in
  the sidecar.
@@ -34,12 +34,12 @@ attribution string for CC BY / CC BY-SA in the `Author` or a note below.

 | Decision | Evidence | Where it landed |
 | --- | --- | --- |
-| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/venues.md#hollywood-boulevard` |
+| e.g. six-column spacing kept at 2.4 m | photo 1, measured against door width | `docs/design/venues.md#hollywood-boulevard` |
 | e.g. banner red sampled to `#8a1f24` | photo 1 + photo 2 | `docs/screens/refs/hollywood/` notes, facade kit |

 ## Generated boards used with this set

-Generated frames live in [`../../concepts/`](../../concepts/README.md); reference them here so the
+Generated frames live in [`../../concepts/`](../concepts/README.md); reference them here so the
 three-up sheet is reproducible.

 | Board | Path | Model | Prompt / seed | Generated | Spend |
@@ -11,7 +11,7 @@ TV Studio board.

 Provenance, licences and the decisions these photos informed are in
 [`SIDECAR.md`](SIDECAR.md). The rules for this folder are in
-[`../README.md`](../README.md); generated art-direction frames live in
+[`../README.md`](README.md); generated art-direction frames live in
 [`../../concepts/hollywood_boulevard/`](../../concepts/hollywood_boulevard/README.md).

 | Photo | What it is evidence for |
@@ -35,5 +35,5 @@ Provenance, licences and the decisions these photos informed are in
 - The east retail neighbour beyond the temple (the modern retail block), for facade rhythm at the
  right-hand edge of the venue.

-Add new files with the naming convention in [`../README.md`](../README.md) and list them in the
+Add new files with the naming convention in [`../README.md`](README.md) and list them in the
 sidecar in the same commit.
@@ -26,7 +26,7 @@
 Licence texts: [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/),
 [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) and
 [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). The CC BY and CC BY-SA files are
-also listed in [`../../../CREDITS.md`](../../../CREDITS.md) under "Development-only reference
+also listed in [`../../../../CREDITS.md`](../../../../CREDITS.md) under "Development-only reference
 images".

 **CC BY-SA review (2026-11-03):** `hollywood-boulevard-night-context-ccbysa.jpg` is redistributed
@@ -51,10 +51,10 @@ before use.

 | Decision | Evidence | Where it landed |
 | --- | --- | --- |
-| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/venues.md#hollywood-boulevard` geometry notes |
+| Six Ionic columns, ~2.4 m spacing, 8 steps | facade photo measured against the door width | `docs/design/venues.md#hollywood-boulevard` geometry notes |
 | Masonic parapet motto and medallions | 1922 elevation + facade photo | `WorldBuilder` facade, `docs/screenshots/01-venue-overview.png` |
 | Three vertical event banners | facade photo | facade banners and the day/night capture set |
-| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/venues.md#hollywood-boulevard` event staging notes |
+| Red carpet + barrier staging narrows the sidewalk | premiere photo | `docs/design/venues.md#hollywood-boulevard` event staging notes |
 | Across-street height and plaza opening | Ovation photo | opposite frontage massing |
 | TV Studio arrival staging (bulb canopy, car, barriers) | premiere staging photo | `VENUE_SPECS["tv_studio"]` and the Late Night TV Studio venue docs |
 | Terrazzo band width, star size/spacing | terrazzo + star close-up photos | `WalkOfFame` band geometry and the paver material |