# NBUS RAILWAY & STATIONS — MASTER PROMPT (v2, 10 Nov 2026)

This document replaces the original "Master Engineering Specification" station prompt (Gemini-drafted, 7 Nov 2026) and every partial instruction given since. Where it conflicts with anything older (old prompts, project notes, handoffs, scripts, comments in code), **this document wins**. It is written for Claude (any model) working on Elie's NeoForge 1.21.1 server "New Big Ultimate Server" (NBUS). It must be read in full at the start of every phase. Section 15 is the phase plan; Section 14 is the catalogue of past mistakes that must never recur.

Claude keeps authority to adapt technical details to how the servers and mods actually work, **but never to drop or weaken a requirement written here without asking Elie**.

---

## 1. Goals in one page

1. A set of **10 station designs**, each built in **4 types** (Basic, Standard, Mini Hub, Super Hub) with **variable platform counts** for hubs, every design and every type having a **genuinely different layout**, that feel like real, working railway stations: correct circulation, believable architecture, working lifts and escalators, clear signage, good lighting, amenities, staff, villagers and guards — with no structural or design mistakes.
2. Three of the designs are **near 1:1 recreations** of real stations: **London Euston, Birmingham Moor Street, Birmingham New Street (with the Grand Central shopping centre parts that make sense)**.
3. A **test server** with (a) a flat showcase of every design × type neatly laid out, and (b) a real-terrain **test circuit** with a rideable long test train, junctions of every kind, a quad-track section and two super hubs (6 and 10 tracks).
4. **Phase B**: the planned rail network (plan v12 + changes) built on production with the generated stations placed automatically — started by Elie from the status page.
5. **Phase C (prepare now, build after B)**: full track electrification with a modest number of substations / a central power plant, finite but very long-lasting fuel.
6. The whole production process is **automated, offline, observable and controllable** from a clear live status page, with work moved freely between machines, and Claude's own usage kept efficient.

---

## 2. Environment, machines and access

### 2.1 Machines and roles
| Machine | What it is | Role |
|---|---|---|
| **Oracle** "navidrome-and-stuff" (ubuntu, 4 cores, 24 GB) | **Central command** (Elie, 10 Nov): the workspace `/home/ubuntu/nbus` (git), orchestrator, job queue, status page (:4534), SSH hub, backups, Google Drive uploads (rclone). Also the test server (container `nbus-test`, `/home/ubuntu/nbus-test`) and Navidrome | Everything is started, tracked and controlled from here |
| **HostBRR** (root, 10 cores, ~19 GB RAM) | Production NBUS server (Docker/discopanel, container `discopanel-server-02d31a17-…`), server dir `/mnt/discopanel/data/servers/my_big_ultimate_server_02d31a17-6f27-4fcd-a55f-3881597f0eb1`; network plan + planner `/opt/nbus/rebuild2`; companion source `/opt/nbus/rebuild2/companions/nbus` | Production; build worker (clone of the workspace); runs Phase B steps sent from Oracle |
| **Contabo** (root, 8 cores) | Build worker only (clone of the workspace) | **Everything moves off Contabo when the station work is finished**; never touch its `~/.ssh/authorized_keys` except to append/remove our own TEMP lines |
| **DownstairsOffice** (Windows, i9-9900KF, 16 threads, 64 GB, no WSL, not admin, Python 3.14) | Build worker `C:\nbus\dworker_win.py` | Build worker — must report CPU/RAM like the Linux machines |
| **GPD Win Mini** (CachyOS, fish shell) | Elie's handheld; Steam screenshots of his play-tests in `~/.local/share/Steam/userdata/907940576/760/remote/10637093/screenshots` | Read screenshots when Elie says "check screenshots"; optional worker |
| HP Elite X2, Mac | Elie's devices | Elie's own Desktop Commander use — leave quota for them |

### 2.2 Access rules
- Claude reaches Oracle through **Desktop Commander** (cloud quota is limited — ~89% used on 10 Nov; it resets monthly). **Oracle is the SSH centre**: it reaches Contabo and HostBRR with TEMP keys in `~/nbus-ctl/keys` (`oracle_contabo`, `oracle_hostbrr`). Servers talk to each other directly over SSH; nothing machine-to-machine should need Desktop Commander.
- **Preferred route (Elie, 10 Nov):** when this session is linked to the GPD (or DownstairsOffice) through the Claude desktop app, run Oracle commands through that link: `~/.nbus-build/o "command"` on the GPD (ssh with its TEMP key `~/.nbus-keys/gpd_oracle`). It does not use the Desktop Commander cloud quota. Desktop Commander cloud is the fallback when no computer is linked.
- **Automatic failover for commands (Elie, 10 Nov):** 1) the linked computer (GPD `~/.nbus-build/o` or DownstairsOffice `C:\\nbus\\o.cmd`); 2) if it is offline, Desktop Commander cloud straight to Oracle; 3) if Oracle's Desktop Commander is down, Desktop Commander on the other PC, then ssh to Oracle from there. Claude switches without asking; the Machines page shows each route's last use.
- Batch Desktop Commander calls: one call should do a whole step (write script → scp → run detached → write a summary). Never poll in short loops; use status files and the watchdog.
- TEMP keys (GPD, Oracle, DownstairsOffice incl. `C:\nbus\keys\dso_oracle` → Oracle with wrapper `C:\nbus\o.cmd` (added 10 Nov), HostBRR→Contabo) are removed when the station work is done. Either the GPD or DownstairsOffice can be the linked computer.

