# Settled decisions, rules of the road, traps

## Owner decisions (2026-10-14) — settled, do not relitigate

1. **Delivery mechanism = Default Options** (+ enforced `config/modernfix-mixins.properties`
   **after B6 passes**). Done in `a01bc3b`.
2. **Puzzles Lib 21.1.64** — done (bugfix only; no NeoForge perf change, LEVERS #14 corrected).
3. **Shaders: opt-in** (packwiz downloads them; nothing enables them). B7 produces the
   policy data; owner decision still pending that data.
4. **Spawn tuning allowed if not detrimental to gameplay** — done, moderate
   (`d80f85b`: alexsmobs/fowlplay/crittersandcompanions partial files). B14 measures it.
5. **Remove no mods.** LEVERS §5 removal candidates are reference only.
   (This includes WATUT — so the WATUT crash must be fixed, not removed away.)
6. **Add any helpful mods** — the five Add-verdict mods went in `a01bc3b` (Sodium Extra,
   Reese's Sodium Options, BadOptimizations, Particle Core, + Default Options).
   Trial mods are B12b's call; the agent may add trial winners.

## Rules of the road (iteration rules from the journal)

- Change tuned defaults **only** via `analysis/client-perf/proposed-configs/build.py`
  (DEFAULT / DECK / HIGH layers) → `build.py --ship` → `packwiz refresh` → commit.
  Never hand-edit `proposed-configs/out/*` or shipped files.
- Shipped defaults are **copy-if-absent**: changes reach fresh installs only. Existing
  players follow PLAYER-TUNING §1 (delete 7 re-seeding config files; do NOT delete
  `options.txt`; set tier video values by hand).
- **`git checkout -- config/` before staging** — the server's mods re-save partial
  spawn files in full on boot; committing those expansions is the known mistake.
- `packwiz update` in bulk resets hand-set `side = "server"` on **petprotect,
  c2me-neoforge, noisium**. Single-mod updates are safe.
- Any new mod: verify NeoForge 1.21.1 build + `neoforge.mods.toml` ranges against pins,
  check `side`, then **re-run B0** (new mod set invalidates the noise floor).
- One recorded commit per matrix row; label all data as **proxy-machine** data.
- Never kill the dedicated server (tmux `onion-mc`, repo root, port 25565) and never
  touch `world/`. `sp-world.tar.gz` (650 MB, untracked) — leave alone.
- `.pi/journal.md` is the running log — append a session entry when you finish.

## Verified facts / traps (don't re-derive, don't re-trip)

- **packwiz `preserve`**: settable only by hand-editing `index.toml`; survives refresh
  and unrelated updates; silently dropped if the file is absent/ignored at refresh
  time; installer writes the file only if absent. Index files have no `side`, so
  shipped configs land on the server too (this repo IS the server).
- **Default Options 21.1.8**: copy-if-absent for `config/defaultoptions/options.txt`
  (key_ lines stripped) and `config/defaultoptions/extra/**`; runs before NeoForge
  constructs mods — too late for `modernfix-mixins.properties` (hence B6 gating).
- Observed defaults were generated from the **same jar versions as current pins**
  (DH 3.3.2, Sodium 0.8.13, EMF 3.3.9, Create 6.0.10/Flywheel 1.0.6, Sable 2.0.5,
  SPR 1.5.1). DH `numberOfThreads` true default = ceil(nproc/2) = 4 here (observed 2
  came from a 4-thread box).
- Flywheel 1.0.x **disables both GPU backends when any shaderpack is active**
  (verified in `Backends.java`). No Iris Flywheel Compat in the pack (B12b trial).
- SSRD 1.8.7 → `config/ssrd-common.toml` (COMMON; server reads it too; slider floor 16).
  LambDynamicLights 4.8.11 → `config/lambdynlights.toml` (lowercase modes).
  SPR merges partial `sound_rates.properties` over generated defaults.
- **More Culling is unusable**: its NeoForge build declares `minecraft [1.21,1.21.1)`.
- `-XX:ShenandoahGCMode=iu` aborts JDK 21 without UnlockExperimentalVMOptions — J3 uses
  plain `-XX:+UseShenandoahGC`.
- Prism 11 `--offline` fails a fresh instance ("Required libraries are missing");
  launch online once, then offline works.
- `xdotool windowactivate --sync` hangs under kwin — use `windowactivate` +
  `windowfocus`.
- MangoHud needs `MANGOHUD_CONFIG` explicit + LD_PRELOAD exported — use the wrapper
  `~/.local/bin/mangohud-local`; system mangohud is not installed.
- cdn.modrinth.com 501s Range requests — download whole jars. No `unzip`; use python
  zipfile. `lodestonelib` is the real slug (`lodestone` has no 1.21.1 build).
- Duplicate `version_number` traps: tarotcards-remastered, room-for-two, too-many-bows
  reuse version strings across MC versions — pin exact filenames by hand.
- Iris 1.8.14-beta.1 ↔ Sodium 0.8.13 mixin incompatibility reported on NeoForge
  (r5) — check when testing shaders (B7).

## Open owner-facing deliverables (owed from Phase 2)

- B7 shader-policy data → owner decision on default-off vs opt-in messaging.
- B12b trial-mod verdicts (which trials earned a permanent add).
- B14 spawn-tuning measurement (keep/back-off call).
- Any B13 "mod >5% of render thread" findings.