OpenPerpetuum · Sellafield · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/docs/backlog/completed.md b/docs/backlog/completed.md
@@ -836,3 +836,63 @@ Enforced a same-IP gate on season activity recording so that a player running mu
 
 ### Notes
 Vendor market fills (no player counterparty) record without gate. `buyOrderPayBack` and `CashInOnSubmit` (no counterparty) left ungated. NAT false-positive limitation documented in spec.
+
+---
+
+## ISSUE-034 - Stale references in CLAUDE.md and docs/codebase misdirect contributors
+
+Status: DONE
+Priority: MEDIUM
+Area: Documentation
+
+### Problem
+Three sets of references in `CLAUDE.md` did not match the repository: the documented run command used a `--GameRoot` option that `Program.cs` does not define, eight `docs/` paths pointed at files that live under `docs/codebase/`, and `.claude/knowledge/architecture.md` was referenced twice but does not exist.
+
+The same `--GameRoot` mistake also appeared in three files under `docs/codebase/`, which the original entry did not cover: the manual-testing command in `TESTING.md`, the CLI description in `STACK.md`, and the entry-point description in `STRUCTURE.md`.
+
+### Impact
+`CLAUDE.md` is the instruction file for agent-assisted work, so a wrong path or command is followed rather than questioned. The documented run command could not succeed, and ten path references resolved to nothing.
+
+`docs/codebase/` is the authoritative documentation set, and `TESTING.md` is where a contributor looks for how to validate a change — with no automated test suite in the repository, running the server by hand is the only validation path there is, and the command given for it did not work.
+
+### Fix
+1. Run command changed to the positional form, `dotnet run -- "<path>"`, matching `app.Argument("<GAMEROOT>", ...)` in `src/Perpetuum.Server/Program.cs`.
+2. The eight `docs/` paths prefixed with `codebase/` — six in Authoritative Documentation plus the repeats under Technical Debt Rules and Code Placement.
+3. Both `.claude/knowledge/architecture.md` references repointed at `docs/codebase/ARCHITECTURE.md` rather than creating the missing file, so the architecture documentation keeps a single source of truth.
+4. The three `docs/codebase/` occurrences corrected: `TESTING.md` now shows the positional command, and `STACK.md` and `STRUCTURE.md` describe the argument as positional `<GAMEROOT>` instead of an option.
+
+### Files Changed
+- `CLAUDE.md` — lines 44, 56, 77, 80, 83, 86, 89, 92, 222, 316, 331 as of `b8d2ec2`
+- `docs/codebase/TESTING.md` — line 34 as of `f9ddac2`
+- `docs/codebase/STACK.md` — line 53 as of `f9ddac2`
+- `docs/codebase/STRUCTURE.md` — line 194 as of `f9ddac2`
+
+### Notes
+The `CLAUDE.md` part merged in PR #20; the three `docs/codebase/` files were corrected afterwards, in the same change that moved this entry here.
+
+`--GameRoot` remains valid for `Perpetuum.ServerService2`, which reads `GameRoot` from `appsettings.json`, and was left alone. Every backticked path in `CLAUDE.md` was resolved against the working tree afterwards; `Commands.cs`, `completed.md` and `graph.json` still do not resolve because they are bare filenames used in prose, not paths.
+
+Five further occurrences of the old command survive under `docs/superpowers/plans/`. Those are dated records of plans that were already carried out, so they were left untouched rather than rewritten after the fact.
+
+---
+
+## ISSUE-033 - FreeRoamingPathFinder throws on presences with no flocks
+
+Status: DONE
+Priority: LOW
+Area: NPC AI / Logging
+
+### Problem
+`TryGetMaxHomeRange` called `presence.Flocks.Max(f => f.HomeRange)` and `TryGetMinSlope` called `presence.Flocks.GetMembers().Min(m => m.Slope)`. On an empty sequence LINQ raises `InvalidOperationException: Sequence contains no elements`, which the surrounding `try/catch` swallowed after writing a full stack trace through `Logger.Exception`.
+
+### Impact
+A presence with no flocks is a normal state, so each one emitted a stack trace during zone startup — exception handling used as ordinary control flow, and traces that make genuine faults harder to spot.
+
+### Fix
+Project the value with `Select`, then supply the fallback with `DefaultIfEmpty` before aggregating. The fallbacks are the values the `catch` blocks already returned, so behaviour is unchanged: `10` before `Clamp(10, 40)` for the home range, `ZoneExtensions.MIN_SLOPE` for the slope. The `try/catch` and the `Logger.Exception` calls stay, still covering genuinely unexpected failures.
+
+### Files Changed
+- `src/Perpetuum/Zones/NpcSystem/Presences/PathFinders/FreeRoamingPathFinder.cs` — `TryGetMaxHomeRange`, `TryGetMinSlope`
+
+### Notes
+Merged in PR #19. Validated against a local P36 server, since there is no automated test suite: the pre-fix startup log carried 8 `Sequence contains no elements` traces, all from `TryGetMaxHomeRange`, and the post-fix log carries none while still spawning 6406 flock members and reaching `[Online]`.
diff --git a/docs/backlog/issues.md b/docs/backlog/issues.md
@@ -29,45 +29,7 @@ Reproduced against SQL Server 2022 Express, named instance, Windows integrated a
 
 `TrustServerCertificate=True` disables server certificate validation. It is appropriate for a local development instance only and must not be carried into a deployment where the connection leaves the machine.
 