### 2.3 Standing safety rules (never break)
- Never read `~/.ssh` or credential files; never print RCON passwords, the CurseForge API key or AutoModpack's client `connection.json`; never print container environments.
- Never run `/locate`. No systemd services or cron (Elie handles persistence); watchdog loops started with `setsid nohup` are fine.
- Never delete world or player data outside an approved wipe; ask before deleting anything that matters. Test-world wipes at each install are approved (backup first).
- Never run two copies of a server; never edit a script while it runs (write `.new`, then `mv`; restart loops by PID).
- **Never `pkill -f`/`pgrep -f` with a pattern that also appears in the current command line** (it kills the caller). Kill by PID from `ps -eo pid,args | awk` on exact arguments — and the awk pattern itself must not match the command running it.
- Companion mod, not patched jars, for behaviour changes; never replace MethodNodes; dry-run with check2. Downloading/patching third-party mods is allowed (Elie, 10 Nov) when a companion can't do it — keep originals, note licences, keep changes revertible.
- **Production changes need Elie's explicit go** (Phase B start button / message). Backups before every production change (save-off → copy → **always** save-on via trap).
- Lights never below 3 blocks above the floor they light (recessed floor lights set *into* the floor are fine).
- Respect classifier/permission denials; never work around them.

---

## 3. Production process (the cleanup) — how all work is done from now on

The 8–10 Nov process failed in specific ways: many ad-hoc scripts in `/tmp`, helpers editing the live generator in parallel, a watchdog that lifted a hold and deployed half-finished edits overnight, status pages patched piecemeal, alerts that cried wolf, and Claude's usage spent on polling. The new process:

### 3.1 One repository, versioned
- All generator code, tools, pipeline scripts, configs, docs and the status page live in **one git repository** (**Oracle `/home/ubuntu/nbus`**, the single workspace — see its `README.md` for the folder map; workers on Contabo/HostBRR/DownstairsOffice get read-only clones; old work is only in `archive/` → `/home/ubuntu/nbus-archive`). Nothing important lives only in `/tmp` or a helper's scratchpad.
- Layout: `research/` (Phase 0), `design/` (specs), `gen/` (station generator), `tools/` (checks, placement, applynames, rotfix …), `pipeline/` (orchestrator, workers, deploy, backup), `stageb/` (Phase B), `electrification/` (Phase C), `status/` (page + collectors), `companion/` (mod notes), `docs/` (this prompt, plan, changelog, handoffs, registry), `STATUS.md` (now/next).
- **Branches**: `main` = what the pipeline builds and may deploy. Work happens on short feature branches; a branch is merged only when its test builds pass the full suite **and** it has a changelog entry. The pipeline builds **only tagged commits on `main`** — a half-finished edit can never reach the test server again.
- `docs/CHANGELOG.md` records every merged change (what, why, which feedback item it answers).

### 3.2 One orchestrator, named stages
A single pipeline orchestrator (`pipeline/orchestrator.py` on Oracle) owns the state machine; every stage has a name, inputs, outputs, a success test, a timeout and a retry rule, and writes one line to `pipeline/state.json` and `pipeline/log.txt`:

`BUILD → CHECK → PACKAGE → DEPLOY_TEST(wipe, place, assemble) → SETTLE → BACKUP(world + mods zip) → INGAME_TEST(villager/guard path test, lift/escalator test, train test on the circuit) → REPORT → WAIT_REVIEW` and, gated by Elie, `PHASE_B_*` and later `PHASE_C_*`.

- No other script starts stages on its own. Watchers (hubs, export, Station Builder, autostart) become stages.
- **Pause/resume** is one flag the orchestrator honours; only the orchestrator or Elie (status page) changes it; Claude only via the documented command. No "auto-release after N quiet hours".
- Every alert is actionable and deduplicated (one alert per condition, cleared automatically when resolved); "machine silent" only fires when a worker holding work has truly stopped.

### 3.3 Work queue that moves work between machines
- One queue (`pipeline/queue/`, served from Oracle) of small jobs (one station template = one job; one hub variant = one job; one test-world chunk region = one job). Workers on **Contabo, HostBRR, DownstairsOffice (and optionally GPD)** pull jobs, heartbeat **every 15 s while working** (CPU %, RAM, load, current job, progress), and return results.
- **Work stealing**: a job held too long (adaptive: 3× its expected time) is re-queued; slow machines get small jobs first; any idle machine can take over. Duplicate finishes are harmless (idempotent outputs).
- The Windows worker reports real CPU/RAM (psutil or `typeperf`), runs as a background process that survives log-off where possible, and shows on the status page like the others.

### 3.4 Status page (rebuilt)
- One page (Oracle `:4534`), phone-first, refresh ≤ 15 s, readable at a glance:
  1. **Big summary**: current phase/sub-phase, overall %, ETA, the one thing happening now, what comes next, "waiting for Elie?" banner.
  2. **Pipeline**: every stage with tick / running (bar + live count) / waiting / failed, with times.
  3. **Machines**: per machine CPU %, cores, RAM, disk, current job(s) by name, jobs done/hour — including Windows.
  4. **Live build log**: each finished job, machine, duration (exact), result.
  5. **Test results**: checks per station, in-game tests per station, links to downloads (world + mods zip), network diagram + track layouts.
  6. **Phase B / Phase C panels** with readiness checklist ("Phase B ready?").
  7. **Controls** (authenticated by a simple secret token stored only on Oracle and given to Elie): Pause / Resume pipeline, Rebuild now, Deploy latest passing build to test, Hold test world (no wipe), **Start Phase B** (enabled only when Phase A is finished and every Phase B readiness item is green), Stop Phase B safely (finish current section, save-on), Revert Phase B mods. Every control writes a request file the orchestrator acts on and logs who/when.
  8. **Claude's helpers** (folded): only when helpers exist.
- No BlueMap screenshots/previews (Elie doesn't want them). Instead: **network diagram and station track layouts before each test-circuit iteration** (PNG/SVG on the page).
- Until Phase 1 delivers it, `status/interim_status.sh` shows Phase 0 progress on :4534.

### 3.5 Claude's working rules (usage efficiency)
- Do the thinking once, write it down, then let scripts run. Prefer one well-built script over many check-in calls.
- **Helpers (sub-agents) sparingly**: only for genuinely parallel, well-separated work; each gets a written brief, a file ownership list, a git branch, a call budget and a model choice suited to the task (Section 15.2). Never two helpers editing the same file. If the usage limit stops helpers, their branches simply stay unmerged — nothing half-done reaches `main`.
- Every phase ends with a **handoff note** (`docs/handoffs/<phase>.md`): what's done, what's verified, what's next, which model/effort Elie should switch to, and the exact first instruction for the next session. `STATUS.md` always says now / then / next.
- Tell Elie what happened in plain words; never claim something works without having checked it.

---

## 4. The 10 designs

Each design is a complete family: architecture, materials, palettes per biome, layouts per type, amenities, lighting style, signage style, details. **Layouts must be entirely different between designs** — circulation concept, building position relative to tracks, levels, roof form, access method, concourse shape — and **within a design the four types must each have their own layout fitted to their size**, not one plan scaled. Avoid the 8–9 Nov failure where every design was the same skeleton with a different skin.

| # | Design | Kind | Reference anchors (inspiration for non-recreations) |
|---|---|---|---|
| 1 | **19th century** | Inspired | Victorian / industrial: St Pancras, York, Bristol Temple Meads, Paddington, Newcastle; country stations with timber canopies and valances |
| 2 | **Early 20th century** | Inspired | Beaux-Arts / Edwardian / early Art Deco: Grand Central NYC (1913), Helsinki Central (1919), Antwerp Centraal, Surbiton (1937), Cincinnati Union Terminal |
| 3 | **Mid 20th century** | Inspired | Post-war modernism 1945–1970: Roma Termini (1950), Coventry (1962), Stockholm T-bana, Moscow metro for grand variants, Festival-of-Britain-era UK stations |
| 4 | **Late 20th century** | Inspired | 1970s–1990s: high-tech and late modern — Stratford Regional, Lille Europe, Canary Wharf (JLE), Hong Kong MTR 1980s–90s, Rotterdam Blaak; must look clearly different from Euston (#8) |
| 5 | **21st century — American** | Inspired | Moynihan Train Hall, WTC Oculus, Denver Union Station, Salesforce Transit Center, Miami/LA metro stations |
| 6 | **21st century — European** | Inspired | Liège-Guillemins, Berlin Hauptbahnhof, Arnhem Centraal, Rotterdam Centraal, Elizabeth line stations, Copenhagen metro |
| 7 | **21st century — Asian** | Inspired (metro allowed) | Kanazawa, Kyoto, Shenzhen Futian, Hong Kong West Kowloon, Singapore MRT/Thomson-East Coast, Taipei metro |
| 8 | **London Euston** | **Recreation (near 1:1)** | 1968 station: long low concourse, departures wall, ramps down to platforms, dark coffered ceiling, forecourt and bus station, Euston Square side; no clutter of posts |
| 9 | **Birmingham Moor Street** | **Recreation (near 1:1)** | Restored 1909–14 GWR terminus + newer through platforms; Edwardian booking hall, GWR canopies, lamp posts, **one** footbridge, forecourt |
| 10 | **Birmingham New Street + Grand Central** | **Recreation (near 1:1)** | 2015 rebuild: atrium under the ETFE roof, mirrored ribbon façade ("Media Eye"), concourse deck over the platforms, platforms in the cutting below, stairs/escalators/lifts down, entrances (Stephenson St, Navigation St, Hill St), the Grand Central levels that make sense for a station (food court/mezzanine retail, John Lewis frontage as a façade block) |

Rules for recreations: building masses, façades, roofs, circulation (where stairs/escalators/lifts/footbridges are), concourse vs platform levels and platform arrangement as faithful as Minecraft scale allows, **especially the Super Hub version**; platform count still variable — extra platforms are added in the real station's pattern. For inspired designs: coherent, believable, period-correct; borrow real details (landmark features may be copied), don't copy one station.

**No platform screen doors** in any design (including recreations and metro-inspired ones). Walkways/footbridges/skybridges are welcome.

### 4.1 Clean start (Elie, 10 Nov 19:16)
All previous designs are forgotten. No old design module, layout, archetype kit or template is used as a starting point. The old workspaces are archived:
- Contabo `/opt/nbus/archive/20261110/` (old `/opt/nbus/stations`, with a code tarball);
- HostBRR `/opt/nbus/archive/20261110/` (old `stations`, `dwork`, `stageb`, `from_contabo_20261109`);
- Oracle `/home/ubuntu/nbus-archive/20261110/` (old `nbus-ctl` scripts, the status page, staged mods, and the Contabo code tarball).

The archive may be consulted only for **technical know-how** (block/NBT formats of mods, how Create contraptions are assembled, companion commands, the mistakes in Section 14) and old reference notes. It is never a source for designs or layouts. New code is written fresh in the new workspace.

---

## 5. The 4 types and platform rules

| Type | Tracks | Platforms | Access | Notes |
|---|---|---|---|---|
| **Basic** | **1 track only** | 1 side platform (6–8 wide) | Step-free from forecourt (platform on the building side, so no track crossing) | Separate Station Master's house on the platform side; ticket booth; no shops |
| **Standard** | **2 tracks only** | 2 side or 1 island | Footbridge **or** other design-appropriate means (subway or underground station allowed when the design calls for it, e.g. metro-inspired) | Ticket office, waiting room, toilets, small kiosk, staff area |
| **Mini Hub** | **3, 4 or 5 tracks** | Variable (any mix of side/island/bay) | Concourse + footbridge/subway/deck, lifts, escalators, stairs | Ticket-gate-ready lines (no barriers placed), 2–4 shops/cafés, info desk |
| **Super Hub** | **6 or more tracks** (tested up to 10+) | Variable | Multi-level concourse, multiple access routes | Grand amenities, staff complex, multiple restroom blocks, food court |

- Through / Bay (terminus) / Hybrid modes are chosen from the routes. Bays have buffer stops and a headhouse apron so passengers walk straight off the end.
- Platform counts are **genuinely variable**: the generator assembles hubs for any count in range (Mini 3–5; Super 6–12 at least), keeping the design's layout logic (e.g. New Street adds platforms in its cutting under a wider deck; Euston adds platforms under a longer concourse; Moor Street adds bays to the terminus side). **Moor Street Super Hub with 5+ platforms (Elie, 10 Nov):** may bring back the disused bay (platform 5) and add the new through platforms planned under **Midlands Rail Hub**, in the real station's pattern. Real numbering (research 10 Nov): platforms 1–2 = 1987 through platforms, 3–4 = restored GWR terminus bays, 5 = disused bay; one footbridge with a lift at each end.
- Stations may be single-level, multi-level, partly or fully underground, single or multi-floor buildings — chosen per design/type to fit the design.
- Basic/Standard track counts are fixed (1 / 2). Hub track counts come from the plan.

---

## 6. Universal design standards (every station, every design)

### 6.1 Circulation and space
- Logical progression: forecourt → entrance → unpaid concourse (tickets, info, shops, toilets) → gate line (planned, empty) → paid concourse / bridge / subway / deck → lifts + escalators + stairs → platforms. Every platform has at least two ways down/up (stairs + lift; escalators in hubs).
- **Goldilocks density**: no empty halls (Elie: New Street and others "feel empty"), no cramming. Concrete targets: circulation lanes 3–4 wide (Basic/Standard), 5–8 wide (hubs); ≥ 3 clear between platform furniture and the tactile strip; a furnished feature (kiosk, seating island, planter, info pillar, column grid) at least every ~12–15 blocks across large open floors; amenity count per type as 6.8.
- **Headroom**: ≥ 3 clear blocks above every walkable surface including **every stair tread and escalator step** (≥ 4 in grand halls/over stairs in hubs). Nothing — beams, signs, lights, ducts — lower than that anywhere a person walks. Stairs need a full-height stairwell opening above them.
- Stairs: ≥ 2 wide (3+ in hubs), landings every 8–10 steps in long flights, handrails/balustrades where open, never blocked at top or bottom (≥ 3 clear in front).
- No sudden holes or exposed underground parts: partly/fully underground stations integrate with terrain — proper portals, ramps, retaining walls, planted banks, light wells, skylights; **no raw pits or cut-outs in the ground** around them.
- Doors only where a wall needs one; **never a free-standing door**, never doors left over from removed elements, never doors that open into the path of the person entering (sliding doors' orientation checked), automatic entrance doors (pressure plates both sides or sliding doors) facing correctly.

### 6.2 Exterior and terrain
- 2–3 blocks of façade depth relief; proper roofs; name signage (modded boards); forecourt plaza with paving, drop-off, lamps, trees, benches, bins, bike racks; waystone garden off the forecourt end.
- Foundation skirts to terrain; cuttings lined (no bare earth); embankments planted; open space around the station is fine, but the transition to terrain must look built, never like a hole or a cliff.
- Track envelope always clear; catenary clearance 7–8 above top of rail under any structure on electrified lines.

### 6.3 Platforms
- Tactile strip one block from the edge (yellow), consistent with the design; canopies with real structure (no forest of 3-block posts — Euston mistake); benches, bins, clocks, PIDS/departure displays, help points; platform name/number boards at sensible spacing.
- No platform screen doors. Edge clear of obstacles by ≥ 3.

### 6.4 Signage and wayfinding (Section 9) — summary
Modded signs or generated custom art only; **no vanilla signs**; the right number of signs at decision points; arrows correct from where you stand; text never cut off; nothing hung low.

### 6.5 Lighting (Section 10) — summary
No hanging lamp clutter; integrated, switchable lighting controlled from the maintenance area; spawn-proof levels; hidden lights only if switchable.

### 6.6 Gates
Design the stations **around ticket gates** — gate lines planned with the right widths, housings, wide/accessible gate, staff positions — but **place no barriers** (Elie adds them later). No staff doors stranded in gate lines; the gap is clean and the fare-line check treats planned lanes as gates.

### 6.7 Staff and services
Staff/maintenance areas underground or out of sight: staff hall, dormitories (beds with 2 air above + floor beside), bell, breakroom, workshop, generator/plant room (Refurbished electricity), **lighting-control room with labelled zone switches**, security office/armoury. Villager routes never cross tracks; wooden doors only on villager routes; 2-wide corridors, 3 headroom.

### 6.8 Amenities and decoration (by type)
- Basic: ticket booth, 1–2 ticket machines, vending, shelter, clock, PIDS, bins, waystone (garden).
- Standard: ticket office, machines, waiting room, toilets (M/F/accessible), kiosk/coffee, vending, staff area.
- Mini: ticket hall (2–3 windows), machines, info desk, 2–4 shops/cafés, lounge, toilets, staff wing + security.
- Super: grand ticket hall, info pavilion, departures wall, 4–6 shops, 2–4 restaurants/cafés with kitchens, food court where the design suits (New Street/Grand Central), standard + first-class lounges, multiple toilet blocks, staff complex + garrison.
- Decoration fitting the design and real references: planters, art, clocks, heritage items (Moor Street's GWR details), maps, line maps, posters, bins, help points, vending — using the installed mods fully (Section 12).

### 6.9 Names, line maps, Station Builder
- Station and line names from the network naming tools (tokens filled at placement); generic tidy text for Station Builder copies.
- **Line maps** in every station (concourse + platforms): use a mod that supports them if one exists (research MTR route maps / other mods), otherwise generate custom map art (map items / painting textures / Big Station Signs boards) per station showing its lines and stops in line colours.
- **Station Builder**: every design × type × mode (and biome variants) exported with clean names so Elie can place any station any time; rotated placement repaired (rotfix) or documented.

### 6.10 Biome variants
Five palettes (temperate, desert, cold, swamp, blossom); historic designs swap materials regionally; modern/recreation designs keep signature materials and swap accents/planting/foundations. Recreations stay recognisable in every biome.

---

## 7. Mechanical systems

### 7.1 Lifts (overhaul)
- Problems seen: when the cabin is already at a floor, pressing the button didn't open both door sets; doors didn't close automatically on leaving; lifts bulky.
- **Test two options** on the test server and let Elie choose: (a) **Moving Elevators** mod (if installable on 1.21.1 NeoForge or via Connector) and (b) a **more compact Create elevator** (smaller shaft than the old 6×6, cabin ≥ 2×2×3 interior or design-appropriate, landing + cabin sliding doors). Build a lift test bay showing both, with a short write-up (reliability, size, look, villager/guard behaviour).
- Required behaviour either way: call button opens both door sets when the cabin is there; doors close automatically a few seconds after entry/exit and before moving; floor display; no exposed redstone/mechanics; works after rotated placement; survives server restarts; pathfinding-safe (villagers don't get stuck).

### 7.2 Escalators
- Many escalators didn't run. Root-cause (assembly, direction, motor, stress, chunk loading, rotation) and fix; up/down pairs; ≥ 3 clear above steps; never blocked at either end; an in-game test that confirms every escalator moves after placement.

### 7.3 Doors
Correct facing for all sliding/automatic doors; no stray doors; pressure plates both sides where used; lift landing doors behave as 7.1.

### 7.4 Electricity (stations)
Refurbished electricity network powers lights, computers, appliances from the plant room; with Phase C, station power can tie into the railway grid (optional).

---

## 8. NPCs — villagers and guards
- MCA villagers staff every workstation; beds with clearance; trades non-depleting and priced sensibly (13A).
- **Guards (all, regular and station)**: reduce **attack range** and **movement speed** (current values too high) — proposed: follow/attack range ~24–32, speed ~0.5× of current (Elie to confirm), applied to regular village guards and station guards.
- **Station guards**: tagged `nbus_station_guard`; **pistol only — remove swords** (TaCZ Glock 17 + 9 mm armoury chest); patrol posts covering the station and footpaths to the village; never on roofs/tracks; reachable posts.
- Stations near villages are part of the village: one MCA building per station (`/nbusmcabuilding`), footpath to the village with guard posts.
- Pathfinding: villagers/guards must reach every public area, staff area and exit; never path onto tracks or roofs (guards only onto roofs that are normally accessible); mobs don't spawn on roofs (lighting/slabs).

---

## 9. Signage and wayfinding — the full rulebook (Elie: "you've consistently messed up wayfinding")
1. **No vanilla signs** of any kind. Use MTR railway signs (multi-icon, combined arrows), Big Station Signs (port, `bigstationsigns:*`), Create: Station Essentials name signs (`tracksta:*`), UK Signs pack (MTR custom signs), and **generated custom art** where needed (custom MTR sign textures in a resource pack, map-art, painting variants).
2. **Right number of signs**: one clear sign (one face, several directions combined) at each decision point — entrance, gate line, top and bottom of each stair/escalator/lift, every footbridge/subway junction, each platform access point; platform number/name boards at platform ends and mid-platform. A per-type maximum and a minimum spacing are enforced by a check (13A); never clusters of hanging signs.
3. **Correct directions**: arrows computed from the final walk graph from where the reader stands, re-checked on the finished structure; every destination listed is actually reachable in the arrow's direction; platform numbers match the real platform numbering of that station; "Way out" leads out.
4. **Mounting**: walls, soffits, ceiling-flush or short rods — never long chains; bottom edge ≥ 3 blocks above the floor or stair tread below (≥ 4 in grand halls); never over a stair flight unless every tread keeps the clearance; never blocking lighting or views of departure boards.
5. **Text never cut off**: sign width chosen from the text length (Big Station Signs ≈ 3 characters per block; MTR sign widths per icon count); abbreviations only from an approved list; a check measures every text against its sign width.
6. Consistent style per design (colours, typeface family where the mod allows), consistent icons (toilets, lifts, tickets, exit, platforms, waystone).
7. Station name boards on the façade, entrances and every platform; line maps (6.9); departure boards (MTR PIDS) on concourses and platforms.

---

## 10. Lighting — the full rulebook (Elie: "way too many hanging lights")
1. **No hanging-lamp clutter**: chain-hung lamps only where period-correct (a few Victorian/Edwardian pendants or chandeliers in a grand hall) and capped (≈ 1 per 150 m² of ceiling, none on platforms).
2. Integrated lighting per design: recessed ceiling panels/strips, coves, wall sconces/uplighters, canopy-underside strips, column-integrated lights, step/floor lighting, back-lit panels, lamp posts outdoors — using mod lights (Refurbished Furniture, Create & addons, Supplementaries, Another Furniture, Macaw's, others if installed) and vanilla (redstone lamps, copper bulbs, froglights, sea lanterns behind panes/in recesses).
3. **Everything controllable** from the station's lighting-control room in the maintenance area (zone switches, labelled). Hidden light sources allowed **only** if they are switchable. Redstone never visible.
4. Spawn-proof: ≥ 11 indoors, ≥ 8 outdoors on every walkable cell; with all switches off, only emergency lighting (≤ 5) and sign glow remain.
5. Lights ≥ 3 above floors (except into-floor fittings); never over stair treads below headroom; never in front of signs.

---

## 11. Test server

### 11.1 Flat showcase
- Every design × type (and hub variants incl. bay/hybrid; biome variants in a separate row) placed **neatly with ≥ 32 blocks between bounding boxes — no overlaps** (8–9 Nov mistake), labelled, with walkways between.
- Each install: backup → wipe → place → assemble → in-game tests → backup + **mods zip** for download.

### 11.2 Real-terrain test circuit (may be a separate dimension — Claude's decision; a custom dimension with real-seed-like terrain is preferred if it makes generation fast and isolated)
- An area of real terrain big enough for the circuit but quick to generate (~100 chunks order of magnitude, adjust as needed).
- A **test circuit** including: one station of **each type** (design chosen at random per type), different junction types (simple turnout, double junction, flying junction/flyover, ladder crossover, scissors), a **long quad-track section**, and **two super hubs — one 6-track and one 10-track**; the 10-track hub has a **very complex, large junction** in and out (flyovers, dive-unders, grade separation) to show variable platforms working.
- A **long test train with multiple carriages** spawned and rideable around the circuit (Create train with controls / schedule); Elie rides it to feel the experience.
- Stations integrate with the terrain (see 6.2; no holes).
- Before each circuit iteration: **network diagram + track layouts of each station** published on the status page. The full circuit only has to exist in one iteration of the test world (later iterations may reuse it).
- Lift test bay (7.1) and escalator test.

---

## 12. Mods
- Use the installed mods fully so stations feel real: MTR 4.1, Create 6 + addons (Steam 'n' Rails, Train Parts, Railway Additions, Pantographs & Wires, Escalated, Station Essentials), Infinite Railways (companion-integrated), Refurbished Furniture, Macaw's, Another Furniture, Supplementaries/Amendments, Quark, Ultra Metro Decorations, Mezzos Railroad Blocks, Big Station Signs (port), Station Builder, TaCZ (+ guards support), Guard Villagers, MCA Reborn, Waystones, Farmer's Delight/Croptopia/etc., Vending Block, Electro Energetics (catenary), biome mods. Keep a machine-readable **block registry** (`docs/registry.json`) of every block id + properties actually available, built from the jars; the generator may only use ids in it.
- Claude may download mods (Modrinth/CurseForge, sha512 verified) and patch them when needed; every mod added to the test server is listed for production and goes into the AutoModpack host modpack.

---

## 13. Phase B and Phase C

### 13.1 Phase B — network + stations on production
- World already regenerated (same seed −5946453591199377425, spawn −2424 2535, 1024-chunk pregen done). Plan v12 (HostBRR `/opt/nbus/rebuild2/r31/preview_nov9p` incl. the new terminus): 77 stations, branches, 8+ main links, quad sections out of super hub A.
- **Super hub A = New Street design** (only A). **New terminus super hub #109 "Tidecliffe Harbour"** on the south-west landmass coastal village (−10656 10976), **Moor Street** design, 6 platforms (4 through + 2 bays), end of the SW main line. Other super hubs use the planner's normal design choice.
- Method (decided 9 Nov): Infinite Railways lays the planned network (companion planFile=true, networkPaused=false) and pastes our templates per station (`nbus_superhubs.txt`: `x z station:<id> tier dx,dz axis:side`); offsets in 64-block steps; quad track on straight sections; postplace: rotfix, `/nbusassemble`, names, footpaths + guard posts, `/nbusmcabuilding`.
- The old runner (archived; rebuild it fresh in `stageb/` of the workspace, using it only for know-how) was `stageb_go.sh <design>` (resumable, locked, per-section chunk backups, installs mods + companion + configs + Station Builder files, revertible with `revert_mods.sh`). Dry run must show 0 PROBLEM with the **final** templates.
- **Start only by Elie** (status page "Start Phase B", available when Phase A is finished and every readiness check is green). Not armed until then.

### 13.2 Phase C — electrification (prepare now, build after Phase B)
- Track electrification fully integrated and operational with **Electro Energetics** catenary via Infinite Railways (catenaryMod set; revertible).
- **Research** the power needed (per train, per km, per substation range in the mods' units) and size the system: few substations (not too big, not too small) along lines and in some villages, possibly one **central power plant** feeding them.
- **Finite fuel**: large stocks lasting a very long time (target weeks/months of real play), but refuelling eventually needed; design so refuelling is rare and convenient (central plant, fuel depots, rail-delivered fuel optional).
- Deliverables before building: power study, substation design (in a matching architectural style), placement plan, refuel procedure, test on the circuit.

---

## 13A. Standing rules carried over from 7–9 Nov (still valid)
- **Tier placement (Elie, 8 Nov):**
  - Basic only on single-track branch lines, at small to medium villages.
  - Standard is the most common: main lines, and branch lines at medium to large villages.
  - Mini Hub is less common: main lines only, favouring junctions where a few lines meet, at medium to large villages.
  - Super Hub is the least common: main lines only, at junctions where many lines meet, at large to very large villages.
  - The network must allow many lines to meet, but rarely. Engine: HostBRR `/opt/nbus/rebuild2/r31/tiers.py`.
- **Station Master's house (Basic):**
  - Separate cottage on the same side of the tracks as the platform.
  - Covered, lit footpath to the platform and booth.
  - Generator room in its basement or shed.
  - Its stairs must have proper headroom.
- **Clock towers:**
  - Elie's 11-wide dial from his schematic, on four faces.
  - Clockwork-bearing hands, glued; 12 glow-frame markers.
  - Use them where the design has a tower.
- **Shops and trades:**
  - Each shop's villager sells what its sign says, using vanilla, Croptopia and Farmer's Delight items.
  - Trades never run out (999 uses), give no XP and never level up.
  - The ticket office sells Single, Day Return and Season tickets, minecarts, and the "Network Guide" book (every line with its colour chip, termini and stops).
  - Vending machines (Vending Block: Restocked, 2×2 cases, infinite stock): Elie still has to OK them for production.
- **Waystones:** each station has its own waystone garden off the forecourt end; no waystones inside halls.
- **Tidiness:**
  - No floating panes, signs or lone blocks; lintels over doors (no gaps).
  - No grass between adjacent tracks; no bare earth in cuttings.
  - Exterior doors are automatic, with pressure plates on both sides.
  - Outdoor platforms, stairs and paths are covered by canopies or overhangs, so snow never blocks them.
- **Footbridges:** the number per station follows the design and its references. Moor Street has exactly one. Extra footbridges at the ends of long platforms only where the design allows it.
- **Names:**
  - Line and station names in a British-railway voice, with colours and codes per line.
  - MCA village names are used where the world has them.
  - Tokens are filled at placement (`applynames`); no raw `{STATION}` tokens are ever visible.
- **Wayfinding:**
  - Elie got lost before. At every subway or footbridge junction, every stair head shows which platform it serves and where it goes.
  - Platform numbers are visible from the concourse and from the bridge or subway.
  - Hard caps on sign faces by tier: Basic ≤ 8, Standard ≤ 20, Mini ≤ 40, Super ≤ 70.
  - Minimum spacing of 8 blocks between signs, except at the same decision point.
- **Rotated placement:** it breaks Refurbished electricity links and lift call buttons, so `rotfix` must repair them. Wire positions must be added when electric motors go in.
- **Mods and downloads:**
  - AutoModpack must never be removed from the test server's mods.
  - Every test-server-only mod is listed for production and also goes into Elie's PC "Server Files" instance.
  - The world download comes with a mods zip laid out to drop straight into the AutoModpack folder.
- **Test cycle:**
  1. A passing build installs on its own.
  2. The world is backed up and the download published.
  3. The world is wiped and the next rebuild starts immediately, offline.
  4. While a new build is being made, the last good build stays live on the test server.
- **Lighting:**
  - Spawn-proofing must not rely on unswitchable hidden light blocks under carpets or slabs.
  - No torch or glowstone spam.

## 14. Catalogue of past mistakes (each must have a rule + check that prevents it)

| # | Mistake (seen by Elie) | Prevention |
|---|---|---|
| 1 | Lifts: button didn't open both doors when cabin present; doors didn't auto-close | 7.1 behaviour + in-game lift test |
| 2 | Escalators not running | 7.2 + in-game escalator test |
| 3 | Too little headroom on stairs; signs low over stairs | 6.1 headroom check incl. treads; sign clearance check |
| 4 | Too many signs, clusters on chains, wrong arrows, cut-off text, vanilla signs | Section 9 + signcheck (count, spacing, clearance, text-fit, correctness, no vanilla) |
| 5 | Too many hanging lights | Section 10 + hanging-lamp cap check |
| 6 | Random doors (birch door + block in New Street; staff doors stranded in gate lines) | 6.1/6.6 + free-standing/stray door check |
| 7 | New Street entrance sliding doors facing wrong way, blocking entry | Door-orientation check + in-game entry test |
| 8 | Stations feel empty / some cramped | 6.1 density targets + check (max empty-floor run, lane widths) |
| 9 | Poor recreations (Moor Street two footbridges; Euston 3-block posts everywhere; New Street not 1:1) | Reference-driven design specs (Phases 0/2) reviewed against the reference dossier before coding |
| 10 | Layouts all feel the same across designs/types | Section 4/5 + layout-diversity review in the design phase |
| 11 | Stations overlapping on the test server | 11.1 spacing check in placement |
| 12 | Sudden holes / out-of-place underground parts | 6.2 terrain integration rules + check of exposed cut faces |
| 13 | Ticket barriers placed / then staff doors left behind | 6.6 |
| 14 | Station guards too strong/fast; swords | Section 8 |
| 15 | Half-finished helper edits deployed overnight | 3.1 git + tagged releases only |
| 16 | Hold auto-released by a timer | 3.2 one orchestrator; no timed releases |
| 17 | Status page confusing (two builds at once, stale numbers, false alarms) | 3.4 rebuild + dedup alerts |
| 18 | Invisible light blocks broke lights-off check; re-running brighten broke lighting | Section 10 + full suite before merge |
| 19 | Path test counted fake routes (tracks, furniture tops, carpets, roofs, sealed voids) | Path test uses generator-intended destinations + strict floor rules |
| 20 | Watchdog false alarms (worker "silent" while busy; path test "stalled" while a sample ran) | Heartbeats during work; alerts tied to orchestrator state |
| 21 | Killing own shell with `pkill -f` / an awk pattern matching its own command (happened again 10 Nov) | 2.3 |
| 22 | Desktop Commander quota drained by polling | 2.2 / 3.5 |
| 23 | Name boards/placeholder tokens visible ({STATION}) in Station Builder copies | applynames for every export; check for raw tokens |
| 24 | Platform screen doors (must not exist) | 4 / 6.3 + check for PSD block ids |
| 25 | Station Master's house stairs lacked headroom | 6.1 headroom check covers every building |
| 26 | AutoModpack deleted by the test-server reset, so Elie couldn't join ("channel missing") | 13A; setup never removes AutoModpack |
| 27 | Glue boxes and item frames moved by entity settling, so lifts failed to assemble ("no_contacts") | Entities with a fixed position are never moved; sanity check on the glue box |
| 28 | Build log on the status page stopped updating; it was unclear which build was live and what came next | 3.4 live log and "now / next" summary |
| 29 | Stations not tested against the real platform numbering, so he got lost at the subway or footbridge | 13A wayfinding + an in-game walk test |

---

## 15. Phase plan, models and handoffs (details in `docs/plan.md`)

### 15.1 Phases
- **Order (renumbered 10 Nov 19:24): Phase 0 Research → Phase 1 Infrastructure → Phase 2 Design specs → Phase 3 Generator → Phase 4 Test world** (0–4 together = **Phase A**) **→ Phase B → Phase C → Phase Z.** The cleanup reset itself (pause, archive, master prompt, plan, new workspace) was done on 10 Nov before Phase 0.
- **Phase 0 — Deep research** (before any design work): reference dossiers for all 10 designs — images, videos, plans/schematics, 3D models, Minecraft worlds/schematics; for the 3 recreations extra thorough: every façade, interiors, concourses, platforms, platform access (stairs/escalators/lifts/bridges/subways), amenities, decorations, lifts; plus systems research (line maps, signage systems, real-station lighting, Moving Elevators vs compact Create lifts, junction types, electrification power). Old reference notes in the archive may be reused as references (never as designs).
- **Phase 1 — Infrastructure**: orchestrator, job queue with work stealing, Windows worker, status page with controls, block registry, guard changes (companion). May overlap Phase 2.
- **Phase 2 — Design specs**: for each design × type, a written + drawn spec (plan, sections, levels, circulation, amenities, materials, lighting, signage plan) checked against the dossier and the mistake catalogue; layout-diversity review across all 40 combinations; Elie reviews key specs (recreation super hubs first).
- **Phase 3 — Generator implementation**: implement specs on branches; full checks; merge per design.
- **Phase 4 — Test world**: flat showcase + real-terrain circuit (network diagram + track layouts first), test train, lift/escalator tests; Elie's play-test; fix loop.
- **Phase B — Production network + stations** (Elie starts it).
- **Phase C — Electrification** (research/prep during Phases 2–4; build after B).
- **Phase Z — Wrap-up**: move everything off Contabo, remove TEMP keys/worker, final docs.

### 15.2 Models and effort (recommendation; Elie switches the main session's model, Claude chooses helper models)
- Claude can choose the model of each helper itself (Sonnet/Opus/Haiku/Fable); the main conversation's model and effort are set by Elie.
- Fable costs much more usage than Opus, so it is reserved for the work where judgement matters most.
- **Phase 0 (research)**: Opus, medium, with Sonnet helpers.
- **Fable, high effort**: Phase 2 design specs (layouts, recreations, diversity), hard debugging, final reviews.
- **Opus, medium–high effort**: Phase 1 and Phases 3–4 implementation and integration into Minecraft (generator code, companion mod, checks), Phase B/C engineering.
- **Sonnet helpers, medium effort**: web research collection, bulk reference cataloguing, mechanical refactors, writing scripts to a clear spec, test-run triage.
- **Haiku / low effort**: routine status checks and simple file operations (rarely needed once the orchestrator runs on its own).
- At each phase boundary Claude stops, writes the handoff note, and tells Elie which model/effort to switch to.

### 15.3 Definition of done (Phase A = Phases 0–4)
All 40 design×type combinations (+ hub variants, modes, biomes) build with 0 FAIL on every check; in-game path, lift, escalator, door and train tests pass; Elie's play-test feedback items all closed; Station Builder export complete; downloads published; Phase B dry run 0 PROBLEM with final templates.