docs(context): merge sim context into one coherent doc; refresh crawler and root

sim/context.md was the M1 graph doc with an M2 appendix bolted on
(state.go listed twice); now one structure covering all files, the full
Step pipeline, determinism, and admin mutations. crawler/context.md
gets the graph-semantics notes consumers need (directed-exit weights,
room-id assumption, exits-only connectivity) and a current consumers
section. Root context.md documents the embedded FS.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: pruuk

context.md

@@ -11,7 +11,10 @@ All fields of `weatherModule` are touched only from the single game-loop
 goroutine — no synchronization needed.
 
 ## Key Components
-- **weather.go**: `weatherModule` struct (plug, cfg, graph, started, simReady,
+- **weather.go**: the `files` embed.FS (`//go:embed files/*` — the config
+  overlay plus `datafiles/` mutator specs and emote tables; the engine loads
+  `mutators/*` from it via the plugin registry, `content` loaders read the
+  rest). `weatherModule` struct (plug, cfg, graph, started, simReady,
   simCfg, climate, tables, state, nextTick, nextEmote). `init()` → `plugins.New`
   + `AttachFileSystem` + `SetOnLoad`, then registers the `weather` command as a
   **player** command (not admin-only; admin subcommands are gated in-handler) and

crawler/context.md

@@ -43,7 +43,23 @@ type WorldReader interface {
 ## Options
 - `IncludeSecretExits bool`, `ExcludeZonePatterns []string`,
   `BuiltAtRound uint64`. `DefaultOptions()` enables secret exits and excludes
-  `instance_*` / `ephemeral_*`.
+  `instance_*` / `ephemeral_*`. `IncludeSecretExits` is wired to module config;
+  `ExcludeZonePatterns` is not yet a config key (M4 follow-up) — consumers get
+  the defaults.
+
+## Graph semantics consumers should know
+- **Edge weight counts *directed* exits, not connections.** Every room-exit
+  crossing a zone border adds 1, so a normal two-way border reads `weight: 2`
+  (one exit each way). Treat weight as a "border width" proxy; halve it for a
+  connection count.
+- **Room→zone resolution assumes zones don't share room ids.** Each room id
+  maps to one zone; if an id were reported under two zones, the mapping (and a
+  few edges) could vary between runs. Real worlds don't do this —
+  `WorldReader.RoomIDs` returns disjoint sets per zone — noted only for
+  `WorldReader` adapter authors.
+- **Exits are the only connectivity source.** Zones reachable solely by
+  teleport or scripted movement get no edges; they form separate components
+  with independent weather.
 
 ## Dependencies
 - `github.com/GoMudEngine/GoMud/modules/weather/sim` (the `Graph` types).
@@ -54,8 +70,10 @@ type WorldReader interface {
   `fakeReader`: adjacency, weights, secret-exit option, zone exclusion, node
   metadata, components, and an end-to-end cache round-trip.
 
-## Status
-M1b is complete: the live `engine.WorldReader` (over `internal/rooms`), the
-`weather graph` / `weather rebuild` admin commands, and cache persistence are
-implemented (see the `engine` and root `weather` packages). Future milestones
-(M2+) add the weather simulation that consumes this graph.
+## Consumers
+- The module root calls `Build` (via `engine.NewWorldReader()`) on the first
+  round after boot and from `weather rebuild`; the result is cached through
+  `plugin.WriteBytes` and feeds the entire weather simulation (`sim.Step`,
+  coverage queries, zone resolution). The crawler itself is milestone-complete;
+  changes here are only needed if graph semantics change (e.g. future
+  directional edge metadata for prevailing wind).

sim/context.md

@@ -1,25 +1,40 @@
 # sim Package Context
 
 ## Overview
-`sim` is the pure, engine-independent core of the weather module. It holds the
-geography `Graph` that the crawler produces and the weather simulation will
-consume. Nothing here imports the GoMud engine (`internal/*`) — a rule enforced
-by `arch_test.go` — so the simulation stays unit-testable without a running
-server and portable across GoMud and DOGMud.
+`sim` is the pure, engine-independent core of the weather module: the geography
+`Graph` (produced by `crawler`, consumed everywhere) and the deterministic
+weather simulation that runs on it. Nothing here imports the GoMud engine
+(`internal/*`) — enforced by `arch_test.go` — and the package is stdlib-only,
+so everything is unit-testable without a server and portable across GoMud and
+DOGMud. All randomness flows through a serializable PRNG carried in `State`,
+making every run exactly reproducible from a seed.
 
 ## Key Components
 ### Core Files
-- **graph.go**: the `Graph`, `ZoneNode`, and `Edge` types; the `GraphVersion`
-  constant; JSON cache serialization (`ToJSON` / `FromJSON`); `Zones()`;
-  `Neighbors` (lazy adjacency index); and `FindZone` (case-insensitive lookup).
-- **state.go**: `NewState` / `DeriveSeed` (FNV-1a over sorted zone names); and
-  the persistence codec `ToJSON` / `StateFromJSON`.
-- **query.go**: `Coverage` and `Covering` — front-projection query that mirrors
-  `resolveWeather`'s coverage rule.
-- **mutate.go**: `ForceSpawn` and `ClearZones` — pure admin-action mutators (no
-  RNG consumed).
-- **arch_test.go**: architecture guardrail — fails if any file in this package
-  imports a `GoMudEngine/GoMud/internal` path.
+- **graph.go**: `Graph`, `ZoneNode`, `Edge`; `GraphVersion`; JSON cache codec
+  (`ToJSON`/`FromJSON`); `Zones()` (sorted, for deterministic iteration);
+  `Neighbors` (lazy adjacency index); `FindZone` (case-insensitive lookup).
+- **rng.go**: `RNG` — serializable splitmix64 PRNG; its entire state is one
+  `uint64` cursor (`State.RNGState`).
+- **weather.go**: core value types — `WeatherType` (open, data-driven; `Clear`
+  is the calm baseline), `ZoneId` (= `string`), `FrontId`, `Front`, `State`,
+  `Clock`, `ZoneChange`, `StateDiff`; `clamp01`.
+- **climate.go**: `ClimateProfile`/`WeatherInfluence`/`Climate` (biome →
+  weather weights, terrain influence, spawn weight); `Climate.For` (falls back
+  to the `"default"` profile); `DefaultClimate()` (built-in profiles for the
+  standard biomes); `Config`/`DefaultConfig()` (front budget, spawn chance,
+  history length, hard age cap, coverage falloff/threshold/radius).
+- **tick.go**: `Step` — the simulation tick — and its helpers (`ageAndFeedback`,
+  `moveFronts`, `evolveTypes`, `removeDead`, `spawnFronts`, `resolveWeather`,
+  `zonesWithin`, `diffWeather`, weighted-pick helpers).
+- **state.go**: `NewState`/`DeriveSeed` plus the `State` persistence codec
+  (`ToJSON`/`StateFromJSON`).
+- **query.go**: `Coverage`/`Covering` — read-only front-projection query that
+  mirrors `resolveWeather`'s coverage rule exactly (a consistency test pins
+  them together).
+- **mutate.go**: `ForceSpawn`/`ClearZones` — pure admin-action mutations.
+- **arch_test.go**: purity guardrail — fails if any file imports a
+  `GoMudEngine/GoMud/internal` path.
 
 ### Key Structures
 ```go
@@ -38,98 +53,120 @@ type Graph struct {
     Nodes        map[string]ZoneNode
     Edges        []Edge
     Components   int                   // connected-component count
-    // adj is a lazy adjacency index; nil after FromJSON, rebuilt on first Neighbors call.
+    // + unexported adj: lazy adjacency index; nil after FromJSON,
+    //   rebuilt on the first Neighbors call (not serialized).
+}
+type Front struct {                    // one traveling weather system
+    Id        FrontId
+    Type      WeatherType
+    Zone      ZoneId    // center
+    Intensity float64   // 0..1; <= 0 means death
+    Moisture  float64   // 0..1
+    Age, MaxAge int     // soft cap; past MaxAge decay accelerates
+    History   []ZoneId  // bounded recent path (no immediate backtrack)
+}
+type State struct {                    // full sim state — serializable
+    Round    uint64
+    RNGState uint64                    // PRNG cursor
+    NextID   FrontId
+    Fronts   []Front
+    Weather  map[ZoneId]WeatherType    // resolved per-zone weather
 }
 type Coverage struct {
     Front     Front
     Effective float64  // projected intensity at the queried zone
-    Hops      int      // graph distance from the front's centre
+    Hops      int      // graph distance from the front's center
 }
 ```
 
 ## Core Functions
-- `(*Graph) ToJSON() ([]byte, error)` / `FromJSON([]byte) (*Graph, error)` —
-  the on-disk cache format (indented JSON). `GraphVersion` lets a loader detect
-  a stale cache and rebuild.
-- `(*Graph) Zones() []string` — sorted zone names for deterministic iteration.
-- `(*Graph) Neighbors(zone string) []Edge` — adjacent zones, each Edge oriented
-  from the queried zone (`Edge.A == zone`). Returns a **shared slice** from a
-  lazily-built index; callers MUST NOT mutate it — copy before sorting. Returns
-  nil for unknown or isolated zones. The adjacency index is rebuilt lazily after
-  `FromJSON` (the `adj` field is not serialized).
-- `(*Graph) FindZone(name string) (string, bool)` — case-insensitive zone
-  lookup; exact match wins over a fold-equal match.
-- `NewState(seed uint64) State` — initial simulation state for a fresh run.
-- `DeriveSeed(g *Graph) uint64` — stable default seed from sorted zone names
-  (FNV-1a); used when the configured `Seed` is 0 so two distinct worlds differ.
-- `(State) ToJSON() ([]byte, error)` / `StateFromJSON([]byte) (State, error)` —
-  persistence codec for the full simulation state.
-- `Covering(g, fronts, cfg, zone) []Coverage` — fronts whose area projection
-  reaches `zone`, strongest effective intensity first (ties by front id). Mirrors
-  `resolveWeather`'s coverage rule exactly.
-- `ForceSpawn(prev, g, cfg, wtype, zone, intensity, clock) (State, StateDiff, bool)`
-  — inject a front bypassing budget and spawn chance. `intensity <= 0` defaults
-  to 0.6. Returns ok=false for an unknown zone. Pure: input state unchanged, no
-  RNG consumed (admin actions must not perturb the deterministic trace).
-- `ClearZones(prev, g, cfg, zones, clock) (State, StateDiff)` — remove fronts
-  and re-resolve weather. No zones = clear all. With zones, uses `Covering` so a
-  named zone clears even when its front is centred elsewhere. Pure; no RNG
-  consumed.
+### Graph
+- `(*Graph) ToJSON / FromJSON` — on-disk cache format (indented JSON);
+  `GraphVersion` lets a loader detect a stale cache and rebuild.
+- `(*Graph) Neighbors(zone) []Edge` — adjacent zones, each Edge oriented from
+  the queried zone (`Edge.A == zone`). Returns a **shared slice** from the
+  lazily-built index: callers MUST NOT mutate it (copy before sorting). Nil
+  for unknown or isolated zones.
+- `(*Graph) FindZone(name) (string, bool)` — case-insensitive resolution to
+  the canonical zone key; exact match wins.
+
+### Simulation
+- `Step(prev State, g *Graph, climate Climate, cfg Config, now Clock) (State, StateDiff)`
+  — one coarse tick, a pure function of its inputs. In order: age fronts and
+  apply the occupied biome's influence (the weather ← biome feedback half);
+  move fronts along edges (chance damped by `MovementResistance`, destination
+  weighted by edge weight, no immediate backtrack via `History`); re-roll a
+  *moved* front's type from the destination climate (biased to keep its
+  current type, so changes read naturally); drop dead fronts (intensity ≤ 0 or
+  past `FrontHardAge`); maybe spawn one front under `MaxActiveFronts` (origin
+  weighted by climate `SpawnWeight`, type from the origin's weights); resolve
+  per-zone weather with **intensity-scaled area coverage** — each front
+  projects onto zones within `MaxFrontRadius` hops at
+  `Intensity × CoverageFalloff^hops`, covering while `>= MinProjected`; per
+  zone the highest effective intensity wins (ties → lowest front id);
+  frontless zones are `Clear` — then emit the `StateDiff` of changed zones
+  (sorted; a `From` of `""` means "previously unset", not "was clear").
+- `NewState(seed) State` — fresh run (NextID 1, empty non-nil Weather map).
+- `DeriveSeed(g) uint64` — stable default seed: FNV-1a over sorted zone names,
+  so each world keeps its seed across boots but two worlds differ. Used when
+  the configured seed is 0.
+- `(State) ToJSON / StateFromJSON` — persistence codec (the engine layer wraps
+  it in a versioned envelope; see `engine/state.go`).
+
+### Queries & admin mutations
+- `Covering(g, fronts, cfg, zone) []Coverage` — every front whose projection
+  reaches `zone`, strongest first. Powers the player `weather` view and the
+  exported `GetWeather` intensity.
+- `ForceSpawn(prev, g, cfg, wtype, zone, intensity, now) (State, StateDiff, bool)`
+  — inject a front, bypassing budget and spawn chance but flowing through the
+  same resolve+diff path as `Step`. `intensity <= 0` defaults to 0.6; fixed
+  `MaxAge` 24; ok=false for an unknown zone. Pure — input state unmodified.
+- `ClearZones(prev, g, cfg, zones, now) (State, StateDiff)` — nil/empty zones
+  removes every front; named zones remove every front whose *coverage* reaches
+  one of them (so the zone actually clears even when the front is centered
+  elsewhere). Pure. Kept fronts share `History` backing arrays with the input;
+  any later mutation must go through `cloneFronts` (`Step` does).
+- **Neither admin mutation consumes RNG** — admin actions must not perturb the
+  deterministic trace.
+
+## Determinism
+All randomness comes from the `RNG` built from `State.RNGState`; the advanced
+cursor is written back into the next `State`. Same seed + graph + tick count ⇒
+byte-identical `State` (asserted by `TestStep_Deterministic` via
+`reflect.DeepEqual` and by a golden-trace test). Anything that would consume
+randomness outside `Step` (emote selection, admin spawns) deliberately does
+not touch this RNG.
 
 ## Dependencies
-- Standard library only (`encoding/json`, `sort`, `strings`). No engine imports (enforced).
+Standard library only (`encoding/json`, `sort`, `strings`). No engine imports
+(enforced), no third-party imports.
 
 ## Consumers
-- `crawler.Build` returns a `*Graph`.
-- `engine.Apply`/`engine.Reconcile` consume `StateDiff` and `State.Weather`.
-- The module root calls `Covering`, `ForceSpawn`, `ClearZones`, `NewState`, and
-  `DeriveSeed` from command handlers, the tick path, and the exported API.
+- `crawler.Build` produces the `*Graph`; `engine.DecodeCache` round-trips it.
+- The module root drives `Step` from the weather tick and feeds
+  `State.Weather` to `engine.Reconcile`; commands/exports call `Covering`,
+  `ForceSpawn`, `ClearZones`, `NewState`, `DeriveSeed`, `FindZone`.
+- `content.LoadClimate` returns a `Climate`; `engine.EmitAmbient` reads
+  `State.Weather`.
 
 ## Testing
-- `graph_test.go`: JSON round-trip, `Neighbors`, `FindZone`.
-- `state_test.go`: `NewState`, `DeriveSeed`, `ToJSON`/`StateFromJSON` round-trip.
-- `query_test.go`: `Covering` projection and ordering.
-- `mutate_test.go`: `ForceSpawn` and `ClearZones` (coverage-based clear).
+- `graph_test.go`: JSON round-trip, `Neighbors` (stability, orientation,
+  unknown/isolated zones, post-decode rebuild), `FindZone`.
+- `rng_test.go`: determinism, cursor round-trip, ranges.
+- `weather_test.go`: `clamp01`.
+- `climate_test.go`: profile fallback, defaults.
+- `tick_test.go`: per-behavior tests (feedback, movement resistance, type
+  evolution, death, budget, coverage), golden trace, full-state determinism,
+  storm-dies-crossing-mountains feedback scenario.
+- `state_test.go`: `NewState`, `DeriveSeed`, state JSON round-trip.
+- `query_test.go`: `Covering` projection/ordering + consistency with
+  `resolveWeather`.
+- `mutate_test.go`: `ForceSpawn`/`ClearZones` incl. purity assertions.
 - `arch_test.go`: purity guardrail.
 
-## Weather simulation (M2)
-
-Beyond the geography `Graph`, `sim` now contains the pure, deterministic weather
-simulation. It consumes a `*Graph` as its read-only world and produces weather
-state as plain data — no engine imports.
-
-### Key files
-- **rng.go**: `RNG`, a serializable splitmix64 PRNG (cursor = one `uint64`).
-- **weather.go**: `WeatherType` (+ `Clear`), `Front`, `State`, `StateDiff`,
-  `ZoneChange`, `Clock`, and `clamp01`.
-- **climate.go**: `ClimateProfile` / `WeatherInfluence` / `Climate` (biome →
-  weather weights + influence + spawn weight), `Climate.For` (default fallback),
-  `DefaultClimate`; plus `Config` / `DefaultConfig` (front budget, spawn chance,
-  history length, hard age cap).
-- **tick.go**: `Step(prev, graph, climate, cfg, clock) -> (next, diff)` and its
-  helpers (`ageAndFeedback`, `moveFronts`, `evolveTypes`, `removeDead`,
-  `spawnFronts`, `resolveWeather`, `diffWeather`).
-- **state.go**: `State.ToJSON` / `StateFromJSON` (persistence codec).
-
-### The tick
-Each `Step`: age fronts and apply the current zone's biome influence (the
-weather ← biome feedback), move fronts along edges (damped by `MovementResistance`,
-no immediate backtrack), evolve a moved front's type from the new zone's climate,
-drop dead fronts (intensity ≤ 0 or past the hard age cap), maybe spawn one front
-under budget (origin weighted by `SpawnWeight`), resolve per-zone weather with
-**intensity-scaled area coverage** (a front projects onto zones within
-`MaxFrontRadius` hops at `Intensity × CoverageFalloff^hops`, covered while
-`>= MinProjected`; per zone the highest *effective* intensity wins; frontless
-zones = `Clear`), and emit the diff.
-
-### Determinism
-All randomness flows through the `RNG` built from `State.RNGState`; the advanced
-cursor is written back into the next `State`. Same seed + graph + tick count ⇒
-identical fronts and per-zone weather (see `TestStep_Deterministic`).
-
-### Deferred (later milestones)
-- **Prevailing-wind direction** (a MUD owner biasing where storms originate/move,
-  e.g. west→east) is a planned later chunk: it needs directional edge metadata,
-  which a future crawler pass can derive from each exit's `MapDirection`.
-- Calm-zone variety (occasional light fog/overcast in frontless zones) and an
-  explicit windward "orographic" precip spike are noted enrichments, not built.
+## Deferred (later milestones)
+- **Prevailing-wind direction** (biasing where fronts originate/travel, e.g.
+  west→east) needs directional edge metadata, derivable by a future crawler
+  pass from each exit's `MapDirection`.
+- Calm-zone variety (occasional light fog/overcast in frontless zones) and a
+  windward "orographic" precipitation spike are noted enrichments, not built.