-## ISSUE-034 - CLAUDE.md contains stale references that misdirect contributors
-
-Status: TODO
-Priority: MEDIUM
-Area: Documentation
-
-### Problem
-Three sets of references in `CLAUDE.md` do not match the repository:
-
-1. Build & Run documents `dotnet run -- --GameRoot "<path>"`. `src/Perpetuum.Server/Program.cs` declares the game root as a positional argument via `app.Argument("<GAMEROOT>", ...)`, so the option does not exist and the run fails with `Unrecognized option '--GameRoot'`. The working form is `dotnet run -- "<path>"`.
-2. Eight `docs/` references point at files that do not exist. Authoritative Documentation links `docs/CONCERNS.md` (line 77), `docs/CONVENTIONS.md` (80), `docs/INTEGRATIONS.md` (83), `docs/STACK.md` (86), `docs/STRUCTURE.md` (89) and `docs/TESTING.md` (92); Technical Debt Rules links `docs/CONCERNS.md` again (222) and Code Placement links `docs/STRUCTURE.md` again (316). All six files live under `docs/codebase/`. Only the `ARCHITECTURE.md` entry (74) already points there.
-3. `.claude/knowledge/architecture.md` does not exist and is referenced twice: as the file to update when introducing major architectural changes (line 44), and as the architecture deep-dive in the Where to Edit table (331). `.claude/knowledge/` contains only `codebase-graph.md`.
-
-### Impact
-`CLAUDE.md` is the instruction file for agent-assisted work, so a wrong path or command is followed rather than questioned. The documented run command cannot succeed, and ten path references resolve to nothing — eight under `docs/` and two under `.claude/knowledge/`.
-
-### Proposed Fix
-Correct the run command to the positional form and prefix the eight `docs/` paths with `codebase/`. The two `.claude/knowledge/architecture.md` references need a maintainer decision: repoint them at `docs/codebase/ARCHITECTURE.md`, which already holds the architecture documentation, or create the missing file.
-
-### Notes
-`--GameRoot` remains valid for `Perpetuum.ServerService2`, which reads `GameRoot` from `appsettings.json`; only the `Perpetuum.Server` console entry point takes it positionally. Line numbers are against `CLAUDE.md` at `b8d2ec2` (P36.7). `Commands.cs` and `completed.md` also appear in the file, but as bare filenames in prose rather than paths.
-
-## ISSUE-033 - FreeRoamingPathFinder throws on presences with no flocks
-
-Status: TODO
-Priority: LOW
-Area: NPC AI / Logging
-
-### Problem
-`FreeRoamingPathFinder.TryGetMaxHomeRange` calls `presence.Flocks.Max(f => f.HomeRange)` and `TryGetMinSlope` calls `presence.Flocks.GetMembers().Min(m => m.Slope)`. When the sequence is empty, LINQ raises `InvalidOperationException: Sequence contains no elements`. The surrounding `try/catch` swallows it, writes a full stack trace through `Logger.Exception`, and returns the fallback value.
-
-### Impact
-A presence with no flocks is a normal state, not a fault, so each one emits a stack trace during zone startup. Exception handling is used as ordinary control flow on a per-presence path, and the resulting traces make genuine faults harder to spot in the log.
-
-### Proposed Fix
-Project the value and use `DefaultIfEmpty` so the empty case yields the fallback without throwing, keeping the `try/catch` for genuinely unexpected failures.
-
-### Notes
-Observed during startup against a P36 database. Existing behaviour must be preserved: empty flocks yield `10` after `Clamp(10, 40)`, and empty members yield `ZoneExtensions.MIN_SLOPE`.
+---
 
 ---
 

diff --git a/docs/codebase/STACK.md b/docs/codebase/STACK.md
@@ -50,7 +50,7 @@
 - `System.Text.RegularExpressions` 4.3.1 — regex utilities (referenced in all projects)
 
 **CLI:**
-- `McMaster.Extensions.CommandLineUtils` 4.1.1 — `--GameRoot` argument parsing in `src/Perpetuum.Server/Program.cs`
+- `McMaster.Extensions.CommandLineUtils` 4.1.1 — positional `<GAMEROOT>` argument parsing in `src/Perpetuum.Server/Program.cs`
 
 **Crypto:**
 - RC4 stream cipher: custom implementation at `src/Perpetuum/Rc4.cs`

diff --git a/docs/codebase/STRUCTURE.md b/docs/codebase/STRUCTURE.md
@@ -191,7 +191,7 @@ src/Perpetuum.RequestHandlers/
 ## Key Files
 
 **Entry Points:**
-- `src/Perpetuum.Server/Program.cs` — console entry; parses `--GameRoot`, calls `bootstrapper.Init/Start`
+- `src/Perpetuum.Server/Program.cs` — console entry; takes the game root as a positional `<GAMEROOT>` argument, calls `bootstrapper.Init/Start`
 - `src/Perpetuum.ServerService2/` — Windows service wrapper for the same bootstrapper
 
 **Bootstrap:**

diff --git a/docs/codebase/TESTING.md b/docs/codebase/TESTING.md
@@ -31,7 +31,7 @@ The team tests by running the server locally against a configured `GameRoot`:
 
 ```bash
 cd src/Perpetuum.Server
-dotnet run -- --GameRoot "E:\PerpetuumServer2\data"
+dotnet run -- "E:\PerpetuumServer2\data"
 ```
 
 Manual verification involves: