docs(website): the atlas reads the shard's tree on every boot, not a snapshot

Follows the redesign in website #112. Two decisions from the original §6 were
rejected in review and replaced; the docs now describe what was actually built.

**The committed artifact is gone.** A shard's maps change over its life, so a
snapshot in the repo silently drifts from the world players actually see. The
ServUO tree is the single source of truth and the atlas is re-derived on every
server boot, hash-gated so an unchanged tree costs one read pass and no write.

**Nothing may name a facet.** The first implementation carried a lookup table of
the six stock UO facets. A shard may add facets, replace them outright, or rename
them when its maps are updated, and a built-in list mishandles all three
silently. Reconciliation is now by matching against the facet set discovered from
the shard's own data, with an unmatched name keeping its own rather than being
forced into a wrong bucket.

## Changes

- **`website/SPAWN_ATLAS.md`** rewritten: the two ideas that shape the design,
  how to configure the tree path, the boot flow as a decision tree, the
  approve/reject flow, and the code layout. The artwork policy is unchanged and
  still explicit — no art ever ships, operators extract their own from their own
  client files.
- **`link/v3.md` §6.1 (new)** records the two rejected decisions plus the two
  boot-path contracts. The old "what real data changed" list becomes §6.2. §6's
  now-superseded passages — the artifact bullet, the payload budget, the operator
  re-run story — are marked rather than deleted, so the reasoning stays legible.
- **`website/BACKEND_DESIGN.md`** documents `shard_atlas_pending` and the two
  contracts that make it safe: a facet removal is staged for a human, and the
  boot refresh can never block startup.

The two contracts are the part worth reviewing. Losing a facet is
indistinguishable at boot from a half-copied or mid-update tree, so it is staged
rather than applied; and no failure mode of the atlas — missing path, unreadable
mount, malformed file, database error — is allowed to stop the site coming up.

---

- [x] AI-assisted: written with **Claude Code** (Claude Opus 5), reviewed before opening.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP

website/BACKEND_DESIGN.md

@@ -391,9 +391,15 @@ discarded. See §6.5.
 ### shard_spawn_* / shard_regions / shard_landmarks / shard_champion_spawns / shard_atlas_meta — the spawn atlas (Protocol 3.0)
 
 Static shard **content**, not live shard state. Nothing here comes from the sidecar: the atlas is
-built from a ServUO tree by a CLI script, committed as JSON under `server/db/data/`, and loaded with
-`npm run atlas:import`. These tables stay populated whether the shard is up or not. Full operator
-detail in [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md); the design is `docs/link/v3.md` §6.
+derived from the shard's own ServUO tree, re-read on **every server boot** and hash-gated so an
+unchanged tree costs one read pass and no write. Nothing is precomputed and committed — a shard's
+maps change over its life, and a snapshot in the repo would silently drift from the world players
+actually see. These tables stay populated whether the shard is up or not. Full operator detail in
+[`SPAWN_ATLAS.md`](SPAWN_ATLAS.md); the design is `docs/link/v3.md` §6.
+
+**No facet name appears anywhere in the code.** A shard may add facets, replace them, or rename them
+when its maps are updated; the facet set is discovered from the tree, and the loose spellings in
+`Data/Locations` are matched against it rather than looked up in a table.
 
 | Table | Key columns |
 |---|---|
@@ -403,13 +409,27 @@ detail in [`SPAWN_ATLAS.md`](SPAWN_ATLAS.md); the design is `docs/link/v3.md` §
 | `shard_regions` | `facet`, `name`, `type`, `priority`, `parent`, `rects` JSON |
 | `shard_landmarks` | `facet`, `name`, `grp`, `x`, `y`, `z` |
 | `shard_champion_spawns` | `slug` PK, `name`, `grp`, `type`, `random_type`, `facet`, `x`, `y`, `z`, `radius`, `label` |
-| `shard_atlas_meta` | Singleton (`id = 1`), `payload` JSON, `imported_at` |
+| `shard_atlas_meta` | Singleton (`id = 1`), `payload` JSON (counts + a sha256 per source file), `imported_at` |
+| `shard_atlas_pending` | Singleton (`id = 1`), `status` (`pending`/`rejected`), `payload` JSON, `detected_at` |
 
-All of them are **import-owned**: `atlas:import` empties and reloads every one inside a single
-transaction, so a failed import leaves the previous atlas intact rather than a half-loaded world.
+The first seven are **import-owned**: a refresh empties and reloads every one inside a single
+transaction, so a failed reload leaves the previous atlas intact rather than a half-loaded world.
 Nothing else writes to them, and nothing holds a foreign key to them — no FKs at all, consistent with
 every other `shard_*` table.
 
+**`shard_atlas_pending` is the security-relevant one.** A refresh that would REMOVE a facet is never
+applied automatically: facet loss is indistinguishable at boot from a half-copied or mid-update tree,
+so it is staged here for an admin to approve or reject, and **startup is never blocked by it**. Only
+the decision is stored — source hashes plus the facet diff, a few KB — and approving re-parses the
+tree, so a multi-megabyte blob never lands in the database and what gets applied matches the tree at
+approval time. A rejection is remembered against those exact hashes so a declined refresh does not
+re-prompt on every restart. Everything else (new facets, renamed regions, changed spawns) applies
+immediately, since none of it can destroy data an operator would miss.
+
+The boot refresh is **best-effort by contract**: no configured path, an unreadable mount, a malformed
+file or a database error is caught and logged, and the site comes up serving whatever atlas it had.
+The tree path comes from the `spawn_atlas_servuo_path` setting, falling back to `SERVUO_PATH`.
+
 Four column choices worth stating, because each one is a trap:
 
 - **`spawn_range`, not `range`**, and **`grp`, not `group`** — both are reserved words.