Merge pull request 'feat(shard)!: Protocol 3.0 cutover — visibility framework, spawn atlas, marketplace' (#118) from edge into main

Reviewed-on: #118
Reviewed-by: Colby Whitlock <whitlocktech@gmail.com>

.env.example

@@ -117,7 +117,10 @@ BOT_INTERNAL_KEY=change-me-to-a-long-random-string
 # token). These URLs are just defaults; the admin can override them at runtime.
 UOLINK_BASE_URL=http://127.0.0.1:8080
 UOLINK_WS_URL=ws://127.0.0.1:8080/ws
-UOLINK_PROTOCOL=1
+# Wire protocol this build speaks (3 = Protocol 3.0). Only a fallback for a site
+# with nothing saved yet — the admin panel's pinned value wins — but set it lower
+# if you deliberately run an older sidecar.
+UOLINK_PROTOCOL=3
 
 # ─── Push notifications (M7) — self-hosted ntfy UnifiedPush relay ───
 # The `ntfy` compose service and the backend's push fan-out (opt-in notifications

.gitea/workflows/pr-checks.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Run server tests
         run: npm test --prefix server
       - name: Check the route manifest is current
-        # The URL surface is frozen while admin.routes.js is carved up by capability
+        # The URL surface is frozen while the routers are carved up by capability
         # (docs/website/API_V2_PLAN.md § Phase 2). Regenerating from the live Express
         # stack and diffing proves a "mechanical" refactor moved no URL. A PR that
         # really does change one has to commit the new manifest, putting it in front

.gitignore

@@ -21,6 +21,24 @@ uploads/
 server/logs/
 logs/
 
+# Operator-supplied spawn atlas artwork. Creature art is never committed: sprites
+# are extracted from the operator's own UO client .mul/.uop files and are theirs,
+# not ours to redistribute. The images live under server/uploads/atlas/, already
+# ignored above; this is the slug -> file-name map pointing at them.
+# See docs/website/SPAWN_ATLAS.md and db/data/spawnAtlas.art.example.json.
+server/db/data/spawnAtlas.art.json
+
+# Operator-supplied cliloc table. UO's localization strings are EA's, extracted
+# from the operator's own client and converted once (docs/website/CLILOCS.md);
+# the repo ships no string table, for the same reason it ships no artwork and no
+# map snapshot. This covers the conventional in-repo location — the supported
+# arrangement is a path OUTSIDE the repo, set from Admin → Shard.
+server/db/data/cliloc*
+server/db/data/clilocs.*
+# The build output of tools/cliloc-export (a throwaway helper, not a package).
+server/tools/cliloc-export/bin/
+server/tools/cliloc-export/obj/
+
 # reference material (extracted from the provided archives)
 _reference/
 

README.md

@@ -389,8 +389,8 @@ npm run routes:manifest             # → routes.manifest.json + routes.guards.j
 npm run routes:manifest -- --check  # exit 1 if either file is stale (what CI runs)
 ```
 
-The generator walks the live Express stack (runtime introspection, not source parsing — route paths in
-`admin.routes.js` sit on the line *after* `adminRouter.get(`, which defeats greps) and keeps only
+The generator walks the live Express stack (runtime introspection, not source parsing — a route's path
+sits on the line *after* `router.get(`, which defeats greps) and keeps only
 `/api/**` and `/.well-known/**` plus the internal listener. The SPA catch-all, `/uploads` and `/brand`
 are filesystem-conditional static mounts, not API contract, so they are excluded and the output does
 not depend on whether the client has been built.

client/src/App.jsx

@@ -22,6 +22,12 @@ import ChampSpawns from './routes/public/ChampSpawns.jsx'
 import Guilds from './routes/public/Guilds.jsx'
 import Governors from './routes/public/Governors.jsx'
 import Houses from './routes/public/Houses.jsx'
+import Rules from './routes/public/Rules.jsx'
+import Atlas from './routes/public/Atlas.jsx'
+import AtlasCreature from './routes/public/AtlasCreature.jsx'
+import Leaderboards from './routes/public/Leaderboards.jsx'
+import Market from './routes/public/Market.jsx'
+import MarketVendor from './routes/public/MarketVendor.jsx'
 import Wiki from './routes/wiki/Wiki.jsx'
 import WikiArticle from './routes/wiki/WikiArticle.jsx'
 import CmsPage from './routes/public/CmsPage.jsx'
@@ -40,6 +46,8 @@ import ActivityAdmin from './routes/admin/views/ActivityAdmin.jsx'
 import BotActivityAdmin from './routes/admin/views/BotActivityAdmin.jsx'
 import DiscordBotAdmin from './routes/admin/views/DiscordBotAdmin.jsx'
 import ShardAdmin from './routes/admin/views/ShardAdmin.jsx'
+import ShardVisibility from './routes/admin/views/ShardVisibility.jsx'
+import SpawnAtlasAdmin from './routes/admin/views/SpawnAtlas.jsx'
 import ShardOps from './routes/admin/views/ShardOps.jsx'
 import AdminCharacters from './routes/admin/views/AdminCharacters.jsx'
 import AdminCharacter from './routes/admin/views/AdminCharacter.jsx'
@@ -97,6 +105,12 @@ export default function App() {
             <Route path="/site/guilds" element={<Guilds />} />
             <Route path="/site/governors" element={<Governors />} />
             <Route path="/site/houses" element={<Houses />} />
+            <Route path="/site/rules" element={<Rules />} />
+            <Route path="/site/atlas" element={<Atlas />} />
+            <Route path="/site/atlas/:slug" element={<AtlasCreature />} />
+            <Route path="/site/leaderboards" element={<Leaderboards />} />
+            <Route path="/site/market" element={<Market />} />
+            <Route path="/site/market/vendors/:serial" element={<MarketVendor />} />
             <Route path="/wiki" element={<Wiki />} />
             <Route path="/wiki/:slug" element={<WikiArticle />} />
             {/* CMS pages: top-level /:slug, matched only after the named routes
@@ -142,6 +156,8 @@ export default function App() {
             <Route path="bot-activity" element={<BotActivityAdmin />} />
             <Route path="discord-bot" element={<DiscordBotAdmin />} />
             <Route path="shard" element={<ShardAdmin />} />
+            <Route path="shard-visibility" element={<ShardVisibility />} />
+            <Route path="shard-atlas" element={<SpawnAtlasAdmin />} />
             <Route
               path="shard-ops"
               element={

client/src/api/client.js

@@ -71,8 +71,10 @@ export const api = {
   resetPassword: (token, password) =>
     req(`/auth/password/reset/${encodeURIComponent(token)}`, { method: 'POST', body: { password } }),
   // Second factor for an SSO login (challenge is held in an httpOnly cookie set by
-  // the callback, so only the code is sent). Returns { user, returnTo }.
-  ssoLoginTotp: (code) => req('/auth/sso/totp', { method: 'POST', body: { code } }),
+  // the callback, so only the code is sent). `extra` carries the trustDevice/
+  // deviceName opt-in, same as the password path. Returns { user, returnTo } — plus
+  // { trustLimitReached, devices } when trust was asked for but the cap is reached.
+  ssoLoginTotp: (code, extra = {}) => req('/auth/sso/totp', { method: 'POST', body: { code, ...extra } }),
   logout: () => req('/auth/logout', { method: 'POST' }),
   // Public SSO provider discovery — drives the login-page provider buttons.
   authProviders: () => req('/auth/providers'),
@@ -145,6 +147,75 @@ export const api = {
     },
     presence: () => req('/public/shard/presence'),
     houses: () => req('/public/shard/houses'),
+    // Protocol 3.0: the shard's published ruleset. Resolves to null when the
+    // shard has never published one — a real answer, not an error.
+    ruleset: () => req('/public/shard/ruleset'),
+    // Protocol 3.0: points/loyalty leaderboards, one board per point system.
+    // `board` 404s for a system the shard has never published.
+    points: () => req('/public/shard/points'),
+    pointsBoard: (system) => req(`/public/shard/points/${encodeURIComponent(system)}`),
+    // Protocol 3.0: the player-vendor marketplace. Rate-limited server-side, so
+    // the page debounces its search box rather than firing per keystroke.
+    market: (opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.q) qs.set('q', opts.q)
+      if (opts.minPrice != null && opts.minPrice !== '') qs.set('minPrice', opts.minPrice)
+      if (opts.maxPrice != null && opts.maxPrice !== '') qs.set('maxPrice', opts.maxPrice)
+      if (opts.itemId != null && opts.itemId !== '') qs.set('itemId', opts.itemId)
+      if (opts.map) qs.set('map', opts.map)
+      if (opts.region) qs.set('region', opts.region)
+      if (opts.sort) qs.set('sort', opts.sort)
+      if (opts.limit) qs.set('limit', opts.limit)
+      if (opts.offset) qs.set('offset', opts.offset)
+      return req(`/public/shard/market${withQs(qs.toString())}`)
+    },
+    marketMeta: () => req('/public/shard/market/meta'),
+    marketVendor: (serial, opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.limit) qs.set('limit', opts.limit)
+      if (opts.offset) qs.set('offset', opts.offset)
+      return req(`/public/shard/market/vendors/${encodeURIComponent(serial)}${withQs(qs.toString())}`)
+    },
+    // Which shard surfaces this caller may reach, plus the audience rung they
+    // resolved to. Drives nav so we never render a link that would 403.
+    features: () => req('/public/shard/features'),
+  },
+
+  // ----- spawn atlas (Protocol 3.0 Part C) -----
+  // Static shard CONTENT, parsed from the shard's own ServUO tree — deliberately
+  // not under /shard, because nothing here depends on the sidecar and the pages
+  // stay populated while the shard is offline.
+  atlas: {
+    creatures: (opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.q) qs.set('q', opts.q)
+      if (opts.facet) qs.set('facet', opts.facet)
+      if (opts.limit) qs.set('limit', opts.limit)
+      if (opts.offset) qs.set('offset', opts.offset)
+      return req(`/public/atlas/creatures${withQs(qs.toString())}`)
+    },
+    creature: (slug, opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.facet) qs.set('facet', opts.facet)
+      if (opts.points) qs.set('points', opts.points)
+      return req(`/public/atlas/creatures/${encodeURIComponent(slug)}${withQs(qs.toString())}`)
+    },
+    regions: (opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.facet) qs.set('facet', opts.facet)
+      if (opts.q) qs.set('q', opts.q)
+      return req(`/public/atlas/regions${withQs(qs.toString())}`)
+    },
+    landmarks: (opts = {}) => {
+      const qs = new URLSearchParams()
+      if (opts.facet) qs.set('facet', opts.facet)
+      if (opts.q) qs.set('q', opts.q)
+      return req(`/public/atlas/landmarks${withQs(qs.toString())}`)
+    },
+    // The CONFIGURED altar roster, not the live board — see shard.champs() for
+    // "which spawn is on level 3 right now".
+    champions: (facet) => req(`/public/atlas/champions${withQs(facet ? `facet=${encodeURIComponent(facet)}` : '')}`),
+    meta: () => req('/public/atlas/meta'),
   },
   // Full paths (incl. /api/v1) for the browser EventSource — the req() wrapper is
   // fetch-only, so SSE subscribers build the URL from here. The admin stream
@@ -344,6 +415,25 @@ export const api = {
     saveUoLinkConfig: (data) => req('/admin/uo-link/config', { method: 'PUT', body: data }),
     postTownCrier: (data) => req('/admin/uo-link/towncrier', { method: 'POST', body: data }),
     deleteTownCrier: (id) => req(`/admin/uo-link/towncrier/${encodeURIComponent(id)}`, { method: 'DELETE' }),
+    // Per-feature shard visibility: who may see which shard surface, and which
+    // sensitive fields within it. Admin only — it decides what ANONYMOUS
+    // visitors get. acct/webId are admin-only always and the API rejects any
+    // attempt to configure them.
+    getShardVisibility: () => req('/admin/shard/visibility'),
+    saveShardVisibility: (features) =>
+      req('/admin/shard/visibility', { method: 'PUT', body: { features } }),
+
+    // ----- spawn atlas operation (admin only) -----
+    // The atlas re-derives itself from the ServUO tree on every boot; these are
+    // for applying a map change without a restart, and for the approve/reject
+    // decision on a refresh that would remove a facet.
+    atlas: {
+      status: () => req('/admin/shard/atlas'),
+      import: (force = false) => req('/admin/shard/atlas/import', { method: 'POST', body: { force } }),
+      approve: () => req('/admin/shard/atlas/approve', { method: 'POST', body: {} }),
+      reject: () => req('/admin/shard/atlas/reject', { method: 'POST', body: {} }),
+      setPath: (path) => req('/admin/shard/atlas/path', { method: 'PUT', body: { path } }),
+    },
 
     // ----- in-game staff operations: write plane + support queue (admin/moderator) -----
     // `actor` is stamped server-side from the session — never sent from here.

client/src/components/CharacterSheet.jsx

@@ -10,24 +10,89 @@ import ShardAccountActions from './ShardAccountActions.jsx'
 
 const RESIST_LABELS = { phys: 'Physical', fire: 'Fire', cold: 'Cold', pois: 'Poison', energy: 'Energy' }
 
+// What to call an equipped item.
+//
+// Items on the wire carry a `LabelNumber`, not a name, so this used to be able
+// to show nothing but the layer and `id 12345`. The server now resolves the
+// cliloc against its own table and attaches `clilocName` (see
+// docs/website/CLILOCS.md); a shard with no cliloc file configured sends none,
+// and the layer fallback below is exactly what the sheet did before.
+//
+// A player-given `name` outranks the resolved type name — "Bob's lucky axe"
+// should not be relabelled "hatchet" — and the server applies the same
+// precedence, so this only re-states it for a profile that arrived with both.
+const itemName = (it) => it.name || it.clilocName || it.layer || 'Item'
+
 // The char.profile `titles` block (Protocol 2.0). fameKarma/skill are already
 // computed display strings; reward entries may be a cliloc NUMBER-as-string or a
-// literal string. Without a cliloc table on the site we can only show literals, so
-// numeric reward entries are skipped rather than shown as a raw number. Returns a
-// de-duped list of human-readable title chips.
+// literal string.
+//
+// `rewardResolved` is the server's parallel array with the numeric entries turned
+// into words (null where the cliloc table had nothing, or is not configured at
+// all). Prefer it, and keep the literal-only path as the fallback for a profile
+// served before the cliloc table existed — a numeric entry with no resolution is
+// still skipped rather than shown as a raw number.
 function displayTitles(titles) {
   if (!titles) return []
   const out = []
   if (titles.fameKarma) out.push(titles.fameKarma)
   if (titles.skill) out.push(titles.skill)
-  const reward = Array.isArray(titles.reward) ? titles.reward : []
+  const raw = Array.isArray(titles.reward) ? titles.reward : []
+  const resolved = Array.isArray(titles.rewardResolved) ? titles.rewardResolved : null
+  const reward = raw.map((r, i) => resolved?.[i] ?? (/^\d+$/.test(String(r)) ? null : String(r)))
   const sel = typeof titles.selected === 'number' ? titles.selected : -1
-  // Prefer the selected reward title; fall back to the first literal one.
-  const candidate = sel >= 0 && sel < reward.length ? reward[sel] : reward.find((r) => r && !/^\d+$/.test(String(r)))
-  if (candidate && !/^\d+$/.test(String(candidate))) out.push(String(candidate))
+  // Prefer the selected reward title; fall back to the first one that resolved.
+  // The `??` matters: a selected title whose cliloc did not resolve must fall
+  // through to the fallback rather than suppress the chip entirely.
+  const candidate = (sel >= 0 && sel < reward.length ? reward[sel] : null) ?? reward.find(Boolean)
+  if (candidate) out.push(String(candidate))
   return [...new Set(out.filter(Boolean))]
 }
 
+// The char.profile `points` block (Protocol 3.0 §7.3): one entry per point system
+// the character actually holds a score in. Systems at zero are omitted by the
+// shard, so an empty list means "this character has earned nothing anywhere",
+// which is a normal state for a new character and renders as nothing at all.
+//
+// `nameString` may be null when the system's name is a cliloc; fall back to
+// humanising the PointsType key, exactly as the leaderboards page does. `rank` is
+// absent unless the shard runs with Bridge.cfg PointsProfileRank=true — absent and
+// "unranked" are different, so the chip only appears when it was actually sent.
+const humanisePoints = (key) =>
+  String(key || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/^./, (c) => c.toUpperCase())
+
+function PointsRow({ entry }) {
+  const label = entry.nameString || humanisePoints(entry.system)
+  const max = Number.isFinite(entry.maxPoints) && entry.maxPoints > 0 ? entry.maxPoints : 0
+  const pct = max ? Math.min(100, Math.round((entry.points / max) * 100)) : 0
+
+  return (
+    <div>
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline', marginBottom: 3, gap: 10 }}>
+        <span className="sans" style={{ color: 'var(--ink)', fontSize: '0.86rem' }}>
+          {label}
+          {Number.isFinite(entry.rank) && (
+            <span className="dim" style={{ fontSize: '0.74rem' }}> · #{entry.rank}</span>
+          )}
+        </span>
+        <span className="sans" style={{ color: 'var(--head)', fontSize: '0.82rem', flex: 'none' }}>
+          {(entry.points ?? 0).toLocaleString()}
+          {max > 0 && <span className="dim"> / {max.toLocaleString()}</span>}
+        </span>
+      </div>
+      {/* Only systems with a real cap get a bar; an uncapped score has nothing to
+          be a fraction of, and a full-width bar would imply completion. */}
+      {max > 0 && (
+        <div style={{ height: 4, borderRadius: 999, background: 'var(--line)', overflow: 'hidden' }}>
+          <div style={{ width: `${pct}%`, height: '100%', background: 'var(--accent)' }} />
+        </div>
+      )}
+    </div>
+  )
+}
+
 function TitleChip({ children, tone = 'var(--muted)' }) {
   return (
     <span
@@ -75,6 +140,11 @@ export default function CharacterSheet({ char, moderation = false }) {
     .filter((s) => (s.value || s.base || 0) > 0)
     .sort((a, b) => (b.value || 0) - (a.value || 0))
   const equipment = char.equipment || []
+  // Best standing first, so the character's strongest loyalty leads. Guarded for
+  // an older shard plugin that sends no `points` block at all.
+  const points = (Array.isArray(char.points) ? char.points : [])
+    .filter((p) => p && (p.points || 0) > 0)
+    .sort((a, b) => (b.points || 0) - (a.points || 0))
 
   return (
     <div style={{ display: 'flex', flexDirection: 'column', gap: 22 }}>
@@ -173,17 +243,37 @@ export default function CharacterSheet({ char, moderation = false }) {
         </section>
       )}
 
+      {/* Loyalty & points — one entry per system this character has scored in */}
+      {points.length > 0 && (
+        <section>
+          <div className="field-label" style={{ marginBottom: 8 }}>
+            Loyalty &amp; points <span className="dim">({points.length})</span>
+          </div>
+          <div className="grid-2" style={{ gap: '8px 18px' }}>
+            {points.map((p) => (
+              <PointsRow key={p.system} entry={p} />
+            ))}
+          </div>
+        </section>
+      )}
+
       {/* Equipment */}
       {equipment.length > 0 && (
         <section>
           <div className="field-label" style={{ marginBottom: 8 }}>Equipment</div>
           <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
-            {equipment.map((it) => (
+            {equipment.map((it) => {
+              const label = itemName(it)
+              const layer = it.layer || 'Item'
+              // The layer only earns its own line once the headline is a real
+              // name; when it IS the headline, repeating it is just noise.
+              const detail = [label === layer ? null : layer, `id ${it.itemId}`, it.hue ? `hue ${it.hue}` : null]
+              return (
               <div key={it.serial} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '10px 14px', border: '1px solid var(--line)', borderRadius: 8 }}>
                 <span style={{ flex: 'none', width: 22, height: 22, borderRadius: 5, border: '1px solid var(--line)', background: 'rgba(255,255,255,0.05)' }} />
                 <div style={{ flex: 1, minWidth: 0 }}>
-                  <div className="sans" style={{ color: 'var(--head)', fontSize: '0.88rem' }}>{it.layer || 'Item'}</div>
-                  <div className="sans dim" style={{ fontSize: '0.74rem' }}>id {it.itemId}{it.hue ? ` · hue ${it.hue}` : ''}</div>
+                  <div className="sans" style={{ color: 'var(--head)', fontSize: '0.88rem' }}>{label}</div>
+                  <div className="sans dim" style={{ fontSize: '0.74rem' }}>{detail.filter(Boolean).join(' · ')}</div>
                 </div>
                 {it.mods && Object.keys(it.mods).length > 0 && (
                   <div className="sans" style={{ display: 'flex', gap: 6, flexWrap: 'wrap', justifyContent: 'flex-end', maxWidth: '55%' }}>
@@ -193,7 +283,8 @@ export default function CharacterSheet({ char, moderation = false }) {
                   </div>
                 )}
               </div>
-            ))}
+              )
+            })}
           </div>
         </section>
       )}

client/src/components/SiteHeader.jsx

@@ -2,9 +2,15 @@ import { Link, NavLink } from 'react-router-dom'
 import MoonDot from './MoonDot.jsx'
 import { useAuth } from '../contexts/AuthContext.jsx'
 import { useSite } from '../contexts/SiteContext.jsx'
+import { useShardFeatures, canSee } from '../lib/useShardFeatures.js'
 
 // One consistent top nav for the whole public site. Every page gets the same
 // main links plus an auth-aware entry on the right (Sign in / My Account / Admin).
+//
+// Entries carrying a `feature` are shard surfaces an admin can disable or gate
+// to a higher audience (Admin -> Shard Visibility). They are hidden when this
+// viewer can't reach them, so we never render a link that would 403. The gate
+// itself is server-side; this is only about not advertising a dead end.
 const NAV = [
   { label: 'Home', to: '/', end: true },
   { label: 'News', to: '/site/news' },
@@ -12,11 +18,15 @@ const NAV = [
   { label: 'Five on Friday', to: '/site/five-on-friday' },
   { label: 'Newsletter', to: '/site/newsletter' },
   { label: 'Wiki', to: '/wiki' },
-  { label: 'Shard', to: '/site/shard' },
-  { label: 'Champions', to: '/site/champs' },
-  { label: 'Guilds', to: '/site/guilds' },
-  { label: 'Governors', to: '/site/governors' },
-  { label: 'Houses', to: '/site/houses' },
+  { label: 'Shard', to: '/site/shard', feature: 'status' },
+  { label: 'Champions', to: '/site/champs', feature: 'champs' },
+  { label: 'Guilds', to: '/site/guilds', feature: 'guilds' },
+  { label: 'Governors', to: '/site/governors', feature: 'governors' },
+  { label: 'Houses', to: '/site/houses', feature: 'houses' },
+  { label: 'Rules', to: '/site/rules', feature: 'ruleset' },
+  { label: 'Atlas', to: '/site/atlas', feature: 'atlas' },
+  { label: 'Leaderboards', to: '/site/leaderboards', feature: 'leaderboards' },
+  { label: 'Market', to: '/site/market', feature: 'market' },
   { label: 'About', to: '/site/about' },
 ]
 
@@ -29,6 +39,8 @@ const linkStyle = ({ isActive }) => ({
 export default function SiteHeader() {
   const { user, loading } = useAuth()
   const { siteTitle } = useSite()
+  const shardFeatures = useShardFeatures()
+  const nav = NAV.filter((item) => !item.feature || canSee(shardFeatures, item.feature))
 
   // Where the auth entry points: staff → admin, player → portal, else sign in.
   let account
@@ -60,7 +72,7 @@ export default function SiteHeader() {
           {siteTitle}
         </Link>
         <nav style={{ display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
-          {NAV.map((l) => (
+          {nav.map((l) => (
             <NavLink key={l.to} to={l.to} end={l.end} className="pill" style={linkStyle}>
               {l.label}
             </NavLink>

client/src/contexts/AuthContext.jsx

@@ -49,9 +49,11 @@ export function AuthProvider({ children }) {
   }, [])
 
   // Step 2 for SSO logins whose account has 2FA on. The pending challenge lives in
-  // an httpOnly cookie, so only the code is sent. Returns { user, returnTo }.
-  const ssoLoginTotp = useCallback(async (code) => {
-    const data = await api.ssoLoginTotp(code)
+  // an httpOnly cookie, so only the code is sent. `extra` carries the trustDevice/
+  // deviceName opt-in. Returns the full payload ({ user, returnTo,
+  // trustLimitReached?, devices? }) so the caller can handle the device-cap prompt.
+  const ssoLoginTotp = useCallback(async (code, extra) => {
+    const data = await api.ssoLoginTotp(code, extra)
     setUser(data.user)
     return data
   }, [])

client/src/lib/useShardFeatures.js

@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react'
+import { api } from '../api/client.js'
+
+// Which shard surfaces the current viewer may reach, from
+// GET /public/shard/features. Admins configure this per feature (Admin → Shard
+// Visibility), so the nav can't be a static list any more.
+//
+// This is PRESENTATION only. The gate is server-side: a disabled feature 404s
+// and an out-of-rung one 403s whether or not the link is rendered. So while the
+// answer is still in flight we return `null` and callers show their default set
+// — better a link that briefly 403s than a nav that flickers in on every load.
+//
+// Cached module-level: the answer is per-viewer but stable for a session, and
+// every consumer would otherwise refetch it on mount.
+let cached = null
+let inFlight = null
+
+export function resetShardFeatures() {
+  cached = null
+  inFlight = null
+}
+
+export function useShardFeatures() {
+  const [features, setFeatures] = useState(cached)
+
+  useEffect(() => {
+    if (cached) return undefined
+    let alive = true
+    inFlight =
+      inFlight ||
+      api.shard
+        .features()
+        .then((data) => {
+          cached = { level: data.level, set: new Set(data.features || []) }
+          return cached
+        })
+        .catch(() => {
+          // A failed lookup must not blank the nav — fall back to "show
+          // everything" and let the server do the gating.
+          cached = null
+          inFlight = null
+          return null
+        })
+    inFlight.then((result) => {
+      if (alive) setFeatures(result)
+    })
+    return () => {
+      alive = false
+    }
+  }, [])
+
+  return features
+}
+
+// Convenience: true when `name` is visible, or when we don't know yet.
+export function canSee(features, name) {
+  return !features || features.set.has(name)
+}

client/src/routes/admin/AdminLayout.jsx

@@ -78,6 +78,8 @@ const NAV = [
       { to: '/admin/auth-providers', label: 'Authentication', icon: IconKey, roles: ['admin'] },
       { to: '/admin/discord-bot', label: 'Discord Bot', icon: IconBot, roles: ['admin'] },
       { to: '/admin/shard', label: 'Shard (uo-link)', icon: IconShard, roles: ['admin'] },
+      { to: '/admin/shard-visibility', label: 'Shard Visibility', icon: IconShard, roles: ['admin'] },
+      { to: '/admin/shard-atlas', label: 'Spawn Atlas', icon: IconShard, roles: ['admin'] },
       { to: '/admin/bot-activity', label: 'Web Bot Activity', icon: IconPulse, roles: ['admin'] },
     ],
   },
@@ -106,6 +108,8 @@ const TITLES = {
   '/admin/bot-activity': 'Web Bot Activity',
   '/admin/discord-bot': 'Discord Bot',
   '/admin/shard': 'Shard (uo-link)',
+  '/admin/shard-visibility': 'Shard Visibility',
+  '/admin/shard-atlas': 'Spawn Atlas',
   '/admin/characters': 'My Characters',
   '/admin/auth-providers': 'Authentication',
   '/admin/users': 'Users',

client/src/routes/admin/AdminLogin.jsx

@@ -123,8 +123,16 @@ export default function AdminLogin() {
     setBusy(true)
     try {
       if (ssoTotp) {
-        const { returnTo } = await ssoLoginTotp(code)
-        navigate(returnTo || '/admin', { replace: true })
+        // Trust works on the SSO second factor exactly as it does on the password
+        // one — the IdP already proved the first factor.
+        const data = await ssoLoginTotp(code.trim(), { trustDevice })
+        const to = data.returnTo || '/admin'
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       } else {
         const entered = code.trim()
         const data = await loginTotp(challenge, useRecovery ? '' : entered, {
@@ -251,12 +259,14 @@ export default function AdminLogin() {
                   {useRecovery ? 'Enter one of your saved single-use recovery codes.' : 'Enter the code from your authenticator app.'}
                 </span>
               </label>
-              {!ssoTotp && (
+              {/* Offered on the SSO second factor too — the trust is on the device,
+                  not on how the first factor was proved. */}
               <label className="sans" style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12, color: 'var(--muted)', fontSize: '0.84rem' }}>
                 <input type="checkbox" checked={trustDevice} onChange={(e) => setTrustDevice(e.target.checked)} />
                 Trust this device for 30 days (skip the code next time)
               </label>
-              )}
+              {/* Recovery codes remain password-login only: the SSO second step
+                  verifies an authenticator code against the staged challenge. */}
               {!ssoTotp && (
                 <button
                   type="button"

client/src/routes/admin/views/Dashboard.jsx

@@ -4,9 +4,15 @@ import { useAsync } from '../../../lib/useAsync.js'
 import { ago, dateTime } from '../../../lib/format.js'
 import { api } from '../../../api/client.js'
 import { useSite } from '../../../contexts/SiteContext.jsx'
+import { useAuth } from '../../../contexts/AuthContext.jsx'
 
 export default function Dashboard() {
   const { refresh: refreshSite } = useSite()
+  const { user } = useAuth()
+  // PUT /admin/site-mode is adminOnly. The dashboard itself is staff-wide, so the
+  // toggle needs its own gate — same rule the sidebar follows (AdminLayout: never
+  // show a non-admin a control that would 403).
+  const isAdmin = user?.role === 'admin'
   const [tick, setTick] = useState(0)
   const reload = useCallback(() => setTick((t) => t + 1), [])
 
@@ -15,6 +21,7 @@ export default function Dashboard() {
     [tick],
   )
   const [busy, setBusy] = useState(false)
+  const [modeError, setModeError] = useState('')
 
   if (loading) return <Loading />
   if (error) return <ErrorState message="Could not load the dashboard." />
@@ -32,12 +39,21 @@ export default function Dashboard() {
     { value: dash.counts?.users ?? 0, label: 'Users' },
   ]
 
+  // The rejection was previously unhandled: a refused toggle surfaced only as an
+  // unhandled promise rejection in the console while the button silently reverted.
   async function toggle() {
     setBusy(true)
+    setModeError('')
     try {
       await api.admin.setSiteMode(isLive ? 'maintenance' : 'live')
       await refreshSite()
       reload()
+    } catch (err) {
+      setModeError(
+        err.status === 403
+          ? 'Only an administrator can change the site mode.'
+          : 'Could not change the site mode. Try again.',
+      )
     } finally {
       setBusy(false)
     }
@@ -78,7 +94,13 @@ export default function Dashboard() {
             {changed.by ? `Changed by ${changed.by}` : 'No changes recorded'}
             {changed.at ? ` · ${dateTime(changed.at)}` : ''}
           </div>
+          {modeError && (
+            <div className="sans" style={{ fontSize: '0.8rem', marginTop: 8, color: 'var(--danger, #d98b8b)' }}>
+              {modeError}
             </div>
+          )}
+        </div>
+        {isAdmin && (
           <button
             onClick={toggle}
             disabled={busy}
@@ -87,6 +109,7 @@ export default function Dashboard() {
           >
             {modeLabel}
           </button>
+        )}
       </div>
 
       <div className="grid-4" style={{ gap: 14, marginBottom: 28 }}>

client/src/routes/admin/views/ShardAdmin.jsx

@@ -155,7 +155,7 @@ export default function ShardAdmin() {
   const [baseUrl, setBaseUrl] = useState('')
   const [wsUrl, setWsUrl] = useState('')
   const [token, setToken] = useState('')
-  const [protocol, setProtocol] = useState(1)
+  const [protocol, setProtocol] = useState(3)
   const [enabled, setEnabled] = useState(false)
   const [busy, setBusy] = useState(false)
   const [msg, setMsg] = useState('')
@@ -172,7 +172,7 @@ export default function ShardAdmin() {
       if (!initializedRef.current) {
         setBaseUrl(c.baseUrl || '')
         setWsUrl(c.wsUrl || '')
-        setProtocol(c.protocol || 1)
+        setProtocol(c.protocol || 3)
         setEnabled(c.enabled)
         initializedRef.current = true
       }

client/src/routes/admin/views/ShardVisibility.jsx

@@ -0,0 +1,325 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import { api } from '../../../api/client.js'
+
+// ── Admin · Shard visibility ────────────────────────────────────────────────
+//
+// Who may see which shard surface, and which sensitive fields within it.
+// Admin-only, because this decides what ANONYMOUS visitors get.
+//
+// Two things the UI must communicate honestly, because they are not negotiable
+// server-side (see docs/link/v3.md §3.4):
+//   • acct / webId are admin-only always and are not listed as editable fields.
+//   • an event kind the server doesn't know about never reaches anyone below
+//     admin, whatever is set here.
+//
+// Defaults reproduce the behavior the site had before this panel existed, so a
+// fresh install shows "everything as it was" rather than an empty form.
+
+const RUNG_LABEL = {
+  anonymous: 'Everyone',
+  logged_in: 'Signed in',
+  player: 'Linked players',
+  staff: 'Staff',
+  admin: 'Admins only',
+}
+
+const RUNG_HINT = {
+  anonymous: 'Visible to anyone, signed in or not.',
+  logged_in: 'Any signed-in account, linked or not.',
+  player: 'Accounts with a linked game account. Staff always qualify.',
+  staff: 'Admins and moderators.',
+  admin: 'Admins only.',
+}
+
+const FEATURE_LABEL = {
+  status: 'Shard status',
+  activity: 'Activity feed',
+  champs: 'Champion spawns',
+  guilds: 'Guilds',
+  governors: 'Town governors',
+  houses: 'Houses / IDOC',
+  presence: 'Players online',
+  ruleset: 'Shard rules',
+  atlas: 'Spawn atlas',
+  leaderboards: 'Leaderboards',
+  market: 'Marketplace',
+}
+
+const FEATURE_HINT = {
+  status: 'Connection state, online count, gold-supply series.',
+  activity: 'Deaths, kills, skill gains, quests, logins.',
+  champs: 'The live champion / mini-champ / sea-boss board.',
+  guilds: 'Guild rosters, alliances and leaders.',
+  governors: 'City Loyalty governors, elections and term history.',
+  houses: 'Houses in danger (IDOC). Owner and price are separate fields below.',
+  presence: 'Population aggregate and the staff-online widget.',
+  ruleset: 'Skill/stat caps, house limits, vet rewards and the rest of the ruleset.',
+  atlas: 'The spawn atlas and bestiary. Static shard content, not live state.',
+  leaderboards: 'Point and loyalty standings across every points system.',
+  market: 'The shard-wide player-vendor index.',
+}
+
+const FIELD_LABEL = {
+  owner: 'House owner',
+  price: 'House price',
+  location: 'In-game location (map + coordinates)',
+  connect: 'Server connect address',
+  // Keyed on the WIRE field, which for a leaderboard entry is `name` — the
+  // projection matches literal JSON keys, so the rule cannot be spelled after the
+  // field's meaning. The label is what carries the meaning to the admin.
+  name: 'Character names on leaderboards',
+  ownerName: 'Vendor owner name',
+  // One rule, one key — `location` is a nested object on both the wire frame and
+  // the stored read model precisely so that hiding it takes the facet, the
+  // coordinates, the region and the house together.
+  ownerSerial: 'Vendor owner character id',
+}
+
+function RungSelect({ value, onChange, ladder, disabled }) {
+  return (
+    <select
+      className="input"
+      value={value}
+      disabled={disabled}
+      onChange={(e) => onChange(e.target.value)}
+      style={{ maxWidth: 200 }}
+    >
+      {ladder.map((rung) => (
+        <option key={rung} value={rung}>
+          {RUNG_LABEL[rung] || rung}
+        </option>
+      ))}
+    </select>
+  )
+}
+
+function FeatureRow({ name, settings, defaults, ladder, onPatch }) {
+  const fields = Object.entries(settings.fields || {})
+  const changed =
+    defaults &&
+    (settings.enabled !== defaults.enabled ||
+      settings.audience !== defaults.audience ||
+      settings.stream !== defaults.stream ||
+      JSON.stringify(settings.fields) !== JSON.stringify(defaults.fields))
+
+  return (
+    <div
+      style={{
+        border: '1px solid var(--line)',
+        borderRadius: 10,
+        padding: 16,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 12,
+        opacity: settings.enabled ? 1 : 0.62,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16 }}>
+        <div style={{ minWidth: 0 }}>
+          <h3 className="display" style={{ margin: 0, fontSize: '1rem', color: 'var(--head)' }}>
+            {FEATURE_LABEL[name] || name}
+            {changed && (
+              <span
+                className="sans"
+                style={{ marginLeft: 8, fontSize: '0.62rem', letterSpacing: '0.06em', textTransform: 'uppercase', color: 'var(--accent)' }}
+              >
+                changed
+              </span>
+            )}
+          </h3>
+          <p className="sans" style={{ margin: '4px 0 0', fontSize: '0.82rem', color: 'var(--muted)', lineHeight: 1.5 }}>
+            {FEATURE_HINT[name]}
+          </p>
+        </div>
+        <label
+          className="sans"
+          style={{ flex: 'none', display: 'inline-flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: '0.86rem', color: 'var(--ink)' }}
+        >
+          <input
+            type="checkbox"
+            checked={settings.enabled}
+            onChange={(e) => onPatch(name, { enabled: e.target.checked })}
+          />
+          Enabled
+        </label>
+      </div>
+
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 20, alignItems: 'flex-end' }}>
+        <label style={{ display: 'block' }}>
+          <span className="field-label">Who can see it</span>
+          <RungSelect
+            value={settings.audience}
+            ladder={ladder}
+            disabled={!settings.enabled}
+            onChange={(audience) => onPatch(name, { audience })}
+          />
+          <span className="sans dim" style={{ display: 'block', marginTop: 4, fontSize: '0.75rem' }}>
+            {RUNG_HINT[settings.audience]}
+          </span>
+        </label>
+        <label
+          className="sans"
+          style={{ display: 'inline-flex', alignItems: 'center', gap: 8, cursor: 'pointer', fontSize: '0.86rem', color: 'var(--ink)', paddingBottom: 22 }}
+        >
+          <input
+            type="checkbox"
+            checked={settings.stream}
+            disabled={!settings.enabled}
+            onChange={(e) => onPatch(name, { stream: e.target.checked })}
+          />
+          Live updates
+        </label>
+      </div>
+
+      {fields.length > 0 && (
+        <div style={{ borderTop: '1px solid var(--line-soft)', paddingTop: 12 }}>
+          <span className="field-label" style={{ display: 'block', marginBottom: 8 }}>
+            Sensitive fields
+          </span>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: 16 }}>
+            {fields.map(([field, rung]) => (
+              <label key={field} style={{ display: 'block' }}>
+                <span className="sans dim" style={{ display: 'block', fontSize: '0.78rem', marginBottom: 4 }}>
+                  {FIELD_LABEL[field] || field}
+                </span>
+                <RungSelect
+                  value={rung}
+                  ladder={ladder}
+                  disabled={!settings.enabled}
+                  onChange={(level) =>
+                    onPatch(name, { fieldRules: { ...settings.fields, [field]: level } })
+                  }
+                />
+              </label>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default function ShardVisibility() {
+  const [config, setConfig] = useState(null)
+  const [defaults, setDefaults] = useState(null)
+  const [ladder, setLadder] = useState([])
+  const [lockedFields, setLockedFields] = useState([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState('')
+  const [saving, setSaving] = useState(false)
+  const [msg, setMsg] = useState('')
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    setError('')
+    try {
+      const data = await api.admin.getShardVisibility()
+      setConfig(data.features)
+      setDefaults(data.defaults)
+      setLadder(data.ladder || [])
+      setLockedFields(data.lockedFields || [])
+    } catch (err) {
+      setError(err.message || 'Could not load visibility settings.')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  function patch(name, changes) {
+    setMsg('')
+    setConfig((prev) => {
+      const next = { ...prev[name], ...changes }
+      // `fieldRules` in the API is `fields` in the effective config.
+      if (changes.fieldRules) {
+        next.fields = changes.fieldRules
+        delete next.fieldRules
+      }
+      return { ...prev, [name]: next }
+    })
+  }
+
+  async function save() {
+    setSaving(true)
+    setMsg('')
+    setError('')
+    try {
+      const body = {}
+      for (const [name, s] of Object.entries(config)) {
+        body[name] = {
+          enabled: s.enabled,
+          audience: s.audience,
+          stream: s.stream,
+          fieldRules: s.fields || {},
+        }
+      }
+      const data = await api.admin.saveShardVisibility(body)
+      setConfig(data.features)
+      setMsg('Saved. Changes take effect within a few seconds, including on open live streams.')
+    } catch (err) {
+      setError(err.message || 'Could not save.')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  function resetToDefaults() {
+    setMsg('')
+    setConfig(structuredClone(defaults))
+  }
+
+  if (loading) return <Loading />
+  if (error && !config) return <ErrorState message={error} onRetry={load} />
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 20 }}>
+      <header>
+        <h2 className="display" style={{ margin: 0, fontSize: '1.3rem', color: 'var(--head)' }}>
+          Shard visibility
+        </h2>
+        <p className="sans" style={{ margin: '6px 0 0', color: 'var(--muted)', fontSize: '0.88rem', lineHeight: 1.6, maxWidth: 760 }}>
+          Choose who can see each shard surface on the public site, and how much detail they get.
+          Turning a feature off hides it entirely — its pages return “not found” rather than
+          revealing that it exists. “Live updates” controls whether the feature streams changes in
+          real time; the pages still work without it, they just refresh on load.
+        </p>
+        {lockedFields.length > 0 && (
+          <p className="sans dim" style={{ margin: '8px 0 0', fontSize: '0.82rem', lineHeight: 1.6, maxWidth: 760 }}>
+            Not configurable: <strong style={{ color: 'var(--ink)' }}>{lockedFields.join(', ')}</strong> —
+            game account names and website user ids are never shown below admin, on any surface. They
+            aren’t visible in game either, so publishing them would disclose something the shard
+            itself doesn’t.
+          </p>
+        )}
+      </header>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 14 }}>
+        {Object.entries(config).map(([name, settings]) => (
+          <FeatureRow
+            key={name}
+            name={name}
+            settings={settings}
+            defaults={defaults?.[name]}
+            ladder={ladder}
+            onPatch={patch}
+          />
+        ))}
+      </div>
+
+      <div style={{ display: 'flex', gap: 10, alignItems: 'center', flexWrap: 'wrap' }}>
+        <button onClick={save} disabled={saving} className="btn btn-primary btn-sq">
+          {saving ? 'Saving…' : 'Save changes'}
+        </button>
+        <button onClick={resetToDefaults} disabled={saving} className="btn btn-sq">
+          Restore defaults
+        </button>
+        {msg && <span className="sans" style={{ color: '#7fd0a4', fontSize: '0.85rem' }}>{msg}</span>}
+        {error && <span className="sans" style={{ color: '#d98b84', fontSize: '0.85rem' }}>{error}</span>}
+      </div>
+    </div>
+  )
+}

client/src/routes/admin/views/SpawnAtlas.jsx

@@ -0,0 +1,285 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Loading, ErrorState } from '../../../components/PageState.jsx'
+import { api } from '../../../api/client.js'
+
+// ── Admin · Spawn atlas ─────────────────────────────────────────────────────
+//
+// The atlas re-derives itself from the shard's ServUO tree on every boot, so
+// this panel exists for the three things a restart cannot do:
+//
+//   • point it at a different tree,
+//   • apply a map change without restarting, and
+//   • answer a refresh that was parsed but deliberately NOT applied because it
+//     would remove a facet.
+//
+// That last one is the reason the panel is worth building. Losing a facet looks
+// exactly like a half-copied or mid-update tree, and boot cannot tell them
+// apart — so it stages the decision for a human instead of guessing. Until
+// someone decides here, the site keeps serving the atlas it already had.
+
+// A refresh reports its outcome rather than throwing (the boot path must never
+// be stopped by a bad tree), so these are answers, not errors — the panel says
+// what happened in the shard's terms instead of showing a failure box.
+const OUTCOME = {
+  imported: (r) =>
+    `Imported — ${r.counts?.points?.toLocaleString() ?? '?'} spawners, ${r.counts?.creatures?.toLocaleString() ?? '?'} creatures.`,
+  unchanged: (r) =>
+    r.reason === 'refresh previously rejected'
+      ? 'Unchanged — this exact tree was already reviewed and declined.'
+      : 'Unchanged — the tree matches what is already loaded.',
+  needsReview: () => 'Staged for review: this refresh would remove a facet, so it was not applied.',
+  unavailable: (r) => `The tree could not be read: ${r.reason || 'unknown reason'}`,
+  skipped: () => 'No ServUO path is configured, so there is nothing to import.',
+  failed: (r) => `Refresh failed: ${r.reason || 'unknown reason'}`,
+  rejected: () => 'Declined. It will not be offered again until the tree changes.',
+}
+
+const describe = (result) => (OUTCOME[result?.status] || (() => `Result: ${result?.status}`))(result)
+
+function Row({ label, children }) {
+  return (
+    <div
+      className="sans"
+      style={{
+        display: 'flex',
+        alignItems: 'baseline',
+        justifyContent: 'space-between',
+        gap: 16,
+        padding: '7px 0',
+        borderBottom: '1px solid var(--line)',
+        fontSize: '0.86rem',
+      }}
+    >
+      <span className="dim">{label}</span>
+      <span style={{ color: 'var(--head)', textAlign: 'right', wordBreak: 'break-all' }}>{children}</span>
+    </div>
+  )
+}
+
+function PendingReview({ pending, busy, onApprove, onReject }) {
+  const declined = pending.status === 'rejected'
+  return (
+    <section
+      style={{
+        border: `1px solid ${declined ? 'var(--line)' : '#c58f4a'}`,
+        borderRadius: 10,
+        padding: 16,
+        background: declined ? 'transparent' : 'rgba(197,143,74,0.08)',
+      }}
+    >
+      <h3 className="display" style={{ margin: 0, fontSize: '1rem', color: 'var(--head)' }}>
+        {declined ? 'A refresh was declined' : 'A refresh is waiting for you'}
+      </h3>
+      <p className="sans" style={{ margin: '6px 0 12px', fontSize: '0.86rem', color: 'var(--muted)', lineHeight: 1.6 }}>
+        {declined ? (
+          <>
+            This tree was reviewed and declined, so it is not offered again until the files change.
+            Approving now applies it anyway.
+          </>
+        ) : (
+          <>
+            The tree parses cleanly but would <strong>remove {pending.removedFacets?.length || 0} facet
+            </strong>
+            {(pending.removedFacets?.length || 0) === 1 ? '' : 's'} the site is currently serving. That
+            is what a half-copied or mid-update tree looks like as well as a real map change, so it was
+            not applied. Approving re-parses the tree as it is right now — if you have since fixed the
+            mount, what lands is the corrected import.
+          </>
+        )}
+      </p>
+      <Row label="Would remove">{(pending.removedFacets || []).join(', ') || '—'}</Row>
+      <Row label="Would add">{(pending.addedFacets || []).join(', ') || '—'}</Row>
+      <Row label="Detected">{pending.detectedAt ? new Date(pending.detectedAt).toLocaleString() : '—'}</Row>
+      <div style={{ display: 'flex', gap: 10, marginTop: 14, flexWrap: 'wrap' }}>
+        <button type="button" className="btn btn-primary btn-sq" disabled={busy} onClick={onApprove}>
+          Approve and import
+        </button>
+        {!declined && (
+          <button type="button" className="btn btn-sq" disabled={busy} onClick={onReject}>
+            Keep the current atlas
+          </button>
+        )}
+      </div>
+    </section>
+  )
+}
+
+export default function SpawnAtlas() {
+  const [status, setStatus] = useState(null)
+  const [path, setPath] = useState('')
+  const [force, setForce] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState('')
+  const [msg, setMsg] = useState('')
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    setError('')
+    try {
+      const data = await api.admin.atlas.status()
+      setStatus(data)
+      setPath(data.path || '')
+    } catch (err) {
+      setError(err.message || 'Could not load atlas status.')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  // Every mutating action shares this: run it, report what it said, then reload
+  // status so the panel reflects the world rather than what we assumed happened.
+  async function run(action, fn) {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      const result = await fn()
+      setMsg(describe(result))
+      const fresh = await api.admin.atlas.status()
+      setStatus(fresh)
+      setPath(fresh.path || '')
+    } catch (err) {
+      setError(err.message || `Could not ${action}.`)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function savePath() {
+    setBusy(true)
+    setMsg('')
+    setError('')
+    try {
+      const fresh = await api.admin.atlas.setPath(path.trim())
+      setStatus(fresh)
+      setPath(fresh.path || '')
+      setMsg(
+        fresh.path === ''
+          ? 'Path cleared. The atlas will be skipped on the next boot; what is loaded keeps serving.'
+          : fresh.treeReadable
+            ? 'Saved. The tree is readable — import when you are ready.'
+            : 'Saved, but the tree could not be read from here. Check the mount and permissions.',
+      )
+    } catch (err) {
+      setError(err.message || 'Could not save the path.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (loading) return <Loading />
+  if (error && !status) return <ErrorState message={error} />
+
+  const counts = status?.counts || null
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 20 }}>
+      <header>
+        <h2 className="display" style={{ margin: 0, fontSize: '1.3rem', color: 'var(--head)' }}>
+          Spawn atlas
+        </h2>
+        <p className="sans" style={{ margin: '6px 0 0', color: 'var(--muted)', fontSize: '0.88rem', lineHeight: 1.6, maxWidth: 760 }}>
+          The bestiary and spawn map on the public site, parsed from the shard’s own ServUO files.
+          It refreshes itself on every server start; everything here is for the times you don’t want
+          to wait for one. Nothing on this page touches the sidecar — the atlas is shard content, not
+          shard state, and stays complete while the shard is down.
+        </p>
+      </header>
+
+      {status?.pending && (
+        <PendingReview
+          pending={status.pending}
+          busy={busy}
+          onApprove={() => run('approve the refresh', () => api.admin.atlas.approve())}
+          onReject={() => run('decline the refresh', () => api.admin.atlas.reject())}
+        />
+      )}
+
+      <section style={{ border: '1px solid var(--line)', borderRadius: 10, padding: 16 }}>
+        <h3 className="display" style={{ margin: '0 0 10px', fontSize: '1rem', color: 'var(--head)' }}>
+          What is loaded
+        </h3>
+        <Row label="Imported">
+          {status?.importedAt ? new Date(status.importedAt).toLocaleString() : 'Never'}
+        </Row>
+        <Row label="Facets">{status?.facets?.length ? status.facets.join(', ') : '—'}</Row>
+        {counts && (
+          <>
+            <Row label="Spawners">{counts.points?.toLocaleString() ?? '—'}</Row>
+            <Row label="Creatures">{counts.creatures?.toLocaleString() ?? '—'}</Row>
+            <Row label="Regions / landmarks">
+              {`${counts.regions?.toLocaleString() ?? '—'} / ${counts.landmarks?.toLocaleString() ?? '—'}`}
+            </Row>
+            <Row label="Champion altars">{counts.champions?.toLocaleString() ?? '—'}</Row>
+          </>
+        )}
+        <Row label="Tree readable">
+          {!status?.configured ? 'No path set' : status.treeReadable ? 'Yes' : 'No'}
+        </Row>
+        <Row label="Tree changed since import">
+          {status?.drift == null ? '—' : status.drift ? 'Yes — an import would pick it up' : 'No'}
+        </Row>
+      </section>
+
+      <section style={{ border: '1px solid var(--line)', borderRadius: 10, padding: 16 }}>
+        <h3 className="display" style={{ margin: '0 0 4px', fontSize: '1rem', color: 'var(--head)' }}>
+          ServUO tree
+        </h3>
+        <p className="sans" style={{ margin: '0 0 12px', fontSize: '0.84rem', color: 'var(--muted)', lineHeight: 1.6 }}>
+          Where the website reads the shard’s spawn files from — the same host, a bind mount or a
+          shared volume. This setting wins over the <code>SERVUO_PATH</code> deploy default, so the
+          mount can move without a redeploy. Leave it blank to turn the atlas off.
+        </p>
+        <div style={{ display: 'flex', gap: 10, flexWrap: 'wrap', alignItems: 'center' }}>
+          <input
+            className="input"
+            value={path}
+            onChange={(e) => setPath(e.target.value)}
+            placeholder="/srv/servuo"
+            style={{ flex: '1 1 320px', minWidth: 0 }}
+          />
+          <button type="button" className="btn btn-sq" disabled={busy} onClick={savePath}>
+            Save path
+          </button>
+        </div>
+      </section>
+
+      <section style={{ border: '1px solid var(--line)', borderRadius: 10, padding: 16 }}>
+        <h3 className="display" style={{ margin: '0 0 4px', fontSize: '1rem', color: 'var(--head)' }}>
+          Re-import
+        </h3>
+        <p className="sans" style={{ margin: '0 0 12px', fontSize: '0.84rem', color: 'var(--muted)', lineHeight: 1.6 }}>
+          Applies a map change without restarting. An unchanged tree costs nothing — the source files
+          are hashed first and skipped when they match. A refresh that would remove a facet still
+          comes back here for approval rather than being applied.
+        </p>
+        <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap', alignItems: 'center' }}>
+          <button
+            type="button"
+            className="btn btn-primary btn-sq"
+            disabled={busy || !status?.configured}
+            onClick={() => run('import the atlas', () => api.admin.atlas.import(force))}
+          >
+            {busy ? 'Working…' : 'Import now'}
+          </button>
+          <label className="sans" style={{ display: 'inline-flex', alignItems: 'center', gap: 8, fontSize: '0.85rem', cursor: 'pointer' }}>
+            <input type="checkbox" checked={force} onChange={(e) => setForce(e.target.checked)} />
+            Re-import even if the tree is unchanged
+          </label>
+        </div>
+      </section>
+
+      {(msg || error) && (
+        <div style={{ display: 'flex', gap: 10, alignItems: 'center', flexWrap: 'wrap' }}>
+          {msg && <span className="sans" style={{ color: '#7fd0a4', fontSize: '0.85rem' }}>{msg}</span>}
+          {error && <span className="sans" style={{ color: '#d98b84', fontSize: '0.85rem' }}>{error}</span>}
+        </div>
+      )}
+    </div>
+  )
+}

client/src/routes/player/PlayerLogin.jsx

@@ -108,15 +108,28 @@ export default function PlayerLogin() {
     setBusy(true)
     try {
       if (ssoTotp) {
-        const { returnTo, redirect } = await ssoLoginTotp(code)
+        // Trust works on the SSO second factor too. On the mobile bridge this page
+        // is running inside the app's Custom Tab, so the cookie set here is what
+        // lets the next app sign-in skip the code.
+        const data = await ssoLoginTotp(code.trim(), { trustDevice })
         // Native SSO bridge (M9): a mobile 2FA completion returns an absolute
         // deep link (e.g. runicgateway://…) to hand the app its one-time code.
         // React Router can't navigate a custom scheme, so leave the SPA for it.
-        if (redirect) {
-          window.location.href = redirect
+        // This wins over the trust-cap prompt: the sign-in itself succeeded and the
+        // deep link is single-use, so stalling here to manage devices would strand
+        // the app. An over-cap user simply isn't trusted and can prune the list
+        // from Account → Trusted Devices.
+        if (data.redirect) {
+          window.location.href = data.redirect
           return
         }
-        navigate(returnTo || '/account', { replace: true })
+        const to = data.returnTo || '/account'
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       } else {
         const entered = code.trim()
         const data = await loginTotp(challenge, useRecovery ? '' : entered, {
@@ -206,14 +219,15 @@ export default function PlayerLogin() {
                 {useRecovery ? 'Enter one of your saved single-use recovery codes.' : 'Enter the code from your authenticator app.'}
               </span>
             </label>
-            {/* Trust-this-device only applies to real authenticator/recovery login,
-                not the SSO 2FA bounce (which has no trust cookie flow here). */}
-            {!ssoTotp && (
+            {/* Offered on the SSO second factor too — the trust is on the device,
+                not on how the first factor was proved. Inside the app's Custom Tab
+                this is also what trusts the device for future native sign-ins. */}
             <label className="sans" style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12, color: 'var(--muted)', fontSize: '0.84rem' }}>
               <input type="checkbox" checked={trustDevice} onChange={(e) => setTrustDevice(e.target.checked)} />
               Trust this device for 30 days (skip the code next time)
             </label>
-            )}
+            {/* Recovery codes remain password-login only: the SSO second step
+                verifies an authenticator code against the staged challenge. */}
             {!ssoTotp && (
               <button
                 type="button"

client/src/routes/public/Atlas.jsx

@@ -0,0 +1,310 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { Link } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// ── The spawn atlas ─────────────────────────────────────────────────────────
+//
+// What the shard CONTAINS, as opposed to what it is doing: which creatures
+// spawn, where, and which champion altars are configured. There is no live feed
+// here and no `connected` indicator, deliberately — this is parsed from the
+// shard's own files and stays complete while the shard is down.
+//
+// Facet names come from the shard's data, never from a list in this file. A
+// shard running custom maps gets its own names in the filter with no code
+// change (docs/link/v3.md §6.1 R2).
+
+const PAGE = 50
+
+const num = (v) => (Number.isFinite(v) ? v.toLocaleString() : '—')
+
+const TABS = [
+  { key: 'creatures', label: 'Creatures' },
+  { key: 'champions', label: 'Champion altars' },
+  { key: 'places', label: 'Places' },
+]
+
+function Chip({ active, onClick, children }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="sans"
+      style={{
+        fontSize: '0.78rem',
+        padding: '5px 12px',
+        borderRadius: 999,
+        cursor: 'pointer',
+        color: active ? 'var(--bg-deep)' : 'var(--muted)',
+        background: active ? 'var(--accent)' : 'transparent',
+        border: `1px solid ${active ? 'var(--accent)' : 'var(--line)'}`,
+      }}
+    >
+      {children}
+    </button>
+  )
+}
+
+function CreatureCard({ creature }) {
+  const facets = Object.entries(creature.facets || {}).sort((a, b) => b[1] - a[1])
+  return (
+    <Link
+      to={`/site/atlas/${encodeURIComponent(creature.slug)}`}
+      className="panel"
+      style={{
+        padding: '13px 15px',
+        display: 'flex',
+        alignItems: 'center',
+        gap: 14,
+        textDecoration: 'none',
+        color: 'inherit',
+      }}
+    >
+      <div style={{ minWidth: 0, flex: 1 }}>
+        <div
+          className="display"
+          style={{
+            fontSize: '0.98rem',
+            color: 'var(--head)',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {creature.name}
+        </div>
+        <div className="sans dim" style={{ fontSize: '0.74rem', marginTop: 3 }}>
+          {facets.length === 0
+            ? '—'
+            : facets.map(([facet, n]) => `${facet} (${n})`).join(' · ')}
+        </div>
+      </div>
+      <div className="sans" style={{ flex: 'none', textAlign: 'right' }}>
+        <div style={{ color: 'var(--head)', fontSize: '0.92rem' }}>{num(creature.total)}</div>
+        <div className="dim" style={{ fontSize: '0.68rem', letterSpacing: '0.05em' }}>
+          {num(creature.points)} spawners
+        </div>
+      </div>
+    </Link>
+  )
+}
+
+// The creature list owns its own paging rather than going through useAsync: a
+// "load more" appends to what is already on screen, which a hook that resets to
+// `{ loading: true, data: null }` on every dependency change cannot express.
+function Creatures({ q, facet }) {
+  const [state, setState] = useState({ loading: true, error: null, items: [], total: 0 })
+  const [more, setMore] = useState(false)
+
+  const load = useCallback(
+    async (offset) => {
+      const page = await api.atlas.creatures({ q, facet, limit: PAGE, offset })
+      return page
+    },
+    [q, facet],
+  )
+
+  useEffect(() => {
+    let alive = true
+    setState({ loading: true, error: null, items: [], total: 0 })
+    load(0)
+      .then((page) => {
+        if (alive) setState({ loading: false, error: null, items: page.creatures || [], total: page.total || 0 })
+      })
+      .catch((error) => alive && setState({ loading: false, error, items: [], total: 0 }))
+    return () => {
+      alive = false
+    }
+  }, [load])
+
+  const loadMore = async () => {
+    setMore(true)
+    try {
+      const page = await load(state.items.length)
+      setState((s) => ({ ...s, items: [...s.items, ...(page.creatures || [])], total: page.total ?? s.total }))
+    } catch {
+      // A failed "load more" leaves what is already on screen alone; the button
+      // simply stays available to retry.
+    } finally {
+      setMore(false)
+    }
+  }
+
+  if (state.loading) return <Loading />
+  if (state.error) return <ErrorState message="Could not load the bestiary right now." />
+  if (state.items.length === 0) {
+    return <EmptyState>Nothing in the atlas matches that.</EmptyState>
+  }
+
+  return (
+    <>
+      <p className="sans dim" style={{ fontSize: '0.78rem', margin: '0 0 12px' }}>
+        Showing {num(state.items.length)} of {num(state.total)}
+      </p>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+        {state.items.map((c) => (
+          <CreatureCard key={c.slug} creature={c} />
+        ))}
+      </div>
+      {state.items.length < state.total && (
+        <div style={{ textAlign: 'center', marginTop: 16 }}>
+          <button type="button" className="btn" onClick={loadMore} disabled={more}>
+            {more ? 'Loading…' : 'Load more'}
+          </button>
+        </div>
+      )}
+    </>
+  )
+}
+
+// The CONFIGURED altar roster — where the altars are and what each summons. The
+// live board ("it is on level 3 right now") is a different page, /site/champs,
+// fed by the sidecar. Both exist; they are not the same thing.
+function Champions({ facet }) {
+  const { loading, error, data } = useAsync(() => api.atlas.champions(facet), [facet])
+  if (loading) return <Loading />
+  if (error) return <ErrorState message="Could not load the champion altars right now." />
+  if (!data || data.length === 0) return <EmptyState>No champion altars are configured.</EmptyState>
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+      {data.map((champ) => (
+        <div key={champ.slug} className="panel" style={{ padding: '13px 15px', display: 'flex', gap: 14, alignItems: 'center' }}>
+          <div style={{ minWidth: 0, flex: 1 }}>
+            <div className="display" style={{ fontSize: '0.98rem', color: 'var(--head)' }}>
+              {champ.label || champ.name}
+            </div>
+            <div className="sans dim" style={{ fontSize: '0.74rem', marginTop: 3 }}>
+              {champ.facet}
+              {champ.group ? ` · ${champ.group}` : ''} · {champ.x}, {champ.y}
+            </div>
+          </div>
+          <span className="sans" style={{ flex: 'none', fontSize: '0.76rem', color: 'var(--muted)' }}>
+            {champ.randomType ? 'Random champion' : champ.type || '—'}
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// Regions and landmarks together: both answer "where is that?", and splitting
+// them into two tabs would make the visitor guess which list a name lives in.
+function Places({ q, facet }) {
+  const { loading, error, data } = useAsync(
+    () => Promise.all([api.atlas.regions({ q, facet }), api.atlas.landmarks({ q, facet })]),
+    [q, facet],
+  )
+  const rows = useMemo(() => {
+    if (!data) return []
+    const [regions, landmarks] = data
+    return [
+      ...regions.map((r) => ({ key: `r:${r.facet}:${r.name}`, name: r.name, facet: r.facet, detail: r.parent || r.type || 'Region', kind: 'Region' })),
+      ...landmarks.map((l) => ({ key: `l:${l.facet}:${l.group || ''}:${l.name}:${l.x}:${l.y}`, name: l.group ? `${l.group} — ${l.name}` : l.name, facet: l.facet, detail: `${l.x}, ${l.y}`, kind: 'Landmark' })),
+    ].sort((a, b) => a.name.localeCompare(b.name))
+  }, [data])
+
+  if (loading) return <Loading />
+  if (error) return <ErrorState message="Could not load places right now." />
+  if (rows.length === 0) return <EmptyState>No regions or landmarks match that.</EmptyState>
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+      {rows.map((row) => (
+        <div key={row.key} className="panel" style={{ padding: '10px 14px', display: 'flex', gap: 12, alignItems: 'baseline' }}>
+          <span className="sans" style={{ flex: 1, minWidth: 0, color: 'var(--head)', fontSize: '0.88rem' }}>{row.name}</span>
+          <span className="sans dim" style={{ fontSize: '0.72rem' }}>{row.facet} · {row.detail}</span>
+          <span className="sans dim" style={{ fontSize: '0.66rem', letterSpacing: '0.06em', flex: 'none' }}>{row.kind}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export default function Atlas() {
+  const [tab, setTab] = useState('creatures')
+  const [input, setInput] = useState('')
+  const [q, setQ] = useState('')
+  const [facet, setFacet] = useState('')
+  const meta = useAsync(() => api.atlas.meta())
+
+  // Debounced: typing "lizardman" should be one request, not nine.
+  useEffect(() => {
+    const timer = setTimeout(() => setQ(input.trim()), 250)
+    return () => clearTimeout(timer)
+  }, [input])
+
+  const facets = meta.data?.facets || []
+  const counts = meta.data?.counts || null
+  const imported = meta.data?.importedAt ? new Date(meta.data.importedAt) : null
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <PageHeader
+          eyebrow="Bestiary"
+          title="Spawn atlas"
+          lead="Where everything lives, read straight out of the shard's own spawn files — so it stays accurate whether or not the server is up."
+        />
+
+        {/* The atlas is only as good as its placement rate, so the page states
+            it rather than implying every spawner resolved to a named place. */}
+        {counts && (
+          <p className="sans dim" style={{ fontSize: '0.76rem', margin: '-12px 0 18px' }}>
+            {num(counts.creatures)} creatures across {num(counts.points)} spawners
+            {Number.isFinite(counts.unresolvedPoints) && counts.points
+              ? ` · ${Math.round(((counts.points - counts.unresolvedPoints) / counts.points) * 100)}% placed to a named region or landmark`
+              : ''}
+            {imported ? ` · parsed ${imported.toLocaleDateString()}` : ''}
+          </p>
+        )}
+
+        <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', marginBottom: 12 }}>
+          {TABS.map((t) => (
+            <Chip key={t.key} active={tab === t.key} onClick={() => setTab(t.key)}>
+              {t.label}
+            </Chip>
+          ))}
+        </div>
+
+        {tab !== 'champions' && (
+          <input
+            className="input"
+            type="search"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder={tab === 'creatures' ? 'Search creatures…' : 'Search regions and landmarks…'}
+            style={{ width: '100%', marginBottom: 12 }}
+          />
+        )}
+
+        {facets.length > 0 && (
+          <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 18 }}>
+            <Chip active={facet === ''} onClick={() => setFacet('')}>
+              All facets
+            </Chip>
+            {facets.map((f) => (
+              <Chip key={f} active={facet === f} onClick={() => setFacet(f)}>
+                {f}
+              </Chip>
+            ))}
+          </div>
+        )}
+
+        {meta.error && <ErrorState message="Could not load the atlas right now." />}
+        {!meta.error && !meta.loading && !imported && (
+          <EmptyState>The spawn atlas has not been imported yet.</EmptyState>
+        )}
+
+        {!meta.error && imported && (
+          <>
+            {tab === 'creatures' && <Creatures q={q} facet={facet} />}
+            {tab === 'champions' && <Champions facet={facet} />}
+            {tab === 'places' && <Places q={q} facet={facet} />}
+          </>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/AtlasCreature.jsx

@@ -0,0 +1,201 @@
+import { useMemo, useState } from 'react'
+import { Link, useParams } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// One creature: where it spawns, and what spawns alongside it.
+//
+// `places` is the point of the page — the aggregate that turns 62 raw
+// coordinates into "Shrines, Isamu-Jima, Yew". The individual spawners are
+// available underneath for the reader who actually wants a coordinate, but they
+// are secondary and collapsed by default.
+
+const num = (v) => (Number.isFinite(v) ? v.toLocaleString() : '—')
+
+// Spawn delays are stored in seconds. A raw "1200" tells the reader nothing.
+function delay(min, max) {
+  const fmt = (s) => (s >= 60 ? `${Math.round(s / 60)}m` : `${s}s`)
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return null
+  if (min === max) return fmt(min)
+  return `${fmt(min)}–${fmt(max)}`
+}
+
+function Panel({ title, right, children }) {
+  return (
+    <section className="panel" style={{ padding: 18 }}>
+      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 12 }}>
+        <h2 className="display" style={{ margin: '0 0 12px', fontSize: '1.02rem', color: 'var(--head)' }}>
+          {title}
+        </h2>
+        {right}
+      </div>
+      {children}
+    </section>
+  )
+}
+
+function Places({ places }) {
+  if (places.length === 0) {
+    return <p className="sans dim" style={{ margin: 0 }}>No placed spawners.</p>
+  }
+  return (
+    <div>
+      {places.map((place) => (
+        <div
+          key={`${place.facet}:${place.label}`}
+          className="sans"
+          style={{
+            display: 'flex',
+            alignItems: 'baseline',
+            justifyContent: 'space-between',
+            gap: 12,
+            padding: '6px 0',
+            borderBottom: '1px solid var(--line)',
+            fontSize: '0.86rem',
+          }}
+        >
+          <span style={{ minWidth: 0, color: 'var(--head)' }}>{place.label}</span>
+          <span className="dim" style={{ flex: 'none' }}>
+            {place.facet} · {num(place.spawners)} spawner{place.spawners === 1 ? '' : 's'} · up to{' '}
+            {num(place.maxAlive)} at once
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function Spawners({ spawners, truncated }) {
+  const [open, setOpen] = useState(false)
+  if (spawners.length === 0) return null
+  return (
+    <Panel
+      title="Individual spawners"
+      right={
+        <button
+          type="button"
+          className="sans"
+          onClick={() => setOpen((v) => !v)}
+          style={{ background: 'none', border: 'none', color: 'var(--accent)', cursor: 'pointer', fontSize: '0.78rem' }}
+        >
+          {open ? 'Hide' : `Show ${num(spawners.length)}`}
+        </button>
+      }
+    >
+      {open && (
+        <div style={{ overflowX: 'auto' }}>
+          <table className="sans" style={{ width: '100%', borderCollapse: 'collapse', fontSize: '0.8rem' }}>
+            <thead>
+              <tr style={{ textAlign: 'left', color: 'var(--muted)' }}>
+                <th style={{ padding: '4px 8px 8px 0' }}>Place</th>
+                <th style={{ padding: '4px 8px 8px 0' }}>Facet</th>
+                <th style={{ padding: '4px 8px 8px 0' }}>Coords</th>
+                <th style={{ padding: '4px 8px 8px 0' }}>Max</th>
+                <th style={{ padding: '4px 0 8px 0' }}>Respawn</th>
+              </tr>
+            </thead>
+            <tbody>
+              {spawners.map((s) => (
+                <tr key={s.id} style={{ borderTop: '1px solid var(--line)' }}>
+                  <td style={{ padding: '6px 8px 6px 0', color: 'var(--head)' }}>{s.label}</td>
+                  <td style={{ padding: '6px 8px 6px 0' }} className="dim">{s.facet}</td>
+                  <td style={{ padding: '6px 8px 6px 0' }} className="dim">{s.x}, {s.y}</td>
+                  <td style={{ padding: '6px 8px 6px 0' }} className="dim">{num(s.maxCount)}</td>
+                  <td style={{ padding: '6px 0' }} className="dim">{delay(s.minDelay, s.maxDelay) || '—'}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          {truncated && (
+            <p className="sans dim" style={{ fontSize: '0.74rem', margin: '10px 0 0' }}>
+              Only the largest spawners are listed.
+            </p>
+          )}
+        </div>
+      )}
+    </Panel>
+  )
+}
+
+export default function AtlasCreature() {
+  const { slug } = useParams()
+  const { loading, error, data } = useAsync(() => api.atlas.creature(slug), [slug])
+
+  // A 404 here means "no such creature in this atlas", which is a real answer
+  // and not a failure — a visitor following a stale link deserves to be told
+  // that plainly rather than shown a generic error box.
+  const missing = error?.status === 404 || error?.message === 'Not Found'
+
+  const facets = useMemo(
+    () => Object.entries(data?.facets || {}).sort((a, b) => b[1] - a[1]),
+    [data],
+  )
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <p className="sans" style={{ marginBottom: 8 }}>
+          <Link to="/site/atlas" style={{ color: 'var(--accent)', fontSize: '0.78rem' }}>
+            ← Spawn atlas
+          </Link>
+        </p>
+
+        {loading && <Loading />}
+        {error && !missing && <ErrorState message="Could not load that creature right now." />}
+        {missing && <EmptyState>Nothing by that name spawns on this shard.</EmptyState>}
+
+        {!loading && !error && data && (
+          <>
+            <PageHeader
+              eyebrow="Bestiary"
+              title={data.name}
+              lead={`Up to ${num(data.total)} alive at once across ${num(data.points)} spawner${data.points === 1 ? '' : 's'}.`}
+            />
+
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+              <Panel
+                title="Where it spawns"
+                right={
+                  <span className="sans dim" style={{ fontSize: '0.74rem' }}>
+                    {facets.map(([facet, n]) => `${facet} (${n})`).join(' · ')}
+                  </span>
+                }
+              >
+                <Places places={data.places || []} />
+              </Panel>
+
+              <Spawners spawners={data.spawners || []} truncated={!!data.spawnersTruncated} />
+
+              {data.alsoHere?.length > 0 && (
+                <Panel title="Shares a spawner with">
+                  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+                    {data.alsoHere.map((other) => (
+                      <Link
+                        key={other.slug}
+                        to={`/site/atlas/${encodeURIComponent(other.slug)}`}
+                        className="sans"
+                        style={{
+                          fontSize: '0.78rem',
+                          padding: '4px 11px',
+                          borderRadius: 999,
+                          border: '1px solid var(--line)',
+                          color: 'var(--muted)',
+                          textDecoration: 'none',
+                        }}
+                      >
+                        {other.name} <span className="dim">×{num(other.shared)}</span>
+                      </Link>
+                    ))}
+                  </div>
+                </Panel>
+              )}
+            </div>
+          </>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/Leaderboards.jsx

@@ -0,0 +1,240 @@
+import { useMemo, useState } from 'react'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { useShardFeed } from '../../lib/useShardFeed.js'
+import { api } from '../../api/client.js'
+import { useSite } from '../../contexts/SiteContext.jsx'
+
+// Points / loyalty leaderboards (Protocol 3.0 §7). The shard carries ~25 separate
+// point currencies — Queen's Loyalty, Void Pool, Clean Up Britannia, the nine city
+// loyalties, the Doom/Khaldun/Kotl treasure systems — every one of them a standing
+// players build over months, and none of them visible anywhere but an in-game gump
+// until now.
+//
+// Loaded from /public/shard/points, then kept current from the live feed. Unlike
+// the ruleset (one frame = the whole thing), a points.board frame describes ONE
+// system, so live frames are merged over the fetched set by system key rather than
+// replacing it.
+const POINTS_KINDS = new Set(['points.board'])
+
+// A board's display name may arrive as a literal (`nameString`), a cliloc id
+// (`nameNumber`), or both — Name is a ServUO TextDefinition. We have no cliloc
+// table on the site, so a cliloc-only board falls back to humanising its own
+// PointsType key, which is already close to a display name ("CleanUpBritannia" →
+// "Clean Up Britannia"). Better than showing a bare number.
+const humanise = (key) =>
+  String(key || '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/^./, (c) => c.toUpperCase())
+
+const boardTitle = (b) => b.nameString || humanise(b.system)
+
+const num = (v) => (Number.isFinite(v) ? v.toLocaleString() : '—')
+
+// Merge live frames over the fetched boards. Newest frame per system wins; a
+// system that has never appeared in either is simply absent.
+function mergeBoards(fetched, events) {
+  const bySystem = new Map()
+  for (const b of Array.isArray(fetched) ? fetched : []) {
+    if (b && b.system) bySystem.set(b.system, b)
+  }
+  // Events arrive newest-first, so walk backwards and let the newest land last.
+  for (let i = events.length - 1; i >= 0; i--) {
+    const ev = events[i]
+    if (ev && ev.system) bySystem.set(ev.system, ev)
+  }
+  return [...bySystem.values()].sort((a, b) => boardTitle(a).localeCompare(boardTitle(b)))
+}
+
+function Medal({ rank }) {
+  // Gold / silver / bronze for the podium, plain for the rest.
+  const tone = rank === 1 ? '#c9a24b' : rank === 2 ? '#b6bcc6' : rank === 3 ? '#b3805a' : 'var(--muted)'
+  return (
+    <span
+      className="display"
+      style={{
+        flex: 'none', width: 26, textAlign: 'right', color: tone,
+        fontSize: rank <= 3 ? '1rem' : '0.86rem',
+      }}
+    >
+      {rank}
+    </span>
+  )
+}
+
+// One ranked player. `name` is absent rather than empty when an admin has gated
+// the leaderboards `name` field above this viewer's rung — the row still renders,
+// because the standing itself is the point.
+function Entry({ entry, best }) {
+  const pct = best > 0 ? Math.max(2, Math.round((entry.points / best) * 100)) : 0
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 10, padding: '6px 0' }}>
+      <Medal rank={entry.rank} />
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline', gap: 10 }}>
+          <span
+            className="sans"
+            style={{
+              color: entry.name ? 'var(--ink)' : 'var(--muted)',
+              fontSize: '0.86rem', fontStyle: entry.name ? 'normal' : 'italic',
+              overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+            }}
+          >
+            {entry.name || 'Name hidden'}
+          </span>
+          <span className="sans" style={{ color: 'var(--head)', fontSize: '0.82rem', flex: 'none' }}>
+            {num(entry.points)}
+          </span>
+        </div>
+        <div style={{ height: 4, borderRadius: 999, background: 'var(--line)', overflow: 'hidden', marginTop: 3 }}>
+          <div style={{ width: `${pct}%`, height: '100%', background: 'var(--accent)' }} />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function Board({ board }) {
+  const { siteTitle } = useSite()
+  const top = Array.isArray(board.top) ? board.top : []
+  // Bars are relative to the board leader, not to maxPoints: most systems have no
+  // cap (maxPoints 0), and where there is one the leader is often nowhere near it,
+  // which would render every bar as a stub.
+  const best = top.reduce((m, e) => Math.max(m, e.points || 0), 0)
+
+  return (
+    <section className="panel" style={{ padding: 18, display: 'flex', flexDirection: 'column', gap: 10 }}>
+      <div style={{ display: 'flex', alignItems: 'baseline', justifyContent: 'space-between', gap: 10 }}>
+        <h2 className="display" style={{ margin: 0, fontSize: '1.02rem', color: 'var(--head)' }}>
+          {boardTitle(board)}
+        </h2>
+        {Number.isFinite(board.players) && (
+          <span className="sans dim" style={{ fontSize: '0.72rem', flex: 'none' }}>
+            {num(board.players)} ranked
+          </span>
+        )}
+      </div>
+
+      {top.length === 0 ? (
+        // A board nobody has scored on still gets a row, so the page reads as a set
+        // of standings waiting to be filled rather than a stack of blanks. It is
+        // deliberately NOT shaped like an Entry — no medal, no bar, an em dash where
+        // a score goes — because a placeholder that looked like a real standing would
+        // be a fabricated one. The first real entry replaces it.
+        <div>
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline', gap: 10, padding: '6px 0' }}>
+            <span
+              className="sans"
+              style={{
+                color: 'var(--muted)', fontSize: '0.86rem',
+                overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+              }}
+            >
+              {siteTitle}
+            </span>
+            <span className="sans dim" style={{ fontSize: '0.82rem', flex: 'none' }}>&mdash;</span>
+          </div>
+          <p className="sans dim" style={{ margin: 0, fontSize: '0.78rem' }}>
+            Nobody has earned points here yet.
+          </p>
+        </div>
+      ) : (
+        <div>
+          {top.map((entry) => (
+            <Entry key={`${board.system}-${entry.rank}-${entry.serial}`} entry={entry} best={best} />
+          ))}
+        </div>
+      )}
+
+      {Number.isFinite(board.maxPoints) && board.maxPoints > 0 && (
+        <span className="sans dim" style={{ fontSize: '0.72rem' }}>
+          Maximum {num(board.maxPoints)} points
+        </span>
+      )}
+    </section>
+  )
+}
+
+export default function Leaderboards() {
+  const { loading, error, data } = useAsync(() => api.shard.points())
+  // Buffer generously: a single sweep can emit a frame for every system at once,
+  // and a board dropped from the buffer would silently revert to its fetched copy.
+  const { events, connected } = useShardFeed({ filter: POINTS_KINDS, max: 60 })
+  const [query, setQuery] = useState('')
+
+  const boards = useMemo(() => mergeBoards(data, events), [data, events])
+
+  const shown = useMemo(() => {
+    const q = query.trim().toLowerCase()
+    if (!q) return boards
+    // Match the board name, the raw system key, or any ranked player on it — the
+    // last is what makes the filter useful ("where do I appear?").
+    return boards.filter(
+      (b) =>
+        boardTitle(b).toLowerCase().includes(q) ||
+        String(b.system).toLowerCase().includes(q) ||
+        (b.top || []).some((e) => e.name && e.name.toLowerCase().includes(q)),
+    )
+  }, [boards, query])
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell page-body">
+        <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16 }}>
+          <PageHeader
+            eyebrow="Live"
+            title="Leaderboards"
+            lead="Loyalty and points standings, straight from the shard — every currency the server tracks, updated as players climb."
+          />
+          <span
+            className="sans"
+            style={{
+              display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: '0.74rem',
+              color: connected ? '#7fd0a4' : 'var(--muted)', flex: 'none', marginTop: 6,
+            }}
+          >
+            <span style={{ width: 8, height: 8, borderRadius: '50%', background: connected ? '#7fd0a4' : 'var(--dim)' }} />
+            {connected ? 'Live' : 'Offline'}
+          </span>
+        </div>
+
+        {loading && <Loading />}
+        {error && <ErrorState message="Could not load the leaderboards right now." />}
+
+        {!loading && !error && boards.length === 0 && (
+          <section className="panel" style={{ padding: 24, textAlign: 'center' }}>
+            <p className="sans dim" style={{ margin: 0 }}>
+              The shard has not published any leaderboards yet.
+            </p>
+          </section>
+        )}
+
+        {!loading && !error && boards.length > 0 && (
+          <>
+            <input
+              className="input"
+              type="search"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder="Filter by board or player name…"
+              aria-label="Filter leaderboards"
+              style={{ maxWidth: 340, marginBottom: 14 }}
+            />
+
+            {shown.length === 0 ? (
+              <p className="sans dim">No board or ranked player matches “{query}”.</p>
+            ) : (
+              <div className="grid-2" style={{ gap: 12, alignItems: 'start' }}>
+                {shown.map((board) => (
+                  <Board key={board.system} board={board} />
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/Market.jsx

@@ -0,0 +1,325 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Link } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// ── The player-vendor marketplace ───────────────────────────────────────────
+//
+// What every player vendor on the shard is selling, for how much, and where it
+// is standing — the same index the in-game Vendor Search gump reads, honouring
+// the same per-vendor opt-out, reachable without logging in to the game.
+//
+// Three things this page must be honest about, all of them consequences of how
+// the data is gathered (docs/link/v3.md §8):
+//
+//   • **The prices are not live.** The shard sweeps vendors round-robin, so a
+//     shop can be a full cycle behind. The banner says how far, from `staleAt`.
+//     A page that implied live prices would send people across the world to a
+//     vendor whose item sold twenty minutes ago.
+//   • **A shop can be truncated.** A commodity reseller with thousands of stacks
+//     publishes only the first N, and saying so beats presenting a partial shop
+//     as complete.
+//   • **An item may have no name.** On a shard whose operator has not converted
+//     a cliloc table, `displayName` is null and the honest render is the item id
+//     — not an invented name.
+//
+// There is deliberately no live feed here. The market feature's SSE stream ships
+// disabled: a firehose of whole vendor inventories would be the site's single
+// biggest bandwidth consumer, and nothing on this page needs it.
+
+const PAGE = 50
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v).toLocaleString() : '—')
+
+const SORTS = [
+  { key: 'price_asc', label: 'Cheapest' },
+  { key: 'price_desc', label: 'Priciest' },
+  { key: 'recent', label: 'Recently seen' },
+]
+
+// How old the index may be, in words. `staleAt` is the OLDEST vendor row, so
+// this is a worst case rather than an average — which is the number worth
+// showing, because the one stale shop is the one that wastes a trip.
+function staleness(staleAt) {
+  if (!staleAt) return null
+  const ms = Date.now() - new Date(staleAt).getTime()
+  if (!Number.isFinite(ms) || ms < 0) return null
+  const mins = Math.round(ms / 60000)
+  if (mins < 1) return 'just now'
+  if (mins < 60) return `${mins} minute${mins === 1 ? '' : 's'} ago`
+  const hours = Math.round(mins / 60)
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`
+  return `${Math.round(hours / 24)} days ago`
+}
+
+// The item's name, or an honest statement that we do not have one. Never a
+// fabricated label — "Item 3922" would be indistinguishable from a real name.
+const itemLabel = (l) => l.displayName || l.name || `id ${l.itemId}`
+
+function Chip({ active, onClick, children }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="sans"
+      style={{
+        fontSize: '0.78rem',
+        padding: '5px 12px',
+        borderRadius: 999,
+        cursor: 'pointer',
+        color: active ? 'var(--bg-deep)' : 'var(--muted)',
+        background: active ? 'var(--accent)' : 'transparent',
+        border: `1px solid ${active ? 'var(--accent)' : 'var(--line)'}`,
+      }}
+    >
+      {children}
+    </button>
+  )
+}
+
+function ListingRow({ listing }) {
+  const v = listing.vendor || {}
+  // `location` is one field the admin can gate away wholesale, so everything
+  // that reads from it has to tolerate its absence rather than assuming a map.
+  const loc = v.location || null
+  const where = loc ? [loc.region, loc.map].filter(Boolean).join(', ') : null
+
+  return (
+    <div className="panel" style={{ padding: '13px 15px', display: 'flex', gap: 14, alignItems: 'center' }}>
+      <div style={{ minWidth: 0, flex: 1 }}>
+        <div
+          className="display"
+          style={{ fontSize: '0.98rem', color: 'var(--head)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}
+        >
+          {listing.amount > 1 ? `${num(listing.amount)} × ` : ''}
+          {itemLabel(listing)}
+        </div>
+        <div className="sans dim" style={{ fontSize: '0.74rem', marginTop: 3 }}>
+          {v.serial ? (
+            <Link to={`/site/market/vendors/${encodeURIComponent(v.serial)}`} style={{ color: 'inherit' }}>
+              {v.shopName || 'an unnamed shop'}
+            </Link>
+          ) : (
+            v.shopName || 'an unnamed shop'
+          )}
+          {v.ownerName ? ` · ${v.ownerName}` : ''}
+          {where ? ` · ${where}` : ''}
+          {/* Priced by the container it sits in, exactly as the in-game search
+              reports it — the price buys the whole container, not this item. */}
+          {listing.child ? ' · sold with its container' : ''}
+        </div>
+      </div>
+      <div className="sans" style={{ flex: 'none', textAlign: 'right' }}>
+        <div style={{ color: 'var(--head)', fontSize: '0.92rem' }}>{num(listing.price)}</div>
+        <div className="dim" style={{ fontSize: '0.68rem', letterSpacing: '0.05em' }}>gold</div>
+      </div>
+    </div>
+  )
+}
+
+export default function Market() {
+  const [input, setInput] = useState('')
+  const [q, setQ] = useState('')
+  const [map, setMap] = useState('')
+  const [region, setRegion] = useState('')
+  const [sort, setSort] = useState('price_asc')
+  const [minPrice, setMinPrice] = useState('')
+  const [maxPrice, setMaxPrice] = useState('')
+  // Applied prices are separate from the typed ones so the search fires when the
+  // user is done, not on every digit of "250000".
+  const [prices, setPrices] = useState({ min: '', max: '' })
+
+  const [state, setState] = useState({ loading: true, error: null, listings: [], total: 0, staleAt: null })
+  const [more, setMore] = useState(false)
+
+  const meta = useAsync(() => api.shard.marketMeta())
+
+  // Debounced: typing "vanquishing" should be one request, not eleven — and the
+  // endpoint is rate-limited, so an undebounced box would 429 a fast typist.
+  useEffect(() => {
+    const timer = setTimeout(() => setQ(input.trim()), 300)
+    return () => clearTimeout(timer)
+  }, [input])
+
+  useEffect(() => {
+    const timer = setTimeout(() => setPrices({ min: minPrice, max: maxPrice }), 500)
+    return () => clearTimeout(timer)
+  }, [minPrice, maxPrice])
+
+  const load = useCallback(
+    (offset) =>
+      api.shard.market({
+        q,
+        map,
+        region,
+        sort,
+        minPrice: prices.min,
+        maxPrice: prices.max,
+        limit: PAGE,
+        offset,
+      }),
+    [q, map, region, sort, prices],
+  )
+
+  useEffect(() => {
+    let alive = true
+    setState({ loading: true, error: null, listings: [], total: 0, staleAt: null })
+    load(0)
+      .then((page) => {
+        if (!alive) return
+        setState({
+          loading: false,
+          error: null,
+          listings: page.listings || [],
+          total: page.total || 0,
+          staleAt: page.staleAt || null,
+        })
+      })
+      .catch((error) => alive && setState({ loading: false, error, listings: [], total: 0, staleAt: null }))
+    return () => {
+      alive = false
+    }
+  }, [load])
+
+  const loadMore = async () => {
+    setMore(true)
+    try {
+      const page = await load(state.listings.length)
+      setState((s) => ({
+        ...s,
+        listings: [...s.listings, ...(page.listings || [])],
+        total: page.total ?? s.total,
+        staleAt: page.staleAt ?? s.staleAt,
+      }))
+    } catch {
+      // A failed "load more" leaves what is on screen alone; the button stays
+      // available to retry.
+    } finally {
+      setMore(false)
+    }
+  }
+
+  const maps = meta.data?.maps || []
+  const regions = meta.data?.regions || []
+  const age = staleness(state.staleAt)
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <PageHeader
+          eyebrow="Marketplace"
+          title="Player vendors"
+          lead="Every shop on the shard, searchable from here — the same index the in-game vendor search reads, and it honours the same per-vendor opt-out."
+        />
+
+        {/* Not decoration. The sweep is round-robin, so the index is inherently
+            up to one full cycle old and the page has to say so. */}
+        {age && (
+          <p className="sans dim" style={{ fontSize: '0.76rem', margin: '-12px 0 18px' }}>
+            Prices last refreshed {age}
+            {meta.data?.vendors ? ` · ${num(meta.data.vendors)} shops` : ''}
+            {meta.data?.items ? ` · ${num(meta.data.items)} listings` : ''}
+          </p>
+        )}
+
+        <input
+          className="input"
+          type="search"
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Search listings…"
+          style={{ width: '100%', marginBottom: 10 }}
+        />
+
+        <div style={{ display: 'flex', gap: 8, marginBottom: 12, flexWrap: 'wrap' }}>
+          <input
+            className="input"
+            type="number"
+            min="0"
+            value={minPrice}
+            onChange={(e) => setMinPrice(e.target.value)}
+            placeholder="Min price"
+            style={{ maxWidth: 140 }}
+          />
+          <input
+            className="input"
+            type="number"
+            min="0"
+            value={maxPrice}
+            onChange={(e) => setMaxPrice(e.target.value)}
+            placeholder="Max price"
+            style={{ maxWidth: 140 }}
+          />
+        </div>
+
+        <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 10 }}>
+          {SORTS.map((s) => (
+            <Chip key={s.key} active={sort === s.key} onClick={() => setSort(s.key)}>
+              {s.label}
+            </Chip>
+          ))}
+        </div>
+
+        {/* Facet and region names come from the shard's own data, never a list in
+            this file — a shard running custom maps gets its own names here with
+            no code change (docs/link/v3.md §6.1 R2). */}
+        {maps.length > 0 && (
+          <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', marginBottom: 10 }}>
+            <Chip active={map === ''} onClick={() => setMap('')}>All facets</Chip>
+            {maps.map((m) => (
+              <Chip key={m} active={map === m} onClick={() => setMap(m)}>{m}</Chip>
+            ))}
+          </div>
+        )}
+
+        {regions.length > 0 && (
+          <select
+            className="input"
+            value={region}
+            onChange={(e) => setRegion(e.target.value)}
+            style={{ width: '100%', marginBottom: 18 }}
+          >
+            <option value="">Anywhere</option>
+            {regions.map((r) => (
+              <option key={r} value={r}>{r}</option>
+            ))}
+          </select>
+        )}
+
+        {state.loading && <Loading />}
+        {state.error && <ErrorState message="Could not load the marketplace right now." />}
+
+        {!state.loading && !state.error && state.listings.length === 0 && (
+          <EmptyState>
+            {meta.data?.vendors
+              ? 'Nothing on the shard matches that.'
+              : 'No player vendors have been indexed yet.'}
+          </EmptyState>
+        )}
+
+        {!state.loading && !state.error && state.listings.length > 0 && (
+          <>
+            <p className="sans dim" style={{ fontSize: '0.78rem', margin: '0 0 12px' }}>
+              Showing {num(state.listings.length)} of {num(state.total)}
+            </p>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+              {state.listings.map((l) => (
+                <ListingRow key={`${l.vendor?.serial}:${l.serial}`} listing={l} />
+              ))}
+            </div>
+            {state.listings.length < state.total && (
+              <div style={{ textAlign: 'center', marginTop: 16 }}>
+                <button type="button" className="btn" onClick={loadMore} disabled={more}>
+                  {more ? 'Loading…' : 'Load more'}
+                </button>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/MarketVendor.jsx

@@ -0,0 +1,102 @@
+import { Link, useParams } from 'react-router-dom'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState, EmptyState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { api } from '../../api/client.js'
+
+// One player vendor: where to find it and everything it is selling.
+//
+// The page a search result points at. Two states it has to render honestly and
+// which the search list cannot (docs/link/v3.md §8):
+//
+//   • `truncated` — the shop holds more than the shard publishes per frame. A
+//     commodity reseller with thousands of stacks is a real thing, and showing
+//     250 of 3,104 as if it were the whole shop would be a lie about the shard.
+//   • a gated `location` — an admin may put vendor whereabouts behind a rung, in
+//     which case there is nothing to render and the page says so rather than
+//     showing an empty coordinate.
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v).toLocaleString() : '—')
+
+const itemLabel = (i) => i.displayName || i.name || `id ${i.itemId}`
+
+export default function MarketVendor() {
+  const { serial } = useParams()
+  const { loading, error, data } = useAsync(() => api.shard.marketVendor(serial), [serial])
+
+  if (loading) {
+    return (
+      <PublicLayout section="website">
+        <div className="shell-narrow page-body"><Loading /></div>
+      </PublicLayout>
+    )
+  }
+
+  if (error || !data) {
+    return (
+      <PublicLayout section="website">
+        <div className="shell-narrow page-body">
+          <ErrorState message="That shop is not in the index — it may have been dismissed or hidden." />
+          <p style={{ marginTop: 16 }}>
+            <Link to="/site/market" className="sans">← Back to the marketplace</Link>
+          </p>
+        </div>
+      </PublicLayout>
+    )
+  }
+
+  const loc = data.location || null
+  const items = data.items || []
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <PageHeader
+          eyebrow={data.ownerName ? `Run by ${data.ownerName}` : 'Player vendor'}
+          title={data.shopName || 'An unnamed shop'}
+          lead={
+            loc
+              ? [loc.house, loc.region, loc.map].filter(Boolean).join(' · ') +
+                (Number.isFinite(loc.x) ? ` — ${loc.x}, ${loc.y}` : '')
+              : 'This shard does not publish vendor locations.'
+          }
+        />
+
+        <p className="sans dim" style={{ fontSize: '0.78rem', margin: '-12px 0 18px' }}>
+          {data.truncated
+            ? `Showing ${num(data.count)} of ${num(data.total)} listings — this shop holds more than the shard publishes.`
+            : `${num(data.total)} listing${data.total === 1 ? '' : 's'}`}
+          {data.updatedAt ? ` · last seen ${new Date(data.updatedAt).toLocaleString()}` : ''}
+        </p>
+
+        {items.length === 0 ? (
+          <EmptyState>This shop has nothing priced for sale.</EmptyState>
+        ) : (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+            {items.map((i) => (
+              <div
+                key={i.serial}
+                className="panel"
+                style={{ padding: '10px 14px', display: 'flex', gap: 12, alignItems: 'baseline' }}
+              >
+                <span className="sans" style={{ flex: 1, minWidth: 0, color: 'var(--head)', fontSize: '0.88rem' }}>
+                  {i.amount > 1 ? `${num(i.amount)} × ` : ''}
+                  {itemLabel(i)}
+                  {i.child ? <span className="dim"> · sold with its container</span> : null}
+                </span>
+                <span className="sans" style={{ flex: 'none', color: 'var(--head)', fontSize: '0.88rem' }}>
+                  {num(i.price)}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+
+        <p style={{ marginTop: 20 }}>
+          <Link to="/site/market" className="sans">← Back to the marketplace</Link>
+        </p>
+      </div>
+    </PublicLayout>
+  )
+}

client/src/routes/public/Rules.jsx

@@ -0,0 +1,341 @@
+import { useMemo } from 'react'
+import PublicLayout from '../../components/PublicLayout.jsx'
+import PageHeader from '../../components/PageHeader.jsx'
+import { Loading, ErrorState } from '../../components/PageState.jsx'
+import { useAsync } from '../../lib/useAsync.js'
+import { useShardFeed } from '../../lib/useShardFeed.js'
+import { api } from '../../api/client.js'
+
+// The shard ruleset. Loaded from /public/shard/ruleset, replaced wholesale by any
+// world.ruleset frame on the live feed (the shard re-emits the entire ruleset, so
+// there is nothing to merge — latest wins).
+//
+// Everything on this page is published BY THE SHARD from its own Config/*.cfg, so
+// it cannot drift the way a hand-written rules page does. That is the whole point
+// of the feature, and the page says so.
+const RULESET_KINDS = new Set(['world.ruleset'])
+
+// Skill and stat caps arrive in tenths, the way ServUO stores them: 1000 is 100.0
+// skill. Showing the raw number would be actively misleading.
+const tenths = (v) => (Number.isFinite(v) ? (v / 10).toFixed(1) : null)
+
+const num = (v) => (Number.isFinite(v) ? v.toLocaleString() : null)
+
+const pct = (v) => (Number.isFinite(v) ? `${v}%` : null)
+
+// The systems block is a flat bag of booleans; these are their display names, and
+// the order here is the order they render. A key the shard sends that we don't
+// know about still renders, humanised, rather than being silently dropped — a new
+// plugin must not go invisible against an older client.
+const SYSTEM_LABELS = {
+  cityLoyalty: 'City Loyalty (governors)',
+  vvv: 'Vice vs Virtue',
+  factions: 'Factions',
+  siege: 'Siege ruleset',
+  chat: 'In-game chat',
+  store: 'Ultima Store',
+  dailyRares: 'Daily rares',
+  honesty: 'Honesty virtue',
+  shadowguard: 'Shadowguard',
+  treasureMaps: 'Treasure maps',
+  vetRewards: 'Veteran rewards',
+  testCenter: 'Test Center',
+}
+
+const humanise = (key) =>
+  key.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase())
+
+function Panel({ title, children }) {
+  return (
+    <section className="panel" style={{ padding: 18 }}>
+      <h2
+        className="display"
+        style={{ margin: '0 0 12px', fontSize: '1.02rem', color: 'var(--head)' }}
+      >
+        {title}
+      </h2>
+      {children}
+    </section>
+  )
+}
+
+// A label/value row. Rows whose value is null are dropped by the caller, so a
+// block never renders a dangling label for something the shard didn't publish.
+function Row({ label, value }) {
+  return (
+    <div
+      className="sans"
+      style={{
+        display: 'flex',
+        alignItems: 'baseline',
+        justifyContent: 'space-between',
+        gap: 12,
+        padding: '5px 0',
+        borderBottom: '1px solid var(--line)',
+        fontSize: '0.86rem',
+      }}
+    >
+      <span className="dim" style={{ minWidth: 0 }}>{label}</span>
+      <strong style={{ flex: 'none', color: 'var(--head)' }}>{value}</strong>
+    </div>
+  )
+}
+
+function Rows({ items }) {
+  const rows = items.filter(([, value]) => value !== null && value !== undefined)
+  if (rows.length === 0) return null
+  return (
+    <div>
+      {rows.map(([label, value]) => (
+        <Row key={label} label={label} value={value} />
+      ))}
+    </div>
+  )
+}
+
+function SystemPill({ label, on }) {
+  const color = on ? '#8fdcae' : 'var(--muted)'
+  return (
+    <span
+      className="sans"
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 7,
+        fontSize: '0.8rem',
+        padding: '5px 11px',
+        borderRadius: 999,
+        color,
+        background: on ? 'rgba(95,185,138,0.12)' : 'rgba(140,150,165,0.1)',
+        border: `1px solid ${on ? 'rgba(95,185,138,0.4)' : 'var(--line)'}`,
+      }}
+    >
+      <span
+        aria-hidden="true"
+        style={{ width: 7, height: 7, borderRadius: '50%', background: color, flex: 'none' }}
+      />
+      {label}
+    </span>
+  )
+}
+
+function Systems({ systems }) {
+  // Known keys first in their declared order, then anything the shard added that
+  // this build doesn't know about.
+  const known = Object.keys(SYSTEM_LABELS).filter((k) => k in systems)
+  const extra = Object.keys(systems).filter((k) => !(k in SYSTEM_LABELS))
+  const keys = [...known, ...extra]
+  if (keys.length === 0) return null
+  return (
+    <Panel title="Systems">
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+        {keys.map((k) => (
+          <SystemPill key={k} label={SYSTEM_LABELS[k] || humanise(k)} on={!!systems[k]} />
+        ))}
+      </div>
+    </Panel>
+  )
+}
+
+function Caps({ caps }) {
+  return (
+    <Panel title="Skill & stat caps">
+      <Rows
+        items={[
+          ['Individual skill cap', tenths(caps.skill)],
+          ['Total skill cap', tenths(caps.totalSkill)],
+          ['Total stat cap', num(caps.stat)],
+          ['Strength cap', num(caps.str)],
+          ['Dexterity cap', num(caps.dex)],
+          ['Intelligence cap', num(caps.int)],
+          ['Strength max', num(caps.strMax)],
+          ['Dexterity max', num(caps.dexMax)],
+          ['Intelligence max', num(caps.intMax)],
+        ]}
+      />
+    </Panel>
+  )
+}
+
+function AccountsAndHousing({ accounts, housing, vetRewards }) {
+  const items = []
+  if (accounts) {
+    items.push(['Accounts per IP', num(accounts.perIp)])
+    items.push(['Character slots', num(accounts.charSlots)])
+    items.push([
+      'In-game account creation',
+      accounts.autoCreate === undefined ? null : accounts.autoCreate ? 'Enabled' : 'Website only',
+    ])
+  }
+  if (housing) items.push(['Houses per account', num(housing.accountHouseLimit)])
+  if (vetRewards?.enabled) {
+    items.push(['Veteran reward interval', vetRewards.rewardIntervalDays
+      ? `${vetRewards.rewardIntervalDays} days`
+      : null])
+  }
+  if (items.length === 0) return null
+  return (
+    <Panel title="Accounts & housing">
+      <Rows items={items} />
+    </Panel>
+  )
+}
+
+function Champions({ champions }) {
+  const t = champions.rankThresholds
+  return (
+    <Panel title="Champion spawns">
+      <Rows
+        items={[
+          ['Power scrolls per spawn', num(champions.powerScrolls)],
+          ['Stat scrolls per spawn', num(champions.statScrolls)],
+          ['Scroll drop chance', pct(champions.scrollChance)],
+          ['Transcendence chance', pct(champions.transcendenceChance)],
+          [
+            'Red skulls per rank',
+            Array.isArray(t) && t.length > 0 ? t.join(' · ') : null,
+          ],
+        ]}
+      />
+    </Panel>
+  )
+}
+
+function Felucca({ loot }) {
+  return (
+    <Panel title="Felucca bonuses">
+      <Rows
+        items={[
+          ['Luck bonus', num(loot.feluccaLuckBonus)],
+          ['Loot budget bonus', num(loot.feluccaBudgetBonus)],
+          ['Max item properties', num(loot.feluccaMaxProps)],
+        ]}
+      />
+    </Panel>
+  )
+}
+
+function Vendors({ vendors }) {
+  return (
+    <Panel title="Vendors">
+      <Rows
+        items={[
+          ['Restock delay', vendors.restockDelayMinutes
+            ? `${vendors.restockDelayMinutes} min`
+            : null],
+          ['Max items sold at once', num(vendors.maxSell)],
+          ['Economy stock amount', num(vendors.economyStockAmount)],
+        ]}
+      />
+    </Panel>
+  )
+}
+
+function Pvp({ vvv }) {
+  return (
+    <Panel title="Vice vs Virtue">
+      <Rows
+        items={[
+          ['Starting silver', num(vvv.startSilver)],
+          ['Enhanced rules', vvv.enhancedRules === undefined
+            ? null
+            : vvv.enhancedRules ? 'On' : 'Off'],
+        ]}
+      />
+    </Panel>
+  )
+}
+
+function Schedule({ schedule }) {
+  const items = []
+  if (schedule.autoSaveEnabled && schedule.autoSaveFrequencyMinutes) {
+    items.push(['World save', `every ${schedule.autoSaveFrequencyMinutes} min`])
+  } else if (schedule.autoSaveEnabled === false) {
+    items.push(['World save', 'Disabled'])
+  }
+  if (schedule.autoRestartEnabled) {
+    const h = String(schedule.autoRestartHour ?? 0).padStart(2, '0')
+    const m = String(schedule.autoRestartMinute ?? 0).padStart(2, '0')
+    items.push(['Automatic restart', `${h}:${m} server time`])
+    if (schedule.autoRestartFrequencyHours) {
+      items.push(['Restart interval', `every ${schedule.autoRestartFrequencyHours}h`])
+    }
+  }
+  if (items.length === 0) return null
+  return (
+    <Panel title="Save & restart schedule">
+      <Rows items={items} />
+    </Panel>
+  )
+}
+
+export default function Rules() {
+  const { loading, error, data } = useAsync(() => api.shard.ruleset())
+  const { events, connected } = useShardFeed({ filter: RULESET_KINDS, max: 4 })
+
+  // The newest world.ruleset on the feed wins outright over the fetched copy —
+  // the frame is a complete ruleset, not a delta.
+  const ruleset = useMemo(() => events[0] || data || null, [data, events])
+
+  return (
+    <PublicLayout section="website">
+      <div className="shell-narrow page-body">
+        <div style={{ display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 16 }}>
+          <PageHeader
+            eyebrow="Live"
+            title="Shard ruleset"
+            lead="Published by the server itself, straight from its configuration — so it cannot drift from how the shard actually plays."
+          />
+          <span
+            className="sans"
+            style={{
+              display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: '0.74rem',
+              color: connected ? '#7fd0a4' : 'var(--muted)', flex: 'none', marginTop: 6,
+            }}
+          >
+            <span style={{ width: 8, height: 8, borderRadius: '50%', background: connected ? '#7fd0a4' : 'var(--dim)' }} />
+            {connected ? 'Live' : 'Offline'}
+          </span>
+        </div>
+
+        {loading && <Loading />}
+        {error && <ErrorState message="Could not load the shard ruleset right now." />}
+
+        {!loading && !error && !ruleset && (
+          <section className="panel" style={{ padding: 24, textAlign: 'center' }}>
+            <p className="sans dim" style={{ margin: 0 }}>
+              The shard has not published its ruleset yet.
+            </p>
+          </section>
+        )}
+
+        {!loading && !error && ruleset && (
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+            <Panel title="Shard">
+              <Rows
+                items={[
+                  ['Name', ruleset.shard || null],
+                  ['Expansion', ruleset.expansion || null],
+                  ['Connect', ruleset.connect || null],
+                ]}
+              />
+            </Panel>
+
+            {ruleset.systems && <Systems systems={ruleset.systems} />}
+            {ruleset.caps && <Caps caps={ruleset.caps} />}
+            <AccountsAndHousing
+              accounts={ruleset.accounts}
+              housing={ruleset.housing}
+              vetRewards={ruleset.vetRewards}
+            />
+            {ruleset.champions && <Champions champions={ruleset.champions} />}
+            {ruleset.loot && <Felucca loot={ruleset.loot} />}
+            {ruleset.vendors && <Vendors vendors={ruleset.vendors} />}
+            {ruleset.vvv?.enabled && <Pvp vvv={ruleset.vvv} />}
+            {ruleset.schedule && <Schedule schedule={ruleset.schedule} />}
+          </div>
+        )}
+      </div>
+    </PublicLayout>
+  )
+}

client/test/apiClient.test.js

@@ -140,3 +140,44 @@ test('DELETE self-service session revoke encodes the id and uses the DELETE meth
   assert.equal(calls[0].opts.method, 'DELETE')
   assert.match(calls[0].url, /\/auth\/me\/sessions\/a%20b%2Fc$/)
 })
+
+// ── spawn atlas (Protocol 3.0 Part C) ───────────────────────────────────
+// The atlas lives at /public/atlas, NOT under /public/shard: it is static shard
+// content parsed from the shard's own files, so it must not look sidecar-backed.
+// Asserted here because the split is a design decision, not an accident of
+// spelling.
+test('atlas reads hit /public/atlas, not /public/shard', async () => {
+  willReply({ body: { creatures: [] } })
+  await api.atlas.creatures()
+  assert.equal(calls[0].url, '/api/v1/public/atlas/creatures')
+})
+
+test('atlas.creatures() sends only the filters that are set', async () => {
+  willReply({ body: { creatures: [] } })
+  await api.atlas.creatures({ q: 'lizard man', facet: 'Ter Mur', limit: 25 })
+  const url = new URL(calls[0].url, 'http://x')
+  assert.equal(url.pathname, '/api/v1/public/atlas/creatures')
+  assert.equal(url.searchParams.get('q'), 'lizard man')
+  assert.equal(url.searchParams.get('facet'), 'Ter Mur')
+  assert.equal(url.searchParams.get('limit'), '25')
+  assert.equal(url.searchParams.get('offset'), null) // 0 is not sent
+})
+
+test('atlas.creature() encodes the slug and carries the facet filter through', async () => {
+  willReply({ body: {} })
+  await api.atlas.creature('lizardman/rare', { facet: 'Felucca' })
+  assert.match(calls[0].url, /\/public\/atlas\/creatures\/lizardman%2Frare\?facet=Felucca$/)
+})
+
+test('admin atlas actions use the right methods and bodies', async () => {
+  willReply({ body: {} })
+  await api.admin.atlas.import(true)
+  assert.equal(calls[0].url, '/api/v1/admin/shard/atlas/import')
+  assert.equal(calls[0].opts.method, 'POST')
+  assert.equal(calls[0].opts.body, JSON.stringify({ force: true }))
+
+  willReply({ body: {} })
+  await api.admin.atlas.setPath('/srv/servuo')
+  assert.equal(calls[1].opts.method, 'PUT')
+  assert.equal(calls[1].opts.body, JSON.stringify({ path: '/srv/servuo' }))
+})

server/db/data/spawnAtlas.art.example.json

@@ -0,0 +1,24 @@
+{
+  "_comment": [
+    "OPTIONAL operator-supplied creature art for the spawn atlas. Copy this file to",
+    "spawnAtlas.art.json (same directory) and edit it, then restart the server or run",
+    "`npm run atlas:import` — the art map is read on every atlas refresh.",
+    "",
+    "This project ships NO creature artwork and never will. UO sprites live in your",
+    "own client's .mul/.uop files and are yours to extract, not ours to redistribute.",
+    "If you want art on the atlas pages, export it yourself (UOFiddler, ClassicUO's",
+    "tooling, or any art extractor), drop the images under server/uploads/atlas/, and",
+    "map each creature slug to its file name here.",
+    "",
+    "Both spawnAtlas.art.json and server/uploads/ are gitignored, so neither the map",
+    "nor the images can be committed by accident.",
+    "",
+    "Keys are creature slugs, as reported by the atlas API and derived from the type",
+    "names in your own shard's Spawns/*.xml. Values are file names relative to",
+    "server/uploads/atlas/. Any creature with no entry here simply renders without",
+    "art — that is the default and fully supported state, not a degraded one."
+  ],
+  "lizardman": "lizardman.png",
+  "orc": "orc.png",
+  "dragon": "dragon.png"
+}

server/db/schema.sql

@@ -215,6 +215,9 @@ CREATE TABLE IF NOT EXISTS mobile_auth_sessions (
   state          VARCHAR(255) NOT NULL,               -- app-generated opaque CSRF value, echoed to the app
   status         ENUM('pending','completed','consumed') NOT NULL DEFAULT 'pending',
   user_id        INT          NULL,                   -- set once SSO resolves the account
+  trust_device   TINYINT(1)   NOT NULL DEFAULT 0,     -- user ticked "trust this device" on the Custom Tab TOTP form;
+                                                      -- a BOOLEAN only — the trust token itself is minted at /exchange
+                                                      -- and returned over that app→server call, never stored here
   created_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
   expires_at     DATETIME NOT NULL,                   -- ~10 min (one redirect round-trip incl. TOTP)
   used_at        DATETIME NULL,                       -- stamped at exchange
@@ -356,7 +359,7 @@ CREATE TABLE IF NOT EXISTS uo_link_config (
   base_url          VARCHAR(255) NULL,
   ws_url            VARCHAR(255) NULL,
   auth_token_enc    TEXT         NULL,
-  protocol          INT          NOT NULL DEFAULT 1,
+  protocol          INT          NOT NULL DEFAULT 3,
   enabled           TINYINT(1)   NOT NULL DEFAULT 0,
   status            VARCHAR(20)  NOT NULL DEFAULT 'disconnected',
   status_detail     VARCHAR(500) NULL,
@@ -594,6 +597,142 @@ CREATE TABLE IF NOT EXISTS shard_presence (
   CONSTRAINT chk_shard_presence_singleton CHECK (id = 1)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 
+-- The shard's published ruleset (Protocol 3.0 world.ruleset). Singleton row
+-- (id = 1) holding the latest frame: expansion, which optional systems are on,
+-- skill/stat caps, account and house limits, champion scroll rules, the
+-- save/restart schedule. The shard re-emits it on every sidecar connect, so this
+-- row is simply overwritten; `rev` is the shard's own FNV-1a of the body, which
+-- distinguishes "same ruleset, re-sent on reconnect" from "an operator changed a
+-- .cfg". No row at all means the shard has never published one — served as null,
+-- which the rules page renders differently from a published ruleset.
+CREATE TABLE IF NOT EXISTS shard_ruleset (
+  id          INT PRIMARY KEY DEFAULT 1,
+  rev         VARCHAR(32)  NULL,
+  expansion   VARCHAR(16)  NULL,                     -- hoisted for cheap display
+  payload     JSON         NOT NULL,                 -- the whole world.ruleset frame
+  t           BIGINT       NULL,                     -- frame time, epoch ms
+  updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT chk_shard_ruleset_singleton CHECK (id = 1)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Points/loyalty leaderboards (Protocol 3.0 points.board). One row per point
+-- system, keyed by the shard's own PointsType name. The shard publishes ~25 of
+-- these (Queen's Loyalty, Void Pool, the nine city loyalties, …), each a standing
+-- players accumulate over months.
+--
+-- The top-N list stays inside `payload` rather than being normalized into a
+-- shard_points_entries table. It is a fixed-size list (10 by default) that is only
+-- ever read whole, exactly like shard_governors.candidates — normalizing it would
+-- buy nothing until something needs a per-character reverse lookup, and a
+-- character's own standings already ride inside char.profile instead.
+--
+-- No delete path: the shard's set of systems is fixed at startup, so there is no
+-- points.remove to mirror.
+CREATE TABLE IF NOT EXISTS shard_points_boards (
+  system        VARCHAR(48) PRIMARY KEY,          -- PointsType name, e.g. QueensLoyalty
+  name          VARCHAR(128) NULL,                -- resolved display name, if the shard sent a literal
+  name_cliloc   INT          NULL,                -- cliloc id when the name is a TextDefinition number
+  max_points    BIGINT       NULL,
+  players       INT          NULL,                -- players actually holding points in this system
+  show_on_gump  TINYINT(1)   NOT NULL DEFAULT 1,  -- the shard's own "is this player-facing?" flag
+  payload       JSON         NOT NULL,            -- the whole points.board frame, incl. `top`
+  t             BIGINT       NULL,                -- frame time, epoch ms
+  updated_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Player-vendor market index (Protocol 3.0 vendor.listing). One row per player
+-- vendor and one per priced listing, so the site can offer the search the in-game
+-- Vendor Search gump offers — from outside the game.
+--
+-- The shard sweeps vendors round-robin and emits one AUTHORITATIVE frame per
+-- vendor, so ingest is delete-then-insert of that vendor's items inside one
+-- transaction (see shardMarket.db.js). No foreign key from items to vendors, in
+-- keeping with every other shard_* table: the ingest transaction is what keeps
+-- them consistent, and an FK would turn a malformed frame into a failed write
+-- rather than a dropped row.
+--
+-- Only vendors whose owner left the in-game Vendor Search flag ON are ever sent,
+-- so a player who hid their shop in game is hidden here too — see BridgeMarket.cs.
+CREATE TABLE IF NOT EXISTS shard_vendors (
+  serial       VARCHAR(20)  NOT NULL PRIMARY KEY,   -- "0x40001234"
+  shop_name    VARCHAR(160) NULL,
+  owner_serial VARCHAR(20)  NULL,
+  owner_name   VARCHAR(64)  NULL,
+  map          VARCHAR(40)  NULL,
+  x            INT          NULL,
+  y            INT          NULL,
+  z            INT          NULL,
+  region       VARCHAR(80)  NULL,
+  house        VARCHAR(160) NULL,                   -- the house SIGN's name, not the house type
+  item_count   INT          NOT NULL DEFAULT 0,     -- listings published in the frame
+  item_total   INT          NOT NULL DEFAULT 0,     -- listings the shop actually holds
+  truncated    TINYINT(1)   NOT NULL DEFAULT 0,     -- item_total > item_count
+  t            BIGINT       NULL,                   -- frame time, epoch ms
+  updated_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_shard_vendors_owner (owner_name),
+  INDEX idx_shard_vendors_map (map),
+  INDEX idx_shard_vendors_region (region),
+  -- The market page's staleness banner is MIN(updated_at) over this column: the
+  -- round-robin sweep means the oldest row is how far behind the index can be.
+  INDEX idx_shard_vendors_updated (updated_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- One priced listing. Unlike the points board's top-N — a fixed-size list read
+-- whole — these are the searchable rows the whole feature exists for, so they are
+-- normalized rather than left inside a payload column, and there is no payload
+-- column on shard_vendors at all.
+--
+-- `display_name` is DENORMALIZED at ingest: the shard sends `cliloc` (the item's
+-- LabelNumber) and, rarely, a literal `name`, and resolving 50 clilocs per page
+-- at query time would make the cliloc table a join on the hot path AND make
+-- search-by-name impossible. Resolving once on write buys the index. It is
+-- re-resolved in bulk after a cliloc import, because the diff sweep will not
+-- re-send an unchanged shop just because the site learned what its items are
+-- called.
+CREATE TABLE IF NOT EXISTS shard_vendor_items (
+  id            BIGINT       NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  vendor_serial VARCHAR(20)  NOT NULL,
+  serial        VARCHAR(20)  NOT NULL,
+  item_id       INT          NOT NULL DEFAULT 0,    -- ItemID (the art/graphic id)
+  hue           INT          NOT NULL DEFAULT 0,
+  amount        INT          NOT NULL DEFAULT 1,
+  price         BIGINT       NOT NULL DEFAULT 0,
+  name          VARCHAR(160) NULL,                  -- the item's literal Name, null for most
+  cliloc        INT          NULL,                  -- LabelNumber, resolved against shard_clilocs
+  display_name  VARCHAR(160) NULL,                  -- resolved at ingest; what search matches
+  child         TINYINT(1)   NOT NULL DEFAULT 0,    -- priced by an enclosing container, not itself
+  INDEX idx_shard_vendor_items_vendor (vendor_serial),
+  INDEX idx_shard_vendor_items_price (price),
+  INDEX idx_shard_vendor_items_item (item_id),
+  INDEX idx_shard_vendor_items_name (display_name),
+  -- Search filters on name and sorts on price; the composite covers the common
+  -- "cheapest matching X" without a filesort over the whole table.
+  INDEX idx_shard_vendor_items_name_price (display_name, price)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Per-feature visibility for every shard-derived surface (Protocol 3.0). One row
+-- per feature; an absent row means "use the compiled default", and the compiled
+-- defaults reproduce the behavior that shipped before v3 — so an empty table is
+-- a no-op. See utils/shardVisibility.js for the catalog and the ladder, and
+-- docs/link/v3.md §3 for the contract.
+--
+--   audience     the minimum rung on anonymous < logged_in < player < staff < admin
+--   stream       whether this feature's kinds fan out over SSE at all (the market
+--                index ships with this off: no page needs a live firehose of
+--                whole vendor inventories)
+--   field_rules  {"<field>": "<rung>"} for SENSITIVE fields only. `acct` and
+--                `webId` are admin-only always and are rejected here — they are
+--                not in-game visible and are deliberately not configurable.
+CREATE TABLE IF NOT EXISTS shard_feature_visibility (
+  feature     VARCHAR(48) NOT NULL PRIMARY KEY,
+  enabled     TINYINT(1)  NOT NULL DEFAULT 1,
+  audience    VARCHAR(20) NOT NULL DEFAULT 'anonymous',
+  stream      TINYINT(1)  NOT NULL DEFAULT 1,
+  field_rules JSON        NULL,
+  updated_by  INT         NULL,
+  updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
 -- Admin email invites (Protocol 2.0 provisioning). A staff member invites someone
 -- by email at a pre-chosen access level; the invitee accepts via a tokened link,
 -- which creates their website user at that role (and optionally a linked game
@@ -996,6 +1135,189 @@ CREATE TABLE IF NOT EXISTS announce_jobs (
   INDEX idx_announce_due_discord (discord_status, discord_next_attempt_at)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
 
+-- ── Spawn atlas (Protocol 3.0 Part C) ───────────────────────────────────────
+-- Static shard CONTENT, not live shard state: what spawns where, which regions
+-- and landmarks exist, and which champion altars are configured. Nothing here
+-- comes from the sidecar — it is imported from a committed artifact built off a
+-- ServUO tree by `npm run atlas:build` (see docs/website/SPAWN_ATLAS.md), so
+-- these tables stay populated whether the shard is up or not.
+--
+-- Every table is import-owned: `npm run atlas:import` TRUNCATEs and reloads them
+-- in one transaction. Nothing else may write here, and nothing else may hold a
+-- foreign key to them. No FKs at all, consistent with every other shard_* table.
+
+-- One row per spawnable type, aggregated across the world. `total` is the sum of
+-- each type's own MX across every point that spawns it (how many exist at once);
+-- `facets` is a per-facet point count, so the facet filter and "where does this
+-- live" both answer without touching shard_spawn_points.
+CREATE TABLE IF NOT EXISTS shard_spawn_creatures (
+  slug        VARCHAR(120) NOT NULL PRIMARY KEY,  -- slugified class name; the /atlas/:slug key
+  name        VARCHAR(120) NOT NULL,              -- display spelling chosen by the build
+  total       INT          NOT NULL DEFAULT 0,
+  points      INT          NOT NULL DEFAULT 0,
+  facets      JSON         NULL,                  -- { "Felucca": 171, "Trammel": 160, ... }
+  -- Operator-supplied artwork, always NULL on a fresh import. The repo ships no
+  -- creature art: sprites live in the operator's own client .mul/.uop files and
+  -- are theirs to extract and place under uploads/atlas/. The UI renders without
+  -- art when this is NULL, which is the normal case.
+  art         VARCHAR(255) NULL,
+  -- Plain INDEX, deliberately NOT FULLTEXT: ~800 rows makes a LIKE scan free,
+  -- and FULLTEXT's min-token-length would break searches for names like "orc".
+  INDEX idx_shard_spawn_creatures_name (name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- One row per spawner. `region`/`landmark` are the resolved place name — the
+-- point-in-rect transform that turns "5411,1234" into "Despise" — and `label` is
+-- the resolved display string (region, else landmark, else 'Wilderness').
+CREATE TABLE IF NOT EXISTS shard_spawn_points (
+  id          INT AUTO_INCREMENT PRIMARY KEY,
+  facet       VARCHAR(40)  NOT NULL,
+  name        VARCHAR(120) NULL,                  -- the ServUO spawner's own name
+  x           INT          NOT NULL,
+  y           INT          NOT NULL,
+  width       INT          NOT NULL DEFAULT 0,
+  height      INT          NOT NULL DEFAULT 0,
+  spawn_range INT          NOT NULL DEFAULT 0,    -- `range` is reserved in MariaDB
+  max_count   INT          NOT NULL DEFAULT 0,
+  min_delay   INT          NOT NULL DEFAULT 0,
+  max_delay   INT          NOT NULL DEFAULT 0,
+  tod_start   INT          NOT NULL DEFAULT 0,    -- meaningless unless tod_mode <> 0
+  tod_end     INT          NOT NULL DEFAULT 0,
+  tod_mode    INT          NOT NULL DEFAULT 0,
+  region      VARCHAR(120) NULL,
+  landmark    VARCHAR(120) NULL,
+  label       VARCHAR(120) NOT NULL DEFAULT 'Wilderness',
+  INDEX idx_shard_spawn_points_facet (facet),
+  INDEX idx_shard_spawn_points_label (label)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- The many-to-many between the two above: one spawner commonly carries several
+-- types (a single Trammel point spawns six), each with its own max. This is how
+-- /atlas/creatures/:slug finds the places a creature appears.
+CREATE TABLE IF NOT EXISTS shard_spawn_point_types (
+  point_id    INT          NOT NULL,
+  slug        VARCHAR(120) NOT NULL,              -- → shard_spawn_creatures.slug (no FK)
+  max_count   INT          NOT NULL DEFAULT 1,
+  PRIMARY KEY (point_id, slug),
+  INDEX idx_shard_spawn_point_types_slug (slug)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Named regions from Data/Regions.xml, flattened out of their nesting. `rects`
+-- holds the region's rectangles; `priority` and rect area are what resolved each
+-- spawn point at build time, kept here so the admin drift check can re-derive.
+CREATE TABLE IF NOT EXISTS shard_regions (
+  id          INT AUTO_INCREMENT PRIMARY KEY,
+  facet       VARCHAR(40)  NOT NULL,
+  name        VARCHAR(120) NOT NULL,
+  type        VARCHAR(80)  NULL,                  -- ServUO region class
+  priority    INT          NOT NULL DEFAULT 0,
+  parent      VARCHAR(120) NULL,                  -- enclosing named region, if any
+  rects       JSON         NULL,
+  INDEX idx_shard_regions_facet (facet),
+  INDEX idx_shard_regions_name (name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Points of interest from Data/Locations/*.xml. `grp` is the innermost enclosing
+-- parent ("Covetous"), which is the label worth showing — "Covetous" reads
+-- better than the individual marker "Level 1". (`group` is reserved in SQL.)
+CREATE TABLE IF NOT EXISTS shard_landmarks (
+  id          INT AUTO_INCREMENT PRIMARY KEY,
+  facet       VARCHAR(40)  NOT NULL,
+  name        VARCHAR(120) NOT NULL,
+  grp         VARCHAR(120) NULL,
+  x           INT          NOT NULL,
+  y           INT          NOT NULL,
+  z           INT          NOT NULL DEFAULT 0,
+  INDEX idx_shard_landmarks_facet (facet),
+  INDEX idx_shard_landmarks_name (name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Configured champion altars from Config/ChampionSpawns.xml. This is static
+-- roster data ("there is an Unholy Terror altar in Deceit") and is distinct from
+-- the live champ.update feed in shard_champs ("it is on level 3 right now").
+CREATE TABLE IF NOT EXISTS shard_champion_spawns (
+  slug        VARCHAR(160) NOT NULL PRIMARY KEY,  -- facet-name, e.g. "felucca-deceit"
+  name        VARCHAR(120) NOT NULL,
+  grp         VARCHAR(80)  NULL,                  -- spawn group; one active per group
+  type        VARCHAR(80)  NULL,                  -- '' when randomised per activation
+  random_type TINYINT(1)   NOT NULL DEFAULT 0,
+  facet       VARCHAR(40)  NOT NULL,
+  x           INT          NOT NULL,
+  y           INT          NOT NULL,
+  z           INT          NOT NULL DEFAULT 0,
+  radius      INT          NOT NULL DEFAULT 0,
+  label       VARCHAR(120) NULL,                  -- resolved place name
+  INDEX idx_shard_champion_spawns_facet (facet)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- UO's localization table: cliloc id -> display string. Items carry a
+-- `LabelNumber` rather than a name, so without this the site can only render
+-- `id 1023721` where the game shows "quarter staff". The shard has always sent
+-- the id (char.profile's `cliloc`, and one per marketplace listing) — the number
+-- was never the missing piece, the table was.
+--
+-- Sourced from a file the OPERATOR converts once from their own UO client and
+-- points the site at (docs/website/CLILOCS.md); nothing derived from the client
+-- is committed, the same rule the spawn atlas and the creature art map follow.
+-- A shard with no cliloc file configured simply renders item ids, which is what
+-- it did before this table existed.
+--
+-- `text` is TEXT, not VARCHAR: real tables top out around 12 KB for the long
+-- property descriptions, and truncating them silently would be worse than
+-- storing them. Item NAMES are all short — the index that matters for search is
+-- on the denormalized `shard_vendor_items.display_name`, not here.
+CREATE TABLE IF NOT EXISTS shard_clilocs (
+  number      INT          NOT NULL PRIMARY KEY,
+  flag        SMALLINT     NOT NULL DEFAULT 0,
+  text        TEXT         NOT NULL
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Singleton (id = 1) describing the cliloc table currently loaded: the source
+-- file, its sha256, the entry count and the parser version. The boot path
+-- compares the stored hash against the file on disk and skips the parse when
+-- they match, which is every restart that did not follow a client patch.
+CREATE TABLE IF NOT EXISTS shard_cliloc_meta (
+  id          TINYINT      NOT NULL PRIMARY KEY DEFAULT 1,
+  payload     JSON         NOT NULL,
+  imported_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT chk_shard_cliloc_meta_singleton CHECK (id = 1)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Singleton (id = 1) describing the artifact currently loaded: when it was
+-- built, its counts, and a sha256 per ServUO source file. The admin drift check
+-- compares this against db/data/spawnAtlas.meta.json to report when the database
+-- is behind the committed artifact.
+CREATE TABLE IF NOT EXISTS shard_atlas_meta (
+  id          TINYINT      NOT NULL PRIMARY KEY DEFAULT 1,
+  payload     JSON         NOT NULL,
+  imported_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT chk_shard_atlas_meta_singleton CHECK (id = 1)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Singleton (id = 1) holding an atlas refresh that was parsed but deliberately
+-- NOT applied, because it would remove a facet the site currently serves.
+--
+-- Losing a facet is the signature of a half-copied or mid-update ServUO tree as
+-- much as of a real map change, and boot cannot tell the two apart — so the
+-- refresh is staged here for a human instead of being applied. Startup is never
+-- blocked by it: the site comes up serving the atlas it already had.
+--
+-- Only the DECISION is stored, not the parsed world: `payload` holds the source
+-- hashes and the facet diff (a few KB), and approving re-parses the tree. That
+-- keeps a multi-megabyte blob out of the database and guarantees the applied
+-- atlas matches the tree as it is at approval time, not as it was at boot.
+--
+-- `rejected` is remembered against those exact source hashes so a declined
+-- refresh does not re-prompt on every restart; changing the tree changes the
+-- hashes and asks again.
+CREATE TABLE IF NOT EXISTS shard_atlas_pending (
+  id          TINYINT      NOT NULL PRIMARY KEY DEFAULT 1,
+  status      ENUM('pending','rejected') NOT NULL DEFAULT 'pending',
+  payload     JSON         NOT NULL,               -- source hashes + facet diff
+  detected_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  CONSTRAINT chk_shard_atlas_pending_singleton CHECK (id = 1)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
 -- Migrations for databases created before the wiki upgrade. Each statement uses
 -- IF NOT EXISTS so re-running on every boot is a harmless no-op. New installs get
 -- these columns from the CREATE TABLE above; existing installs get them here.
@@ -1069,3 +1391,25 @@ ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS in_registry TINYINT(1) NOT NUL
 -- self-service list. Both nullable and additive; existing rows get them here.
 ALTER TABLE mobile_refresh_tokens ADD COLUMN IF NOT EXISTS device_name VARCHAR(100) NULL;
 ALTER TABLE mobile_refresh_tokens ADD COLUMN IF NOT EXISTS last_used_at DATETIME NULL;
+
+-- SSO trusted devices: records that the user ticked "trust this device" on the
+-- Custom Tab TOTP form, so /auth/mobile/sso/exchange knows to mint the app's own
+-- trust token. A boolean only — the token is returned over that app→server call
+-- and never persisted here (only its sha256 lands in trusted_devices).
+ALTER TABLE mobile_auth_sessions ADD COLUMN IF NOT EXISTS trust_device TINYINT(1) NOT NULL DEFAULT 0;
+
+-- Protocol 3.0 cutover: this build speaks wire protocol 3 (world.ruleset,
+-- points.board, vendor.listing), so the pinned version an existing install
+-- carries has to move with it — a 2 against a v3 sidecar 409s every REST call
+-- and closes the WS on ws.hello. MODIFY fixes the column default for installs
+-- created before the bump (idempotent, like the other MODIFYs here).
+ALTER TABLE uo_link_config MODIFY COLUMN protocol INT NOT NULL DEFAULT 3;
+-- The row itself is admin-editable, and schema.sql runs on EVERY boot, so this
+-- must be one-shot: an operator who deliberately pins an older sidecar in
+-- Admin → Shard has to stay pinned. The marker row in `settings` is what makes
+-- it fire once — written after the UPDATE, and on a fresh install (no
+-- uo_link_config row yet) it is simply written with nothing to update.
+UPDATE uo_link_config SET protocol = 3
+  WHERE id = 1 AND protocol < 3
+    AND NOT EXISTS (SELECT 1 FROM settings WHERE `key` = 'uo_link_protocol_3_migrated');
+INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_3_migrated', '1');

server/package.json

@@ -9,6 +9,7 @@
     "seed": "node db/seed.js",
     "swagger": "node swagger/swagger.js",
     "routes:manifest": "node scripts/routeManifest.js",
+    "atlas:import": "node scripts/importSpawnAtlas.js",
     "test": "node --test"
   },
   "keywords": [

server/routes.guards.json

@@ -636,6 +636,55 @@
         "requireAuth"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/atlas",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/approve",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/import",
+      "handlers": 4,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/atlas/path",
+      "handlers": 4,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/reject",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/audit",
@@ -678,6 +727,37 @@
         "validate"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/clilocs",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/clilocs/import",
+      "handlers": 5,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/clilocs/path",
+      "handlers": 4,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/houses",
@@ -782,6 +862,26 @@
         "validate"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/visibility",
+      "handlers": 2,
+      "gates": [
+        "noindex",
+        "requireAuth"
+      ]
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/visibility",
+      "handlers": 4,
+      "gates": [
+        "noindex",
+        "requireAuth",
+        "middleware",
+        "validate"
+      ]
+    },
     {
       "method": "PUT",
       "path": "/api/v1/admin/site-mode",
@@ -1550,7 +1650,7 @@
     {
       "method": "POST",
       "path": "/api/v1/auth/sso/totp",
-      "handlers": 6,
+      "handlers": 8,
       "gates": [
         "backoffGuard",
         "middleware",
@@ -1761,6 +1861,64 @@
         "validate"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/champions",
+      "handlers": 5,
+      "gates": [
+        "middleware",
+        "validate",
+        "siteMode"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures",
+      "handlers": 8,
+      "gates": [
+        "middleware",
+        "validate",
+        "siteMode"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures/:slug",
+      "handlers": 7,
+      "gates": [
+        "middleware",
+        "validate",
+        "siteMode"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/landmarks",
+      "handlers": 6,
+      "gates": [
+        "middleware",
+        "validate",
+        "siteMode"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/meta",
+      "handlers": 3,
+      "gates": [
+        "siteMode"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/regions",
+      "handlers": 6,
+      "gates": [
+        "middleware",
+        "validate",
+        "siteMode"
+      ]
+    },
     {
       "method": "POST",
       "path": "/api/v1/public/contact",
@@ -1809,22 +1967,28 @@
     {
       "method": "GET",
       "path": "/api/v1/public/shard/champs",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/economy",
-      "handlers": 3,
+      "handlers": 4,
       "gates": [
         "middleware",
         "validate"
       ]
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/features",
+      "handlers": 1,
+      "gates": []
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/feed",
-      "handlers": 4,
+      "handlers": 5,
       "gates": [
         "middleware",
         "validate"
@@ -1833,13 +1997,13 @@
     {
       "method": "GET",
       "path": "/api/v1/public/shard/governors",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/governors/:city/history",
-      "handlers": 4,
+      "handlers": 5,
       "gates": [
         "middleware",
         "validate"
@@ -1848,37 +2012,79 @@
     {
       "method": "GET",
       "path": "/api/v1/public/shard/guilds",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/houses",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/idoc",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market",
+      "handlers": 13,
+      "gates": [
+        "middleware",
+        "validate"
+      ]
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/meta",
+      "handlers": 2,
+      "gates": []
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/vendors/:serial",
+      "handlers": 7,
+      "gates": [
+        "middleware",
+        "validate"
+      ]
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/online",
-      "handlers": 1,
+      "handlers": 2,
+      "gates": []
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/points",
+      "handlers": 2,
+      "gates": []
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/points/:system",
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/presence",
-      "handlers": 1,
+      "handlers": 2,
+      "gates": []
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/ruleset",
+      "handlers": 2,
       "gates": []
     },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/status",
-      "handlers": 1,
+      "handlers": 2,
       "gates": []
     },
     {

server/routes.manifest.json

@@ -257,6 +257,26 @@
       "method": "GET",
       "path": "/api/v1/admin/shard/accounts"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/atlas"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/approve"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/import"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/atlas/path"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/atlas/reject"
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/audit"
@@ -273,6 +293,18 @@
       "method": "GET",
       "path": "/api/v1/admin/shard/char/:serial"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/clilocs"
+    },
+    {
+      "method": "POST",
+      "path": "/api/v1/admin/shard/clilocs/import"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/clilocs/path"
+    },
     {
       "method": "GET",
       "path": "/api/v1/admin/shard/houses"
@@ -313,6 +345,14 @@
       "method": "GET",
       "path": "/api/v1/admin/shard/vendors/:account"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/admin/shard/visibility"
+    },
+    {
+      "method": "PUT",
+      "path": "/api/v1/admin/shard/visibility"
+    },
     {
       "method": "PUT",
       "path": "/api/v1/admin/site-mode"
@@ -705,6 +745,30 @@
       "method": "GET",
       "path": "/api/v1/player/shard/vendors/:account"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/champions"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/creatures/:slug"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/landmarks"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/meta"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/atlas/regions"
+    },
     {
       "method": "POST",
       "path": "/api/v1/public/contact"
@@ -737,6 +801,10 @@
       "method": "GET",
       "path": "/api/v1/public/shard/economy"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/features"
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/feed"
@@ -761,14 +829,38 @@
       "method": "GET",
       "path": "/api/v1/public/shard/idoc"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/meta"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/market/vendors/:serial"
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/online"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/points"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/points/:system"
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/presence"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/shard/ruleset"
+    },
     {
       "method": "GET",
       "path": "/api/v1/public/shard/status"

server/scripts/importSpawnAtlas.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+//
+// Refresh the spawn atlas from a ServUO tree, from the command line.
+//
+//   npm run atlas:import                       # use the configured path
+//   npm run atlas:import -- --servuo <path>    # override it for this run
+//   npm run atlas:import -- --force            # reimport even if unchanged
+//   npm run atlas:import -- --approve          # apply a staged refresh
+//   npm run atlas:import -- --status           # report without changing anything
+//
+// The server does this itself on every boot (see `shardAtlas.refreshOnBoot`), so
+// this is for operators who want to apply a map change without a restart, and
+// for approving a refresh that was staged because it would remove a facet.
+//
+// All the logic lives in `src/model/shardAtlas/shardAtlas.model.js`; this file
+// is argument parsing and output formatting.
+
+const db = () => require('../src/utils/db')
+
+function parseArgs(argv) {
+  const args = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i]
+    if (flag === '--servuo') args.servuo = argv[++i]
+    else if (flag === '--force') args.force = true
+    else if (flag === '--approve') args.approve = true
+    else if (flag === '--reject') args.reject = true
+    else if (flag === '--status') args.status = true
+    else if (flag === '--help' || flag === '-h') args.help = true
+  }
+  return args
+}
+
+const USAGE = `
+Refresh the spawn atlas from a ServUO tree.
+
+  node scripts/importSpawnAtlas.js [options]
+
+  --servuo <path>  Use this tree for this run instead of the configured path.
+  --force          Reimport even when the source files are unchanged.
+  --approve        Apply a refresh that was staged for removing a facet.
+  --reject         Keep the current atlas and dismiss the staged refresh.
+  --status         Report atlas and source state; change nothing.
+
+With no options this imports only if the tree differs from what is loaded.
+`
+
+function describe(result) {
+  switch (result.status) {
+    case 'skipped':
+      return (
+        'No ServUO path configured — nothing to import.\n' +
+        'Set one with SERVUO_PATH, the admin panel, or --servuo <path>.\n'
+      )
+    case 'unavailable':
+      return `ServUO tree unavailable: ${result.reason}\n`
+    case 'unchanged':
+      return `Atlas is already up to date${result.reason ? ` (${result.reason})` : ''}.\n`
+    case 'needsReview': {
+      return (
+        'Refresh NOT applied — it would remove ' +
+        `${result.removedFacets.length} facet(s): ${result.removedFacets.join(', ')}.\n` +
+        'This is what a half-copied or mid-update tree looks like, so it has been\n' +
+        'staged for review. The current atlas is unchanged.\n' +
+        'Apply it with --approve, or dismiss it with --reject.\n'
+      )
+    }
+    case 'imported': {
+      const c = result.counts
+      const added = result.addedFacets?.length ? ` Added facets: ${result.addedFacets.join(', ')}.` : ''
+      const removed = result.removedFacets?.length
+        ? ` Removed facets: ${result.removedFacets.join(', ')}.`
+        : ''
+      return (
+        `Atlas imported: ${c.points} points, ${c.creatures} creatures, ` +
+        `${c.pointTypes} point/type rows, ${c.regions} regions, ` +
+        `${c.landmarks} landmarks, ${c.champions} champion altars.${added}${removed}\n`
+      )
+    }
+    case 'failed':
+      return `Atlas refresh failed: ${result.reason}\n`
+    default:
+      return `${JSON.stringify(result, null, 2)}\n`
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    process.stdout.write(USAGE)
+    return
+  }
+
+  const shardAtlas = require('../src/model/shardAtlas/shardAtlas.model')
+
+  // `--servuo` is a per-run override and deliberately does NOT persist to the
+  // configured path; changing where the atlas permanently reads from is an
+  // admin action, not a side effect of a one-off import.
+  const override = { path: args.servuo ?? '' }
+
+  if (args.status) {
+    process.stdout.write(`${JSON.stringify(await shardAtlas.status(override), null, 2)}\n`)
+    return
+  }
+  if (args.reject) {
+    process.stdout.write(`${JSON.stringify(await shardAtlas.rejectPending(), null, 2)}\n`)
+    return
+  }
+
+  const result = args.approve
+    ? await shardAtlas.approvePending(override)
+    : await shardAtlas.refresh({ ...override, force: Boolean(args.force) })
+
+  process.stdout.write(describe(result))
+  if (result.status === 'failed') process.exitCode = 1
+}
+
+if (require.main === module) {
+  main()
+    .catch((err) => {
+      process.stderr.write(`atlas:import failed: ${err.message}\n`)
+      process.exitCode = 1
+    })
+    .finally(() => db().close())
+}
+
+module.exports = { describe, parseArgs }

server/scripts/routeManifest.js

@@ -11,8 +11,8 @@
  * in front of a reviewer instead of letting it slip through a "mechanical" PR.
  *
  * Runtime introspection, not source parsing: it is authoritative about mounts, and
- * the route paths in admin.routes.js sit on the line *after* `adminRouter.get(`,
- * which defeats naive greps. Not swagger-output.json either — that is annotation-
+ * a route's path sits on the line *after* `router.get(`, which defeats naive
+ * greps. Not swagger-output.json either — that is annotation-
  * derived (only annotated routes appear) and documents intent; this records reality.
  *
  * Scope: only `/api/**` and `/.well-known/**` from the public app, plus everything

server/src/middleware/rateLimit.js

@@ -118,6 +118,19 @@ const passwordResetConfirmLimiter = makeLimiter({
   message: 'Too many attempts. Please try again later.',
 })
 
+// The player-vendor market search. The first genuinely expensive PUBLIC endpoint
+// on the site: every call is a LIKE scan plus a COUNT over the listings table,
+// which on a large shard is the biggest table there is, and it is anonymous by
+// default. Generous for a human browsing shops (a typed search is debounced to
+// one request, and paging is a click), tight enough that it cannot be used as a
+// cheap way to load the database.
+const marketLimiter = makeLimiter({
+  windowMs: 60 * 1000,
+  max: 60,
+  label: 'market',
+  message: 'Too many searches. Please slow down.',
+})
+
 // CSP violation reports. Unauthenticated by necessity (browsers send them with no
 // session), and every accepted report writes a log line — so an attacker who can get
 // a victim to load a page could otherwise use it as a log-flood amplifier. Generous
@@ -141,5 +154,6 @@ module.exports = {
   mobileSsoExchangeLimiter,
   passwordResetRequestLimiter,
   passwordResetConfirmLimiter,
+  marketLimiter,
   cspReportLimiter,
 }

server/src/model/announceJobs/announceJobs.logic.js

@@ -11,7 +11,7 @@
 const { deriveExcerpt } = require('../../utils/sanitizeHtml')
 
 // Sidecar town-crier caps, mirrored from the admin route validation
-// (admin.routes.js: lines isArray({ max: 8 }), lines.* isLength({ max: 200 })).
+// (admin/uoLink.router.js: lines isArray({ max: 8 }), lines.* isLength({ max: 200 })).
 // We pre-truncate to these so a published post never bounces with towncrier.error.
 const MAX_LINES = 8
 const MAX_LINE_LEN = 200

server/src/model/mobileAuthBridge/mobileAuthBridge.db.js

@@ -37,6 +37,20 @@ async function completeSession(sessionId, userId) {
   return Number(res.affectedRows || 0)
 }
 
+// Record that the user asked to trust this device on the Custom Tab TOTP form.
+// Guarded on status + expiry for the same reason completeSession is: a replayed
+// TOTP post must not re-arm a session that has already been consumed. Stores a
+// boolean only — the trust token is minted at /exchange and never lands here.
+async function setTrustDevice(sessionId) {
+  const res = await query(
+    `UPDATE mobile_auth_sessions
+        SET trust_device = 1
+      WHERE session_id = ? AND status = 'pending' AND expires_at > NOW()`,
+    [sessionId],
+  )
+  return Number(res.affectedRows || 0)
+}
+
 // Mark a session `consumed` after a successful token exchange (stamps used_at).
 async function consumeSession(sessionId) {
   const res = await query(
@@ -93,6 +107,7 @@ module.exports = {
   insertSession,
   getSession,
   completeSession,
+  setTrustDevice,
   consumeSession,
   insertCode,
   findValidCode,

server/src/model/mobileAuthBridge/mobileAuthBridge.model.js

@@ -79,6 +79,14 @@ async function consumeCode(rawCode) {
   return changed > 0
 }
 
+// Flag that the user ticked "trust this device" on the Custom Tab TOTP form. The
+// exchange step reads this to decide whether to mint the app's own trust token.
+// Returns true iff the session was still eligible to be flagged.
+async function markTrustRequested(sessionId) {
+  if (!sessionId) return false
+  return (await db.setTrustDevice(sessionId)) > 0
+}
+
 // Mark a session fully consumed after a successful exchange.
 async function finishSession(sessionId) {
   return db.consumeSession(sessionId)
@@ -97,6 +105,7 @@ module.exports = {
   issueAuthCode,
   findRedeemableCode,
   consumeCode,
+  markTrustRequested,
   finishSession,
   pruneExpired,
 }

server/src/model/settings/settings.model.js

@@ -70,6 +70,24 @@ async function isMobileAppLinksEnabled() {
   }
 }
 
+/**
+ * This instance's name, resolved exactly as `getPublic().brand.name` resolves it —
+ * the admin-editable site title wins over BRAND_NAME. Anything that has to *speak*
+ * the instance's name outside the settings payload must use this rather than
+ * `brand.name`, or an install that set only the site title gets two different names
+ * on two different pages.
+ *
+ * Never throws: a name is always better than an error, so a DB fault falls back to
+ * the env value.
+ */
+async function getInstanceName() {
+  try {
+    return (await settingsDb.get('site_title')) || brand.name
+  } catch {
+    return brand.name
+  }
+}
+
 async function get(key) {
   return settingsDb.get(key)
 }
@@ -154,6 +172,7 @@ module.exports = {
   setMany,
   getAll,
   getPublic,
+  getInstanceName,
   PUBLIC_KEYS,
   REGISTRATION_KEY,
   REGISTRATION_MODES,

server/src/model/shardAtlas/shardAtlas.db.js

@@ -0,0 +1,390 @@
+const { pool, query } = require('../../utils/db')
+
+// Raw SQL for the spawn atlas. Every table here is IMPORT-OWNED: `replaceAtlas`
+// empties and refills all six inside one transaction, and nothing else in the
+// codebase writes to them. There are no foreign keys, consistent with every
+// other shard_* table.
+
+const BATCH = 500
+
+const ATLAS_TABLES = [
+  'shard_spawn_point_types',
+  'shard_spawn_points',
+  'shard_spawn_creatures',
+  'shard_regions',
+  'shard_landmarks',
+  'shard_champion_spawns',
+]
+
+async function insertBatched(conn, sql, rows) {
+  for (let i = 0; i < rows.length; i += BATCH) {
+    await conn.batch(sql, rows.slice(i, i + BATCH))
+  }
+  return rows.length
+}
+
+/**
+ * Replace the entire atlas in one transaction.
+ *
+ * All-or-nothing on purpose: a failed reload must leave the previous atlas
+ * intact rather than a half-loaded world, since a partially-imported atlas is
+ * indistinguishable from a real one to anyone reading it.
+ *
+ * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly
+ * commits, which would defeat exactly that guarantee. At ~7k rows the cost of
+ * `DELETE` is irrelevant.
+ */
+async function replaceAtlas(atlas, art = {}) {
+  const conn = await pool.getConnection()
+  const counts = {}
+  try {
+    await conn.beginTransaction()
+
+    for (const table of ATLAS_TABLES) await conn.query(`DELETE FROM ${table}`)
+
+    counts.creatures = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_creatures (slug, name, total, points, facets, art) VALUES (?,?,?,?,?,?)',
+      atlas.creatures.map((c) => [
+        c.slug,
+        c.name,
+        c.total ?? 0,
+        c.points ?? 0,
+        JSON.stringify(c.facets ?? {}),
+        art[c.slug] ?? null,
+      ]),
+    )
+
+    counts.regions = await insertBatched(
+      conn,
+      'INSERT INTO shard_regions (facet, name, type, priority, parent, rects) VALUES (?,?,?,?,?,?)',
+      atlas.regions.map((r) => [
+        r.facet,
+        r.name,
+        r.type || null,
+        r.priority ?? 0,
+        r.parent || null,
+        JSON.stringify(r.rects ?? []),
+      ]),
+    )
+
+    counts.landmarks = await insertBatched(
+      conn,
+      'INSERT INTO shard_landmarks (facet, name, grp, x, y, z) VALUES (?,?,?,?,?,?)',
+      atlas.landmarks.map((l) => [
+        l.facet,
+        l.name,
+        l.group || null,
+        l.x ?? 0,
+        l.y ?? 0,
+        l.z ?? 0,
+      ]),
+    )
+
+    counts.champions = await insertBatched(
+      conn,
+      'INSERT INTO shard_champion_spawns ' +
+        '(slug, name, grp, type, random_type, facet, x, y, z, radius, label) ' +
+        'VALUES (?,?,?,?,?,?,?,?,?,?,?)',
+      atlas.champions.map((c) => [
+        c.slug,
+        c.name,
+        c.group || null,
+        c.type || null,
+        c.randomType ? 1 : 0,
+        c.facet,
+        c.x ?? 0,
+        c.y ?? 0,
+        c.z ?? 0,
+        c.radius ?? 0,
+        c.label || null,
+      ]),
+    )
+
+    // Point ids are assigned explicitly rather than left to AUTO_INCREMENT: the
+    // join rows need to know them and `conn.batch()` reports no usable insertId
+    // for a multi-row insert. Safe because this transaction just emptied the
+    // table and nothing else writes to it.
+    counts.points = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_points ' +
+        '(id, facet, name, x, y, width, height, spawn_range, max_count, min_delay, max_delay, ' +
+        'tod_start, tod_end, tod_mode, region, landmark, label) ' +
+        'VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
+      atlas.points.map((p, i) => [
+        i + 1,
+        p.facet,
+        p.name,
+        p.x,
+        p.y,
+        p.width ?? 0,
+        p.height ?? 0,
+        p.range ?? 0,
+        p.maxCount ?? 0,
+        p.minDelay ?? 0,
+        p.maxDelay ?? 0,
+        p.todStart ?? 0,
+        p.todEnd ?? 0,
+        p.todMode ?? 0,
+        p.region,
+        p.landmark,
+        p.label || 'Wilderness',
+      ]),
+    )
+
+    counts.pointTypes = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_point_types (point_id, slug, max_count) VALUES (?,?,?)',
+      atlas.pointTypes,
+    )
+
+    await conn.query(
+      'INSERT INTO shard_atlas_meta (id, payload) VALUES (1, ?) ' +
+        'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP',
+      [JSON.stringify({ ...atlas.meta, importedCounts: counts })],
+    )
+
+    // A completed import answers whatever was pending.
+    await conn.query('DELETE FROM shard_atlas_pending')
+
+    await conn.commit()
+    return counts
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+async function getMeta() {
+  const rows = await query('SELECT payload, imported_at FROM shard_atlas_meta WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, importedAt: rows[0].imported_at }
+}
+
+/** Facet names currently loaded, used to detect a facet disappearing. */
+async function getFacets() {
+  const rows = await query('SELECT DISTINCT facet FROM shard_spawn_points ORDER BY facet')
+  return rows.map((row) => row.facet)
+}
+
+// ── Pending review ─────────────────────────────────────────────────────────
+
+async function getPending() {
+  const rows = await query('SELECT payload, status, detected_at FROM shard_atlas_pending WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, status: rows[0].status, detectedAt: rows[0].detected_at }
+}
+
+async function setPending(payload, status = 'pending') {
+  return query(
+    'INSERT INTO shard_atlas_pending (id, status, payload) VALUES (1, ?, ?) ' +
+      'ON DUPLICATE KEY UPDATE status = VALUES(status), payload = VALUES(payload), ' +
+      'detected_at = CURRENT_TIMESTAMP',
+    [status, JSON.stringify(payload)],
+  )
+}
+
+async function clearPending() {
+  return query('DELETE FROM shard_atlas_pending')
+}
+
+// ── Reads (the public /atlas surface) ──────────────────────────────────────
+//
+// Every read here is a plain indexed query over ~7k rows and is served entirely
+// from MariaDB: the atlas is static shard content, so nothing on this path
+// touches the sidecar and nothing degrades when the shard is down.
+//
+// A facet filter is expressed as EXISTS over the points, never as a JSON path
+// built from caller input. `shard_spawn_creatures.facets` is a JSON object keyed
+// by facet name, and matching a key means either concatenating the name into a
+// path or handing it to JSON_SEARCH — whose search string treats `%` and `_` as
+// wildcards, so `?facet=%` would quietly match everything. The join is exact and
+// uses the indexes that already exist.
+const CREATURE_FACET_EXISTS = `EXISTS (
+  SELECT 1 FROM shard_spawn_point_types t
+    JOIN shard_spawn_points p ON p.id = t.point_id
+   WHERE t.slug = c.slug AND p.facet = ?
+)`
+
+// Build the WHERE for a creature search. `q` is a substring match on the display
+// name — a LIKE scan, which is free at ~800 rows and, unlike FULLTEXT, has no
+// minimum token length to break a search for "orc".
+function creatureWhere({ q, facet }) {
+  const where = []
+  const params = []
+  if (q) {
+    where.push('c.name LIKE ?')
+    params.push(`%${q}%`)
+  }
+  if (facet) {
+    where.push(CREATURE_FACET_EXISTS)
+    params.push(facet)
+  }
+  return { sql: where.length ? `WHERE ${where.join(' AND ')}` : '', params }
+}
+
+async function countCreatures({ q = '', facet = '' } = {}) {
+  const { sql, params } = creatureWhere({ q, facet })
+  const rows = await query(`SELECT COUNT(*) AS n FROM shard_spawn_creatures c ${sql}`, params)
+  return rows[0] ? Number(rows[0].n) : 0
+}
+
+function listCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) {
+  const { sql, params } = creatureWhere({ q, facet })
+  return query(
+    `SELECT c.slug, c.name, c.total, c.points, c.facets, c.art
+       FROM shard_spawn_creatures c
+       ${sql}
+      ORDER BY c.total DESC, c.name ASC
+      LIMIT ? OFFSET ?`,
+    [...params, limit, offset],
+  )
+}
+
+async function getCreature(slug) {
+  const rows = await query(
+    'SELECT slug, name, total, points, facets, art FROM shard_spawn_creatures WHERE slug = ?',
+    [slug],
+  )
+  return rows[0] || null
+}
+
+/**
+ * Where a creature spawns, grouped by resolved place.
+ *
+ * This is the answer the atlas exists to give — "lizardman → Shrines,
+ * Isamu-Jima, Yew" — so it is aggregated in SQL rather than by summing 6,455
+ * point rows in Node.
+ */
+function listCreaturePlaces(slug, { facet = '' } = {}) {
+  const params = [slug]
+  let facetSql = ''
+  if (facet) {
+    facetSql = 'AND p.facet = ?'
+    params.push(facet)
+  }
+  return query(
+    `SELECT p.facet, p.label, COUNT(*) AS spawners, SUM(t.max_count) AS max_alive
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_points p ON p.id = t.point_id
+      WHERE t.slug = ? ${facetSql}
+      GROUP BY p.facet, p.label
+      ORDER BY spawners DESC, p.facet ASC, p.label ASC`,
+    params,
+  )
+}
+
+/** The individual spawners for a creature, newest-largest first. Bounded. */
+function listCreaturePoints(slug, { facet = '', limit = 200 } = {}) {
+  const params = [slug]
+  let facetSql = ''
+  if (facet) {
+    facetSql = 'AND p.facet = ?'
+    params.push(facet)
+  }
+  params.push(limit)
+  return query(
+    `SELECT p.id, p.facet, p.name, p.x, p.y, p.width, p.height, p.spawn_range,
+            p.min_delay, p.max_delay, p.tod_start, p.tod_end, p.tod_mode,
+            p.region, p.landmark, p.label, t.max_count
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_points p ON p.id = t.point_id
+      WHERE t.slug = ? ${facetSql}
+      ORDER BY t.max_count DESC, p.facet ASC, p.label ASC, p.id ASC
+      LIMIT ?`,
+    params,
+  )
+}
+
+/** Every other creature sharing a spawner with this one. */
+function listCreatureCompanions(slug, { limit = 24 } = {}) {
+  return query(
+    `SELECT o.slug, c.name, COUNT(*) AS shared
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_point_types o ON o.point_id = t.point_id AND o.slug <> t.slug
+       JOIN shard_spawn_creatures c ON c.slug = o.slug
+      WHERE t.slug = ?
+      GROUP BY o.slug, c.name
+      ORDER BY shared DESC, c.name ASC
+      LIMIT ?`,
+    [slug, limit],
+  )
+}
+
+function listRegions({ facet = '', q = '' } = {}) {
+  const where = []
+  const params = []
+  if (facet) {
+    where.push('facet = ?')
+    params.push(facet)
+  }
+  if (q) {
+    where.push('name LIKE ?')
+    params.push(`%${q}%`)
+  }
+  return query(
+    `SELECT facet, name, type, priority, parent, rects
+       FROM shard_regions
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      ORDER BY facet ASC, name ASC`,
+    params,
+  )
+}
+
+function listLandmarks({ facet = '', q = '' } = {}) {
+  const where = []
+  const params = []
+  if (facet) {
+    where.push('facet = ?')
+    params.push(facet)
+  }
+  if (q) {
+    where.push('(name LIKE ? OR grp LIKE ?)')
+    params.push(`%${q}%`, `%${q}%`)
+  }
+  return query(
+    `SELECT facet, name, grp, x, y, z
+       FROM shard_landmarks
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      ORDER BY facet ASC, grp ASC, name ASC`,
+    params,
+  )
+}
+
+function listChampions({ facet = '' } = {}) {
+  const params = []
+  let where = ''
+  if (facet) {
+    where = 'WHERE facet = ?'
+    params.push(facet)
+  }
+  return query(
+    `SELECT slug, name, grp, type, random_type, facet, x, y, z, radius, label
+       FROM shard_champion_spawns
+       ${where}
+      ORDER BY facet ASC, name ASC`,
+    params,
+  )
+}
+
+module.exports = {
+  replaceAtlas,
+  getMeta,
+  getFacets,
+  getPending,
+  setPending,
+  clearPending,
+  countCreatures,
+  listCreatures,
+  getCreature,
+  listCreaturePlaces,
+  listCreaturePoints,
+  listCreatureCompanions,
+  listRegions,
+  listLandmarks,
+  listChampions,
+}

server/src/model/shardAtlas/shardAtlas.model.js

@@ -0,0 +1,485 @@
+const fs = require('fs')
+const path = require('path')
+
+const db = require('./shardAtlas.db')
+const settings = require('../settings/settings.model')
+const { slugify } = require('../../utils/spawnAtlasParse')
+const {
+  AtlasSourceError,
+  PARSER_VERSION,
+  buildAtlas,
+  hashSources,
+  sameSources,
+} = require('../../utils/spawnAtlasSource')
+const log = require('../../utils/logger')('shardAtlas')
+
+// The spawn atlas, refreshed from the shard's own ServUO tree.
+//
+// The tree is the single source of truth. Nothing is precomputed and committed,
+// because a shard's maps change over its lifetime — facets get added, replaced
+// or renamed — and a snapshot in the repo would go stale against the world
+// players actually see. So the atlas is re-derived on every boot.
+//
+// Two rules govern the boot path:
+//
+//   1. **It never blocks startup.** No configured path, an unreadable path, a
+//      malformed file, a database error — all of it is caught and logged. The
+//      site comes up either way, serving whatever atlas it already had.
+//   2. **A facet disappearing is not applied automatically.** Losing a facet is
+//      the signature of a half-copied or mid-update tree as much as of a real
+//      map change, and the two are indistinguishable from here. The refresh is
+//      staged for a human instead, and an admin approves or rejects it.
+//
+// Everything else — new facets, renamed regions, changed spawns — applies
+// straight away, because none of it can silently destroy data an operator would
+// miss.
+
+const SETTING_KEY = 'spawn_atlas_servuo_path'
+
+/**
+ * Where the ServUO tree lives.
+ *
+ * The admin setting wins over the environment so an operator can point the
+ * atlas at a different tree without a redeploy, matching how the rest of the
+ * shard integration is admin-managed rather than env-configured. `SERVUO_PATH`
+ * remains as the deploy-time default, since the path usually describes a mount
+ * that the deployment sets up.
+ */
+async function getServuoPath() {
+  try {
+    const configured = await settings.get(SETTING_KEY)
+    if (configured && String(configured).trim() !== '') return String(configured).trim()
+  } catch {
+    // Settings unavailable is not fatal — fall through to the env default.
+  }
+  const fromEnv = process.env.SERVUO_PATH
+  return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : ''
+}
+
+async function setServuoPath(value, updatedBy = null) {
+  return settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy)
+}
+
+/**
+ * Optional operator-supplied art map, `{ "<slug>": "<file under uploads/atlas/>" }`.
+ *
+ * Never committed and never shipped — creature sprites come out of the
+ * operator's own client `.mul`/`.uop` files, which are theirs, not ours to
+ * redistribute. Absent (the normal case) every `art` stays NULL and the UI
+ * renders text-only.
+ */
+function loadArtMap(dir = path.join(__dirname, '..', '..', '..', 'db', 'data')) {
+  try {
+    const file = path.join(dir, 'spawnAtlas.art.json')
+    if (!fs.existsSync(file)) return {}
+    const map = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return map && typeof map === 'object' ? map : {}
+  } catch (err) {
+    log.warn('spawn atlas art map could not be read', { error: err.message })
+    return {}
+  }
+}
+
+/**
+ * Flatten each point's types into `shard_spawn_point_types` rows.
+ *
+ * A spawner may legitimately list the same type twice, and the primary key is
+ * (point_id, slug), so duplicates collapse to the larger max rather than
+ * failing the insert.
+ */
+function pointTypeRows(points) {
+  const rows = []
+  points.forEach((point, i) => {
+    const bySlug = new Map()
+    for (const entry of point.types ?? []) {
+      const slug = slugify(entry.type)
+      if (slug === '') continue
+      bySlug.set(slug, Math.max(bySlug.get(slug) ?? 0, entry.max ?? 1))
+    }
+    for (const [slug, max] of bySlug) rows.push([i + 1, slug, max])
+  })
+  return rows
+}
+
+async function applyAtlas(atlas) {
+  return db.replaceAtlas({ ...atlas, pointTypes: pointTypeRows(atlas.points) }, loadArtMap())
+}
+
+/**
+ * Refresh the atlas from the configured ServUO tree.
+ *
+ * Returns a result describing what happened rather than throwing, so the caller
+ * — including the boot path — can log it and move on:
+ *
+ *   `skipped`     no path configured
+ *   `unavailable` path configured but unreadable / missing required files
+ *   `unchanged`   source hashes match the loaded atlas; nothing parsed
+ *   `imported`    parsed and applied
+ *   `needsReview` parsed, but a facet would be lost; staged for an admin
+ *   `failed`      parsed or applied and something went wrong
+ *
+ * `force` skips the hash check (an admin asking for a reimport) and `approve`
+ * additionally accepts facet loss (an admin approving a staged refresh).
+ */
+/**
+ * Was the loaded atlas built by THIS parser?
+ *
+ * An atlas imported before `parserVersion` existed reports undefined, which is
+ * correctly "no" — those are exactly the ones carrying the old readings.
+ */
+const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION
+
+async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) {
+  // An explicit override wins outright — it is a one-off "use this tree", and it
+  // must not be silently overruled by the configured path the way an env default
+  // would be.
+  const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath()
+  if (root === '') return { status: 'skipped', reason: 'no ServUO path configured' }
+
+  let hashes
+  try {
+    hashes = hashSources(root)
+  } catch (err) {
+    if (err instanceof AtlasSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: root }
+    }
+    return { status: 'failed', reason: err.message, path: root }
+  }
+
+  const meta = await db.getMeta().catch(() => null)
+  const loaded = meta?.source
+    ? Object.fromEntries(Object.entries(meta.source).map(([label, v]) => [label, v.sha256]))
+    : null
+
+  // Two things make a loaded atlas stale: the tree changed, or the PARSER did.
+  // Only checking the tree would strand an install whose maps never change on
+  // whatever an older build derived — a corrected parse would ship and never
+  // reach the data.
+  if (!force && sameSources(hashes, loaded) && currentParser(meta)) {
+    return { status: 'unchanged', path: root }
+  }
+
+  // A rejected refresh must not re-prompt on every boot. It stays rejected until
+  // the tree changes again, at which point the hashes differ and it is a new
+  // decision.
+  const pending = await db.getPending().catch(() => null)
+  if (!approve && !force && pending?.status === 'rejected' && sameSources(hashes, pending.hashes)) {
+    return { status: 'unchanged', path: root, reason: 'refresh previously rejected' }
+  }
+
+  let atlas
+  try {
+    atlas = buildAtlas(root)
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: root }
+  }
+
+  const currentFacets = await db.getFacets().catch(() => [])
+  const incomingFacets = atlas.facets
+  const removedFacets = currentFacets.filter((facet) => !incomingFacets.includes(facet))
+  const addedFacets = incomingFacets.filter((facet) => !currentFacets.includes(facet))
+
+  // Losing a facet is indistinguishable here from a half-copied tree, so it is
+  // staged rather than applied — but startup is never blocked by it.
+  if (removedFacets.length > 0 && !approve) {
+    const summary = {
+      hashes,
+      path: root,
+      currentFacets,
+      incomingFacets,
+      removedFacets,
+      addedFacets,
+      counts: atlas.meta.counts,
+    }
+    await db.setPending(summary, 'pending').catch((err) => {
+      log.warn('could not stage spawn atlas refresh', { error: err.message })
+    })
+    return { status: 'needsReview', ...summary }
+  }
+
+  try {
+    const counts = await applyAtlas(atlas)
+    return { status: 'imported', path: root, counts, addedFacets, removedFacets }
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: root }
+  }
+}
+
+/** Admin approved a staged refresh: apply it, facet loss and all. */
+async function approvePending(options = {}) {
+  return refresh({ ...options, approve: true, force: true })
+}
+
+/**
+ * Admin rejected a staged refresh: keep the current atlas and remember the
+ * decision against those exact source hashes, so it does not re-prompt every
+ * boot. A further change to the tree produces different hashes and asks again.
+ */
+async function rejectPending() {
+  const pending = await db.getPending()
+  if (!pending) return { status: 'none' }
+  await db.setPending({ ...pending, rejectedAt: new Date().toISOString() }, 'rejected')
+  return { status: 'rejected' }
+}
+
+/** Everything the admin panel needs to describe atlas state. */
+async function status({ path: pathOverride = '' } = {}) {
+  const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath()
+  const [meta, pending, facets] = await Promise.all([
+    db.getMeta().catch(() => null),
+    db.getPending().catch(() => null),
+    db.getFacets().catch(() => []),
+  ])
+
+  let treeReadable = false
+  let drift = null
+  if (root !== '') {
+    try {
+      const hashes = hashSources(root)
+      treeReadable = true
+      const loaded = meta?.source
+        ? Object.fromEntries(Object.entries(meta.source).map(([l, v]) => [l, v.sha256]))
+        : null
+      // Same question `refresh` asks: an import picks something up when either
+      // the tree or the parser has moved on.
+      drift = !sameSources(hashes, loaded) || !currentParser(meta)
+    } catch {
+      treeReadable = false
+    }
+  }
+
+  return {
+    configured: root !== '',
+    path: root,
+    treeReadable,
+    drift,
+    facets,
+    importedAt: meta?.importedAt ?? null,
+    counts: meta?.counts ?? null,
+    pending,
+  }
+}
+
+/**
+ * Boot hook. Best-effort by contract: it logs and returns, never throws, so a
+ * missing tree or a bad file can never stop the site coming up.
+ */
+async function refreshOnBoot() {
+  try {
+    const result = await refresh()
+    switch (result.status) {
+      case 'imported':
+        log.info('spawn atlas refreshed from ServUO tree', {
+          ...result.counts,
+          added: result.addedFacets,
+        })
+        break
+      case 'needsReview':
+        log.warn(
+          'spawn atlas refresh staged for admin review — a facet would be removed; ' +
+            'the existing atlas is unchanged',
+          { removed: result.removedFacets, added: result.addedFacets },
+        )
+        break
+      case 'unavailable':
+        log.warn('spawn atlas source unavailable', { reason: result.reason, path: result.path })
+        break
+      case 'failed':
+        log.warn('spawn atlas refresh failed', { reason: result.reason })
+        break
+      default:
+        break
+    }
+    return result
+  } catch (err) {
+    log.warn('spawn atlas refresh errored', { error: err.message })
+    return { status: 'failed', reason: err.message }
+  }
+}
+
+// ── Reads ──────────────────────────────────────────────────────────────────
+//
+// The shapes the /public/atlas endpoints serve. Rows are camelCased here rather
+// than in the controller, for the same reason shardState does it: the column
+// names are an implementation detail of the import, and the browser contract
+// should not move when a column is renamed.
+
+const jsonOr = (value, fallback) => {
+  if (value == null) return fallback
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return fallback
+  }
+}
+
+const shapeCreature = (row) => ({
+  slug: row.slug,
+  name: row.name,
+  // `total` is the summed MaxCount across every spawner (how many can be alive
+  // at once); `points` is how many spawners mention it. They answer different
+  // questions and the UI shows both.
+  total: row.total,
+  points: row.points,
+  facets: jsonOr(row.facets, {}),
+  art: row.art || null,
+})
+
+const shapePlace = (row) => ({
+  facet: row.facet,
+  label: row.label,
+  spawners: Number(row.spawners) || 0,
+  maxAlive: Number(row.max_alive) || 0,
+})
+
+const shapePoint = (row) => ({
+  id: row.id,
+  facet: row.facet,
+  name: row.name || null,
+  x: row.x,
+  y: row.y,
+  width: row.width,
+  height: row.height,
+  range: row.spawn_range,
+  maxCount: row.max_count,
+  minDelay: row.min_delay,
+  maxDelay: row.max_delay,
+  todStart: row.tod_start,
+  todEnd: row.tod_end,
+  todMode: row.tod_mode,
+  region: row.region || null,
+  landmark: row.landmark || null,
+  label: row.label,
+})
+
+/**
+ * Paginated creature search. Returns the page plus the unpaginated total, so
+ * the UI can say "showing 50 of 800" without a second round trip.
+ */
+async function searchCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) {
+  const [rows, total] = await Promise.all([
+    db.listCreatures({ q, facet, limit, offset }),
+    db.countCreatures({ q, facet }),
+  ])
+  return { total, limit, offset, creatures: rows.map(shapeCreature) }
+}
+
+/**
+ * One creature: its totals, the places it spawns (the aggregate the atlas
+ * exists for), the individual spawners, and what else shares those spawners.
+ *
+ * `null` when the slug is unknown — the controller turns that into a 404.
+ */
+async function getCreature(slug, { facet = '', points = 200 } = {}) {
+  const row = await db.getCreature(slug)
+  if (!row) return null
+  const [places, pointRows, alsoHere] = await Promise.all([
+    db.listCreaturePlaces(slug, { facet }),
+    db.listCreaturePoints(slug, { facet, limit: points }),
+    db.listCreatureCompanions(slug),
+  ])
+  return {
+    ...shapeCreature(row),
+    places: places.map(shapePlace),
+    // `spawners`, not `points`: shapeCreature already uses `points` for the
+    // COUNT of spawners, and reusing the key for the list of them would make the
+    // same field a number on the search route and an array here.
+    spawners: pointRows.map(shapePoint),
+    // Bounded by the query, so a creature on hundreds of spawners returns a page
+    // rather than the world.
+    spawnersTruncated: pointRows.length >= points,
+    alsoHere: alsoHere.map((r) => ({
+      slug: r.slug,
+      name: r.name,
+      shared: Number(r.shared) || 0,
+    })),
+  }
+}
+
+async function listRegions(opts = {}) {
+  const rows = await db.listRegions(opts)
+  return rows.map((r) => ({
+    facet: r.facet,
+    name: r.name,
+    type: r.type || null,
+    priority: r.priority,
+    parent: r.parent || null,
+    rects: jsonOr(r.rects, []),
+  }))
+}
+
+async function listLandmarks(opts = {}) {
+  const rows = await db.listLandmarks(opts)
+  return rows.map((r) => ({
+    facet: r.facet,
+    name: r.name,
+    group: r.grp || null,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+  }))
+}
+
+async function listChampions(opts = {}) {
+  const rows = await db.listChampions(opts)
+  return rows.map((r) => ({
+    slug: r.slug,
+    name: r.name,
+    group: r.grp || null,
+    // '' on the wire means "randomised at activation"; `randomType` says so
+    // explicitly rather than making the client infer it from an empty string.
+    type: r.type || null,
+    randomType: !!r.random_type,
+    facet: r.facet,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    radius: r.radius,
+    label: r.label || null,
+  }))
+}
+
+/**
+ * What is loaded: the facet list, the counts, and when it was imported.
+ *
+ * Deliberately does NOT report the source path, the per-file hashes or whether
+ * a refresh is pending. Those describe the operator's filesystem, and this is a
+ * public endpoint; the admin status route carries them instead.
+ */
+async function publicMeta() {
+  const [meta, facets] = await Promise.all([
+    db.getMeta().catch(() => null),
+    db.getFacets().catch(() => []),
+  ])
+  return {
+    importedAt: meta?.importedAt ?? null,
+    generatedAt: meta?.generatedAt ?? null,
+    // The parse counts, not the row counts: `unresolvedPoints` is what lets the
+    // page state its own placement accuracy instead of implying it is complete.
+    counts: meta?.counts ?? null,
+    facets,
+  }
+}
+
+const listFacets = () => db.getFacets()
+
+module.exports = {
+  refresh,
+  refreshOnBoot,
+  approvePending,
+  rejectPending,
+  status,
+  getServuoPath,
+  setServuoPath,
+  pointTypeRows,
+  loadArtMap,
+  SETTING_KEY,
+  searchCreatures,
+  getCreature,
+  listRegions,
+  listLandmarks,
+  listChampions,
+  listFacets,
+  publicMeta,
+}

server/src/model/shardClilocs/shardClilocs.db.js

@@ -0,0 +1,108 @@
+const { pool, query } = require('../../utils/db')
+
+// Raw SQL for the cliloc table. `shard_clilocs` is IMPORT-OWNED: `replaceAll`
+// empties and refills it inside one transaction, and nothing else in the
+// codebase writes to it. No foreign keys, consistent with every other shard_*
+// table.
+
+const BATCH = 1000
+
+/**
+ * Replace the entire cliloc table in one transaction.
+ *
+ * All-or-nothing on purpose: a failed reload must leave the previous table
+ * intact rather than a half-loaded one, because a partially-imported cliloc
+ * table is indistinguishable from a complete one to anyone reading it — you
+ * would just see some items named and some not, which is also what "no table at
+ * all" looks like.
+ *
+ * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly
+ * commits, which would defeat exactly that guarantee. (The same trap the spawn
+ * atlas import documents; at ~123k rows `DELETE` is still well under a second.)
+ */
+async function replaceAll(entries, meta) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_clilocs')
+
+    // Blank entries are dropped rather than stored. Roughly HALF of a real
+    // cliloc table is empty strings — ids the client reserves and never uses —
+    // and a row that resolves to no name is indistinguishable from no row at
+    // all to every caller. Dropping them halves the table (123,490 → ~67,500)
+    // and, more importantly, makes the binary and text imports converge on
+    // identical content: the binary format carries the blanks explicitly and a
+    // text export may or may not, depending on the tool.
+    //
+    // Later duplicates win. Merging across sources already happened upstream in
+    // `readCliloc`, so in practice this collapses nothing — it is kept because
+    // the plain format permits a repeated id WITHIN one file and the client's
+    // own loader resolves it the same way (its dictionary assignment
+    // overwrites). Without it, a file the game itself would load happily would
+    // fail the batch insert on a primary-key collision.
+    const byNumber = new Map()
+    let blank = 0
+    for (const entry of entries) {
+      if (!Number.isInteger(entry.number)) continue
+      if (String(entry.text ?? '').trim() === '') {
+        blank++
+        continue
+      }
+      byNumber.set(entry.number, entry)
+    }
+
+    const rows = [...byNumber.values()].map((e) => [e.number, e.flag ?? 0, e.text])
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch('INSERT INTO shard_clilocs (number, flag, text) VALUES (?,?,?)', rows.slice(i, i + BATCH))
+    }
+
+    await conn.query(
+      'INSERT INTO shard_cliloc_meta (id, payload) VALUES (1, ?) ' +
+        'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP',
+      [JSON.stringify({ ...meta, count: rows.length })],
+    )
+
+    await conn.commit()
+    return { count: rows.length, blank, duplicates: entries.length - blank - rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+async function getMeta() {
+  const rows = await query('SELECT payload, imported_at FROM shard_cliloc_meta WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, importedAt: rows[0].imported_at }
+}
+
+/**
+ * Look up a batch of ids.
+ *
+ * Batched rather than one-at-a-time because every caller has a LIST: a character
+ * sheet resolves a dozen equipment ids at once, and a page of marketplace
+ * listings resolves fifty. `IN (...)` with generated placeholders keeps it one
+ * round trip and one parameterized statement.
+ */
+async function lookup(numbers) {
+  if (!Array.isArray(numbers) || numbers.length === 0) return []
+  const ids = [...new Set(numbers.filter((n) => Number.isInteger(n)))]
+  if (ids.length === 0) return []
+  const placeholders = ids.map(() => '?').join(',')
+  return query(`SELECT number, text FROM shard_clilocs WHERE number IN (${placeholders})`, ids)
+}
+
+async function count() {
+  const rows = await query('SELECT COUNT(*) AS n FROM shard_clilocs')
+  return Number(rows[0]?.n) || 0
+}
+
+module.exports = {
+  replaceAll,
+  getMeta,
+  lookup,
+  count,
+}

server/src/model/shardClilocs/shardClilocs.model.js

@@ -0,0 +1,368 @@
+const db = require('./shardClilocs.db')
+const settings = require('../settings/settings.model')
+const { displayText } = require('../../utils/clilocParse')
+const {
+  ClilocFormatError,
+  ClilocSourceError,
+  PARSER_VERSION,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+} = require('../../utils/clilocSource')
+const log = require('../../utils/logger')('shardClilocs')
+
+// The cliloc table — UO's id → display-string map, refreshed from a file the
+// operator converts once from their own client.
+//
+// Why the site holds this at all: items on the wire carry a `LabelNumber`, not a
+// name. `char.profile.equipment` has always sent `cliloc`, and every marketplace
+// listing sends one too. Without the table the UI can only print `id 1023721`
+// where the game prints "quarter staff".
+//
+// Two rules govern the boot path, both inherited from the spawn atlas:
+//
+//   1. **It never blocks startup.** No configured path, an unreadable file, a
+//      wrong-format file, a database error — all caught and logged. The site
+//      comes up either way, serving whatever table it already had (or none, in
+//      which case the UI falls back to item ids exactly as it did before).
+//   2. **Nothing client-derived is committed.** The table is built from the
+//      operator's own file at a configured path. The repo ships no strings.
+//
+// The table is built from a SET of sources — the converted client table plus
+// every operator-maintained overlay beside it — because shards edit items and
+// add new ones, and those carry cliloc ids no stock client table has. All of
+// them are re-read on every boot and hash-gated together, so adding one custom
+// item never means re-exporting a 5 MB client file. Later sources win.
+//
+// That set is also why this has the atlas's escalation, in a lighter form. A
+// single corrupt file fails the parse loudly, but a source that has simply
+// VANISHED parses perfectly and imports a table quietly missing everything it
+// contributed — the same ambiguity (real change vs half-copied mount) the atlas
+// stages a facet removal for. So a disappearing source is refused and reported
+// rather than applied.
+//
+// It is lighter than the atlas's because it needs to be: the atlas stores a
+// pending decision in its own table and adds approve/reject endpoints, whereas
+// here the decision is a single boolean an admin passes to the import they were
+// already going to run. Re-parsing at approval time — the property that makes
+// the atlas store only the decision — is automatic when there is nothing stored.
+
+const SETTING_KEY = 'cliloc_client_path'
+
+/**
+ * Where the converted cliloc file lives.
+ *
+ * The admin setting wins over the environment so an operator can repoint it
+ * without a redeploy, matching how the rest of the shard integration is
+ * admin-managed rather than env-configured. `UO_CLIENT_PATH` remains as the
+ * deploy-time default, since the path usually describes a mount the deployment
+ * sets up.
+ */
+async function getClientPath() {
+  try {
+    const configured = await settings.get(SETTING_KEY)
+    if (configured && String(configured).trim() !== '') return String(configured).trim()
+  } catch {
+    // Settings unavailable is not fatal — fall through to the env default.
+  }
+  const fromEnv = process.env.UO_CLIENT_PATH
+  return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : ''
+}
+
+async function setClientPath(value, updatedBy = null) {
+  const result = await settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy)
+  invalidate()
+  return result
+}
+
+// ── Refresh ────────────────────────────────────────────────────────────────
+
+/** Was the loaded table built by THIS parser? */
+const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION
+
+/**
+ * Refresh the cliloc table from the configured file.
+ *
+ * Returns a result describing what happened rather than throwing, so the caller
+ * — including the boot path — can log it and move on:
+ *
+ *   `skipped`     no path configured
+ *   `unavailable` path configured but missing / unreadable / not a cliloc file
+ *   `unchanged`   source hashes match the loaded table; nothing parsed
+ *   `imported`    parsed and applied
+ *   `needsReview` a previously-present source has vanished; NOT applied
+ *   `failed`      parsed or applied and something went wrong
+ *
+ * `force` skips the hash check (an admin asking for a reimport). `approve`
+ * additionally accepts a vanished source.
+ */
+async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) {
+  // An explicit override wins outright — a one-off "use this file", which must
+  // not be silently overruled by the configured path the way an env default is.
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  if (configured === '') return { status: 'skipped', reason: 'no cliloc path configured' }
+
+  let fingerprint
+  try {
+    fingerprint = hashSources(configured)
+  } catch (err) {
+    if (err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  const meta = await db.getMeta().catch(() => null)
+
+  // Two things make a loaded table stale: any source changed, or the PARSER did.
+  // Only checking the sources would strand an install whose client never patches
+  // on whatever an older build derived.
+  if (!force && sameSources(fingerprint.hashes, meta?.hashes) && currentParser(meta)) {
+    return {
+      status: 'unchanged',
+      path: configured,
+      file: fingerprint.file,
+      count: meta.count ?? null,
+      customCount: fingerprint.customCount,
+    }
+  }
+
+  // A source that was there last import and is not there now is refused, not
+  // applied — an unmounted volume and a deliberate deletion look identical from
+  // here, and the wrong guess silently drops every name that file contributed.
+  const gone = missingSources(fingerprint.hashes, meta?.hashes)
+  if (gone.length > 0 && !approve) {
+    return {
+      status: 'needsReview',
+      reason: `${gone.length} previously-loaded cliloc source(s) are missing; the existing table is unchanged`,
+      missingSources: gone,
+      path: configured,
+      file: fingerprint.file,
+    }
+  }
+
+  let parsed
+  try {
+    parsed = readCliloc(configured)
+  } catch (err) {
+    if (err instanceof ClilocFormatError || err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  try {
+    const applied = await db.replaceAll(parsed.entries, parsed.source)
+    invalidate()
+    return {
+      status: 'imported',
+      path: configured,
+      file: parsed.source.file,
+      count: applied.count,
+      parsed: parsed.entries.length,
+      blank: applied.blank,
+      // Per-source breakdown: how many entries each file contributed and how
+      // many of them overrode something already merged. An operator who adds an
+      // overlay wants to see it took effect, and "overrode: 0" on a file meant
+      // to re-label stock items says it did not.
+      sources: parsed.source.sources,
+      acceptedMissing: gone.length > 0 ? gone : undefined,
+    }
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+}
+
+/**
+ * Boot hook. Best-effort by contract: it logs and returns, never throws, so a
+ * missing or malformed cliloc file can never stop the site coming up.
+ */
+async function refreshOnBoot() {
+  try {
+    const result = await refresh()
+    switch (result.status) {
+      case 'imported':
+        log.info('cliloc table refreshed', {
+          file: result.file,
+          count: result.count,
+          overlays: (result.sources || []).filter((s) => s.kind === 'custom').length,
+        })
+        break
+      case 'needsReview':
+        log.warn(
+          'cliloc refresh staged for admin review — a previously-loaded source is missing; ' +
+            'the existing table is unchanged',
+          { missing: result.missingSources },
+        )
+        break
+      case 'unavailable':
+        // Deliberately a warning, not an error: an operator who has not supplied
+        // a cliloc file is in a supported state (the UI shows item ids), and the
+        // most common cause — pointing at the client's own compressed file —
+        // needs the reason spelled out rather than a stack trace.
+        log.warn('cliloc source unavailable (item names will show as ids)', {
+          reason: result.reason,
+          code: result.code,
+          path: result.path,
+        })
+        break
+      case 'failed':
+        log.warn('cliloc refresh failed', { reason: result.reason })
+        break
+      default:
+        break
+    }
+    return result
+  } catch (err) {
+    log.warn('cliloc refresh errored', { error: err.message })
+    return { status: 'failed', reason: err.message }
+  }
+}
+
+/** Everything the admin panel needs to describe cliloc state. */
+async function status({ path: pathOverride = '' } = {}) {
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  const meta = await db.getMeta().catch(() => null)
+  const loaded = await db.count().catch(() => 0)
+
+  let fileReadable = false
+  let file = null
+  let drift = null
+  let problem = null
+  let code = null
+  let sources = []
+  let missing = []
+  if (configured !== '') {
+    try {
+      const fingerprint = hashSources(configured)
+      fileReadable = true
+      file = fingerprint.file
+      sources = Object.keys(fingerprint.hashes)
+      missing = missingSources(fingerprint.hashes, meta?.hashes)
+      // A compressed file is readable but not importable, and the panel has to
+      // say so HERE — otherwise pointing at an unconverted client directory
+      // reports a healthy file with pending drift ("ready to import") and the
+      // operator only finds out when the import fails. `drift` stays null
+      // because comparing hashes with an unusable file answers nothing.
+      if (fingerprint.compressed) {
+        problem =
+          'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+          'Convert it to the plain format first — see docs/website/CLILOCS.md.'
+        code = 'COMPRESSED'
+      } else {
+        drift = !sameSources(fingerprint.hashes, meta?.hashes) || !currentParser(meta)
+      }
+    } catch (err) {
+      fileReadable = false
+      problem = err.message
+      code = err.code ?? null
+    }
+  }
+
+  return {
+    configured: configured !== '',
+    path: configured,
+    file,
+    fileReadable,
+    problem,
+    code,
+    drift,
+    count: loaded,
+    // Every source found now (base first, then overlays), what each contributed
+    // at the last import, and any that have since vanished — which is the state
+    // an import will refuse without `approve`.
+    sources,
+    loadedSources: meta?.sources ?? null,
+    missingSources: missing,
+    importedAt: meta?.importedAt ?? null,
+    sourceBytes: meta?.bytes ?? null,
+  }
+}
+
+// ── Lookup ─────────────────────────────────────────────────────────────────
+//
+// Resolution happens SERVER-SIDE, not in the browser. Two reasons: the table is
+// ~123k rows and shipping it to a client would dwarf every page that uses it,
+// and the Android app consumes the same JSON and would otherwise need its own
+// copy. Callers get names, not ids-plus-a-table.
+
+// A small write-through cache in front of the table. Item ids repeat heavily —
+// one page of listings is mostly the same few hundred clilocs, and a character
+// sheet re-resolves the same gear on every view — so this turns the steady state
+// into zero queries. Capped so a pathological caller cannot grow it without
+// bound; on overflow it is dropped wholesale rather than evicted entry-by-entry,
+// which is cheap and correct for a table that only changes on reimport.
+const CACHE_MAX = 20000
+let cache = new Map()
+
+function invalidate() {
+  cache = new Map()
+}
+
+/**
+ * Resolve a batch of cliloc ids to display strings.
+ *
+ * Returns a `Map<number, string>` holding only the ids that resolved to
+ * something displayable — an id with no row, or one whose text is nothing but
+ * interpolated arguments we do not have, is simply absent. Callers fall back to
+ * whatever they had (the item id), so "missing" and "unnamed" collapse into one
+ * branch at the call site.
+ *
+ * Never throws: a cliloc lookup is decoration on someone's character sheet, and
+ * a database blip must not fail the sheet.
+ */
+async function resolveMany(numbers) {
+  const out = new Map()
+  if (!Array.isArray(numbers)) return out
+
+  const wanted = [...new Set(numbers.filter((n) => Number.isInteger(n) && n > 0))]
+  if (wanted.length === 0) return out
+
+  const missing = []
+  for (const number of wanted) {
+    if (cache.has(number)) {
+      const hit = cache.get(number)
+      if (hit !== '') out.set(number, hit)
+    } else {
+      missing.push(number)
+    }
+  }
+
+  if (missing.length > 0) {
+    try {
+      const rows = await db.lookup(missing)
+      const found = new Map(rows.map((r) => [Number(r.number), displayText(r.text)]))
+      if (cache.size + missing.length > CACHE_MAX) invalidate()
+      for (const number of missing) {
+        // Cache the miss too ('' meaning "no usable name"), so an id absent from
+        // the table does not re-query on every page view.
+        const text = found.get(number) ?? ''
+        cache.set(number, text)
+        if (text !== '') out.set(number, text)
+      }
+    } catch (err) {
+      log.warn('cliloc lookup failed', { message: err.message })
+    }
+  }
+
+  return out
+}
+
+/** Single-id convenience. Returns `null` when there is no usable name. */
+async function resolve(number) {
+  const found = await resolveMany([number])
+  return found.get(number) ?? null
+}
+
+module.exports = {
+  SETTING_KEY,
+  getClientPath,
+  setClientPath,
+  refresh,
+  refreshOnBoot,
+  status,
+  resolveMany,
+  resolve,
+  invalidate,
+}

server/src/model/shardEvents/shardEvents.db.js

@@ -16,6 +16,11 @@ async function insertIgnore({ kind, t, bootId, payload, dedupeKey }) {
 // `kinds` (IN clause) — the public feed uses the allowlist so it can never leak
 // staff/sensitive kinds. limit is clamped by the model.
 async function list({ kind, kinds, limit }) {
+  // An allowlist that resolved to NOTHING means "serve nothing" — never "serve
+  // everything". Falling through to the unfiltered query below would have turned
+  // a fully-gated visibility config into a full dump of the event log, staff
+  // audit and cheat detections included.
+  if (kinds && kinds.length === 0) return []
   if (kinds && kinds.length) {
     const placeholders = kinds.map(() => '?').join(', ')
     return query(

server/src/model/shardMarket/shardMarket.db.js

@@ -0,0 +1,299 @@
+const { pool, query } = require('../../utils/db')
+
+// Raw SQL for the player-vendor market index (Protocol 3.0 vendor.listing).
+//
+// Two tables, both INGEST-OWNED: `shard_vendors` (one row per shop) and
+// `shard_vendor_items` (one row per priced listing). Nothing else in the codebase
+// writes to either. No foreign keys, consistent with every other shard_* table.
+
+// Insert batch size for one vendor's listings. A shop is capped at
+// MarketMaxListings (250 by default) on the shard side, so in practice this is
+// one batch — it exists for the operator who raised that cap.
+const BATCH = 500
+
+// LIKE wildcards in user input. `%` and `_` are not special to the parameterized
+// query — they are special to LIKE itself — so a search for "50% off" would
+// otherwise match everything containing "50" and a search for "_" would match
+// every single-character name. Escaped with a backslash, which is MariaDB's
+// default LIKE escape (no ESCAPE clause needed).
+const likeTerm = (q) => `%${String(q).replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+
+/**
+ * Replace one vendor's whole row and listing set, in one transaction.
+ *
+ * Delete-then-insert rather than a diff, because the frame is AUTHORITATIVE for
+ * that vendor: the shard's sweep only emits a shop whose contents, prices or
+ * location moved, and when it does it sends the whole shop. Reconciling it item
+ * by item would be more code for the same result and would leave sold items
+ * behind on any path the reconciliation missed.
+ *
+ * All-or-nothing matters here for a specific reason: the two writes are "the
+ * shop" and "what is in it", and a failure between them leaves a shop advertising
+ * an inventory it no longer has (or none at all) — visibly wrong on the page, and
+ * indistinguishable from a genuinely empty shop.
+ */
+async function replaceVendor(vendor, items) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+
+    await conn.query(
+      `INSERT INTO shard_vendors
+         (serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+          item_count, item_total, truncated, t)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+       ON DUPLICATE KEY UPDATE shop_name = VALUES(shop_name), owner_serial = VALUES(owner_serial),
+         owner_name = VALUES(owner_name), map = VALUES(map), x = VALUES(x), y = VALUES(y),
+         z = VALUES(z), region = VALUES(region), house = VALUES(house),
+         item_count = VALUES(item_count), item_total = VALUES(item_total),
+         truncated = VALUES(truncated), t = VALUES(t),
+         -- Touched explicitly rather than left to ON UPDATE CURRENT_TIMESTAMP:
+         -- MariaDB does not fire that when every column is written back
+         -- unchanged, and a shop that is re-published identically is still
+         -- FRESHLY CONFIRMED. Without this the staleness banner would age a
+         -- perfectly current shop forever.
+         updated_at = CURRENT_TIMESTAMP`,
+      [
+        vendor.serial,
+        vendor.shopName ?? null,
+        vendor.ownerSerial ?? null,
+        vendor.ownerName ?? null,
+        vendor.map ?? null,
+        Number.isFinite(vendor.x) ? vendor.x : null,
+        Number.isFinite(vendor.y) ? vendor.y : null,
+        Number.isFinite(vendor.z) ? vendor.z : null,
+        vendor.region ?? null,
+        vendor.house ?? null,
+        items.length,
+        Number.isFinite(vendor.itemTotal) ? vendor.itemTotal : items.length,
+        vendor.truncated ? 1 : 0,
+        Number.isFinite(vendor.t) ? vendor.t : null,
+      ],
+    )
+
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [vendor.serial])
+
+    const rows = items.map((i) => [
+      vendor.serial,
+      i.serial,
+      i.itemId,
+      i.hue,
+      i.amount,
+      i.price,
+      i.name,
+      i.cliloc,
+      i.displayName,
+      i.child ? 1 : 0,
+    ])
+
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch(
+        `INSERT INTO shard_vendor_items
+           (vendor_serial, serial, item_id, hue, amount, price, name, cliloc, display_name, child)
+         VALUES (?,?,?,?,?,?,?,?,?,?)`,
+        rows.slice(i, i + BATCH),
+      )
+    }
+
+    await conn.commit()
+    return { items: rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+/** Drop one vendor and its listings (vendor.listing.remove). */
+async function removeVendor(serial) {
+  const conn = await pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [serial])
+    await conn.query('DELETE FROM shard_vendors WHERE serial = ?', [serial])
+    await conn.commit()
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+// ── Search ─────────────────────────────────────────────────────────────────
+//
+// The unit of a search RESULT is a listing, not a vendor: "who sells a vanquishing
+// kryss and for how much" is the question, and answering it per vendor would make
+// the caller flatten the shops back out. The vendor's columns ride along on the
+// join so a result row is self-contained.
+
+function searchWhere({ q, minPrice, maxPrice, itemId, map, region }) {
+  const where = ['i.price > 0']
+  const params = []
+
+  if (q) {
+    // Both the resolved display name and the item's own literal, because an item
+    // with a player-set name (most of what is actually worth searching for on a
+    // player-run shard) may have a generic cliloc.
+    where.push('(i.display_name LIKE ? OR i.name LIKE ?)')
+    params.push(likeTerm(q), likeTerm(q))
+  }
+  if (Number.isFinite(minPrice)) {
+    where.push('i.price >= ?')
+    params.push(minPrice)
+  }
+  if (Number.isFinite(maxPrice)) {
+    where.push('i.price <= ?')
+    params.push(maxPrice)
+  }
+  if (Number.isFinite(itemId)) {
+    where.push('i.item_id = ?')
+    params.push(itemId)
+  }
+  if (map) {
+    where.push('v.map = ?')
+    params.push(map)
+  }
+  if (region) {
+    where.push('v.region = ?')
+    params.push(region)
+  }
+
+  return { sql: `WHERE ${where.join(' AND ')}`, params }
+}
+
+// Whitelisted, because this interpolates into the statement. `recent` sorts by
+// the vendor's freshness, which is the only way to see what has just been listed
+// on a shard whose sweep is minutes wide.
+const SORTS = {
+  price_asc: 'i.price ASC, i.id ASC',
+  price_desc: 'i.price DESC, i.id ASC',
+  recent: 'v.updated_at DESC, i.id ASC',
+}
+
+async function searchListings({ q, minPrice, maxPrice, itemId, map, region, sort, limit, offset }) {
+  const { sql, params } = searchWhere({ q, minPrice, maxPrice, itemId, map, region })
+  const order = SORTS[sort] || SORTS.price_asc
+
+  const rows = await query(
+    `SELECT i.serial, i.item_id, i.hue, i.amount, i.price, i.name, i.cliloc, i.display_name, i.child,
+            v.serial AS vendor_serial, v.shop_name, v.owner_serial, v.owner_name,
+            v.map, v.x, v.y, v.z, v.region, v.house, v.updated_at
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}
+      ORDER BY ${order}
+      LIMIT ? OFFSET ?`,
+    [...params, limit, offset],
+  )
+
+  const counted = await query(
+    `SELECT COUNT(*) AS n
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}`,
+    params,
+  )
+
+  return { rows, total: Number(counted[0]?.n) || 0 }
+}
+
+async function getVendor(serial) {
+  const rows = await query(
+    `SELECT serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+            item_count, item_total, truncated, t, updated_at
+       FROM shard_vendors WHERE serial = ?`,
+    [serial],
+  )
+  return rows[0] || null
+}
+
+async function listVendorItems(serial, { limit, offset }) {
+  return query(
+    `SELECT serial, item_id, hue, amount, price, name, cliloc, display_name, child
+       FROM shard_vendor_items
+      WHERE vendor_serial = ?
+      ORDER BY price ASC, id ASC
+      LIMIT ? OFFSET ?`,
+    [serial, limit, offset],
+  )
+}
+
+/**
+ * What the market page's header needs: how big the index is, and how stale it may
+ * be. `staleAt` is the OLDEST vendor row — the round-robin sweep means a shop can
+ * be a full cycle behind, and the page says so rather than implying live prices.
+ */
+async function meta() {
+  const rows = await query(
+    `SELECT COUNT(*) AS vendors, MIN(updated_at) AS stale_at, MAX(updated_at) AS fresh_at
+       FROM shard_vendors`,
+  )
+  const items = await query('SELECT COUNT(*) AS n FROM shard_vendor_items')
+  return {
+    vendors: Number(rows[0]?.vendors) || 0,
+    items: Number(items[0]?.n) || 0,
+    staleAt: rows[0]?.stale_at || null,
+    freshAt: rows[0]?.fresh_at || null,
+  }
+}
+
+/** The distinct facets and regions holding vendors — drives the page's filters. */
+async function listPlaces() {
+  const maps = await query(
+    'SELECT DISTINCT map FROM shard_vendors WHERE map IS NOT NULL ORDER BY map',
+  )
+  const regions = await query(
+    'SELECT DISTINCT region FROM shard_vendors WHERE region IS NOT NULL ORDER BY region',
+  )
+  return { maps: maps.map((r) => r.map), regions: regions.map((r) => r.region) }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+/**
+ * One page of listings whose name still needs resolving, for the bulk pass that
+ * runs after a cliloc import.
+ *
+ * Keyed on `id > after` rather than OFFSET: the pass updates the very rows it is
+ * scanning, and an OFFSET walk over a table being rewritten skips rows. Every
+ * row with a cliloc is re-read, not just the unresolved ones, because an import
+ * can also CHANGE a name — a shard overlay relabelling a stock item is the whole
+ * reason overlays exist.
+ */
+async function listResolvableItems(after, limit) {
+  return query(
+    `SELECT id, cliloc, name, display_name
+       FROM shard_vendor_items
+      WHERE cliloc IS NOT NULL AND cliloc > 0 AND id > ?
+      ORDER BY id
+      LIMIT ?`,
+    [after, limit],
+  )
+}
+
+/** Write back a batch of re-resolved display names. */
+async function updateDisplayNames(pairs) {
+  if (pairs.length === 0) return 0
+  const conn = await pool.getConnection()
+  try {
+    await conn.batch('UPDATE shard_vendor_items SET display_name = ? WHERE id = ?', pairs)
+    return pairs.length
+  } finally {
+    conn.release()
+  }
+}
+
+module.exports = {
+  replaceVendor,
+  removeVendor,
+  searchListings,
+  getVendor,
+  listVendorItems,
+  meta,
+  listPlaces,
+  listResolvableItems,
+  updateDisplayNames,
+  likeTerm,
+}

server/src/model/shardMarket/shardMarket.model.js

@@ -0,0 +1,329 @@
+// ── Player-vendor market index (Protocol 3.0 vendor.listing) ───────────────
+//
+// The shard-wide shop index: what every player vendor is selling, for how much,
+// and where it is standing. This is the website's half of the search the in-game
+// Vendor Search gump offers — the same data, the same opt-out, reachable without
+// logging in to the game.
+//
+// Ingest is per-vendor and authoritative: the shard's round-robin sweep emits one
+// `vendor.listing` frame per shop whose contents, prices or location moved, and
+// the frame is the whole shop (see docs/link/v3.md §8 and BridgeMarket.cs). This
+// module normalizes it into shard_vendors + shard_vendor_items and, crucially,
+// resolves each listing's cliloc to a DISPLAY NAME on the way in — a search for
+// "kryss" is a search over names, and the shard only ever sends numbers.
+
+const db = require('./shardMarket.db')
+const clilocs = require('../shardClilocs/shardClilocs.model')
+const log = require('../../utils/logger')('shard-market')
+
+// Defense in depth on top of the shard's own MarketMaxListings cap. The shard is
+// trusted, but it is a separately-versioned component: a frame from a plugin
+// whose cap was raised (or a shard running modified scripts) must not be able to
+// turn one ingest into an unbounded transaction.
+const MAX_ITEMS_PER_VENDOR = 5000
+
+// Column widths in schema.sql. Truncating here rather than letting MariaDB do it
+// keeps the behavior the same in strict mode, where an over-length value is an
+// ERROR and would fail the whole vendor rather than shortening one name.
+const MAX_NAME = 160
+const MAX_SHOP = 160
+const MAX_OWNER = 64
+const MAX_MAP = 40
+const MAX_REGION = 80
+const MAX_SERIAL = 20
+
+const clip = (value, max) => {
+  if (value == null) return null
+  const s = String(value)
+  return s.length > max ? s.slice(0, max) : s
+}
+
+const int = (value, fallback = 0) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.trunc(n) : fallback
+}
+
+// ── Ingest ─────────────────────────────────────────────────────────────────
+
+/**
+ * Flatten one `vendor.listing` frame into the row shapes the DB layer wants.
+ *
+ * `location` arrives as a nested object rather than flat map/x/y/region, and that
+ * shape is load-bearing rather than cosmetic: the visibility projection matches
+ * literal JSON keys, so ONE `market.location` rule can hide a vendor's
+ * whereabouts only if `location` is a single key on both the live frame and the
+ * stored read model. Flattening it here for storage and re-nesting it on read is
+ * what keeps that true on both paths.
+ *
+ * Exported for tests — it is the part with rules in it, and it is pure.
+ */
+function flattenFrame(ev) {
+  const loc = (ev && ev.location) || {}
+  return {
+    serial: clip(ev.serial, MAX_SERIAL),
+    shopName: clip(ev.shopName, MAX_SHOP),
+    ownerSerial: clip(ev.ownerSerial, MAX_SERIAL),
+    ownerName: clip(ev.ownerName, MAX_OWNER),
+    map: clip(loc.map, MAX_MAP),
+    x: Number.isFinite(loc.x) ? Math.trunc(loc.x) : null,
+    y: Number.isFinite(loc.y) ? Math.trunc(loc.y) : null,
+    z: Number.isFinite(loc.z) ? Math.trunc(loc.z) : null,
+    region: clip(loc.region, MAX_REGION),
+    house: clip(loc.house, MAX_SHOP),
+    // What the SHOP holds, which is not what the frame carries when it was
+    // truncated. Kept apart so the page can say "showing 250 of 3,104" rather
+    // than presenting a partial shop as a complete one.
+    itemTotal: int(ev.total, int(ev.count, 0)),
+    truncated: ev.truncated === true,
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  }
+}
+
+/**
+ * Resolve each listing's display name.
+ *
+ * Order of preference is the item's own literal `name` first, then the cliloc.
+ * That is the opposite of what "resolve the id" suggests and it is right: a
+ * literal name only exists because a player set one ("Bob's vanquishing kryss"),
+ * and it is strictly more specific than the generic cliloc the item still
+ * carries.
+ *
+ * One batched lookup per frame rather than per item; `resolveMany` is cached and
+ * never throws, so a cliloc table that is missing entirely just leaves
+ * `displayName` null and the page renders item ids, exactly as it did before the
+ * table existed.
+ */
+async function shapeItems(ev) {
+  const raw = Array.isArray(ev.items) ? ev.items.slice(0, MAX_ITEMS_PER_VENDOR) : []
+
+  const wanted = raw
+    .map((i) => int(i && i.cliloc, 0))
+    .filter((n) => n > 0)
+
+  const names = await clilocs.resolveMany(wanted)
+
+  return raw
+    .filter((i) => i && i.serial)
+    .map((i) => {
+      const literal = clip(i.name, MAX_NAME)
+      const cliloc = int(i.cliloc, 0) || null
+      return {
+        serial: clip(i.serial, MAX_SERIAL),
+        itemId: int(i.itemId, 0),
+        hue: int(i.hue, 0),
+        amount: int(i.amount, 1),
+        price: int(i.price, 0),
+        name: literal,
+        cliloc,
+        displayName: literal || (cliloc ? clip(names.get(cliloc) ?? null, MAX_NAME) : null),
+        child: i.child === true,
+      }
+    })
+    // Unpriced rows are inventory, not listings. The shard already drops them;
+    // this is the same rule enforced where the table is written, so a plugin that
+    // stops enforcing it cannot put un-buyable rows on the market page.
+    .filter((i) => i.price > 0)
+}
+
+/** Ingest one `vendor.listing` frame. */
+async function upsertVendor(ev) {
+  if (!ev || !ev.serial) return
+  const vendor = flattenFrame(ev)
+  const items = await shapeItems(ev)
+  await db.replaceVendor(vendor, items)
+}
+
+/** Ingest one `vendor.listing.remove` frame. */
+async function removeVendor(serial) {
+  if (!serial) return
+  await db.removeVendor(String(serial).slice(0, MAX_SERIAL))
+}
+
+// ── Read models ────────────────────────────────────────────────────────────
+//
+// `location` is re-nested (see flattenFrame) so the stored read model and the
+// live wire frame present the same keys to the visibility projection.
+
+const place = (r) => ({
+  map: r.map,
+  x: r.x,
+  y: r.y,
+  z: r.z,
+  region: r.region,
+  house: r.house,
+})
+
+// A listing as the search returns it: the item, plus enough of its shop to be
+// actionable without a second request. `displayName` falls back to nothing rather
+// than to a fabricated "Item 3922" — the client decides how to render an
+// unresolved id, and inventing a name here would make it indistinguishable from
+// a real one.
+const shapeListing = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+  vendor: {
+    serial: r.vendor_serial,
+    shopName: r.shop_name,
+    ownerSerial: r.owner_serial,
+    ownerName: r.owner_name,
+    location: place(r),
+    updatedAt: r.updated_at,
+  },
+})
+
+const shapeVendor = (r) => ({
+  serial: r.serial,
+  shopName: r.shop_name,
+  ownerSerial: r.owner_serial,
+  ownerName: r.owner_name,
+  location: place(r),
+  count: r.item_count,
+  total: r.item_total,
+  truncated: !!r.truncated,
+  updatedAt: r.updated_at,
+})
+
+const shapeItem = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+})
+
+/**
+ * Search the index. Returns a page of LISTINGS (not vendors) plus the
+ * unpaginated total and the staleness stamp the page's banner needs.
+ */
+async function search({
+  q = '',
+  minPrice,
+  maxPrice,
+  itemId,
+  map = '',
+  region = '',
+  sort = 'price_asc',
+  limit = 50,
+  offset = 0,
+} = {}) {
+  const { rows, total } = await db.searchListings({
+    q: q.trim(),
+    minPrice: Number.isFinite(minPrice) ? minPrice : undefined,
+    maxPrice: Number.isFinite(maxPrice) ? maxPrice : undefined,
+    itemId: Number.isFinite(itemId) ? itemId : undefined,
+    map: map.trim(),
+    region: region.trim(),
+    sort,
+    limit,
+    offset,
+  })
+
+  const info = await db.meta()
+
+  return {
+    listings: rows.map(shapeListing),
+    total,
+    limit,
+    offset,
+    // Repeated on every search response rather than left to a separate /meta
+    // call: the banner that says how old these prices are must age with the
+    // results it labels, and a client that fetched it once would keep showing a
+    // stamp from before the page it is looking at.
+    staleAt: info.staleAt,
+    vendors: info.vendors,
+  }
+}
+
+/** One shop and its listings. `null` when the index has never seen that serial. */
+async function getVendor(serial, { limit = 250, offset = 0 } = {}) {
+  const row = await db.getVendor(serial)
+  if (!row) return null
+  const items = await db.listVendorItems(serial, { limit, offset })
+  return { ...shapeVendor(row), items: items.map(shapeItem) }
+}
+
+/** Index size, staleness, and the facet/region filter options. */
+async function meta() {
+  const [info, places] = await Promise.all([db.meta(), db.listPlaces()])
+  return { ...info, ...places }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+// Batch size for the post-import pass. Big enough that a 40k-row table is ~40
+// round trips, small enough that a single batch is not a long-held connection.
+const RESOLVE_BATCH = 1000
+
+/**
+ * Re-resolve every listing's display name against the current cliloc table.
+ *
+ * Called after a cliloc import, and it has to be: the market's diff sweep will
+ * NOT re-send an unchanged shop just because the site learned what its items are
+ * called, so without this an operator who configures clilocs after the first
+ * market sweep sees item ids until every shop happens to change. That is the same
+ * class of staleness the spawn atlas avoids by re-parsing on boot — here the
+ * source of truth for names moved, not the data.
+ *
+ * Never throws. It is a cosmetic backfill on a table that is already serving; a
+ * failure means names stay as they were, which is exactly the pre-import state.
+ */
+async function refreshDisplayNames() {
+  let after = 0
+  let scanned = 0
+  let changed = 0
+
+  try {
+    for (;;) {
+      const rows = await db.listResolvableItems(after, RESOLVE_BATCH)
+      if (rows.length === 0) break
+
+      after = rows[rows.length - 1].id
+      scanned += rows.length
+
+      const names = await clilocs.resolveMany(rows.map((r) => Number(r.cliloc)))
+
+      const pairs = []
+      for (const row of rows) {
+        // The literal name still wins, so a re-resolution never overwrites a
+        // player-set name with the generic cliloc behind it.
+        const next = row.name
+          ? clip(row.name, MAX_NAME)
+          : clip(names.get(Number(row.cliloc)) ?? null, MAX_NAME)
+        if (next !== row.display_name) pairs.push([next, row.id])
+      }
+
+      changed += await db.updateDisplayNames(pairs)
+    }
+
+    if (changed > 0) log.info('market display names refreshed', { scanned, changed })
+    return { scanned, changed }
+  } catch (err) {
+    log.warn('market display-name refresh failed', { message: err.message, scanned, changed })
+    return { scanned, changed, error: err.message }
+  }
+}
+
+module.exports = {
+  upsertVendor,
+  removeVendor,
+  search,
+  getVendor,
+  meta,
+  refreshDisplayNames,
+  flattenFrame,
+  shapeItems,
+  shapeListing,
+  shapeVendor,
+  MAX_ITEMS_PER_VENDOR,
+}

server/src/model/shardState/shardState.db.js

@@ -259,6 +259,69 @@ async function latestPresence() {
   return rows[0] || null
 }
 
+// ── Shard ruleset (Protocol 3.0 world.ruleset) ─────────────────────────────
+// Singleton, same shape as shard_presence: the shard re-emits the whole frame on
+// every connect, so there is nothing to merge — the latest one wins outright.
+async function setRuleset({ rev, expansion, payload, t }) {
+  await query(
+    `INSERT INTO shard_ruleset (id, rev, expansion, payload, t) VALUES (1, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE rev = VALUES(rev), expansion = VALUES(expansion),
+       payload = VALUES(payload), t = VALUES(t)`,
+    [rev ?? null, expansion ?? null, payload, Number.isFinite(t) ? t : null],
+  )
+}
+
+async function getRuleset() {
+  const rows = await query(
+    'SELECT rev, expansion, payload, t, updated_at FROM shard_ruleset WHERE id = 1',
+  )
+  return rows[0] || null
+}
+
+// ── Points/loyalty boards (Protocol 3.0 points.board) ──────────────────────
+// One row per point system. The shard only emits a system whose top N actually
+// moved, so this is a sparse stream of overwrites; there is no delete, because
+// the shard's set of systems is fixed at startup.
+async function upsertPointsBoard({ system, name, nameCliloc, maxPoints, players, showOnGump, payload, t }) {
+  await query(
+    `INSERT INTO shard_points_boards
+       (system, name, name_cliloc, max_points, players, show_on_gump, payload, t)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE name = VALUES(name), name_cliloc = VALUES(name_cliloc),
+       max_points = VALUES(max_points), players = VALUES(players),
+       show_on_gump = VALUES(show_on_gump), payload = VALUES(payload), t = VALUES(t)`,
+    [
+      system,
+      name ?? null,
+      Number.isFinite(nameCliloc) ? nameCliloc : null,
+      Number.isFinite(maxPoints) ? maxPoints : null,
+      Number.isFinite(players) ? players : null,
+      showOnGump ? 1 : 0,
+      payload,
+      Number.isFinite(t) ? t : null,
+    ],
+  )
+}
+
+// Ordered by display name, falling back to the system key for a board whose name
+// arrived as a bare cliloc — otherwise every unresolved board would sort together
+// under NULL.
+async function listPointsBoards() {
+  return query(
+    `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at
+       FROM shard_points_boards ORDER BY COALESCE(name, system), system`,
+  )
+}
+
+async function getPointsBoard(system) {
+  const rows = await query(
+    `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at
+       FROM shard_points_boards WHERE system = ?`,
+    [system],
+  )
+  return rows[0] || null
+}
+
 module.exports = {
   upsertOnline,
   removeOnline,
@@ -290,6 +353,11 @@ module.exports = {
   listGovernorTerms,
   setPresence,
   latestPresence,
+  setRuleset,
+  getRuleset,
+  upsertPointsBoard,
+  listPointsBoards,
+  getPointsBoard,
   upsertChamp,
   removeChamp,
   clearChamps,

server/src/model/shardState/shardState.model.js

@@ -508,6 +508,79 @@ async function latestPresence() {
   }
 }
 
+// ── Shard ruleset (Protocol 3.0 world.ruleset) ─────────────────────────────
+//
+// The whole frame is stored in `payload` and served back whole. Nothing is
+// normalized out of it: it is a flat description of config read as one page, and
+// splitting it into columns would mean a schema change every time the shard grows
+// a new block. `rev` and `expansion` are hoisted only because they are cheap to
+// index/display, following shard_champs' payload-plus-hoisted-columns pattern.
+async function setRuleset(ev) {
+  if (!ev) return
+  await db.setRuleset({
+    rev: ev.rev ?? null,
+    expansion: ev.expansion ?? null,
+    payload: JSON.stringify(ev),
+    t: ev.t,
+  })
+}
+
+// The stored ruleset, or null when the shard has never published one (an old
+// plugin, or Bridge.RulesetEnabled=false). Null is a real answer here — the page
+// says "not published yet" rather than rendering an empty ruleset as if the shard
+// had no rules — so it is deliberately not smoothed into {}.
+async function getRuleset() {
+  const r = await db.getRuleset()
+  if (!r) return null
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  if (!payload) return null
+  return { ...payload, updatedAt: r.updated_at }
+}
+
+// ── Points/loyalty boards (Protocol 3.0 points.board) ──────────────────────
+//
+// The whole frame is stored in `payload`; the columns beside it are hoisted for
+// listing and ordering only. The top-N list deliberately stays inside the payload
+// (see schema.sql) — it is a fixed-size list read whole, like the governor board's
+// candidates.
+async function upsertPointsBoard(ev) {
+  if (!ev || !ev.system) return
+  await db.upsertPointsBoard({
+    system: String(ev.system).slice(0, 48),
+    name: ev.nameString ?? null,
+    nameCliloc: ev.nameNumber,
+    maxPoints: ev.maxPoints,
+    players: ev.players,
+    showOnGump: ev.showOnGump !== false,
+    payload: JSON.stringify(ev),
+    t: ev.t,
+  })
+}
+
+// A stored frame plus the freshness stamp. `top` is normalized to an array so a
+// caller never has to guard it — a board with nobody on it is a real state (a
+// system nobody has scored in yet), distinct from a system that was never
+// published at all, which is absent from the table entirely.
+function shapePointsBoard(r) {
+  const payload = (typeof r.payload === 'string' ? safeJson(r.payload) : r.payload) || {}
+  return {
+    ...payload,
+    system: r.system,
+    top: Array.isArray(payload.top) ? payload.top : [],
+    updatedAt: r.updated_at,
+  }
+}
+
+async function listPointsBoards() {
+  const rows = await db.listPointsBoards()
+  return rows.map(shapePointsBoard)
+}
+
+async function getPointsBoard(system) {
+  const r = await db.getPointsBoard(system)
+  return r ? shapePointsBoard(r) : null
+}
+
 function safeJson(s) {
   try {
     return JSON.parse(s)
@@ -557,4 +630,9 @@ module.exports = {
   replaceGovernors,
   setPresence,
   latestPresence,
+  setRuleset,
+  getRuleset,
+  upsertPointsBoard,
+  listPointsBoards,
+  getPointsBoard,
 }

server/src/model/shardVisibility/shardVisibility.db.js

@@ -0,0 +1,37 @@
+const { query } = require('../../utils/db')
+
+// One row per shard feature. Absent rows are fine — utils/shardVisibility.js
+// compiles a default for every known feature and merges stored rows over it, so
+// a fresh install with an empty table behaves exactly as the site did pre-v3.
+
+const COLS = 'feature, enabled, audience, stream, field_rules, updated_by, updated_at'
+
+const listAll = () => query(`SELECT ${COLS} FROM shard_feature_visibility`)
+
+const getOne = (feature) =>
+  query(`SELECT ${COLS} FROM shard_feature_visibility WHERE feature = ?`, [feature])
+
+// Upsert one feature's settings. `fieldRules` is stored as a JSON object of
+// {field: rung}; the caller has already stripped locked fields and validated
+// every rung against the ladder.
+const upsert = ({ feature, enabled, audience, stream, fieldRules, updatedBy }) =>
+  query(
+    `INSERT INTO shard_feature_visibility (feature, enabled, audience, stream, field_rules, updated_by)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE
+       enabled     = VALUES(enabled),
+       audience    = VALUES(audience),
+       stream      = VALUES(stream),
+       field_rules = VALUES(field_rules),
+       updated_by  = VALUES(updated_by)`,
+    [
+      feature,
+      enabled ? 1 : 0,
+      audience,
+      stream ? 1 : 0,
+      fieldRules == null ? null : JSON.stringify(fieldRules),
+      updatedBy ?? null,
+    ],
+  )
+
+module.exports = { listAll, getOne, upsert }

server/src/model/shardVisibility/shardVisibility.model.js

@@ -0,0 +1,44 @@
+// ── Shard feature visibility (model) ───────────────────────────────────────
+//
+// Thin row-shaping layer over shardVisibility.db. The policy — the ladder, the
+// feature catalog, the locked fields, the kind→feature map — lives in
+// utils/shardVisibility.js; this file only reads and writes rows.
+
+const db = require('./shardVisibility.db')
+
+// The `field_rules` JSON column comes back as a string on the mariadb driver.
+function parseRules(raw) {
+  if (raw == null) return {}
+  if (typeof raw === 'object') return raw
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+const toSafe = (row) =>
+  row && {
+    feature: row.feature,
+    enabled: !!row.enabled,
+    audience: row.audience,
+    stream: row.stream == null ? null : !!row.stream,
+    fieldRules: parseRules(row.field_rules),
+    updatedBy: row.updated_by,
+    updatedAt: row.updated_at,
+  }
+
+async function listAll() {
+  const rows = await db.listAll()
+  return rows.map(toSafe)
+}
+
+async function getOne(feature) {
+  const rows = await db.getOne(feature)
+  return toSafe(rows[0])
+}
+
+const upsert = (entry) => db.upsert(entry)
+
+module.exports = { listAll, getOne, upsert }

server/src/model/uoLinkConfig/uoLinkConfig.model.js

@@ -7,7 +7,10 @@
 const db = require('./uoLinkConfig.db')
 const secretBox = require('../../utils/secretBox')
 
-const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 1
+// The wire protocol this build speaks (link/sidecar/src/main.rs PROTOCOL_VERSION).
+// Only used before an admin has saved anything — the stored row wins once it exists,
+// and UOLINK_PROTOCOL still overrides for an operator running an older sidecar.
+const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 3
 
 function toSafe(row) {
   if (!row) {

server/src/router/v1/admin/admin.routes.js

@@ -1,472 +0,0 @@
-// Residual /admin routes — the capabilities not yet carved into their own
-// router file (docs/website/API_V2_PLAN.md § Phase 2). Mounted at the root of
-// /api/v1/admin by admin/index.js, *after* the extracted capability routers and
-// behind the shared `noindex, isLoggedIn, staffOnly` gate it owns, so the URLs
-// here are unchanged from when this file held all 110 admin routes.
-//
-// Already extracted: users, account, invites, auth/providers, moderation,
-// bot-activity, activity, posts, uploads, wiki, pages.
-// Still here: shard, dashboard, site-mode, settings, discord-bot, email,
-// uo-link.
-// This file disappears when the last group moves.
-
-const express = require('express')
-const { body, param } = require('express-validator')
-
-const ctrl = require('./admin.controller')
-const discordBot = require('./discordBot.controller')
-const emailConfig = require('./emailConfig.controller')
-const uoLink = require('./uoLink.controller')
-const shardOps = require('./shardOps.controller')
-const selfShard = require('../player/shard.controller')
-const { requireRole } = require('../../../utils/auth')
-const validate = require('../../../middleware/validate')
-
-const adminRouter = express.Router()
-
-// Admin-only gate. Editors may manage content (posts/wiki), but user
-// management, site mode, and settings are restricted to the admin role.
-const adminOnly = requireRole('admin')
-
-// Moderator gate. Admins can do everything a moderator can. Since the moderation
-// dashboard moved to moderation.router.js this guards only the in-game staff
-// operations below (/shard/*), which stay here until PR 4.
-const modAccess = requireRole('admin', 'moderator')
-
-// ── Game account linking (self-service, any staff role) ───────────────
-// Staff link their OWN in-game account here, exactly like players do under
-// /player/shard. The controller keys off req.user.id, so the same handlers work.
-const SHARD_ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
-adminRouter.post(
-  '/shard/link',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Link an in-game account with a one-time code (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */
-  /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  body('code').isString().trim().isLength({ min: 4, max: 32 }),
-  validate,
-  selfShard.link,
-)
-adminRouter.get(
-  '/shard/accounts',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'List the caller’s linked game accounts (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
-  selfShard.listAccounts,
-)
-adminRouter.get(
-  '/shard/roster/:account',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Character roster for an account (self; admins: any account)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
-  /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('account').matches(SHARD_ACCOUNT_RE),
-  validate,
-  selfShard.roster,
-)
-adminRouter.get(
-  '/shard/vendors/:account',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Player vendors for an account (self; admins: any account)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
-  /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('account').matches(SHARD_ACCOUNT_RE),
-  validate,
-  selfShard.vendors,
-)
-adminRouter.get(
-  '/shard/char/:serial',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Character sheet (self-linked characters; admins: any character)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' }
-  /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('serial').matches(/^0x[0-9a-fA-F]+$/),
-  validate,
-  selfShard.getChar,
-)
-adminRouter.get(
-  '/shard/sales',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
-  selfShard.getSales,
-)
-adminRouter.post(
-  '/shard/account',
-  // #swagger.tags = ['Admin · Account']
-  // #swagger.summary = 'Create a game account and link it to the caller (staff self-service)'
-  // #swagger.description = 'Same as POST /player/shard/account but for a signed-in staff user — provisions a game account (own username + password) and links it. Gated by game_account_signup + the shard’s mode; the password is never stored or logged.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */
-  /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/),
-  body('password').isString().isLength({ min: 8, max: 64 }),
-  validate,
-  selfShard.createGameAccount,
-)
-
-// ── In-game staff operations (uo-link write plane + support queue) ─────
-// Privileged live-shard actions and the help-page queue, open to moderators as
-// well as admins (modAccess). `actor` is stamped server-side from the session in
-// the controller — the body never carries it. See shardOps.controller.js.
-adminRouter.post(
-  '/shard/kick',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Kick every live session of an account (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Kicked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  modAccess,
-  body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE),
-  body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/),
-  validate,
-  shardOps.kick,
-)
-adminRouter.post(
-  '/shard/ban',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Ban an account, timed or indefinite (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" }, durationSec: { type: "integer" }, reason: { type: "string" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Banned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  modAccess,
-  body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE),
-  body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/),
-  body('durationSec').optional().isInt({ min: 0, max: 315360000 }),
-  body('reason').optional({ values: 'falsy' }).isString().trim().isLength({ max: 500 }),
-  validate,
-  shardOps.ban,
-)
-adminRouter.post(
-  '/shard/unban',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Clear an account ban (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" } }, required: ["account"] } } } } */
-  /* #swagger.responses[200] = { description: 'Unbanned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  modAccess,
-  body('account').matches(SHARD_ACCOUNT_RE),
-  validate,
-  shardOps.unban,
-)
-adminRouter.post(
-  '/shard/broadcast',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Broadcast a system message to everyone online (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { text: { type: "string" }, hue: { type: "integer" } }, required: ["text"] } } } } */
-  /* #swagger.responses[200] = { description: 'Broadcast', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  modAccess,
-  body('text').isString().trim().isLength({ min: 1, max: 300 }),
-  body('hue').optional().isInt({ min: 0, max: 3000 }),
-  validate,
-  shardOps.broadcast,
-)
-adminRouter.get(
-  '/shard/pages',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Open help-page (support) queue (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Open pages', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
-  modAccess,
-  shardOps.listPages,
-)
-adminRouter.post(
-  '/shard/pages/:id/respond',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Reply to a help page, optionally closing it (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' }
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { message: { type: "string" }, close: { type: "boolean" } }, required: ["message"] } } } } */
-  /* #swagger.responses[200] = { description: 'Responded', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[404] = { description: 'Unknown page', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  modAccess,
-  param('id').matches(/^0x[0-9a-fA-F]+$/),
-  body('message').isString().trim().isLength({ min: 1, max: 500 }),
-  body('close').optional().isBoolean(),
-  validate,
-  shardOps.respondPage,
-)
-adminRouter.post(
-  '/shard/pages/:id/close',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Resolve a help page without a reply (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' }
-  /* #swagger.responses[200] = { description: 'Closed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  modAccess,
-  param('id').matches(/^0x[0-9a-fA-F]+$/),
-  validate,
-  shardOps.closePage,
-)
-adminRouter.get(
-  '/shard/audit',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Recent in-game moderation audit events (admin/moderator)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'admin.audit events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */
-  modAccess,
-  shardOps.listAudit,
-)
-adminRouter.get(
-  '/shard/houses',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Full house registry — owner, price, decay (admin/moderator)'
-  // #swagger.description = 'The complete house registry. The public endpoint shows only IDOC houses with location; this staff view carries owner/price/co-owner/decay detail.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
-  modAccess,
-  shardOps.listHouses,
-)
-
-// ── Dashboard & site mode ─────────────────────────────────────────────
-adminRouter.get(
-  '/dashboard',
-  // #swagger.tags = ['Admin · Dashboard']
-  // #swagger.summary = 'Dashboard summary counts'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Summary: site mode, last change, post/user counts and recent activity', content: { "application/json": { schema: { type: "object", properties: { site_mode: { type: "string", example: "live" }, last_change: { type: "object", properties: { at: { type: "string", nullable: true }, by: { type: "string", nullable: true } } }, counts: { type: "object", properties: { posts: { type: "object", additionalProperties: true }, users: { type: "integer" } } }, recent_activity: { type: "array", items: { type: "object", additionalProperties: true } } } } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ctrl.dashboard,
-)
-adminRouter.put(
-  '/site-mode',
-  // #swagger.tags = ['Admin · Dashboard']
-  // #swagger.summary = 'Set site mode (admin only)'
-  // #swagger.description = 'Switch the site between live and maintenance.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SiteModeRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Updated site mode', content: { "application/json": { schema: { $ref: "#/components/schemas/SiteModeState" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('mode').isIn(['live', 'maintenance']),
-  validate,
-  ctrl.setSiteMode,
-)
-
-// ── Settings ──────────────────────────────────────────────────────────
-adminRouter.get(
-  '/settings',
-  // #swagger.tags = ['Admin · Settings']
-  // #swagger.summary = 'Get all site settings (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'All settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  ctrl.getSettings,
-)
-adminRouter.put(
-  '/settings',
-  // #swagger.tags = ['Admin · Settings']
-  // #swagger.summary = 'Update site settings (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", additionalProperties: true, description: "An object of key/value settings." } } } } */
-  /* #swagger.responses[200] = { description: 'Updated settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[400] = { description: 'Body must be an object of key/value settings', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  ctrl.updateSettings,
-)
-
-// ── Discord bot control (admin only) ──────────────────────────────────
-// Phase 1: entering/enabling the bot token here — never an env var. The token
-// is write-only over this API (SECURITY note in discordBot.controller.js).
-adminRouter.get(
-  '/discord-bot/config',
-  // #swagger.tags = ['Admin · Discord Bot']
-  // #swagger.summary = 'Get Discord bot config + live status (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Masked config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  discordBot.getConfig,
-)
-adminRouter.put(
-  '/discord-bot/config',
-  // #swagger.tags = ['Admin · Discord Bot']
-  // #swagger.summary = 'Save Discord bot config (admin only)'
-  // #swagger.description = 'token is write-only — omit/blank it to keep the existing one unchanged.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { guildId: { type: "string" }, token: { type: "string" }, enabled: { type: "boolean" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Updated config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error, invalid token, or missing token while enabling', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('guildId').optional({ values: 'falsy' }).isString().trim(),
-  body('token').optional({ values: 'falsy' }).isString().trim(),
-  body('enabled').optional().isBoolean(),
-  validate,
-  discordBot.saveConfig,
-)
-
-// ── Email delivery (Gmail OAuth2, admin only) ─────────────────────────
-// Modern replacement for env SMTP: the refresh token is captured by the connect
-// flow and is write-only over this API (stored encrypted, never returned).
-adminRouter.get(
-  '/email/config',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'Get email delivery config + status (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Config (refresh token stripped) + status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  emailConfig.getConfig,
-)
-adminRouter.put(
-  '/email/config',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'Update email delivery config (admin only)'
-  // #swagger.description = 'Set the From display name and enabled toggle. Enabling requires a connected Gmail account.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { content: { "application/json": { schema: { type: "object", properties: { senderName: { type: "string" }, enabled: { type: "boolean" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Updated config', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[400] = { description: 'Cannot enable before connecting a mailbox', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('senderName').optional({ values: 'null' }).isString().trim().isLength({ max: 120 }),
-  body('enabled').optional().isBoolean(),
-  validate,
-  emailConfig.saveConfig,
-)
-adminRouter.get(
-  '/email/connect/start',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'Begin the Gmail OAuth2 connect flow (admin only)'
-  // #swagger.description = 'Returns { url } to redirect the browser to Google. Reuses the google SSO OAuth client.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Authorization URL', content: { "application/json": { schema: { type: "object", properties: { url: { type: "string" } } } } } } */
-  /* #swagger.responses[400] = { description: 'Google OAuth client not configured', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  emailConfig.connectStart,
-)
-adminRouter.get(
-  '/email/connect/callback',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'OAuth2 callback — stores the refresh token, redirects to Settings'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[302] = { description: 'Redirect back to /admin/settings' } */
-  adminOnly,
-  emailConfig.connectCallback,
-)
-adminRouter.post(
-  '/email/test',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'Send a test email (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { content: { "application/json": { schema: { type: "object", properties: { to: { type: "string", format: "email" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Sent', content: { "application/json": { schema: { type: "object", properties: { sent: { type: "boolean" }, to: { type: "string" } } } } } } */
-  /* #swagger.responses[502] = { description: 'Send failed / not configured', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('to').optional({ values: 'falsy' }).isEmail().isLength({ max: 255 }),
-  validate,
-  emailConfig.testSend,
-)
-adminRouter.post(
-  '/email/disconnect',
-  // #swagger.tags = ['Admin · Email']
-  // #swagger.summary = 'Disconnect Gmail and disable email (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Disconnected config', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  emailConfig.disconnect,
-)
-
-
-// ── uo-link sidecar control (admin only) ──────────────────────────────────
-// Connection config (base/ws URL + token + protocol + enabled) and the town
-// crier. The token is write-only (SECURITY note in uoLink.controller.js).
-adminRouter.get(
-  '/uo-link/config',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Get uo-link config + live status + ingestion stats (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Masked config, health and ingestion stats', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  uoLink.getConfig,
-)
-adminRouter.put(
-  '/uo-link/config',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Save uo-link connection config (admin only)'
-  // #swagger.description = 'token is write-only — omit/blank it to keep the existing one. Saving (re)starts the WS ingest client.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { baseUrl: { type: "string" }, wsUrl: { type: "string" }, token: { type: "string" }, protocol: { type: "integer" }, enabled: { type: "boolean" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Updated config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error, or missing token while enabling', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('baseUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['http', 'https'] }),
-  body('wsUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['ws', 'wss'] }),
-  body('token').optional({ values: 'falsy' }).isString().trim(),
-  body('protocol').optional().isInt({ min: 1, max: 99 }),
-  body('enabled').optional().isBoolean(),
-  validate,
-  uoLink.saveConfig,
-)
-adminRouter.post(
-  '/uo-link/towncrier',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Publish / replace a town-crier message (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TownCrierRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Posted', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[400] = { description: 'Rejected (over caps)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  body('id').isString().trim().isLength({ min: 1, max: 64 }),
-  body('lines').isArray({ min: 1, max: 8 }),
-  body('lines.*').isString().isLength({ max: 200 }),
-  body('durationSec').optional().isInt({ min: 1, max: 86400 }),
-  validate,
-  uoLink.postTownCrier,
-)
-adminRouter.delete(
-  '/uo-link/towncrier/:id',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Remove a town-crier message (admin only)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Town-crier message id.' }
-  /* #swagger.responses[200] = { description: 'Removed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[404] = { description: 'Unknown id', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  adminOnly,
-  param('id').isString().trim().isLength({ min: 1, max: 64 }),
-  validate,
-  uoLink.deleteTownCrier,
-)
-adminRouter.get(
-  '/uo-link/stream',
-  // #swagger.tags = ['Admin · Shard']
-  // #swagger.summary = 'Full live shard event stream incl. audit/cheat (SSE, admin only)'
-  /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
-  adminOnly,
-  uoLink.stream,
-)
-
-module.exports = adminRouter

server/src/router/v1/admin/botActivity.controller.js

@@ -1,7 +1,7 @@
 // Bot-scoring / IP-ban visibility for admins. Read-only view of the botScore
 // middleware's in-memory state plus a recent-events feed, and a single mutating
 // action — an emergency unban for false positives. Mounted behind the admin-only
-// RBAC gate (see admin.routes.js). This is visibility + emergency unban only;
+// RBAC gate (see botActivity.router.js). This is visibility + emergency unban only;
 // there is deliberately no way to add a ban or change scoring weights from here.
 
 const botScore = require('../../../middleware/botScore')

server/src/router/v1/admin/dashboard.router.js

@@ -0,0 +1,58 @@
+// Admin · Dashboard — the landing summary, plus the /site-mode singleton.
+//
+// Mounted at the ROOT of /api/v1/admin by admin/index.js (not at a prefix),
+// which already applied `noindex, isLoggedIn, staffOnly`. Two singleton URLs
+// that share a swagger tag and a screen but not a path segment live together
+// here rather than in two one-route files, which is what the target tree in
+// docs/website/API_V2_PLAN.md § Phase 2 calls for.
+//
+// A root mount is the one place the split's "always mount at a prefix" rule is
+// relaxed, and it is safe ONLY because this file declares no router-level
+// middleware: a bare `use(gate)` here would run for every request passing
+// through toward another mount and 403 an editor on an unrelated route. Keep
+// gates per-route in this file.
+//
+//   GET /dashboard — stats overview, any staff role.
+//   PUT /site-mode — live ↔ maintenance, admin only.
+//
+// Neither is the audit log (/activity) nor the bot-scoring state
+// (/bot-activity); those are separate capabilities that read alike. Handlers
+// still live in admin.controller.js; this re-wires routes, not logic.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const ctrl = require('./admin.controller')
+const { requireRole } = require('../../../utils/auth')
+const validate = require('../../../middleware/validate')
+
+const dashboardRouter = express.Router()
+const adminOnly = requireRole('admin')
+
+dashboardRouter.get(
+  '/dashboard',
+  // #swagger.tags = ['Admin · Dashboard']
+  // #swagger.summary = 'Dashboard summary counts'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Summary: site mode, last change, post/user counts and recent activity', content: { "application/json": { schema: { type: "object", properties: { site_mode: { type: "string", example: "live" }, last_change: { type: "object", properties: { at: { type: "string", nullable: true }, by: { type: "string", nullable: true } } }, counts: { type: "object", properties: { posts: { type: "object", additionalProperties: true }, users: { type: "integer" } } }, recent_activity: { type: "array", items: { type: "object", additionalProperties: true } } } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.dashboard,
+)
+dashboardRouter.put(
+  '/site-mode',
+  // #swagger.tags = ['Admin · Dashboard']
+  // #swagger.summary = 'Set site mode (admin only)'
+  // #swagger.description = 'Switch the site between live and maintenance.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SiteModeRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated site mode', content: { "application/json": { schema: { $ref: "#/components/schemas/SiteModeState" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('mode').isIn(['live', 'maintenance']),
+  validate,
+  ctrl.setSiteMode,
+)
+
+module.exports = dashboardRouter

server/src/router/v1/admin/discordBot.router.js

@@ -0,0 +1,51 @@
+// Admin · Discord Bot — control plane for the bot process.
+//
+// Mounted at /api/v1/admin/discord-bot by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. The bot token is entered and enabled here,
+// never through an env var, and is write-only over this API (SECURITY note in
+// discordBot.controller.js).
+//
+// Admin-only, and kept as a per-route gate rather than a router-level `use` so
+// the middleware chain each route carries is unchanged by the move.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const discordBot = require('./discordBot.controller')
+const { requireRole } = require('../../../utils/auth')
+const validate = require('../../../middleware/validate')
+
+const discordBotRouter = express.Router()
+const adminOnly = requireRole('admin')
+
+discordBotRouter.get(
+  '/config',
+  // #swagger.tags = ['Admin · Discord Bot']
+  // #swagger.summary = 'Get Discord bot config + live status (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Masked config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  discordBot.getConfig,
+)
+discordBotRouter.put(
+  '/config',
+  // #swagger.tags = ['Admin · Discord Bot']
+  // #swagger.summary = 'Save Discord bot config (admin only)'
+  // #swagger.description = 'token is write-only — omit/blank it to keep the existing one unchanged.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { guildId: { type: "string" }, token: { type: "string" }, enabled: { type: "boolean" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Updated config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error, invalid token, or missing token while enabling', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('guildId').optional({ values: 'falsy' }).isString().trim(),
+  body('token').optional({ values: 'falsy' }).isString().trim(),
+  body('enabled').optional().isBoolean(),
+  validate,
+  discordBot.saveConfig,
+)
+
+module.exports = discordBotRouter

server/src/router/v1/admin/email.router.js

@@ -0,0 +1,96 @@
+// Admin · Email — outbound mail delivery via Gmail OAuth2.
+//
+// Mounted at /api/v1/admin/email by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. The modern replacement for env SMTP: the
+// refresh token is captured by the connect flow below and is write-only over
+// this API (stored encrypted by utils/secretBox.js, never returned).
+//
+// Admin-only, and kept as a per-route gate rather than a router-level `use` so
+// the middleware chain each route carries is unchanged by the move.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const emailConfig = require('./emailConfig.controller')
+const { requireRole } = require('../../../utils/auth')
+const validate = require('../../../middleware/validate')
+
+const emailRouter = express.Router()
+const adminOnly = requireRole('admin')
+
+emailRouter.get(
+  '/config',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'Get email delivery config + status (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Config (refresh token stripped) + status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  emailConfig.getConfig,
+)
+emailRouter.put(
+  '/config',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'Update email delivery config (admin only)'
+  // #swagger.description = 'Set the From display name and enabled toggle. Enabling requires a connected Gmail account.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { content: { "application/json": { schema: { type: "object", properties: { senderName: { type: "string" }, enabled: { type: "boolean" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Updated config', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Cannot enable before connecting a mailbox', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('senderName').optional({ values: 'null' }).isString().trim().isLength({ max: 120 }),
+  body('enabled').optional().isBoolean(),
+  validate,
+  emailConfig.saveConfig,
+)
+emailRouter.get(
+  '/connect/start',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'Begin the Gmail OAuth2 connect flow (admin only)'
+  // #swagger.description = 'Returns { url } to redirect the browser to Google. Reuses the google SSO OAuth client.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Authorization URL', content: { "application/json": { schema: { type: "object", properties: { url: { type: "string" } } } } } } */
+  /* #swagger.responses[400] = { description: 'Google OAuth client not configured', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  emailConfig.connectStart,
+)
+emailRouter.get(
+  '/connect/callback',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'OAuth2 callback — stores the refresh token, redirects to Settings'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[302] = { description: 'Redirect back to /admin/settings' } */
+  adminOnly,
+  emailConfig.connectCallback,
+)
+emailRouter.post(
+  '/test',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'Send a test email (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { content: { "application/json": { schema: { type: "object", properties: { to: { type: "string", format: "email" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Sent', content: { "application/json": { schema: { type: "object", properties: { sent: { type: "boolean" }, to: { type: "string" } } } } } } */
+  /* #swagger.responses[502] = { description: 'Send failed / not configured', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('to').optional({ values: 'falsy' }).isEmail().isLength({ max: 255 }),
+  validate,
+  emailConfig.testSend,
+)
+emailRouter.post(
+  '/disconnect',
+  // #swagger.tags = ['Admin · Email']
+  // #swagger.summary = 'Disconnect Gmail and disable email (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Disconnected config', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  emailConfig.disconnect,
+)
+
+module.exports = emailRouter

server/src/router/v1/admin/index.js

@@ -6,7 +6,10 @@
 // emitted URL set is byte-identical — proved per PR by a zero-line diff in
 // server/routes.manifest.json (`npm run routes:manifest`).
 //
-// See docs/website/API_V2_PLAN.md § Phase 2 for the split and its remaining PRs.
+// The admin group is fully split as of PR 4: admin.routes.js is gone and every
+// one of the 110 admin routes is declared in a capability router below.
+//
+// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
 
 const express = require('express')
 
@@ -24,7 +27,12 @@ const postsRouter = require('./posts.router')
 const uploadsRouter = require('./uploads.router')
 const wikiRouter = require('./wiki.router')
 const pagesRouter = require('./pages.router')
-const residualRouter = require('./admin.routes')
+const shardRouter = require('./shard.router')
+const uoLinkRouter = require('./uoLink.router')
+const emailRouter = require('./email.router')
+const discordBotRouter = require('./discordBot.router')
+const settingsRouter = require('./settings.router')
+const dashboardRouter = require('./dashboard.router')
 
 const adminRouter = express.Router()
 
@@ -56,9 +64,20 @@ adminRouter.use('/posts', postsRouter)
 adminRouter.use('/uploads', uploadsRouter)
 adminRouter.use('/wiki', wikiRouter)
 adminRouter.use('/pages', pagesRouter)
+// Ops and configuration. /shard mixes tiers on one prefix — self-service game
+// account linking (no extra gate) alongside modAccess in-game staff ops — so
+// one router owns the prefix and gates per route. The rest are admin-only.
+// /admin/shard/pages is the in-game help-page queue, unrelated to /admin/pages.
+adminRouter.use('/shard', shardRouter)
+adminRouter.use('/uo-link', uoLinkRouter)
+adminRouter.use('/email', emailRouter)
+adminRouter.use('/discord-bot', discordBotRouter)
+adminRouter.use('/settings', settingsRouter)
 
-// Everything not yet extracted, at the group root. Mounted last, but none of the
-// prefixes above appear in it, so nothing here depends on the ordering.
-adminRouter.use('/', residualRouter)
+// The two singletons that own no path segment of their own: GET /dashboard and
+// PUT /site-mode. Mounted at the group root, last, exactly where the residual
+// admin.routes.js used to sit — safe because dashboard.router.js declares no
+// router-level middleware, only its two routes.
+adminRouter.use('/', dashboardRouter)
 
 module.exports = adminRouter

server/src/router/v1/admin/moderation.controller.js

@@ -1,6 +1,6 @@
 // Admin moderation dashboard (Phase 6). Read-only views over the bot's
 // mod_actions log plus server-owned staff notes. Mounted behind the
-// admin+moderator RBAC gate (see admin.routes.js). The only mutation here is
+// admin+moderator RBAC gate (see moderation.router.js). The only mutation here is
 // adding a staff note; admin_only notes are further restricted to the admin role.
 const moderation = require('../../../model/moderation/moderation.model')
 const modNotes = require('../../../model/modNotes/modNotes.model')

server/src/router/v1/admin/settings.router.js

@@ -0,0 +1,45 @@
+// Admin · Settings — the site-wide key/value settings store.
+//
+// Mounted at /api/v1/admin/settings by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. Editors may manage content, but settings
+// are admin-only: this store gates registration, game-account signup, the
+// contact form and the rest of the site's behaviour switches.
+//
+// Admin-only, and kept as a per-route gate rather than a router-level `use` so
+// the middleware chain each route carries is unchanged by the move. Handlers
+// still live in admin.controller.js; this re-wires routes, not logic.
+
+const express = require('express')
+
+const ctrl = require('./admin.controller')
+const { requireRole } = require('../../../utils/auth')
+
+const settingsRouter = express.Router()
+const adminOnly = requireRole('admin')
+
+settingsRouter.get(
+  '/',
+  // #swagger.tags = ['Admin · Settings']
+  // #swagger.summary = 'Get all site settings (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'All settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  ctrl.getSettings,
+)
+settingsRouter.put(
+  '/',
+  // #swagger.tags = ['Admin · Settings']
+  // #swagger.summary = 'Update site settings (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", additionalProperties: true, description: "An object of key/value settings." } } } } */
+  /* #swagger.responses[200] = { description: 'Updated settings', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Body must be an object of key/value settings', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  ctrl.updateSettings,
+)
+
+module.exports = settingsRouter

server/src/router/v1/admin/shard.router.js

@@ -0,0 +1,386 @@
+// Admin · Shard — everything under /api/v1/admin/shard, in two tiers.
+//
+// Mounted at /api/v1/admin/shard by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. Two capabilities share this prefix, and
+// prefix ownership is the invariant the split preserves — so they share a file:
+//
+//   1. Self-service game-account linking (no extra gate). A staff member links
+//      and inspects their OWN in-game account exactly as a player does under
+//      /player/shard; the handlers are the very same `player/shard.controller`
+//      ones, keyed off req.user.id. These keep their `Admin · Account` swagger
+//      tag, which is why the tag disagrees with this filename.
+//   2. Privileged live-shard operations and the help-page queue (`modAccess` —
+//      admin or moderator). `actor` is stamped server-side from the session in
+//      shardOps.controller.js; the request body never carries it.
+//
+// `modAccess` stays a per-route gate rather than a router-level `use`: it was
+// per-route in admin.routes.js, and half the routes here must NOT have it.
+//
+// NOTE: /admin/shard/pages is the in-game help-page (support) queue. It is
+// unrelated to /admin/pages, the CMS page builder.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const shardOps = require('./shardOps.controller')
+const shardVisibility = require('./shardVisibility.controller')
+const shardAtlas = require('./shardAtlas.controller')
+const shardClilocs = require('./shardClilocs.controller')
+const selfShard = require('../player/shard.controller')
+const { requireRole } = require('../../../utils/auth')
+const validate = require('../../../middleware/validate')
+
+const shardRouter = express.Router()
+
+// Moderator gate. Admins can do everything a moderator can.
+const modAccess = requireRole('admin', 'moderator')
+// Admin-only gate, for settings that decide what the PUBLIC sees.
+const adminOnly = requireRole('admin')
+
+// ── Game account linking (self-service, any staff role) ───────────────
+// Staff link their OWN in-game account here, exactly like players do under
+// /player/shard. The controller keys off req.user.id, so the same handlers work.
+const SHARD_ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
+shardRouter.post(
+  '/link',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Link an in-game account with a one-time code (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */
+  /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('code').isString().trim().isLength({ min: 4, max: 32 }),
+  validate,
+  selfShard.link,
+)
+shardRouter.get(
+  '/accounts',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'List the caller’s linked game accounts (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
+  selfShard.listAccounts,
+)
+shardRouter.get(
+  '/roster/:account',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Character roster for an account (self; admins: any account)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(SHARD_ACCOUNT_RE),
+  validate,
+  selfShard.roster,
+)
+shardRouter.get(
+  '/vendors/:account',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Player vendors for an account (self; admins: any account)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(SHARD_ACCOUNT_RE),
+  validate,
+  selfShard.vendors,
+)
+shardRouter.get(
+  '/char/:serial',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Character sheet (self-linked characters; admins: any character)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' }
+  /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('serial').matches(/^0x[0-9a-fA-F]+$/),
+  validate,
+  selfShard.getChar,
+)
+shardRouter.get(
+  '/sales',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
+  selfShard.getSales,
+)
+shardRouter.post(
+  '/account',
+  // #swagger.tags = ['Admin · Account']
+  // #swagger.summary = 'Create a game account and link it to the caller (staff self-service)'
+  // #swagger.description = 'Same as POST /player/shard/account but for a signed-in staff user — provisions a game account (own username + password) and links it. Gated by game_account_signup + the shard’s mode; the password is never stored or logged.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */
+  /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/),
+  body('password').isString().isLength({ min: 8, max: 64 }),
+  validate,
+  selfShard.createGameAccount,
+)
+
+// ── In-game staff operations (uo-link write plane + support queue) ─────
+// Privileged live-shard actions and the help-page queue, open to moderators as
+// well as admins (modAccess). `actor` is stamped server-side from the session in
+// the controller — the body never carries it. See shardOps.controller.js.
+shardRouter.post(
+  '/kick',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Kick every live session of an account (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Kicked', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  modAccess,
+  body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE),
+  body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/),
+  validate,
+  shardOps.kick,
+)
+shardRouter.post(
+  '/ban',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Ban an account, timed or indefinite (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, serial: { type: "string" }, durationSec: { type: "integer" }, reason: { type: "string" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Banned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Protected target or write plane disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  modAccess,
+  body('account').optional({ values: 'falsy' }).matches(SHARD_ACCOUNT_RE),
+  body('serial').optional({ values: 'falsy' }).matches(/^0x[0-9a-fA-F]+$/),
+  body('durationSec').optional().isInt({ min: 0, max: 315360000 }),
+  body('reason').optional({ values: 'falsy' }).isString().trim().isLength({ max: 500 }),
+  validate,
+  shardOps.ban,
+)
+shardRouter.post(
+  '/unban',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Clear an account ban (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" } }, required: ["account"] } } } } */
+  /* #swagger.responses[200] = { description: 'Unbanned', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  modAccess,
+  body('account').matches(SHARD_ACCOUNT_RE),
+  validate,
+  shardOps.unban,
+)
+shardRouter.post(
+  '/broadcast',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Broadcast a system message to everyone online (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { text: { type: "string" }, hue: { type: "integer" } }, required: ["text"] } } } } */
+  /* #swagger.responses[200] = { description: 'Broadcast', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  modAccess,
+  body('text').isString().trim().isLength({ min: 1, max: 300 }),
+  body('hue').optional().isInt({ min: 0, max: 3000 }),
+  validate,
+  shardOps.broadcast,
+)
+shardRouter.get(
+  '/pages',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Open help-page (support) queue (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Open pages', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  modAccess,
+  shardOps.listPages,
+)
+shardRouter.post(
+  '/pages/:id/respond',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Reply to a help page, optionally closing it (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' }
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { message: { type: "string" }, close: { type: "boolean" } }, required: ["message"] } } } } */
+  /* #swagger.responses[200] = { description: 'Responded', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown page', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  modAccess,
+  param('id').matches(/^0x[0-9a-fA-F]+$/),
+  body('message').isString().trim().isLength({ min: 1, max: 500 }),
+  body('close').optional().isBoolean(),
+  validate,
+  shardOps.respondPage,
+)
+shardRouter.post(
+  '/pages/:id/close',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Resolve a help page without a reply (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page id (sender serial).' }
+  /* #swagger.responses[200] = { description: 'Closed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  modAccess,
+  param('id').matches(/^0x[0-9a-fA-F]+$/),
+  validate,
+  shardOps.closePage,
+)
+shardRouter.get(
+  '/audit',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Recent in-game moderation audit events (admin/moderator)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'admin.audit events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */
+  modAccess,
+  shardOps.listAudit,
+)
+shardRouter.get(
+  '/houses',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Full house registry — owner, price, decay (admin/moderator)'
+  // #swagger.description = 'The complete house registry. The public endpoint shows only IDOC houses with location; this staff view carries owner/price/co-owner/decay detail.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
+  modAccess,
+  shardOps.listHouses,
+)
+
+// ── Spawn atlas (admin only) ──────────────────────────────────────────
+// Operating the atlas import. Admin-only rather than moderator: it reads a path
+// on the server's filesystem and replaces every atlas table, which is closer to
+// a deploy action than to moderation.
+//
+// These routes sit under /admin/shard even though the public ones deliberately
+// do NOT sit under /public/shard. That is not an inconsistency: the public split
+// says "this data does not come from the sidecar", while the admin panel is
+// simply part of shard administration and belongs beside the rest of it.
+shardRouter.get(
+  '/atlas',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Spawn atlas status: path, drift, counts, pending review (admin only)'
+  // #swagger.description = 'Where the ServUO tree is, whether it can be read, whether its source files have drifted from the loaded atlas, and any refresh staged for approval. The public /atlas/meta route reports the game world only; the filesystem detail is here.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Atlas status', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasStatus" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  shardAtlas.getStatus,
+)
+shardRouter.post(
+  '/atlas/import',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Re-import the spawn atlas from the ServUO tree (admin only)'
+  // #swagger.description = 'Applies a map change without a restart. `force` reimports even when the source hashes match what is loaded. A refresh that would REMOVE a facet is still staged for approval rather than applied — that decision is never taken implicitly. An unreadable tree answers 200 with status "unavailable" rather than 500: the refresh contract reports outcomes instead of throwing, and the admin needs to be told what is wrong with the path.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { type: "object", properties: { force: { type: "boolean", description: "Reimport even if the tree is unchanged." } } } } } } */
+  /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */
+  adminOnly,
+  body('force').optional().isBoolean(),
+  validate,
+  shardAtlas.importAtlas,
+)
+shardRouter.post(
+  '/atlas/approve',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Approve a staged atlas refresh that removes a facet (admin only)'
+  // #swagger.description = 'Re-parses the tree and applies it, facet loss included. Only the decision was stored, never the parsed world, so what lands matches the tree at approval time — an operator who has since fixed a half-copied mount gets the corrected import.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */
+  adminOnly,
+  shardAtlas.approve,
+)
+shardRouter.post(
+  '/atlas/reject',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Reject a staged atlas refresh (admin only)'
+  // #swagger.description = 'Keeps the current atlas and remembers the decision against those exact source hashes, so a declined refresh does not re-prompt on every restart. Changing the tree asks again.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Rejected', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasRefreshResult" } } } } */
+  /* #swagger.responses[404] = { description: 'Nothing is awaiting review', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  shardAtlas.reject,
+)
+shardRouter.put(
+  '/atlas/path',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Set the ServUO tree the atlas reads from (admin only)'
+  // #swagger.description = 'Persisted as a setting, which wins over the SERVUO_PATH deploy default so the mount can move without a redeploy. Blank clears it and the atlas is simply skipped on the next boot. Deliberately does not import as a side effect — the response carries the refreshed status so the panel can offer that as the next step.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["path"], properties: { path: { type: "string", description: "Absolute path to the ServUO server root. Blank disables the atlas." } } } } } } */
+  /* #swagger.responses[200] = { description: 'Atlas status after the change', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasStatus" } } } } */
+  adminOnly,
+  body('path').isString().isLength({ max: 512 }),
+  validate,
+  shardAtlas.setPath,
+)
+
+// ── Cliloc table (admin only) ─────────────────────────────────────────────
+// UO's id → display-string map, converted once by the operator from their own
+// client (docs/website/CLILOCS.md). Sits beside the atlas for the same reason:
+// it is static content derived from operator-supplied files rather than anything
+// the sidecar sends, and operating it is shard administration.
+//
+// There is deliberately NO public counterpart. The table is never served as a
+// table — 123k rows would dwarf any page that used it, and the Android client
+// consumes the same already-resolved JSON. Names are applied server-side to the
+// responses that need them.
+shardRouter.get(
+  '/clilocs',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Cliloc table status: sources, drift, entry count (admin only)'
+  // #swagger.description = 'Where the cliloc sources are, whether they can be read, how many entries are loaded, and whether the files on disk have drifted from them. The table is built from a SET of sources — the converted client table plus every operator-maintained overlay under `custom/`, which is how shard-added and shard-edited items get names. `missingSources` lists any source that was loaded before and is now gone; an import refuses that without `approve`. A shard with nothing configured is a supported state — item names simply render as ids.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Cliloc status', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  shardClilocs.getStatus,
+)
+shardRouter.post(
+  '/clilocs/import',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Re-import the cliloc table from its source files (admin only)'
+  // #swagger.description = 'Applies a client patch, or a change to the shard\'s own overlay files, without a restart. `force` reimports even when the source hashes match what is loaded. `approve` accepts a refresh in which a previously-loaded source has VANISHED — refused by default, because an unmounted volume and a deliberate deletion are indistinguishable from the server, and the wrong guess silently drops every name that file contributed. A missing path — or the common mistake of pointing at the client\'s own COMPRESSED Cliloc.enu — answers 200 with status "unavailable" and the reason, rather than 500: the refresh contract reports outcomes instead of throwing, and the admin needs to be told which file to convert.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { type: "object", properties: { force: { type: "boolean", description: "Reimport even if the sources are unchanged." }, approve: { type: "boolean", description: "Accept a refresh in which a previously-loaded source has vanished." } } } } } } */
+  /* #swagger.responses[200] = { description: 'What happened', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocRefreshResult" } } } } */
+  adminOnly,
+  body('force').optional().isBoolean(),
+  body('approve').optional().isBoolean(),
+  validate,
+  shardClilocs.importClilocs,
+)
+shardRouter.put(
+  '/clilocs/path',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Set the cliloc source the site reads from (admin only)'
+  // #swagger.description = 'Accepts either the converted base file itself or a directory to search. Overlays are read from a `custom/` directory beside it either way — pointing at a file does not forfeit them. Persisted as a setting, which wins over the UO_CLIENT_PATH deploy default so the mount can move without a redeploy. Blank clears it and resolution is skipped on the next boot. Deliberately does not import as a side effect — the response carries the refreshed status so the panel can offer that as the next step.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["path"], properties: { path: { type: "string", description: "Path to the converted cliloc file, or a directory containing one. Blank disables resolution." } } } } } } */
+  /* #swagger.responses[200] = { description: 'Cliloc status after the change', content: { "application/json": { schema: { $ref: "#/components/schemas/ClilocStatus" } } } } */
+  adminOnly,
+  body('path').isString().isLength({ max: 512 }),
+  validate,
+  shardClilocs.setPath,
+)
+
+// ── Feature visibility (admin only) ───────────────────────────────────
+// Who can see which shard surface, and which sensitive fields within it. This
+// decides what ANONYMOUS visitors get, so it sits above the moderator tier.
+shardRouter.get(
+  '/visibility',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Get per-feature shard visibility config (admin only)'
+  // #swagger.description = 'The effective config (compiled defaults merged with stored overrides) plus the vocabulary the admin UI renders from: the audience ladder and the always-locked fields. Defaults reproduce pre-v3 behavior.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Visibility config', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityConfig" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  shardVisibility.getVisibility,
+)
+shardRouter.put(
+  '/visibility',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Update per-feature shard visibility config (admin only)'
+  // #swagger.description = 'Patch one or more features. Unknown feature names, unknown rungs, and any attempt to configure a locked field (acct / webId — admin-only always) are rejected with 400 rather than silently dropped.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityUpdate" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated config', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardVisibilityConfig" } } } } */
+  /* #swagger.responses[400] = { description: 'Unknown feature, rung, or a locked field', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('features').isObject(),
+  validate,
+  shardVisibility.putVisibility,
+)
+
+module.exports = shardRouter

server/src/router/v1/admin/shardAtlas.controller.js

@@ -0,0 +1,117 @@
+// ── Admin · Spawn atlas ────────────────────────────────────────────────────
+//
+// Operating the atlas import: where the ServUO tree is, whether it has drifted
+// from what is loaded, and the approve/reject decision for a refresh that would
+// remove a facet (docs/website/SPAWN_ATLAS.md).
+//
+// The policy lives in the model. This controller does three things and no more:
+// it validates input, it maps a refresh RESULT onto an HTTP status, and it
+// records the action in the admin activity log.
+//
+// **A refresh result is not an exception.** `shardAtlas.refresh()` reports
+// `unavailable` / `failed` / `needsReview` rather than throwing, because the boot
+// path must never be stopped by a bad tree. That contract is preserved here: an
+// unreadable mount is a 200 carrying `status: 'unavailable'`, not a 500. The
+// admin needs to be told what is wrong with their path, and a 500 says only
+// "something broke".
+
+const atlas = require('../../../model/shardAtlas/shardAtlas.model')
+const activity = require('../../../model/activity/activity.model')
+
+const log = require('../../../utils/logger')('admin-shard-atlas')
+
+// GET /admin/shard/atlas — what is loaded, what the tree looks like, what is
+// staged. Unlike the public /atlas/meta route this DOES carry the filesystem
+// path and the drift flag: that is the whole point of the panel.
+async function getStatus(req, res) {
+  try {
+    return res.json(await atlas.status())
+  } catch (err) {
+    log.error('getStatus', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/atlas/import — apply a map change without a restart.
+//
+// `force` reimports even when the source hashes match what is loaded (the escape
+// hatch for "the database is wrong but the tree is not"). Facet loss is still
+// staged rather than applied — approving is a separate, explicit act.
+async function importAtlas(req, res) {
+  try {
+    const force = !!req.body?.force
+    const result = await atlas.refresh({ force })
+    await activity.log({
+      req,
+      action: 'shard.atlas.import',
+      detail: { force, status: result.status, counts: result.counts ?? null },
+    })
+    return res.json(result)
+  } catch (err) {
+    log.error('importAtlas', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/atlas/approve — apply a staged refresh, facet loss and all.
+//
+// Re-parses the tree rather than applying something captured at boot: only the
+// DECISION was stored, so what lands matches the tree as it is now. If the
+// operator has since fixed a half-copied mount, the approved import is simply
+// the corrected one — which is the desired outcome, not a surprise.
+async function approve(req, res) {
+  try {
+    const result = await atlas.approvePending()
+    await activity.log({
+      req,
+      action: 'shard.atlas.approve',
+      detail: { status: result.status, removed: result.removedFacets ?? null },
+    })
+    return res.json(result)
+  } catch (err) {
+    log.error('approveAtlas', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/atlas/reject — keep the current atlas and remember the
+// decision against those exact source hashes, so a declined refresh does not
+// re-prompt on every restart. Changing the tree asks again.
+async function reject(req, res) {
+  try {
+    const result = await atlas.rejectPending()
+    if (result.status === 'none') {
+      return res.status(404).json({ message: 'No refresh is awaiting review.' })
+    }
+    await activity.log({ req, action: 'shard.atlas.reject', detail: {} })
+    return res.json(result)
+  } catch (err) {
+    log.error('rejectAtlas', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /admin/shard/atlas/path — point the atlas at a different ServUO tree.
+//
+// Persisted as a setting, which wins over the SERVUO_PATH env default so an
+// operator can move the mount without a redeploy. Blank clears it, which turns
+// the atlas off (boot skips, the loaded atlas keeps serving) — that is a
+// legitimate thing to want, so it is allowed rather than validated away.
+//
+// Deliberately does NOT import as a side effect: changing where the atlas reads
+// from and reloading it are separate decisions, and an operator fixing a typo
+// should not have a multi-thousand-row replace happen under them. The response
+// carries the refreshed status so the panel can offer the import immediately.
+async function setPath(req, res) {
+  try {
+    const value = String(req.body?.path ?? '').trim()
+    await atlas.setServuoPath(value, req.user?.id ?? null)
+    await activity.log({ req, action: 'shard.atlas.path', detail: { path: value } })
+    return res.json(await atlas.status())
+  } catch (err) {
+    log.error('setAtlasPath', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { getStatus, importAtlas, approve, reject, setPath }

server/src/router/v1/admin/shardClilocs.controller.js

@@ -0,0 +1,106 @@
+// ── Admin · Cliloc table ───────────────────────────────────────────────────
+//
+// Operating the cliloc import: where the converted cliloc file is, whether it
+// has drifted from what is loaded, and a forced reimport after a client patch
+// (docs/website/CLILOCS.md).
+//
+// The policy lives in the model. This controller does three things and no more:
+// it validates input, it maps a refresh RESULT onto an HTTP status, and it
+// records the action in the admin activity log.
+//
+// **A refresh result is not an exception.** `shardClilocs.refresh()` reports
+// `unavailable` / `failed` rather than throwing, because the boot path must never
+// be stopped by a bad file. That contract is preserved here: a missing file, or
+// the single most likely operator mistake — pointing at the client's own
+// COMPRESSED `Cliloc.enu` — is a 200 carrying `status: 'unavailable'` and the
+// reason, not a 500. A 500 would say only "something broke"; the operator needs
+// to be told which file to convert.
+
+const clilocs = require('../../../model/shardClilocs/shardClilocs.model')
+const market = require('../../../model/shardMarket/shardMarket.model')
+const activity = require('../../../model/activity/activity.model')
+
+const log = require('../../../utils/logger')('admin-shard-clilocs')
+
+// GET /admin/shard/clilocs — what is loaded, what the file looks like, whether
+// they disagree. There is no public counterpart: the cliloc table is never
+// served as a table, only applied to names the site already returns.
+async function getStatus(req, res) {
+  try {
+    return res.json(await clilocs.status())
+  } catch (err) {
+    log.error('getStatus', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/clilocs/import — reload after a client patch or a change to
+// the shard's own overlay files, without a restart.
+//
+// `force` reimports even when the source hashes match what is loaded (the escape
+// hatch for "the database is wrong but the files are not").
+//
+// `approve` accepts a refresh in which a previously-loaded source has VANISHED.
+// That is refused by default because an unmounted volume and a deliberate
+// deletion look identical from the server — the lighter cousin of the atlas's
+// approve/reject flow, and the reason it can be a flag here rather than a
+// pending table is that nothing is stored to approve: the import re-reads the
+// files at approval time by construction.
+async function importClilocs(req, res) {
+  try {
+    const force = !!req.body?.force
+    const approve = !!req.body?.approve
+    const result = await clilocs.refresh({ force, approve })
+
+    // The marketplace denormalizes resolved item names into
+    // shard_vendor_items.display_name, and the shard's market sweep will NOT
+    // re-send an unchanged shop just because the site learned what its items are
+    // called — so without this pass, an operator who imports clilocs after the
+    // first sweep keeps seeing item ids until every shop happens to change.
+    // Awaited (rather than fired and forgotten) so the panel's "imported" is
+    // honest about the names being live; the pass is a bounded walk of one table
+    // and never throws.
+    if (result.status === 'imported') await market.refreshDisplayNames()
+
+    await activity.log({
+      req,
+      action: 'shard.clilocs.import',
+      detail: {
+        force,
+        approve,
+        status: result.status,
+        count: result.count ?? null,
+        missingSources: result.missingSources ?? result.acceptedMissing ?? null,
+      },
+    })
+    return res.json(result)
+  } catch (err) {
+    log.error('importClilocs', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /admin/shard/clilocs/path — point the site at a different cliloc file.
+//
+// Persisted as a setting, which wins over the UO_CLIENT_PATH env default so an
+// operator can move the mount without a redeploy. Blank clears it, which turns
+// resolution off (boot skips, the loaded table keeps serving) — a legitimate
+// thing to want, so it is allowed rather than validated away.
+//
+// Deliberately does NOT import as a side effect, for the same reason the atlas
+// path does not: changing where the table reads from and reloading it are
+// separate decisions. The response carries the refreshed status so the panel can
+// offer the import immediately.
+async function setPath(req, res) {
+  try {
+    const value = String(req.body?.path ?? '').trim()
+    await clilocs.setClientPath(value, req.user?.id ?? null)
+    await activity.log({ req, action: 'shard.clilocs.path', detail: { path: value } })
+    return res.json(await clilocs.status())
+  } catch (err) {
+    log.error('setClilocPath', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { getStatus, importClilocs, setPath }

server/src/router/v1/admin/shardVisibility.controller.js

@@ -0,0 +1,98 @@
+// ── Admin · Shard visibility ───────────────────────────────────────────────
+//
+// Read/write the per-feature audience config that gates every shard-derived
+// surface. Admin-only: this decides what anonymous visitors can see, so it is
+// not part of the moderator tier.
+//
+// The policy itself (the ladder, the feature catalog, which fields are locked)
+// lives in utils/shardVisibility.js. This controller only validates input
+// against that policy and persists it.
+
+const model = require('../../../model/shardVisibility/shardVisibility.model')
+const visibility = require('../../../utils/shardVisibility')
+const log = require('../../../utils/logger')('admin-shard-visibility')
+
+// GET /admin/shard/visibility — the effective config (defaults merged with any
+// stored overrides), plus the vocabulary the admin UI needs to render itself:
+// the ladder, and which fields each feature exposes as configurable.
+async function getVisibility(req, res) {
+  try {
+    const config = await visibility.getConfig()
+    return res.json({
+      ladder: visibility.LADDER,
+      lockedFields: Object.keys(visibility.LOCKED_FIELDS),
+      defaults: visibility.compileDefaults(),
+      features: config,
+    })
+  } catch (err) {
+    log.error('getVisibility', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /admin/shard/visibility — replace the settings for one or more features.
+// Body: { features: { <name>: { enabled, audience, stream, fieldRules } } }
+//
+// Rejects unknown feature names, unknown rungs, and any attempt to configure a
+// locked field — a 400 rather than a silent drop, so an admin who tries to make
+// `acct` public learns that it is not negotiable.
+async function putVisibility(req, res) {
+  try {
+    const incoming = req.body?.features
+    if (!incoming || typeof incoming !== 'object' || Array.isArray(incoming)) {
+      return res.status(400).json({ message: 'features object required' })
+    }
+
+    const entries = []
+    for (const [name, patch] of Object.entries(incoming)) {
+      if (!visibility.isFeature(name)) {
+        return res.status(400).json({ message: `Unknown feature: ${name}` })
+      }
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+        return res.status(400).json({ message: `Invalid settings for ${name}` })
+      }
+      if (patch.audience != null && !visibility.isLevel(patch.audience)) {
+        return res.status(400).json({ message: `Unknown audience for ${name}: ${patch.audience}` })
+      }
+
+      const fieldRules = {}
+      for (const [field, level] of Object.entries(patch.fieldRules || {})) {
+        // Matches flattened spellings too (`ownerAcct`, `leaderWebId`), so the
+        // rejection covers every way the field can be named rather than the two
+        // canonical keys.
+        if (visibility.isLockedField(field)) {
+          return res.status(400).json({ message: `Field '${field}' is admin-only and cannot be configured` })
+        }
+        if (!visibility.isLevel(level)) {
+          return res.status(400).json({ message: `Unknown rung for ${name}.${field}: ${level}` })
+        }
+        fieldRules[field] = level
+      }
+
+      const current = (await visibility.getConfig())[name]
+      entries.push({
+        feature: name,
+        enabled: patch.enabled == null ? current.enabled : !!patch.enabled,
+        audience: patch.audience ?? current.audience,
+        stream: patch.stream == null ? current.stream : !!patch.stream,
+        fieldRules,
+        updatedBy: req.user?.id ?? null,
+      })
+    }
+
+    for (const entry of entries) await model.upsert(entry)
+    visibility.invalidate()
+
+    log.info('shard visibility updated', {
+      by: req.user?.id,
+      features: entries.map((e) => e.feature),
+    })
+
+    return res.json({ features: await visibility.getConfig() })
+  } catch (err) {
+    log.error('putVisibility', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { getVisibility, putVisibility }

server/src/router/v1/admin/uoLink.router.js

@@ -0,0 +1,99 @@
+// Admin · uo-link — the sidecar connection config, the town crier, and the
+// staff SSE stream.
+//
+// Mounted at /api/v1/admin/uo-link by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. This is where shard integration is
+// configured: base/ws URL, bearer token, protocol version and the enabled
+// toggle all live in the DB (uoLinkConfig), never in env. The token is
+// write-only over this API (SECURITY note in uoLink.controller.js).
+//
+// /stream is the ADMIN SSE channel — it carries staff audit, cheat detection
+// and login attempts on top of the public event kinds. The public/admin
+// allowlist split in utils/shardIngest.js is a security boundary; the adminOnly
+// gate below is its other half.
+//
+// The routes keep their `Admin · Shard` swagger tag: retagging is a real
+// OpenAPI diff and does not belong in a route-move PR.
+//
+// Admin-only, and kept as a per-route gate rather than a router-level `use` so
+// the middleware chain each route carries is unchanged by the move.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const uoLink = require('./uoLink.controller')
+const { requireRole } = require('../../../utils/auth')
+const validate = require('../../../middleware/validate')
+
+const uoLinkRouter = express.Router()
+const adminOnly = requireRole('admin')
+
+uoLinkRouter.get(
+  '/config',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Get uo-link config + live status + ingestion stats (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Masked config, health and ingestion stats', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  uoLink.getConfig,
+)
+uoLinkRouter.put(
+  '/config',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Save uo-link connection config (admin only)'
+  // #swagger.description = 'token is write-only — omit/blank it to keep the existing one. Saving (re)starts the WS ingest client.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", properties: { baseUrl: { type: "string" }, wsUrl: { type: "string" }, token: { type: "string" }, protocol: { type: "integer" }, enabled: { type: "boolean" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Updated config + live status', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error, or missing token while enabling', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Admin role required', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('baseUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['http', 'https'] }),
+  body('wsUrl').optional({ values: 'falsy' }).isString().trim().isURL({ require_tld: false, protocols: ['ws', 'wss'] }),
+  body('token').optional({ values: 'falsy' }).isString().trim(),
+  body('protocol').optional().isInt({ min: 1, max: 99 }),
+  body('enabled').optional().isBoolean(),
+  validate,
+  uoLink.saveConfig,
+)
+uoLinkRouter.post(
+  '/towncrier',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Publish / replace a town-crier message (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TownCrierRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Posted', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Rejected (over caps)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  body('id').isString().trim().isLength({ min: 1, max: 64 }),
+  body('lines').isArray({ min: 1, max: 8 }),
+  body('lines.*').isString().isLength({ max: 200 }),
+  body('durationSec').optional().isInt({ min: 1, max: 86400 }),
+  validate,
+  uoLink.postTownCrier,
+)
+uoLinkRouter.delete(
+  '/towncrier/:id',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Remove a town-crier message (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Town-crier message id.' }
+  /* #swagger.responses[200] = { description: 'Removed', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown id', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  adminOnly,
+  param('id').isString().trim().isLength({ min: 1, max: 64 }),
+  validate,
+  uoLink.deleteTownCrier,
+)
+uoLinkRouter.get(
+  '/stream',
+  // #swagger.tags = ['Admin · Shard']
+  // #swagger.summary = 'Full live shard event stream incl. audit/cheat (SSE, admin only)'
+  /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
+  adminOnly,
+  uoLink.stream,
+)
+
+module.exports = uoLinkRouter

server/src/router/v1/auth/auth.routes.js

@@ -1,214 +0,0 @@
-const express = require('express')
-const { body, param } = require('express-validator')
-
-const { login, register, loginTotp, logout, me, HONEYPOT_FIELD } = require('./auth.controller')
-const { getInvite, acceptInvite } = require('./invite.controller')
-const { requestReset, lookupReset, confirmReset } = require('./passwordReset.controller')
-const { isLoggedIn } = require('../../../utils/auth')
-const { attachSession } = require('../../../auth/session.middleware')
-const {
-  loginLimiter,
-  registerLimiter,
-  passwordResetRequestLimiter,
-  passwordResetConfirmLimiter,
-} = require('../../../middleware/rateLimit')
-const { slowLogin, backoffGuard } = require('../../../middleware/loginProtection')
-const validate = require('../../../middleware/validate')
-const mobileRouter = require('./mobile.routes')
-const ssoRouter = require('./sso.routes')
-const meRouter = require('./me.routes')
-const notifRouter = require('./notifications.routes')
-
-const authRouter = express.Router()
-
-// Native/Android bearer-token auth. Additive alongside the web cookie flow below.
-authRouter.use('/mobile', mobileRouter)
-
-// SSO discovery + OAuth redirect flow (/auth/providers, /auth/sso/:provider/*).
-// Additive; the web cookie + TOTP flow below is unchanged.
-authRouter.use(ssoRouter)
-
-// Role-agnostic self-service ("me") — /auth/me/account*, reusing the same
-// account.controller handlers as /player/account/* and /admin/account/* behind
-// requireAuth (any role). Additive; gives the app one self surface that never
-// touches /admin. The bare GET /me below is unaffected (meRouter has no /account-
-// free route, so /me falls through to its own handler).
-authRouter.use('/me', meRouter)
-
-// Push-notification self-service — /auth/me/devices*, /auth/me/notifications/*.
-// A second sub-router at /me (Express allows multiple), same requireAuth gate,
-// keeping the notification surface separate from the account/identity handlers.
-authRouter.use('/me', notifRouter)
-
-// Login protection order (cheapest rejection first):
-//   backoffGuard → per-IP exponential lockout on repeated failures
-//   slowLogin    → progressive per-request delay within the window
-//   loginLimiter → hard 10-per-15-min cap
-const loginGuards = [backoffGuard, slowLogin, loginLimiter]
-
-authRouter.post(
-  '/login',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Log in with username and password'
-  // #swagger.description = 'On success sets the httpOnly session cookie. If the account has 2FA enabled, returns { totpRequired, challenge } instead and no cookie is set — complete login at POST /login/totp. Rate limited and behind bot/backoff guards.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/LoginRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Session issued, or TOTP challenge required', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[401] = { description: 'Incorrect username or password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ...loginGuards,
-  body('username').isString().trim().notEmpty(),
-  body('password').isString().notEmpty(),
-  // Honeypot must be absent/empty for humans; bots that fill it are caught in
-  // the controller. Accept-but-ignore here so a filled value still reaches it.
-  body(HONEYPOT_FIELD).optional(),
-  validate,
-  login,
-)
-
-// Public self-registration (player accounts). Gated in the controller by the
-// player_registration setting; here it reuses the login backoff/limiter stack
-// plus its own per-IP cap, and accepts the honeypot field.
-authRouter.post(
-  '/register',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Register a player account'
-  // #swagger.description = 'Creates a self-service player account and logs it in (sets the session cookie). Available only when an admin has enabled password registration (player_registration = password|both); otherwise returns 403. Rate limited and behind bot/backoff guards; a hidden honeypot field must stay empty.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/RegisterRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Account created and session issued', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error or unavailable username', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[403] = { description: 'Registration is not open', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ...loginGuards,
-  registerLimiter,
-  body('username').isString().trim().isLength({ min: 3, max: 32 }),
-  body('password').isString().isLength({ min: 8, max: 64 }),
-  body('email').optional({ values: 'falsy' }).isEmail().isLength({ max: 255 }),
-  body(HONEYPOT_FIELD).optional(),
-  validate,
-  register,
-)
-
-// Second factor: same throttling, since it's a code-guessing surface too.
-authRouter.post(
-  '/login/totp',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Complete login with a TOTP or recovery code'
-  // #swagger.description = 'Second step for 2FA accounts. Exchange the challenge from /login plus either the current authenticator code OR a single-use recovery code for a session cookie. Set trustDevice to remember this browser and skip TOTP on future logins (30 days); if the trusted-device limit is reached the session is still issued and the response carries { trustLimitReached, devices } so the user can revoke one first.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpLoginRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Session issued (optionally with a trusted-device-limit prompt)', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[401] = { description: 'Invalid code or expired challenge', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ...loginGuards,
-  body('challenge').isString().notEmpty(),
-  // Either a TOTP code or a recovery code satisfies the second factor; the
-  // controller rejects the request when neither verifies.
-  body('code').optional({ values: 'falsy' }).isString().trim().isLength({ min: 6, max: 8 }),
-  body('recoveryCode').optional({ values: 'falsy' }).isString().trim().isLength({ min: 8, max: 32 }),
-  body('trustDevice').optional().isBoolean(),
-  body('deviceName').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
-  validate,
-  loginTotp,
-)
-
-// ── Email-invite acceptance (public, token-gated) ──────────────────────────
-authRouter.get(
-  '/invite/:token',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Look up an email invite by token'
-  // #swagger.description = 'Returns the pre-assigned email + role for a valid, pending, unexpired invite so the accept form can render. 404 for anything not currently acceptable.'
-  /* #swagger.responses[200] = { description: 'Invite details', content: { "application/json": { schema: { type: "object", properties: { email: { type: "string" }, role: { type: "string" } } } } } } */
-  /* #swagger.responses[404] = { description: 'Invalid or expired invite', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('token').isString().isLength({ min: 8, max: 128 }),
-  validate,
-  getInvite,
-)
-authRouter.post(
-  '/invite/:token/accept',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Accept an email invite (creates the account at the invited role)'
-  // #swagger.description = 'Creates the website user at the invite’s pre-assigned role and logs them in (sets the session cookie). Bypasses the player_registration gate — the invite is its own authority. Rate limited + honeypot-guarded like registration.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["username","password"], properties: { username: { type: "string" }, password: { type: "string" } } } } } */
-  /* #swagger.responses[200] = { description: 'Account created and session issued', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[404] = { description: 'Invalid or expired invite', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Username taken or invite already used', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ...loginGuards,
-  registerLimiter,
-  param('token').isString().isLength({ min: 8, max: 128 }),
-  body('username').isString().trim().isLength({ min: 3, max: 32 }),
-  body('password').isString().isLength({ min: 8, max: 64 }),
-  body(HONEYPOT_FIELD).optional(),
-  validate,
-  acceptInvite,
-)
-
-// ── Self-service password reset (public, token-gated) ──────────────────────
-// Request → email a tokened link; then validate the link and set a new password.
-// The request step never reveals whether an email exists (always 200, generic).
-authRouter.post(
-  '/password/forgot',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Request a password-reset link by email'
-  // #swagger.description = 'Emails a single-use, ~1h reset link to every active account on the address. Always returns the same generic 200 whether or not the email matches (no account enumeration). Email is non-unique, so multiple accounts may each receive a link naming their username. Rate limited per IP.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["email"], properties: { email: { type: "string", format: "email" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Generic acknowledgement (sent if the account exists)', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many requests', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  passwordResetRequestLimiter,
-  body('email').isString().trim().isEmail().isLength({ max: 255 }),
-  validate,
-  requestReset,
-)
-authRouter.get(
-  '/password/reset/:token',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Validate a password-reset link'
-  // #swagger.description = 'Returns the target username for a valid, pending, unexpired reset link so the reset form can render. 404 for anything not currently usable (never distinguishes expired from used from never-existed).'
-  /* #swagger.responses[200] = { description: 'Reset link is valid', content: { "application/json": { schema: { type: "object", properties: { username: { type: "string" } } } } } } */
-  /* #swagger.responses[404] = { description: 'Invalid or expired reset link', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('token').isString().isLength({ min: 8, max: 128 }),
-  validate,
-  lookupReset,
-)
-authRouter.post(
-  '/password/reset/:token',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Set a new password from a reset link'
-  // #swagger.description = 'Consumes the single-use link and sets the new password. Rotates the hash and revokes every existing session (web + mobile). Does NOT sign the user in — they log in fresh afterwards (so a 2FA account still passes TOTP). Rate limited per IP.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["password"], properties: { password: { type: "string", minLength: 8, maxLength: 64 } } } } } } */
-  /* #swagger.responses[200] = { description: 'Password changed', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[404] = { description: 'Invalid, expired, or already-used reset link', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many attempts', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  passwordResetConfirmLimiter,
-  param('token').isString().isLength({ min: 8, max: 128 }),
-  body('password').isString().isLength({ min: 8, max: 64 }),
-  validate,
-  confirmReset,
-)
-
-authRouter.post(
-  '/logout',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Log out (clear the cookie and revoke this session)'
-  /* #swagger.responses[200] = { description: 'Logged out', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
-  // Best-effort attach (never rejects) so the controller can revoke this session's
-  // jti — logout stays a no-op for an already-anonymous caller.
-  attachSession,
-  logout,
-)
-authRouter.get(
-  '/me',
-  // #swagger.tags = ['Auth']
-  // #swagger.summary = 'Current authenticated user'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'The signed-in user', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/User" } } } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  isLoggedIn,
-  me,
-)
-
-module.exports = authRouter

server/src/router/v1/auth/index.js

@@ -0,0 +1,67 @@
+// /api/v1/auth — the authentication surface, assembled from per-capability
+// routers.
+//
+// This file owns the mount table and nothing else; no route is declared here.
+// Each capability router mounts at the prefix it already owned inside the old
+// monolithic auth.routes.js, so the emitted URL set is byte-identical — proved by
+// a zero-line diff in server/routes.manifest.json (`npm run routes:manifest`).
+//
+// **There is deliberately no group gate.** /auth is where an anonymous caller
+// becomes authenticated, so most of it must stay reachable logged-out. The
+// authenticated parts gate themselves: meRouter and notifRouter each apply
+// `noindex, requireAuth` at their own router level, and /sso/:provider/link
+// carries requireAuth per route.
+//
+// **Mount order is load-bearing** — see the two notes inline below.
+//
+// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
+
+const express = require('express')
+
+const mobileRouter = require('./mobile.routes')
+const ssoRouter = require('./sso.routes')
+const meRouter = require('./me.routes')
+const notifRouter = require('./notifications.routes')
+const loginRouter = require('./login.router')
+const registerRouter = require('./register.router')
+const inviteRouter = require('./invite.router')
+const passwordRouter = require('./password.router')
+const sessionRouter = require('./session.router')
+
+const authRouter = express.Router()
+
+// Native/Android bearer-token auth. Additive alongside the web cookie flow below.
+authRouter.use('/mobile', mobileRouter)
+
+// SSO discovery + OAuth redirect flow. Mounted **pathless** because it owns two
+// prefixes (/auth/providers and /auth/sso/*); it declares no router-level
+// middleware, so passing through it is a no-op for every other route.
+authRouter.use(ssoRouter)
+
+// Role-agnostic self-service ("me") — /auth/me/account*, reusing the same
+// account.controller handlers as /player/account/* and /admin/account/* behind
+// requireAuth (any role). Additive; gives the app one self surface that never
+// touches /admin.
+authRouter.use('/me', meRouter)
+
+// Push-notification self-service — /auth/me/devices*, /auth/me/notifications/*.
+// A second sub-router at /me (Express allows multiple), same requireAuth gate,
+// keeping the notification surface separate from the account/identity handlers.
+authRouter.use('/me', notifRouter)
+
+// Credential surfaces, each at the prefix it owns.
+authRouter.use('/login', loginRouter)
+authRouter.use('/register', registerRouter)
+authRouter.use('/invite', inviteRouter)
+authRouter.use('/password', passwordRouter)
+
+// The two singletons that own no path segment of their own: POST /logout and
+// GET /me. Mounted at the group root and **last**, because `use('/me', …)` above
+// matches the bare path /me too: GET /auth/me runs meRouter's and notifRouter's
+// `noindex, requireAuth`, matches no route inside either, and falls through to
+// here. Mounting this ahead of them would drop the X-Robots-Tag header they set.
+// Safe at the root only because session.router.js declares no router-level
+// middleware (see the note in that file).
+authRouter.use('/', sessionRouter)
+
+module.exports = authRouter

server/src/router/v1/auth/invite.router.js

@@ -0,0 +1,51 @@
+// Auth · Invite — email-invite acceptance. Public but token-gated: the invite
+// token is the whole authority, which is why acceptance bypasses the
+// player_registration setting that register.router.js honours.
+//
+// Mounted at /api/v1/auth/invite by auth/index.js, so the routes below emit
+// GET /auth/invite/:token and POST /auth/invite/:token/accept. Staff issue the
+// invites from admin/invites.router.js.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const { getInvite, acceptInvite } = require('./invite.controller')
+const { HONEYPOT_FIELD } = require('./auth.controller')
+const { loginGuards } = require('./loginGuards')
+const { registerLimiter } = require('../../../middleware/rateLimit')
+const validate = require('../../../middleware/validate')
+
+const inviteRouter = express.Router()
+
+inviteRouter.get(
+  '/:token',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Look up an email invite by token'
+  // #swagger.description = 'Returns the pre-assigned email + role for a valid, pending, unexpired invite so the accept form can render. 404 for anything not currently acceptable.'
+  /* #swagger.responses[200] = { description: 'Invite details', content: { "application/json": { schema: { type: "object", properties: { email: { type: "string" }, role: { type: "string" } } } } } } */
+  /* #swagger.responses[404] = { description: 'Invalid or expired invite', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('token').isString().isLength({ min: 8, max: 128 }),
+  validate,
+  getInvite,
+)
+inviteRouter.post(
+  '/:token/accept',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Accept an email invite (creates the account at the invited role)'
+  // #swagger.description = 'Creates the website user at the invite’s pre-assigned role and logs them in (sets the session cookie). Bypasses the player_registration gate — the invite is its own authority. Rate limited + honeypot-guarded like registration.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["username","password"], properties: { username: { type: "string" }, password: { type: "string" } } } } } */
+  /* #swagger.responses[200] = { description: 'Account created and session issued', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[404] = { description: 'Invalid or expired invite', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Username taken or invite already used', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ...loginGuards,
+  registerLimiter,
+  param('token').isString().isLength({ min: 8, max: 128 }),
+  body('username').isString().trim().isLength({ min: 3, max: 32 }),
+  body('password').isString().isLength({ min: 8, max: 64 }),
+  body(HONEYPOT_FIELD).optional(),
+  validate,
+  acceptInvite,
+)
+
+module.exports = inviteRouter

server/src/router/v1/auth/login.router.js

@@ -0,0 +1,64 @@
+// Auth · Login — the web cookie login flow and its TOTP second step.
+//
+// Mounted at /api/v1/auth/login by auth/index.js, so the two routes below emit
+// POST /auth/login and POST /auth/login/totp. No group gate: this is the
+// unauthenticated front door. Both routes carry the shared loginGuards stack —
+// the TOTP step is a code-guessing surface too.
+//
+// The bearer-token equivalents for native clients live in mobile.routes.js, and
+// the OAuth/OIDC flow in sso.routes.js. Logout and GET /auth/me are in
+// session.router.js.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const { login, loginTotp, HONEYPOT_FIELD } = require('./auth.controller')
+const { loginGuards } = require('./loginGuards')
+const validate = require('../../../middleware/validate')
+
+const loginRouter = express.Router()
+
+loginRouter.post(
+  '/',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Log in with username and password'
+  // #swagger.description = 'On success sets the httpOnly session cookie. If the account has 2FA enabled, returns { totpRequired, challenge } instead and no cookie is set — complete login at POST /login/totp. Rate limited and behind bot/backoff guards.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/LoginRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued, or TOTP challenge required', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Incorrect username or password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ...loginGuards,
+  body('username').isString().trim().notEmpty(),
+  body('password').isString().notEmpty(),
+  // Honeypot must be absent/empty for humans; bots that fill it are caught in
+  // the controller. Accept-but-ignore here so a filled value still reaches it.
+  body(HONEYPOT_FIELD).optional(),
+  validate,
+  login,
+)
+
+// Second factor: same throttling, since it's a code-guessing surface too.
+loginRouter.post(
+  '/totp',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Complete login with a TOTP or recovery code'
+  // #swagger.description = 'Second step for 2FA accounts. Exchange the challenge from /login plus either the current authenticator code OR a single-use recovery code for a session cookie. Set trustDevice to remember this browser and skip TOTP on future logins (30 days); if the trusted-device limit is reached the session is still issued and the response carries { trustLimitReached, devices } so the user can revoke one first.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpLoginRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued (optionally with a trusted-device-limit prompt)', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[401] = { description: 'Invalid code or expired challenge', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ...loginGuards,
+  body('challenge').isString().notEmpty(),
+  // Either a TOTP code or a recovery code satisfies the second factor; the
+  // controller rejects the request when neither verifies.
+  body('code').optional({ values: 'falsy' }).isString().trim().isLength({ min: 6, max: 8 }),
+  body('recoveryCode').optional({ values: 'falsy' }).isString().trim().isLength({ min: 8, max: 32 }),
+  body('trustDevice').optional().isBoolean(),
+  body('deviceName').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
+  validate,
+  loginTotp,
+)
+
+module.exports = loginRouter

server/src/router/v1/auth/loginGuards.js

@@ -0,0 +1,23 @@
+// The shared login-protection stack, ordered cheapest-rejection-first:
+//
+//   backoffGuard → per-IP exponential lockout on repeated failures
+//   slowLogin    → progressive per-request delay within the window
+//   loginLimiter → hard 10-per-15-min cap
+//
+// Every credential-guessing surface spreads it with `...loginGuards`: local
+// login, the TOTP second step, registration, invite acceptance and the SSO TOTP
+// step. It lived inline in auth.routes.js while all but one of those were in the
+// same file; the domain split (docs/website/API_V2_PLAN.md § Phase 2) puts them in
+// five, so it moved here rather than being copied five times. Duplicating a
+// throttling stack is how the copies drift — and the copy that drifts is the one
+// that stops throttling.
+//
+// The array is exported frozen: it is module-level shared state, and a router
+// that pushed onto it would silently add middleware to every other login surface.
+
+const { loginLimiter } = require('../../../middleware/rateLimit')
+const { slowLogin, backoffGuard } = require('../../../middleware/loginProtection')
+
+const loginGuards = Object.freeze([backoffGuard, slowLogin, loginLimiter])
+
+module.exports = { loginGuards }

server/src/router/v1/auth/me.routes.js

@@ -12,7 +12,7 @@
 //
 // requireAuth sets req.user to the fresh DB row and enforces the status + session
 // cutoff/revocation checks on every request, exactly as the account handlers
-// expect. Mounted at /me by auth.routes.js, so paths below are /auth/me/account*.
+// expect. Mounted at /me by auth/index.js, so paths below are /auth/me/account*.
 
 const express = require('express')
 const { body, param } = require('express-validator')

server/src/router/v1/auth/mobileSso.controller.js

@@ -22,6 +22,7 @@ const settings = require('../../../model/settings/settings.model')
 const sessionService = require('../../../auth/session.service')
 const ssoState = require('../../../auth/ssoState')
 const ssoController = require('./sso.controller')
+const { establishTrust } = require('./trustDevice.helper')
 
 const log = require('../../../utils/logger')('auth-mobile-sso')
 
@@ -163,12 +164,36 @@ async function exchange(req, res) {
       expiresAt: out.refreshExpiresAt,
     })
     await activity.log({ req, userId: user.id, action: 'auth.mobile.login', detail: { sso: sess.provider } })
+
+    // The user ticked "trust this device" on the Custom Tab TOTP form. That already
+    // set the browser's rg_trust cookie (which is what lets the NEXT Custom Tab SSO
+    // sign-in skip the code); mint the app its OWN trust token here so a native
+    // password login on the same device skips the code too. Minting at this point
+    // — an authenticated app→server call — is deliberate: the token reaches the app
+    // in a JSON body and never travels in the deep-link URL or sits in the bridge
+    // row. Best-effort: a device at the trust cap just gets no token, never a failed
+    // sign-in, so this can't turn a good login into an error.
+    let trustToken = null
+    if (sess.trust_device) {
+      try {
+        const trust = await establishTrust(req, user, {
+          platform: 'mobile',
+          deviceName: req.body.device_name || null,
+        })
+        if (trust.ok) trustToken = trust.trustToken
+        else if (trust.capReached) log.info('mobile sso: trust refused, device cap reached', { id: user.id })
+      } catch (err) {
+        log.error('mobile sso: could not establish trust (continuing, sign-in already succeeded)', err)
+      }
+    }
+
     log.info('mobile sso exchange success', { id: user.id, provider: sess.provider, ip: req.ip })
     return res.json({
       accessToken: out.accessToken,
       refreshToken: out.refreshToken,
       expiresIn: out.expiresIn,
       user: { id: user.id, username: user.username, role: user.role },
+      ...(trustToken ? { trustToken } : {}),
     })
   } catch (err) {
     log.error('mobile sso exchange', err)

server/src/router/v1/auth/mobileSso.routes.js

@@ -39,9 +39,9 @@ mobileSsoRouter.post(
   '/exchange',
   // #swagger.tags = ['Auth · Mobile']
   // #swagger.summary = 'Exchange an SSO authorization code for mobile tokens'
-  // #swagger.description = 'Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401.'
+  // #swagger.description = 'Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401. If the user ticked "trust this device" on the TOTP form during this flow, the response also carries { trustToken } for the app to store and replay via X-Trust-Token — minted here rather than passed through the deep link so it never appears in a URL.'
   /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/MobileSsoExchangeRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Access + refresh tokens', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
+  /* #swagger.responses[200] = { description: 'Access + refresh tokens (optionally with a trustToken to persist)', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
   /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
   /* #swagger.responses[401] = { description: 'Invalid/expired/used code or failed PKCE verification', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   /* #swagger.responses[429] = { description: 'Too many attempts (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */

server/src/router/v1/auth/notifications.routes.js

@@ -1,7 +1,7 @@
 // ── Push-notification self-service under /auth/me ──────────────────────────
 //
 // Device registration + per-user stream subscriptions for the app's opt-in push
-// (docs/android/PLAN.md §11). Mounted at /me by auth.routes.js alongside
+// (docs/android/PLAN.md §11). Mounted at /me by auth/index.js alongside
 // me.routes.js, behind requireAuth ONLY (role-agnostic — every authenticated
 // role manages its own devices/subscriptions), and noindex. The app calls these
 // and never touches /admin.

server/src/router/v1/auth/password.router.js

@@ -0,0 +1,70 @@
+// Auth · Password — self-service password reset. Public but token-gated: request
+// a link by email, then validate the link and set a new password.
+//
+// Mounted at /api/v1/auth/password by auth/index.js, so the routes below emit
+// POST /auth/password/forgot and GET|POST /auth/password/reset/:token.
+//
+// Two anti-enumeration properties are load-bearing and must survive any edit
+// here: the request step always returns the same generic 200 whether or not the
+// email matches an account, and the lookup step never distinguishes expired from
+// used from never-existed. Both live in passwordReset.controller; the per-IP
+// limiters below are what stop the endpoints being used as an oracle by volume.
+//
+// Changing a password while signed in is a different route —
+// PATCH /player/account/password (and its /auth/me and /admin twins).
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const { requestReset, lookupReset, confirmReset } = require('./passwordReset.controller')
+const {
+  passwordResetRequestLimiter,
+  passwordResetConfirmLimiter,
+} = require('../../../middleware/rateLimit')
+const validate = require('../../../middleware/validate')
+
+const passwordRouter = express.Router()
+
+passwordRouter.post(
+  '/forgot',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Request a password-reset link by email'
+  // #swagger.description = 'Emails a single-use, ~1h reset link to every active account on the address. Always returns the same generic 200 whether or not the email matches (no account enumeration). Email is non-unique, so multiple accounts may each receive a link naming their username. Rate limited per IP.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["email"], properties: { email: { type: "string", format: "email" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Generic acknowledgement (sent if the account exists)', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many requests', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  passwordResetRequestLimiter,
+  body('email').isString().trim().isEmail().isLength({ max: 255 }),
+  validate,
+  requestReset,
+)
+passwordRouter.get(
+  '/reset/:token',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Validate a password-reset link'
+  // #swagger.description = 'Returns the target username for a valid, pending, unexpired reset link so the reset form can render. 404 for anything not currently usable (never distinguishes expired from used from never-existed).'
+  /* #swagger.responses[200] = { description: 'Reset link is valid', content: { "application/json": { schema: { type: "object", properties: { username: { type: "string" } } } } } } */
+  /* #swagger.responses[404] = { description: 'Invalid or expired reset link', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('token').isString().isLength({ min: 8, max: 128 }),
+  validate,
+  lookupReset,
+)
+passwordRouter.post(
+  '/reset/:token',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Set a new password from a reset link'
+  // #swagger.description = 'Consumes the single-use link and sets the new password. Rotates the hash and revokes every existing session (web + mobile). Does NOT sign the user in — they log in fresh afterwards (so a 2FA account still passes TOTP). Rate limited per IP.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["password"], properties: { password: { type: "string", minLength: 8, maxLength: 64 } } } } } } */
+  /* #swagger.responses[200] = { description: 'Password changed', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[404] = { description: 'Invalid, expired, or already-used reset link', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  passwordResetConfirmLimiter,
+  param('token').isString().isLength({ min: 8, max: 128 }),
+  body('password').isString().isLength({ min: 8, max: 64 }),
+  validate,
+  confirmReset,
+)
+
+module.exports = passwordRouter

server/src/router/v1/auth/register.router.js

@@ -0,0 +1,43 @@
+// Auth · Register — public self-registration of player accounts.
+//
+// Mounted at /api/v1/auth/register by auth/index.js, so the single route below
+// emits POST /auth/register. Gated in the controller by the player_registration
+// setting (403 when closed); here it reuses the shared loginGuards stack plus its
+// own per-IP registerLimiter, and accepts the honeypot field.
+//
+// Invite acceptance is the other account-creating route and lives in
+// invite.router.js — it deliberately bypasses the player_registration gate, since
+// the invite is its own authority.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const { register, HONEYPOT_FIELD } = require('./auth.controller')
+const { loginGuards } = require('./loginGuards')
+const { registerLimiter } = require('../../../middleware/rateLimit')
+const validate = require('../../../middleware/validate')
+
+const registerRouter = express.Router()
+
+registerRouter.post(
+  '/',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Register a player account'
+  // #swagger.description = 'Creates a self-service player account and logs it in (sets the session cookie). Available only when an admin has enabled password registration (player_registration = password|both); otherwise returns 403. Rate limited and behind bot/backoff guards; a hidden honeypot field must stay empty.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/RegisterRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Account created and session issued', content: { "application/json": { schema: { $ref: "#/components/schemas/LoginResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unavailable username', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[403] = { description: 'Registration is not open', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ...loginGuards,
+  registerLimiter,
+  body('username').isString().trim().isLength({ min: 3, max: 32 }),
+  body('password').isString().isLength({ min: 8, max: 64 }),
+  body('email').optional({ values: 'falsy' }).isEmail().isLength({ max: 255 }),
+  body(HONEYPOT_FIELD).optional(),
+  validate,
+  register,
+)
+
+module.exports = registerRouter

server/src/router/v1/auth/session.router.js

@@ -0,0 +1,51 @@
+// Auth · Session — the two session-lifecycle singletons that own no path segment
+// of their own: POST /auth/logout and GET /auth/me.
+//
+// Mounted at the group root by auth/index.js, **last**. This is the auth group's
+// counterpart to admin/dashboard.router.js, and the same two rules apply:
+//
+//  1. **No router-level middleware here.** A bare `use(gate)` in a root-mounted
+//     router runs for every request passing through toward another mount, so it
+//     would gate /auth/login and /auth/mobile/* too. Keep gates on the routes.
+//
+//  2. **The mount must stay last.** `authRouter.use('/me', meRouter)` matches the
+//     bare path /me as well as /me/*, so a request to GET /auth/me runs meRouter's
+//     `noindex, requireAuth` (and notifRouter's), finds no matching route inside
+//     either, and falls through to the handler below. Mounting this router ahead
+//     of them would answer /auth/me first and silently drop the X-Robots-Tag
+//     header those routers apply. Verified by asserting the response headers, not
+//     by reading the mount table.
+//
+// Splitting the session is elsewhere by client: mobile.routes.js revokes refresh
+// tokens, and me.routes.js owns DELETE /auth/me/sessions/:id.
+
+const express = require('express')
+
+const { logout, me } = require('./auth.controller')
+const { isLoggedIn } = require('../../../utils/auth')
+const { attachSession } = require('../../../auth/session.middleware')
+
+const sessionRouter = express.Router()
+
+sessionRouter.post(
+  '/logout',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Log out (clear the cookie and revoke this session)'
+  /* #swagger.responses[200] = { description: 'Logged out', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  // Best-effort attach (never rejects) so the controller can revoke this session's
+  // jti — logout stays a no-op for an already-anonymous caller.
+  attachSession,
+  logout,
+)
+sessionRouter.get(
+  '/me',
+  // #swagger.tags = ['Auth']
+  // #swagger.summary = 'Current authenticated user'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The signed-in user', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/User" } } } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  isLoggedIn,
+  me,
+)
+
+module.exports = sessionRouter

server/src/router/v1/auth/sso.controller.js

@@ -26,6 +26,7 @@ const usernamePolicy = require('../../../auth/usernamePolicy')
 const botScore = require('../../../middleware/botScore')
 const loginProtection = require('../../../middleware/loginProtection')
 const { needsTotp } = require('./auth.controller')
+const { establishTrust } = require('./trustDevice.helper')
 
 const log = require('../../../utils/logger')('sso')
 
@@ -226,6 +227,29 @@ async function provisionSsoPlayer(req, providerId, profile) {
   return null
 }
 
+// Trusted-device skip for the SSO paths — the exact analogue of the check in
+// auth.controller.login, and the reason SSO used to demand a code on every single
+// sign-in even from a browser the user had explicitly trusted.
+//
+// The first factor here is the IdP authentication that just succeeded, so skipping
+// the SECOND factor on a device the user deliberately trusted is the same posture
+// as the password path. The trust must belong to THIS user (a trust token is
+// scoped to the account that minted it), and any store hiccup falls through to the
+// normal TOTP challenge — fail closed to asking for the code.
+async function trustedDeviceSkips(req, user, providerId) {
+  try {
+    const device = await sessionService.resolveTrustedDevice(req)
+    if (!device || device.user_id !== user.id) return false
+    await sessionService.honorTrustedDevice(device.id)
+    await activity.log({ req, userId: user.id, action: 'auth.login.trusted_device', detail: { provider: providerId, sso: true } })
+    log.info('sso login via trusted device (TOTP skipped)', { provider: providerId, id: user.id, ip: req.ip })
+    return true
+  } catch (err) {
+    log.error('sso trusted-device check failed; falling back to TOTP', err)
+    return false
+  }
+}
+
 // SSO login. Normally link-only: a login succeeds only if the external identity
 // is already linked. The one setting-gated relaxation is auto-provisioning a
 // player when player_registration ∈ {sso, both} (see provisionSsoPlayer).
@@ -257,10 +281,11 @@ async function finishLogin(req, res, providerId, kind, tx, profile) {
   const authMethod = sessionService.AUTH_METHODS.includes(kind) ? kind : 'sso'
 
   // 2FA parity with the local login (auth.controller): if the account has TOTP
-  // enabled, an SSO sign-in must NOT bypass the second factor. Stage a signed,
-  // httpOnly challenge and route the browser through the TOTP form instead of
-  // minting a session here. See issue #31.
-  if (needsTotp(user)) {
+  // enabled, an SSO sign-in must NOT bypass the second factor — unless this browser
+  // is a trusted device, which skips the second factor exactly as it does for a
+  // password login. Otherwise stage a signed, httpOnly challenge and route the
+  // browser through the TOTP form instead of minting a session here. See issue #31.
+  if (needsTotp(user) && !(await trustedDeviceSkips(req, user, providerId))) {
     const pending = ssoState.createTotpPending({
       userId: user.id,
       provider: providerId,
@@ -381,10 +406,17 @@ async function finishMobileLogin(req, res, providerId, kind, tx, profile) {
 
   const authMethod = sessionService.AUTH_METHODS.includes(kind) ? kind : 'sso'
 
-  if (needsTotp(user)) {
-    // Same second-factor gate as web: stage a signed pending-TOTP cookie (now
-    // carrying the bridge session) and route the Custom Tab through the player
-    // TOTP form. finishSsoTotp completes the mobile flow on a correct code.
+  // Same second-factor gate as web, including the trusted-device skip. This request
+  // is the IdP redirect landing in the app's Custom Tab, which shares the system
+  // browser's cookie jar — so an rg_trust cookie set by a previous SSO sign-in from
+  // this app IS presented here, and the app gets the same "don't ask me again"
+  // behaviour as the website without having to inject a header into a tab it does
+  // not control. (Putting the token in the start URL instead would leak a secret
+  // into query strings and logs.)
+  if (needsTotp(user) && !(await trustedDeviceSkips(req, user, providerId))) {
+    // Stage a signed pending-TOTP cookie (now carrying the bridge session) and route
+    // the Custom Tab through the player TOTP form. finishSsoTotp completes the
+    // mobile flow on a correct code.
     const pending = ssoState.createTotpPending({
       userId: user.id,
       provider: providerId,
@@ -432,6 +464,19 @@ async function finishSsoTotp(req, res) {
     res.clearCookie(ssoState.TOTP_COOKIE, token.cookieOptions(req))
     loginProtection.recordSuccess(req.ip)
 
+    // Optionally remember this browser, exactly as the password path does. On the
+    // mobile flow this browser IS the Custom Tab, so the cookie set here is what
+    // lets the NEXT app sign-in skip the code.
+    let trustLimit = null
+    if (req.body.trustDevice) {
+      const result = await establishTrust(req, user, {
+        platform: 'web',
+        deviceName: req.body.deviceName || null,
+      })
+      if (result.ok) token.setTrustCookie(req, res, result.trustToken)
+      else if (result.capReached) trustLimit = result.devices
+    }
+
     // Mobile SSO bridge: instead of a web session, mint the one-time auth code and
     // return a deep link for the app to redeem. The second factor is now complete,
     // so the code is issued no earlier than an ordinary web session would be.
@@ -440,11 +485,18 @@ async function finishSsoTotp(req, res) {
       if (!sess || sess.status !== 'pending' || new Date(sess.expires_at).getTime() <= Date.now()) {
         return res.status(401).json({ message: 'Your sign-in session expired. Please sign in again from the app.' })
       }
+      // Record the user's choice on the bridge session (a boolean — never the token)
+      // so /auth/mobile/sso/exchange can mint the APP's own trust token and hand it
+      // back over that authenticated app→server call. The token therefore never
+      // travels in the deep-link URL.
+      if (req.body.trustDevice && !trustLimit) {
+        await mobileBridge.markTrustRequested(sess.session_id)
+      }
       const link = await mintMobileAuthLink(req, sess, user, pending.provider, true)
       if (!link) {
         return res.status(409).json({ message: 'This sign-in session was already used. Please sign in again from the app.' })
       }
-      return res.json({ redirect: link })
+      return res.json({ redirect: link, ...(trustLimit ? { trustLimitReached: true, devices: trustLimit } : {}) })
     }
 
     const authMethod = sessionService.AUTH_METHODS.includes(pending.authMethod) ? pending.authMethod : 'sso'
@@ -456,6 +508,7 @@ async function finishSsoTotp(req, res) {
     return res.json({
       user: { id: user.id, username: user.username, role: user.role },
       returnTo: sanitizeReturn(pending.returnTo) || homePath(portalFor(pending.returnTo)),
+      ...(trustLimit ? { trustLimitReached: true, devices: trustLimit } : {}),
     })
   } catch (err) {
     log.error('sso totp error', err)

server/src/router/v1/auth/sso.routes.js

@@ -2,17 +2,13 @@ const express = require('express')
 const { body } = require('express-validator')
 
 const ctrl = require('./sso.controller')
+const { loginGuards } = require('./loginGuards')
 const { requireAuth } = require('../../../auth/session.middleware')
-const { ssoStartLimiter, loginLimiter } = require('../../../middleware/rateLimit')
-const { slowLogin, backoffGuard } = require('../../../middleware/loginProtection')
+const { ssoStartLimiter } = require('../../../middleware/rateLimit')
 const validate = require('../../../middleware/validate')
 
 const ssoRouter = express.Router()
 
-// Same throttling stack the local login/TOTP endpoints use — the SSO TOTP step is
-// a code-guessing surface too (cheapest rejection first).
-const loginGuards = [backoffGuard, slowLogin, loginLimiter]
-
 // Public discovery — the login page reads this to render provider buttons.
 ssoRouter.get(
   '/providers',
@@ -71,13 +67,15 @@ ssoRouter.post(
   '/sso/totp',
   // #swagger.tags = ['Auth · SSO']
   // #swagger.summary = 'Complete an SSO login with a TOTP code'
-  // #swagger.description = 'Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Rate limited and behind bot/backoff guards.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["code"], properties: { code: { type: "string" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Session issued', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/SafeUser" }, returnTo: { type: "string" } } } } } } */
+  // #swagger.description = 'Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Set trustDevice to remember this browser and skip TOTP on future SSO sign-ins (30 days) — on the mobile flow this browser is the app Custom Tab, and the app additionally receives its own trustToken at /auth/mobile/sso/exchange. If the trusted-device limit is reached the sign-in still completes and the response carries { trustLimitReached, devices }. Rate limited and behind bot/backoff guards.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["code"], properties: { code: { type: "string" }, trustDevice: { type: "boolean" }, deviceName: { type: "string" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued (web), or a deep link to redeem (mobile bridge); optionally with a trusted-device-limit prompt', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/SafeUser" }, returnTo: { type: "string" }, redirect: { type: "string" }, trustLimitReached: { type: "boolean" }, devices: { type: "array", items: { $ref: "#/components/schemas/TrustedDevice" } } } } } } } */
   /* #swagger.responses[401] = { description: 'Invalid code or expired challenge', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   ...loginGuards,
   body('code').isString().trim().isLength({ min: 6, max: 8 }),
+  body('trustDevice').optional().isBoolean(),
+  body('deviceName').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
   validate,
   ctrl.finishSsoTotp,
 )

server/src/router/v1/player/account.router.js

@@ -0,0 +1,130 @@
+// Player · Account — self-service credentials, 2FA and linked identities for the
+// signed-in account.
+//
+// Mounted at /api/v1/player/account by player/index.js, which already applied
+// `noindex, requireAuth`. No extra gate: every handler is self-scoped to
+// req.user.id, and staff are a superset of players (see player/index.js).
+//
+// The handlers are admin/account.controller — the same code serving
+// /admin/account/* and /auth/me/account/*. Three URL surfaces, one implementation;
+// this file must not grow a fourth copy of the logic.
+//
+// The swagger tag stays 'Player', matching the committed spec.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const account = require('../admin/account.controller')
+const validate = require('../../../middleware/validate')
+const { accountChangeLimiter } = require('../../../middleware/rateLimit')
+
+const accountRouter = express.Router()
+
+accountRouter.get(
+  '/',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Get the current player account (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The player account', content: { "application/json": { schema: { $ref: "#/components/schemas/PlayerAccount" } } } } */
+  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  account.getAccount,
+)
+
+accountRouter.patch(
+  '/username',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Change the current player’s username'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangeUsernameRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Updated username (session cookie re-issued)', content: { "application/json": { schema: { type: "object", properties: { username: { type: "string" } } } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or unavailable username', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  accountChangeLimiter,
+  body('username').isString().trim().isLength({ min: 3, max: 32 }),
+  validate,
+  account.changeUsername,
+)
+
+accountRouter.patch(
+  '/password',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Change or set the current player’s password'
+  // #swagger.description = 'If the account already has a password, currentPassword is required and verified. SSO-provisioned accounts with no password may set an initial one without a current password. On success the caller’s session is re-issued (they stay logged in) while all other sessions are revoked.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangePasswordRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Password changed', content: { "application/json": { schema: { $ref: "#/components/schemas/OkFlag" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or wrong current password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  accountChangeLimiter,
+  body('newPassword').isString().isLength({ min: 8, max: 64 }),
+  body('currentPassword').optional({ values: 'falsy' }).isString(),
+  validate,
+  account.changePassword,
+)
+
+// TOTP self-enrollment — identical to the admin account flow (disable requires a
+// valid current code; it does not take a password).
+accountRouter.post(
+  '/totp/setup',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Begin 2FA enrollment (returns secret + QR)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'otpauth URL and QR data to scan', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpSetup" } } } } */
+  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  account.totpSetup,
+)
+accountRouter.post(
+  '/totp/enable',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Enable 2FA by confirming a code'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
+  /* #swagger.responses[200] = { description: '2FA enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
+  /* #swagger.responses[400] = { description: 'Setup not started, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('code').isString().trim().isLength({ min: 6, max: 8 }),
+  validate,
+  account.totpEnable,
+)
+accountRouter.post(
+  '/totp/disable',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Disable 2FA by confirming a code'
+  // #swagger.description = 'Requires a valid current authenticator code (proves control of the authenticator); it does not take a password.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
+  /* #swagger.responses[200] = { description: '2FA disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
+  /* #swagger.responses[400] = { description: 'Not enabled, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('code').isString().trim().isLength({ min: 6, max: 8 }),
+  validate,
+  account.totpDisable,
+)
+
+// Linked SSO identities (self-service). Linking itself starts at
+// GET /auth/sso/:provider/link (already behind requireAuth; works for players).
+accountRouter.get(
+  '/identities',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'List linked SSO identities (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Linked identities', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/LinkedIdentity" } } } } } */
+  account.listIdentities,
+)
+accountRouter.delete(
+  '/identities/:provider',
+  // #swagger.tags = ['Player']
+  // #swagger.summary = 'Unlink an SSO identity (self)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
+  /* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { $ref: "#/components/schemas/UnlinkedFlag" } } } } */
+  /* #swagger.responses[404] = { description: 'No linked account for that provider', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('provider').matches(/^[a-z0-9-]+$/),
+  validate,
+  account.unlinkIdentity,
+)
+
+module.exports = accountRouter

server/src/router/v1/player/appeals.controller.js

@@ -4,7 +4,8 @@
 // one that hasn't been resolved yet. Ownership is proven by matching the
 // action's target_user_id against the caller's linked Discord identity — the
 // same (provider='discord', subject=<snowflake>) link the SSO flow writes.
-// Mounted behind the player-role gate (see player.routes.js).
+// Mounted behind the /player group gate — authenticated only, no role restriction
+// (see player/index.js); ownership is enforced per handler.
 const appeals = require('../../../model/appeals/appeals.model')
 const appealsDb = require('../../../model/appeals/appeals.db')
 const { isAppealableType, isTerminal } = require('../../../model/appeals/appeals.pure')

server/src/router/v1/player/appeals.router.js

@@ -0,0 +1,73 @@
+// Player · Appeals — a player appeals one of their own ban/mute mod_actions.
+// Ownership is proven by matching the action against the caller's linked Discord
+// identity (see appeals.controller); the staff side of the queue lives in
+// admin/moderation.router.js.
+//
+// Mounted at /api/v1/player/appeals by player/index.js, which already applied
+// `noindex, requireAuth`. No extra gate — every handler is self-scoped.
+//
+// Declaration order: GET /eligible is a literal path and sits ahead of the only
+// :param route (POST /:id/withdraw), which is a different method at a different
+// depth, so nothing here can shadow anything else.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const appeals = require('./appeals.controller')
+const validate = require('../../../middleware/validate')
+const { accountChangeLimiter } = require('../../../middleware/rateLimit')
+
+const appealsRouter = express.Router()
+
+appealsRouter.get(
+  '/',
+  // #swagger.tags = ['Player · Appeals']
+  // #swagger.summary = 'List the caller’s moderation appeals'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The caller’s appeals', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Appeal" } } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  appeals.listMine,
+)
+appealsRouter.get(
+  '/eligible',
+  // #swagger.tags = ['Player · Appeals']
+  // #swagger.summary = 'List the caller’s ban/mute actions eligible for appeal'
+  // #swagger.description = 'The caller’s ban/mute mod_actions that have no active appeal. Returns an empty array when the caller has no linked Discord account (the UI shows a “link Discord” hint).'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Appealable actions', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AppealEligibleAction" } } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  appeals.listEligible,
+)
+appealsRouter.post(
+  '/',
+  // #swagger.tags = ['Player · Appeals']
+  // #swagger.summary = 'Submit a moderation appeal for one of the caller’s actions'
+  // #swagger.description = 'Opens an appeal for a ban/mute mod_action that belongs to the caller (its target matches the caller’s linked Discord identity) and has no active appeal.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateAppealRequest" } } } } */
+  /* #swagger.responses[201] = { description: 'Appeal created', content: { "application/json": { schema: { $ref: "#/components/schemas/Appeal" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error, or the action type is not appealable', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[403] = { description: 'The action does not belong to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Mod action not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'An appeal for this action is already open', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  accountChangeLimiter,
+  body('mod_action_id').isInt({ min: 1 }).toInt(),
+  body('submitted_text').isString().trim().isLength({ min: 1, max: 4000 }),
+  validate,
+  appeals.create,
+)
+appealsRouter.post(
+  '/:id/withdraw',
+  // #swagger.tags = ['Player · Appeals']
+  // #swagger.summary = 'Withdraw one of the caller’s pending appeals'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Appeal id (must belong to the caller).' }
+  /* #swagger.responses[200] = { description: 'The withdrawn appeal', content: { "application/json": { schema: { $ref: "#/components/schemas/Appeal" } } } } */
+  /* #swagger.responses[404] = { description: 'No such appeal for the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Appeal is already resolved', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }),
+  validate,
+  appeals.withdraw,
+)
+
+module.exports = appealsRouter

server/src/router/v1/player/index.js

@@ -0,0 +1,43 @@
+// /api/v1/player — the player self-service surface, assembled from
+// per-capability routers.
+//
+// This file owns exactly two things: the gate every player route shares, and the
+// mount table. No route is declared here. Each capability router mounts at the
+// prefix it already owned inside the old monolithic player.routes.js, so the
+// emitted URL set is byte-identical — proved by a zero-line diff in
+// server/routes.manifest.json (`npm run routes:manifest`).
+//
+// **Staff are a superset of players.** This group is open to any authenticated
+// account, not just role 'player': every read/write is self-scoped to req.user.id,
+// and a staff member has every player ability plus their staff tools on top.
+// Adding a requireRole('player') here would 403 an admin off their own characters
+// (it happened once — see docs/website/BACKEND_DESIGN.md). Staff also reach the
+// identical self-scoped handlers under /admin/shard and /auth/me/account; those
+// are alternative URLs onto the same controllers, not duplicated logic.
+//
+// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
+
+const express = require('express')
+
+const { requireAuth } = require('../../../auth/session.middleware')
+const noindex = require('../../../middleware/noindex')
+
+const accountRouter = require('./account.router')
+const shardRouter = require('./shard.router')
+const appealsRouter = require('./appeals.router')
+
+const playerRouter = express.Router()
+
+// Group gate: authenticated only (no role restriction). Keep it out of search
+// indexes. requireAuth also enforces the account status check (a disabled/banned
+// account is rejected here with 403 before any handler runs).
+//
+// It lives here, ahead of every mount, so a capability router added later cannot
+// silently ship without it.
+playerRouter.use(noindex, requireAuth)
+
+playerRouter.use('/account', accountRouter)
+playerRouter.use('/shard', shardRouter)
+playerRouter.use('/appeals', appealsRouter)
+
+module.exports = playerRouter

server/src/router/v1/player/player.routes.js

@@ -1,296 +0,0 @@
-// ── Player self-service (any authenticated account) ─────────────────────────
-//
-// The player self-service surface: linked game accounts, character/vendor/house
-// reads, and account-credential changes, all self-scoped to the caller by
-// req.user.id. Staff are a *superset* of players — they have every player ability
-// plus their staff tools on top — so this group is open to any authenticated
-// account, not just role 'player'. Staff also reach the identical self-scoped
-// handlers under /admin/shard (they are the same controller); this group lets a
-// staff account use the player surface directly. Handlers are shared with the
-// admin account view (account.controller) — the same TOTP / identity logic, plus
-// the net-new self-scoped credential changes. Future self-service endpoints hang
-// off this group.
-
-const express = require('express')
-const { body, param } = require('express-validator')
-
-const account = require('../admin/account.controller')
-const shard = require('./shard.controller')
-const appeals = require('./appeals.controller')
-const { requireAuth } = require('../../../auth/session.middleware')
-const noindex = require('../../../middleware/noindex')
-const validate = require('../../../middleware/validate')
-const { accountChangeLimiter } = require('../../../middleware/rateLimit')
-
-const playerRouter = express.Router()
-
-// Group gate: authenticated only (no role restriction) — players and staff alike
-// use this self-service surface; every read/write is scoped to the caller. Keep it
-// out of search indexes. requireAuth also enforces the account status check (a
-// disabled/banned account is rejected here with 403 before any handler runs).
-playerRouter.use(noindex, requireAuth)
-
-playerRouter.get(
-  '/account',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Get the current player account (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'The player account', content: { "application/json": { schema: { $ref: "#/components/schemas/PlayerAccount" } } } } */
-  /* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  account.getAccount,
-)
-
-playerRouter.patch(
-  '/account/username',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Change the current player’s username'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangeUsernameRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Updated username (session cookie re-issued)', content: { "application/json": { schema: { type: "object", properties: { username: { type: "string" } } } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error or unavailable username', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Username already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  accountChangeLimiter,
-  body('username').isString().trim().isLength({ min: 3, max: 32 }),
-  validate,
-  account.changeUsername,
-)
-
-playerRouter.patch(
-  '/account/password',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Change or set the current player’s password'
-  // #swagger.description = 'If the account already has a password, currentPassword is required and verified. SSO-provisioned accounts with no password may set an initial one without a current password. On success the caller’s session is re-issued (they stay logged in) while all other sessions are revoked.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChangePasswordRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Password changed', content: { "application/json": { schema: { $ref: "#/components/schemas/OkFlag" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error or wrong current password', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many changes (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  accountChangeLimiter,
-  body('newPassword').isString().isLength({ min: 8, max: 64 }),
-  body('currentPassword').optional({ values: 'falsy' }).isString(),
-  validate,
-  account.changePassword,
-)
-
-// TOTP self-enrollment — identical to the admin account flow (disable requires a
-// valid current code; it does not take a password).
-playerRouter.post(
-  '/account/totp/setup',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Begin 2FA enrollment (returns secret + QR)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'otpauth URL and QR data to scan', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpSetup" } } } } */
-  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  account.totpSetup,
-)
-playerRouter.post(
-  '/account/totp/enable',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Enable 2FA by confirming a code'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
-  /* #swagger.responses[200] = { description: '2FA enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
-  /* #swagger.responses[400] = { description: 'Setup not started, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Two-factor already enabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  body('code').isString().trim().isLength({ min: 6, max: 8 }),
-  validate,
-  account.totpEnable,
-)
-playerRouter.post(
-  '/account/totp/disable',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Disable 2FA by confirming a code'
-  // #swagger.description = 'Requires a valid current authenticator code (proves control of the authenticator); it does not take a password.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TotpCodeRequest" } } } } */
-  /* #swagger.responses[200] = { description: '2FA disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/TotpState" } } } } */
-  /* #swagger.responses[400] = { description: 'Not enabled, or invalid code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  body('code').isString().trim().isLength({ min: 6, max: 8 }),
-  validate,
-  account.totpDisable,
-)
-
-// Linked SSO identities (self-service). Linking itself starts at
-// GET /auth/sso/:provider/link (already behind requireAuth; works for players).
-playerRouter.get(
-  '/account/identities',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'List linked SSO identities (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Linked identities', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/LinkedIdentity" } } } } } */
-  account.listIdentities,
-)
-playerRouter.delete(
-  '/account/identities/:provider',
-  // #swagger.tags = ['Player']
-  // #swagger.summary = 'Unlink an SSO identity (self)'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['provider'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Provider id.' }
-  /* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { $ref: "#/components/schemas/UnlinkedFlag" } } } } */
-  /* #swagger.responses[404] = { description: 'No linked account for that provider', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('provider').matches(/^[a-z0-9-]+$/),
-  validate,
-  account.unlinkIdentity,
-)
-
-// ── Game account linking (uo-link) ─────────────────────────────────────────
-// Link an in-game account with a one-time code from [link, then read the
-// account's roster / vendors (ownership-checked against the local link mirror).
-const ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
-playerRouter.post(
-  '/shard/link',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Link an in-game account with a one-time code'
-  // #swagger.description = 'The player runs [link in game to get a code, then submits it here. The server confirms it with the sidecar and mirrors the link.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */
-  /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  body('code').isString().trim().isLength({ min: 4, max: 32 }),
-  validate,
-  shard.link,
-)
-playerRouter.post(
-  '/shard/account',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Create a game account (hybrid signup) and link it to the caller'
-  // #swagger.description = 'Provisions a new game account with its own username + password and auto-links it to the signed-in website user. Available only when game_account_signup is enabled and the shard accepts website signups. The password is hashed on the shard and never stored or logged by the site.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */
-  /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, linked: { type: "boolean" } } } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error or rejected name/password', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[429] = { description: 'Per-IP account cap reached', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  accountChangeLimiter,
-  body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/),
-  body('password').isString().isLength({ min: 8, max: 64 }),
-  validate,
-  shard.createGameAccount,
-)
-playerRouter.get(
-  '/shard/accounts',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'List the caller’s linked game accounts'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
-  shard.listAccounts,
-)
-playerRouter.get(
-  '/shard/roster/:account',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Character roster for a linked account'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
-  /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('account').matches(ACCOUNT_RE),
-  validate,
-  shard.roster,
-)
-playerRouter.get(
-  '/shard/vendors/:account',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Player vendors for a linked account'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
-  /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('account').matches(ACCOUNT_RE),
-  validate,
-  shard.vendors,
-)
-playerRouter.get(
-  '/shard/char/:serial',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Character sheet — only for a character on the caller’s linked account'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' }
-  /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('serial').matches(/^0x[0-9a-fA-F]+$/),
-  validate,
-  shard.getChar,
-)
-playerRouter.get(
-  '/shard/sales',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
-  shard.getSales,
-)
-playerRouter.get(
-  '/shard/houses',
-  // #swagger.tags = ['Player · Shard']
-  // #swagger.summary = 'The caller’s own houses (home status)'
-  // #swagger.description = 'Houses owned by the caller’s linked accounts, with decay/IDOC status. Only the caller’s own houses — never anyone else’s.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'The caller’s houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
-  shard.getHouses,
-)
-
-// ── Moderation appeals (uo-link / Discord moderation) ──────────────────────
-// A player appeals one of their own ban/mute mod_actions. Ownership is proven by
-// matching the action against the caller's linked Discord identity.
-playerRouter.get(
-  '/appeals',
-  // #swagger.tags = ['Player · Appeals']
-  // #swagger.summary = 'List the caller’s moderation appeals'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'The caller’s appeals', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Appeal" } } } } } */
-  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  appeals.listMine,
-)
-playerRouter.get(
-  '/appeals/eligible',
-  // #swagger.tags = ['Player · Appeals']
-  // #swagger.summary = 'List the caller’s ban/mute actions eligible for appeal'
-  // #swagger.description = 'The caller’s ban/mute mod_actions that have no active appeal. Returns an empty array when the caller has no linked Discord account (the UI shows a “link Discord” hint).'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.responses[200] = { description: 'Appealable actions', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AppealEligibleAction" } } } } } */
-  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  appeals.listEligible,
-)
-playerRouter.post(
-  '/appeals',
-  // #swagger.tags = ['Player · Appeals']
-  // #swagger.summary = 'Submit a moderation appeal for one of the caller’s actions'
-  // #swagger.description = 'Opens an appeal for a ban/mute mod_action that belongs to the caller (its target matches the caller’s linked Discord identity) and has no active appeal.'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateAppealRequest" } } } } */
-  /* #swagger.responses[201] = { description: 'Appeal created', content: { "application/json": { schema: { $ref: "#/components/schemas/Appeal" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error, or the action type is not appealable', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[403] = { description: 'The action does not belong to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[404] = { description: 'Mod action not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'An appeal for this action is already open', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  accountChangeLimiter,
-  body('mod_action_id').isInt({ min: 1 }).toInt(),
-  body('submitted_text').isString().trim().isLength({ min: 1, max: 4000 }),
-  validate,
-  appeals.create,
-)
-playerRouter.post(
-  '/appeals/:id/withdraw',
-  // #swagger.tags = ['Player · Appeals']
-  // #swagger.summary = 'Withdraw one of the caller’s pending appeals'
-  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
-  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Appeal id (must belong to the caller).' }
-  /* #swagger.responses[200] = { description: 'The withdrawn appeal', content: { "application/json": { schema: { $ref: "#/components/schemas/Appeal" } } } } */
-  /* #swagger.responses[404] = { description: 'No such appeal for the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[409] = { description: 'Appeal is already resolved', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  param('id').isInt({ min: 1 }),
-  validate,
-  appeals.withdraw,
-)
-
-module.exports = playerRouter

server/src/router/v1/player/shard.controller.js

@@ -10,6 +10,7 @@
 const uoLinkClient = require('../../../utils/uoLinkClient')
 const shardLinks = require('../../../model/shardLinks/shardLinks.model')
 const shardState = require('../../../model/shardState/shardState.model')
+const shardClilocs = require('../../../model/shardClilocs/shardClilocs.model')
 const settings = require('../../../model/settings/settings.model')
 const { salesForAccounts } = require('../../../utils/shardSales')
 const activity = require('../../../model/activity/activity.model')
@@ -18,9 +19,62 @@ const log = require('../../../utils/logger')('player-shard')
 
 const SERIAL_RE = /^0x[0-9a-fA-F]+$/
 
+/**
+ * Resolve the cliloc ids on a profile into display names.
+ *
+ * Items on the wire carry a `LabelNumber`, not a name — `BridgeProfile.WriteItem`
+ * sends `cliloc` on every equipment entry and `name` only for the minority of
+ * items a player has renamed. Reward titles are the same shape: the shard sends
+ * a cliloc number as a string, which the sheet previously had to SKIP because it
+ * had no way to turn it into words.
+ *
+ * Resolution happens here rather than in the browser because the table is ~123k
+ * rows: shipping it to render a dozen names would dwarf the page, and the
+ * Android client consumes this same JSON and would otherwise need its own copy.
+ *
+ * A shard with no cliloc table configured resolves nothing and the sheet renders
+ * ids exactly as it did before — this is decoration, and it is applied in the
+ * same best-effort block as the guild/governor cross-links.
+ */
+async function resolveProfileClilocs(profile) {
+  const wanted = []
+
+  const equipment = Array.isArray(profile.equipment) ? profile.equipment : []
+  for (const item of equipment) {
+    if (Number.isInteger(item?.cliloc)) wanted.push(item.cliloc)
+  }
+
+  // Reward titles arrive as strings that may be either a literal ("Knight of
+  // Trinsic") or a cliloc number in string form. Only the numeric ones need us.
+  const reward = Array.isArray(profile.titles?.reward) ? profile.titles.reward : []
+  const rewardNumbers = reward.map((r) => (/^\d+$/.test(String(r)) ? Number(r) : null))
+  for (const n of rewardNumbers) if (n !== null) wanted.push(n)
+
+  if (wanted.length === 0) return
+
+  const names = await shardClilocs.resolveMany(wanted)
+  if (names.size === 0) return
+
+  for (const item of equipment) {
+    // A player-given name always wins over the type name: an item called "Bob's
+    // lucky axe" should not be relabelled "hatchet".
+    if (item?.name) continue
+    const resolved = names.get(item?.cliloc)
+    if (resolved) item.clilocName = resolved
+  }
+
+  if (rewardNumbers.some((n) => n !== null)) {
+    profile.titles.rewardResolved = reward.map((raw, i) => {
+      const n = rewardNumbers[i]
+      return n === null ? String(raw) : names.get(n) ?? null
+    })
+  }
+}
+
 // Decorate a char.profile with cross-links from our own board data: the guild the
-// character leads and any city governorship on its account. Best-effort — a
-// failure here never fails the profile (it's a nicety, not the sheet).
+// character leads and any city governorship on its account, plus resolved cliloc
+// names. Best-effort — a failure here never fails the profile (it's a nicety,
+// not the sheet).
 async function enrichCharProfile(profile) {
   if (!profile) return profile
   try {
@@ -30,6 +84,7 @@ async function enrichCharProfile(profile) {
       const govs = await shardState.listGovernorshipsForAccounts([profile.acct])
       if (govs.length) profile.governorOf = govs.map((g) => g.city)
     }
+    await resolveProfileClilocs(profile)
   } catch (err) {
     log.warn('enrichCharProfile failed', { serial: profile.serial, message: err.message })
   }

server/src/router/v1/player/shard.router.js

@@ -0,0 +1,124 @@
+// Player · Shard — game-account linking and the caller's own roster / vendors /
+// characters / sales / houses, ownership-checked against the local link mirror.
+//
+// Mounted at /api/v1/player/shard by player/index.js, which already applied
+// `noindex, requireAuth`. No extra gate: every handler is self-scoped to
+// req.user.id.
+//
+// These are the *same* handlers (player/shard.controller) that admin/shard.router.js
+// serves under /admin/shard for the seven self-service routes — staff are a
+// superset of players, and the controller keys off req.user.id either way. Two
+// URL surfaces, one implementation.
+
+const express = require('express')
+const { body, param } = require('express-validator')
+
+const shard = require('./shard.controller')
+const validate = require('../../../middleware/validate')
+const { accountChangeLimiter } = require('../../../middleware/rateLimit')
+
+const shardRouter = express.Router()
+
+// Link an in-game account with a one-time code from [link, then read the
+// account's roster / vendors (ownership-checked against the local link mirror).
+const ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
+
+shardRouter.post(
+  '/link',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Link an in-game account with a one-time code'
+  // #swagger.description = 'The player runs [link in game to get a code, then submits it here. The server confirms it with the sidecar and mirrors the link.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Linked', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardLinkResult" } } } } */
+  /* #swagger.responses[400] = { description: 'Unknown or expired code', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  body('code').isString().trim().isLength({ min: 4, max: 32 }),
+  validate,
+  shard.link,
+)
+shardRouter.post(
+  '/account',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Create a game account (hybrid signup) and link it to the caller'
+  // #swagger.description = 'Provisions a new game account with its own username + password and auto-links it to the signed-in website user. Available only when game_account_signup is enabled and the shard accepts website signups. The password is hashed on the shard and never stored or logged by the site.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["account","password"], properties: { account: { type: "string" }, password: { type: "string" } } } } } */
+  /* #swagger.responses[201] = { description: 'Account created and linked', content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, linked: { type: "boolean" } } } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error or rejected name/password', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[403] = { description: 'Game-account signup unavailable (site or shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Account name already taken', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Per-IP account cap reached', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  accountChangeLimiter,
+  body('account').matches(/^[A-Za-z0-9][A-Za-z0-9_.-]{2,29}$/),
+  body('password').isString().isLength({ min: 8, max: 64 }),
+  validate,
+  shard.createGameAccount,
+)
+shardRouter.get(
+  '/accounts',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'List the caller’s linked game accounts'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
+  shard.listAccounts,
+)
+shardRouter.get(
+  '/roster/:account',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Character roster for a linked account'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Account roster', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(ACCOUNT_RE),
+  validate,
+  shard.roster,
+)
+shardRouter.get(
+  '/vendors/:account',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Player vendors for a linked account'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'A game account linked to the caller.' }
+  /* #swagger.responses[200] = { description: 'Vendor snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Account not linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('account').matches(ACCOUNT_RE),
+  validate,
+  shard.vendors,
+)
+shardRouter.get(
+  '/char/:serial',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Character sheet — only for a character on the caller’s linked account'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' }
+  /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[403] = { description: 'Character not on an account linked to the caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard unavailable — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('serial').matches(/^0x[0-9a-fA-F]+$/),
+  validate,
+  shard.getChar,
+)
+shardRouter.get(
+  '/sales',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'Recent player-vendor sales for the caller’s linked accounts'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
+  shard.getSales,
+)
+shardRouter.get(
+  '/houses',
+  // #swagger.tags = ['Player · Shard']
+  // #swagger.summary = 'The caller’s own houses (home status)'
+  // #swagger.description = 'Houses owned by the caller’s linked accounts, with decay/IDOC status. Only the caller’s own houses — never anyone else’s.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The caller’s houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
+  shard.getHouses,
+)
+
+module.exports = shardRouter

server/src/router/v1/public/atlas.controller.js

@@ -0,0 +1,134 @@
+// ── Public: the spawn atlas ────────────────────────────────────────────────
+//
+// A browsable catalogue of what the shard CONTAINS — which creatures spawn,
+// where, how many, and which champion altars are configured. Everything here is
+// a plain indexed read of the tables the boot-time import fills from the shard's
+// own ServUO tree (docs/website/SPAWN_ATLAS.md).
+//
+// Two properties separate this from /public/shard/*:
+//
+//   • **Nothing touches the sidecar.** The atlas is static shard content, not
+//     live shard state, so these pages stay fully populated while the shard is
+//     down. That is why the routes are mounted at /public/atlas and are
+//     siteMode-gated like /posts and /wiki, rather than under /shard.
+//   • **The live champion feed is a different thing.** `/atlas/champions` is the
+//     configured roster ("there is an Unholy Terror altar in Deceit");
+//     `/shard/champs` is the running state ("it is on level 3 right now").
+//
+// Every response is still passed through `projectFeature` for the `atlas`
+// feature. It declares no sensitive fields today, so the projection is a
+// no-op — but v3.md §3.6.1's rule is that a read path returning shard data and
+// not projecting is a bug, and the cost of honouring it is one call per handler
+// rather than a retrofit the first time a field needs gating.
+
+const atlas = require('../../../model/shardAtlas/shardAtlas.model')
+const visibility = require('../../../utils/shardVisibility')
+
+const log = require('../../../utils/logger')('public-atlas')
+
+const FEATURE = 'atlas'
+
+// Query params arrive as strings; express-validator has already bounded them.
+const int = (value, fallback) => {
+  const n = Number.parseInt(value, 10)
+  return Number.isFinite(n) ? n : fallback
+}
+
+const str = (value) => (typeof value === 'string' ? value.trim() : '')
+
+// GET /public/atlas/creatures?q=&facet=&limit=&offset=
+async function getCreatures(req, res) {
+  try {
+    const page = await atlas.searchCreatures({
+      q: str(req.query.q),
+      facet: str(req.query.facet),
+      limit: int(req.query.limit, 50),
+      offset: int(req.query.offset, 0),
+    })
+    return res.json(await visibility.project(FEATURE, page, req))
+  } catch (err) {
+    log.error('atlas.getCreatures', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/atlas/creatures/:slug — one creature, with the places it spawns.
+//
+// 404 means "no such creature in this atlas", which also covers "the atlas has
+// never been imported" — an empty atlas has no slugs, and there is nothing more
+// specific to say to an anonymous caller.
+async function getCreature(req, res) {
+  try {
+    const creature = await atlas.getCreature(req.params.slug, {
+      facet: str(req.query.facet),
+      points: int(req.query.points, 200),
+    })
+    if (!creature) return res.status(404).json({ message: 'Not Found' })
+    return res.json(await visibility.project(FEATURE, creature, req))
+  } catch (err) {
+    log.error('atlas.getCreature', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/atlas/regions?facet=&q=
+async function getRegions(req, res) {
+  try {
+    const regions = await atlas.listRegions({
+      facet: str(req.query.facet),
+      q: str(req.query.q),
+    })
+    return res.json(await visibility.project(FEATURE, regions, req))
+  } catch (err) {
+    log.error('atlas.getRegions', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/atlas/landmarks?facet=&q=
+async function getLandmarks(req, res) {
+  try {
+    const landmarks = await atlas.listLandmarks({
+      facet: str(req.query.facet),
+      q: str(req.query.q),
+    })
+    return res.json(await visibility.project(FEATURE, landmarks, req))
+  } catch (err) {
+    log.error('atlas.getLandmarks', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/atlas/champions?facet= — the CONFIGURED altar roster.
+async function getChampions(req, res) {
+  try {
+    const champions = await atlas.listChampions({ facet: str(req.query.facet) })
+    return res.json(await visibility.project(FEATURE, champions, req))
+  } catch (err) {
+    log.error('atlas.getChampions', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/atlas/meta — what is loaded: facets, counts, when it was imported.
+//
+// Public-safe by construction: the model omits the ServUO path, the per-file
+// hashes and the pending-refresh state, all of which describe the operator's
+// filesystem rather than the game world. The admin status route carries those.
+async function getMeta(req, res) {
+  try {
+    return res.json(await visibility.project(FEATURE, await atlas.publicMeta(), req))
+  } catch (err) {
+    log.error('atlas.getMeta', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = {
+  getCreatures,
+  getCreature,
+  getRegions,
+  getLandmarks,
+  getChampions,
+  getMeta,
+}

server/src/router/v1/public/atlas.router.js

@@ -0,0 +1,128 @@
+// Public · Atlas — the spawn atlas / bestiary. Static shard CONTENT derived from
+// the shard's own ServUO tree, not live shard state.
+//
+// Mounted at /api/v1/public/atlas by public/index.js. Two deliberate differences
+// from the /public/shard routes next door (docs/link/v3.md §6):
+//
+//   • **Not under /shard.** Nothing here round-trips the sidecar, and the pages
+//     stay fully populated while the shard is down. Mounting it under /shard
+//     would imply a dependency it does not have.
+//   • **siteMode-gated, like /posts and /wiki.** The shard routes are exempt
+//     because shard status is wanted *during* maintenance; a bestiary is site
+//     content and follows site content's rules.
+//
+// Every route also carries `requireFeature('atlas')` — 404 when an admin has
+// disabled the feature, 403 when the caller sits below its configured audience.
+// The default audience is `anonymous`, so these gates are inert until an admin
+// changes something.
+
+const express = require('express')
+const { param, query } = require('express-validator')
+
+const atlas = require('./atlas.controller')
+const siteMode = require('../../../middleware/siteMode')
+const validate = require('../../../middleware/validate')
+const { requireFeature } = require('../../../utils/shardVisibility')
+
+const atlasRouter = express.Router()
+
+// Facet names come from the shard's own files and are never validated against a
+// list — nothing in the codebase names a facet (§6.1 R2). Only the length is
+// bounded, and the query matches exactly, so an unknown name returns an empty
+// result rather than an error.
+const facetParam = query('facet').optional({ values: 'falsy' }).isString().isLength({ max: 40 })
+
+atlasRouter.get(
+  '/creatures',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'Search the bestiary (paginated)'
+  // #swagger.description = 'Every creature the shard spawns, most numerous first. `total` is how many can be alive at once across all spawners; `points` is how many spawners mention it; `facets` maps facet name to that creature\'s share on it. Static content parsed from the shard\'s ServUO tree — unaffected by the shard being offline.'
+  // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the creature name (max 60 chars).' }
+  // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to creatures spawning on this facet. Facet names come from the shard\'s own files; an unknown one returns an empty page.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, 1..100 (default 50).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'A page of creatures plus the unpaginated total', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasCreaturePage" } } } } */
+  /* #swagger.responses[403] = { description: 'The atlas feature is gated above this caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'The atlas feature is disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }),
+  facetParam,
+  query('limit').optional().isInt({ min: 1, max: 100 }),
+  query('offset').optional().isInt({ min: 0, max: 100000 }),
+  validate,
+  siteMode,
+  atlas.getCreatures,
+)
+atlasRouter.get(
+  '/creatures/:slug',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'One creature: where it spawns, and what spawns with it'
+  // #swagger.description = 'The answer the atlas exists to give. `places` is the aggregate — "lizardman → Shrines, Isamu-Jima, Yew" — resolved by point-in-rect against the shard\'s own region rectangles, falling back to the nearest landmark, else "Wilderness". `spawners` lists the individual spawn points (bounded; `spawnersTruncated` says when the list was cut), and `alsoHere` is what shares those spawners.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Creature slug, e.g. lizardman.' }
+  // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Restrict places and spawners to one facet.' }
+  // #swagger.parameters['points'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max spawners to return, 1..1000 (default 200).' }
+  /* #swagger.responses[200] = { description: 'The creature', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasCreature" } } } } */
+  /* #swagger.responses[404] = { description: 'No such creature in this atlas (or the feature is disabled)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('slug').isString().isLength({ min: 1, max: 120 }),
+  facetParam,
+  query('points').optional().isInt({ min: 1, max: 1000 }),
+  validate,
+  siteMode,
+  atlas.getCreature,
+)
+atlasRouter.get(
+  '/regions',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'Named regions and their rectangles'
+  // #swagger.description = 'Flattened out of the shard\'s nested Regions.xml. `priority` and the rectangles are what placed each spawn point, kept so the placement can be re-derived rather than taken on trust.'
+  // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' }
+  // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the region name.' }
+  /* #swagger.responses[200] = { description: 'Regions, by facet then name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasRegion" } } } } } */
+  facetParam,
+  query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }),
+  validate,
+  siteMode,
+  atlas.getRegions,
+)
+atlasRouter.get(
+  '/landmarks',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'Points of interest (dungeon levels, town markers)'
+  // #swagger.description = 'From the shard\'s Data/Locations files. `group` is the innermost enclosing parent ("Covetous"), which is the label worth showing over the individual marker ("Level 1").'
+  // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' }
+  // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the landmark name or its group.' }
+  /* #swagger.responses[200] = { description: 'Landmarks, by facet then group', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasLandmark" } } } } } */
+  facetParam,
+  query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }),
+  validate,
+  siteMode,
+  atlas.getLandmarks,
+)
+atlasRouter.get(
+  '/champions',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'Configured champion altars (the roster, not the live board)'
+  // #swagger.description = 'Where the altars are and what each one summons — "there is an Unholy Terror altar in Deceit". `randomType` marks altars whose champion is drawn at activation. Do not conflate this with GET /public/shard/champs, which is the live sidecar-fed board ("it is on level 3 right now").'
+  // #swagger.parameters['facet'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet.' }
+  /* #swagger.responses[200] = { description: 'Altars, by facet then name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/AtlasChampion" } } } } } */
+  facetParam,
+  validate,
+  siteMode,
+  atlas.getChampions,
+)
+atlasRouter.get(
+  '/meta',
+  requireFeature('atlas'),
+  // #swagger.tags = ['Public · Atlas']
+  // #swagger.summary = 'What atlas is loaded: facets, counts, when it was imported'
+  // #swagger.description = 'Drives the facet filter and the "parsed from the shard\'s own files on <date>" line. Reports the game world only — the ServUO path, the per-file hashes and any pending refresh are operator detail and live on the admin status route.'
+  /* #swagger.responses[200] = { description: 'Atlas metadata', content: { "application/json": { schema: { $ref: "#/components/schemas/AtlasMeta" } } } } */
+  siteMode,
+  atlas.getMeta,
+)
+
+module.exports = atlasRouter

server/src/router/v1/public/index.js

@@ -0,0 +1,49 @@
+// /api/v1/public — the anonymous public surface, assembled from per-capability
+// routers.
+//
+// This file owns the mount table and nothing else; no route is declared here.
+// Each capability router mounts at the prefix it already owned inside the old
+// monolithic public.routes.js, so the emitted URL set is byte-identical — proved
+// by a zero-line diff in server/routes.manifest.json (`npm run routes:manifest`).
+//
+// **There is deliberately no group gate.** Unlike /admin (staffOnly) and /player
+// (requireAuth), this group is unauthenticated by design and must stay that way:
+// the SPA renders logged-out, the Discord bot reads it anonymously, and the
+// Android app's ShardStreamClient consumes /public/shard/stream with no
+// Authorization header. Content visibility during maintenance is handled by the
+// per-route `siteMode` middleware, not by an auth gate.
+//
+// See docs/website/API_V2_PLAN.md § Phase 2 for the split.
+
+const express = require('express')
+
+const postsRouter = require('./posts.router')
+const wikiRouter = require('./wiki.router')
+const pagesRouter = require('./pages.router')
+const shardRouter = require('./shard.router')
+const atlasRouter = require('./atlas.router')
+const siteRouter = require('./site.router')
+
+const publicRouter = express.Router()
+
+// Content. All three are site-mode gated per route (the /pages draft-preview
+// route is the one deliberate exception — see pages.router.js).
+publicRouter.use('/posts', postsRouter)
+publicRouter.use('/wiki', wikiRouter)
+publicRouter.use('/pages', pagesRouter)
+// Live shard data, never site-mode gated.
+publicRouter.use('/shard', shardRouter)
+// The spawn atlas: static shard CONTENT, parsed from the shard's ServUO tree
+// rather than fetched from the sidecar. Deliberately not under /shard — nothing
+// here depends on the bridge — and site-mode gated per route like the content
+// routers above, which is the other half of that distinction.
+publicRouter.use('/atlas', atlasRouter)
+
+// The four singletons that own no path segment of their own: /settings, /status,
+// /version and /contact. Mounted at the group root, last — safe only because
+// site.router.js declares no router-level middleware (a bare `use(gate)` in a
+// root-mounted router runs for every request passing through toward another
+// mount). Same arrangement as admin/dashboard.router.js.
+publicRouter.use('/', siteRouter)
+
+module.exports = publicRouter

server/src/router/v1/public/pages.router.js

@@ -0,0 +1,40 @@
+// Public · Pages — the block-based CMS pages, read side. Counterpart of
+// admin/pages.router.js (the page builder). Unrelated to /admin/shard/pages,
+// which is the in-game help-page queue.
+//
+// Mounted at /api/v1/public/pages by public/index.js. No group gate.
+//
+// Declaration order is load-bearing: the draft-preview route is registered ahead
+// of /:slug, and it is deliberately NOT site-mode gated so a preview link keeps
+// working during maintenance — the single-use token is the access control.
+
+const express = require('express')
+
+const ctrl = require('./public.controller')
+const siteMode = require('../../../middleware/siteMode')
+
+const pagesRouter = express.Router()
+
+pagesRouter.get(
+  '/:id/preview/:token',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Render a page from a draft-preview token'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Page id.' }
+  // #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Preview token from POST /admin/pages/:id/preview.' }
+  /* #swagger.responses[200] = { description: 'The page (any status)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Token invalid/expired or page missing', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.getPagePreview,
+)
+pagesRouter.get(
+  '/:slug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a published CMS page by slug'
+  // #swagger.description = 'Drafts 404 for the public; staff sessions see drafts. Gated by site mode.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page slug.' }
+  /* #swagger.responses[200] = { description: 'The page', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPage,
+)
+
+module.exports = pagesRouter

server/src/router/v1/public/posts.router.js

@@ -0,0 +1,39 @@
+// Public · Posts — the published news / five-on-friday / newsletter / screenshots
+// feed. The read-only counterpart of admin/posts.router.js, sharing the same
+// posts model through public.controller.
+//
+// Mounted at /api/v1/public/posts by public/index.js. No group gate: this is the
+// anonymous public surface. `siteMode` is applied per route — during maintenance
+// only an admin with a valid session sees content.
+
+const express = require('express')
+
+const ctrl = require('./public.controller')
+const siteMode = require('../../../middleware/siteMode')
+
+const postsRouter = express.Router()
+
+postsRouter.get(
+  '/:category',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List published posts in a category'
+  // #swagger.description = 'Gated by site mode: during maintenance only admins with a valid session see content.'
+  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'news | five-on-friday | newsletter | screenshots' }
+  /* #swagger.responses[200] = { description: 'Published posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPosts,
+)
+postsRouter.get(
+  '/:category/:idOrSlug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a single published post'
+  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Post category.' }
+  // #swagger.parameters['idOrSlug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Numeric id or slug.' }
+  /* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
+  /* #swagger.responses[404] = { description: 'Unknown category or post not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getPost,
+)
+
+module.exports = postsRouter

server/src/router/v1/public/public.routes.js

@@ -1,248 +0,0 @@
-const express = require('express')
-const { body, param, query } = require('express-validator')
-
-const ctrl = require('./public.controller')
-const shard = require('./shard.controller')
-const siteMode = require('../../../middleware/siteMode')
-const validate = require('../../../middleware/validate')
-const { contactLimiter } = require('../../../middleware/rateLimit')
-
-const publicRouter = express.Router()
-
-// Always available (so the client can render the maintenance page + contact).
-publicRouter.get(
-  '/settings',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Public site settings + branding'
-  // #swagger.description = 'Whitelisted, non-sensitive settings plus the per-shard brand block (name/colors/logo/hero/favicon) a client themes itself from, and derived registration / game-account-signup availability flags.'
-  /* #swagger.responses[200] = { description: 'Public settings + branding', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicSettings" } } } } */
-  ctrl.getSettings,
-)
-publicRouter.get(
-  '/status',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Site mode / status'
-  // #swagger.description = 'Current site mode (live or maintenance) so the client can show the maintenance page, plus a version block (service id + API/server versions) for a client first-run probe and version-mismatch guard.'
-  /* #swagger.responses[200] = { description: 'Site status', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicStatus" } } } } */
-  ctrl.getStatus,
-)
-publicRouter.get(
-  '/version',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Backend identity + version'
-  // #swagger.description = 'Lightweight, DB-free descriptor of this backend: a stable service id and the API/server versions. A client uses it to recognize a Runic Gateway backend on first-run and to run a version-mismatch guard. Doubles as a cheap liveness check.'
-  /* #swagger.responses[200] = { description: 'Backend version', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicVersion" } } } } */
-  ctrl.getVersion,
-)
-publicRouter.post(
-  '/contact',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Send a contact message'
-  // #swagger.description = 'Emails the site owner (or falls back to a mailto). Rate limited.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContactRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Message sent', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
-  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
-  /* #swagger.responses[429] = { description: 'Too many messages (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  /* #swagger.responses[502] = { description: 'Mail delivery failed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  contactLimiter,
-  body('message').isString().trim().notEmpty().isLength({ max: 5000 }),
-  body('email').optional({ values: 'falsy' }).isEmail(),
-  body('name').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
-  validate,
-  ctrl.contact,
-)
-
-// Content — gated by site mode (admins with a valid token bypass for preview).
-publicRouter.get(
-  '/posts/:category',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'List published posts in a category'
-  // #swagger.description = 'Gated by site mode: during maintenance only admins with a valid session see content.'
-  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'news | five-on-friday | newsletter | screenshots' }
-  /* #swagger.responses[200] = { description: 'Published posts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/Post" } } } } } */
-  /* #swagger.responses[404] = { description: 'Unknown category', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  siteMode,
-  ctrl.getPosts,
-)
-publicRouter.get(
-  '/posts/:category/:idOrSlug',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Get a single published post'
-  // #swagger.parameters['category'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Post category.' }
-  // #swagger.parameters['idOrSlug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Numeric id or slug.' }
-  /* #swagger.responses[200] = { description: 'The post', content: { "application/json": { schema: { $ref: "#/components/schemas/Post" } } } } */
-  /* #swagger.responses[404] = { description: 'Unknown category or post not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  siteMode,
-  ctrl.getPost,
-)
-publicRouter.get(
-  '/wiki',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'List published wiki pages'
-  /* #swagger.responses[200] = { description: 'Published wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
-  siteMode,
-  ctrl.getWikiList,
-)
-// Static paths must precede the :slug route so they aren't captured as a slug.
-publicRouter.get(
-  '/wiki/categories',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'List wiki categories'
-  /* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
-  siteMode,
-  ctrl.getWikiCategories,
-)
-publicRouter.get(
-  '/wiki/tags',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'List wiki tags'
-  /* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
-  siteMode,
-  ctrl.getWikiTags,
-)
-publicRouter.get(
-  '/wiki/:slug',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Get a single published wiki page'
-  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
-  /* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
-  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  siteMode,
-  ctrl.getWikiPage,
-)
-
-// ── CMS pages (block-based) ────────────────────────────────────────────
-// Preview is registered before /pages/:slug and is NOT site-mode gated, so a
-// draft-preview link keeps working during maintenance. The token itself is the
-// access control.
-publicRouter.get(
-  '/pages/:id/preview/:token',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Render a page from a draft-preview token'
-  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Page id.' }
-  // #swagger.parameters['token'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Preview token from POST /admin/pages/:id/preview.' }
-  /* #swagger.responses[200] = { description: 'The page (any status)', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[404] = { description: 'Token invalid/expired or page missing', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  ctrl.getPagePreview,
-)
-publicRouter.get(
-  '/pages/:slug',
-  // #swagger.tags = ['Public']
-  // #swagger.summary = 'Get a published CMS page by slug'
-  // #swagger.description = 'Drafts 404 for the public; staff sessions see drafts. Gated by site mode.'
-  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Page slug.' }
-  /* #swagger.responses[200] = { description: 'The page', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
-  siteMode,
-  ctrl.getPage,
-)
-
-// ── Shard live data (uo-link) ──────────────────────────────────────────────
-// Token-free, same-origin reads. The status/feed/economy/idoc endpoints read
-// the site's own ingested data; /char round-trips the live shard (cached). Not
-// site-mode gated — shard status is useful even during site maintenance.
-publicRouter.get(
-  '/shard/status',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Shard connection state, online count and latest economy'
-  /* #swagger.responses[200] = { description: 'Shard status', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardStatus" } } } } */
-  shard.getStatus,
-)
-publicRouter.get(
-  '/shard/feed',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Recent notable shard events (from the ingested log)'
-  // #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale.' }
-  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max rows (default 100, max 1000).' }
-  /* #swagger.responses[200] = { description: 'Events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */
-  query('kind').optional({ values: 'falsy' }).isString().isLength({ max: 48 }),
-  query('limit').optional().isInt({ min: 1, max: 1000 }),
-  validate,
-  shard.getFeed,
-)
-publicRouter.get(
-  '/shard/economy',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Gold-supply time series (oldest → newest)'
-  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max samples (default 100, max 1000).' }
-  /* #swagger.responses[200] = { description: 'Economy samples', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEconomyPoint" } } } } } */
-  query('limit').optional().isInt({ min: 1, max: 1000 }),
-  validate,
-  shard.getEconomy,
-)
-publicRouter.get(
-  '/shard/online',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Staff online now (linked staff accounts; location is admin/moderator-only)'
-  /* #swagger.responses[200] = { description: 'Online players', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardOnlinePlayer" } } } } } */
-  shard.getOnline,
-)
-publicRouter.get(
-  '/shard/idoc',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Houses currently in danger (IDOC)'
-  /* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
-  shard.getIdoc,
-)
-publicRouter.get(
-  '/shard/champs',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Current champion-spawn board (all categories)'
-  // #swagger.description = 'The live board of every champion / mini-champ / sea-boss spawn. Update in place via the champ.update / champ.remove frames on /shard/stream.'
-  /* #swagger.responses[200] = { description: 'Champion spawns, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
-  shard.getChamps,
-)
-publicRouter.get(
-  '/shard/guilds',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Current guild board (rosters, alliances, leaders)'
-  // #swagger.description = 'The live board of every guild. Update in place via the guild.update / guild.remove / guild.join frames on /shard/stream.'
-  /* #swagger.responses[200] = { description: 'Guilds, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
-  shard.getGuilds,
-)
-publicRouter.get(
-  '/shard/governors',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Current town-governor board (City Loyalty)'
-  // #swagger.description = 'One entry per city with its governor and election phase. Empty if the shard does not run the City Loyalty system. Live via city.update on /shard/stream.'
-  /* #swagger.responses[200] = { description: 'Cities, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
-  shard.getGovernors,
-)
-publicRouter.get(
-  '/shard/governors/:city/history',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Governor term history for a city'
-  // #swagger.parameters['city'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'City name, e.g. Britain.' }
-  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max terms (default 100, max 500).' }
-  /* #swagger.responses[200] = { description: 'Terms, newest first', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
-  param('city').isString().isLength({ min: 1, max: 40 }),
-  query('limit').optional().isInt({ min: 1, max: 500 }),
-  validate,
-  shard.getGovernorHistory,
-)
-publicRouter.get(
-  '/shard/presence',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Online population aggregate (count + per-facet + per-region)'
-  // #swagger.description = 'The latest presence.online snapshot powering the "Players Online" widget. Live via presence.online on /shard/stream.'
-  /* #swagger.responses[200] = { description: 'Population snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
-  shard.getPresence,
-)
-publicRouter.get(
-  '/shard/houses',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'House registry (owner, co-owners, price, decay)'
-  // #swagger.description = 'Every house seen via the house.update registry feed. `price` is the placement value, not a for-sale flag. Live via house.update / house.remove on /shard/stream.'
-  /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
-  shard.getHouses,
-)
-publicRouter.get(
-  '/shard/stream',
-  // #swagger.tags = ['Public · Shard']
-  // #swagger.summary = 'Live shard event stream (Server-Sent Events, public/safe kinds)'
-  // #swagger.description = 'text/event-stream of curated live events. Sensitive kinds (staff audit, cheat detection, login attempts, IPs) are NOT sent on this channel.'
-  /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
-  shard.stream,
-)
-
-module.exports = publicRouter

server/src/router/v1/public/shard.controller.js

@@ -11,9 +11,10 @@
 
 const shardEvents = require('../../../model/shardEvents/shardEvents.model')
 const shardState = require('../../../model/shardState/shardState.model')
+const shardMarket = require('../../../model/shardMarket/shardMarket.model')
 const uoLinkConfig = require('../../../model/uoLinkConfig/uoLinkConfig.model')
 const broadcast = require('../../../utils/shardBroadcast')
-const auth = require('../../../utils/auth')
+const visibility = require('../../../utils/shardVisibility')
 
 const log = require('../../../utils/logger')('public-shard')
 
@@ -39,21 +40,49 @@ async function getStatus(req, res) {
   }
 }
 
-// GET /public/shard/feed?kind=&limit= — recent notable events from the log,
-// restricted to the public-safe allowlist so staff audit / cheat / link events
-// (which are stored for the admin channel) can never leak to the public.
+// GET /public/shard/feed?kind=&limit= — recent notable events from the log.
+//
+// This is the stored-history twin of the SSE stream, and it must reach the same
+// verdict the stream does about the same event. Two things are therefore resolved
+// against the LIVE config rather than the compiled defaults:
+//
+//   • which kinds this viewer may read at all — `visibleKinds`, not the static
+//     PUBLIC_KINDS set (which is fixed at module load, so an admin moving
+//     `guilds` to `staff` would gate /guilds while /feed kept serving
+//     guild.join to anonymous callers), and
+//   • the payload itself, projected per event against ITS OWN kind's feature —
+//     the rows are a mix of features, and without this the stored frames were
+//     returned verbatim, `acct`/`webId` and all, on an anonymous endpoint.
 async function getFeed(req, res) {
   try {
+    const config = await visibility.getConfig()
+    const level = req.viewerLevel || (await visibility.viewerLevel(req))
+    const allowed = new Set(visibility.visibleKinds(level, config))
+
     const { kind, limit } = req.query
+    // No readable kinds ⇒ nothing to serve. Returning early also keeps us clear
+    // of `list({ kinds: [] })`, which means "no filter", not "match nothing".
+    if (allowed.size === 0) return res.json([])
+
     let events
     if (kind) {
-      // A specific kind is only served if it is itself public-safe.
-      if (!broadcast.PUBLIC_KINDS.has(kind)) return res.json([])
+      if (!allowed.has(kind)) return res.json([])
       events = await shardEvents.list({ kind, limit })
     } else {
-      events = await shardEvents.list({ kinds: [...broadcast.PUBLIC_KINDS], limit })
+      events = await shardEvents.list({ kinds: [...allowed], limit })
     }
-    return res.json(events)
+
+    return res.json(
+      events.map((ev) => ({
+        ...ev,
+        payload: visibility.projectFeature(
+          visibility.KIND_FEATURE.get(ev.kind),
+          ev.payload,
+          level,
+          config,
+        ),
+      })),
+    )
   } catch (err) {
     log.error('shard.getFeed', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -72,18 +101,21 @@ async function getEconomy(req, res) {
 
 // GET /public/shard/online — players online now whose account is linked to a
 // STAFF website user (admin/editor/moderator). Everyone sees that a staff member
-// is online (name + serial); their in-game location (map + coordinates) is only
-// included for privileged viewers (admin/moderator) so it is never exposed to
-// players or the public via the network tab. Non-staff players are never listed.
-function canSeeStaffLocation(req) {
-  const viewer = auth.getUserFromRequest(req)
-  return !!viewer && (viewer.role === 'admin' || viewer.role === 'moderator')
+// is online (name + serial); their in-game location (map + coordinates) is gated
+// on the `presence` feature's `location` field rule, which defaults to `staff`
+// — the same admin/moderator set this used to hardcode. Non-staff players are
+// never listed.
+async function canSeeStaffLocation(req) {
+  const config = await visibility.getConfig()
+  const required = config.presence?.fields?.location || 'staff'
+  const level = req.viewerLevel || (await visibility.viewerLevel(req))
+  return visibility.meets(level, required)
 }
 
 async function getOnline(req, res) {
   try {
     const rows = await shardState.listOnlineLinked()
-    const showLocation = canSeeStaffLocation(req)
+    const showLocation = await canSeeStaffLocation(req)
     return res.json(
       rows.map((r) => {
         const entry = { serial: r.serial, name: r.name }
@@ -103,9 +135,14 @@ async function getOnline(req, res) {
 }
 
 // GET /public/shard/idoc — houses currently in danger (stage IDOC).
+//
+// Projected: shapeHouse flattens the owner actor into `ownerSerial`/`ownerAcct`/
+// `ownerName`, so this endpoint used to hand an anonymous caller the house
+// owner's GAME ACCOUNT NAME. The public IDOC board only ever needed name, region
+// and location — which is all that survives projection below `staff`.
 async function getIdoc(req, res) {
   try {
-    return res.json(await shardState.listIdoc())
+    return res.json(await visibility.project('houses', await shardState.listIdoc(), req))
   } catch (err) {
     log.error('shard.getIdoc', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -117,7 +154,7 @@ async function getIdoc(req, res) {
 // the public SSE stream so the page can update in place.
 async function getChamps(req, res) {
   try {
-    return res.json(await shardState.listChamps())
+    return res.json(await visibility.project('champs', await shardState.listChamps(), req))
   } catch (err) {
     log.error('shard.getChamps', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -126,9 +163,13 @@ async function getChamps(req, res) {
 
 // GET /public/shard/guilds — the current guild board. Served from our store;
 // live via guild.update / guild.remove / guild.join on the public SSE stream.
+//
+// Projected: the stored payload is the raw guild.update frame, whose `leader`
+// actor carries `acct` and `webId`. Those are admin-only and were previously
+// returned verbatim to anonymous callers.
 async function getGuilds(req, res) {
   try {
-    return res.json(await shardState.listGuilds())
+    return res.json(await visibility.project('guilds', await shardState.listGuilds(), req))
   } catch (err) {
     log.error('shard.getGuilds', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -136,10 +177,11 @@ async function getGuilds(req, res) {
 }
 
 // GET /public/shard/governors — the current town-governor board (empty on shards
-// without City Loyalty). Live via city.update on the public SSE stream.
+// without City Loyalty). Live via city.update on the public SSE stream. Projected
+// for the same reason as getGuilds: `governor` / `governorElect` are actors.
 async function getGovernors(req, res) {
   try {
-    return res.json(await shardState.listGovernors())
+    return res.json(await visibility.project('governors', await shardState.listGovernors(), req))
   } catch (err) {
     log.error('shard.getGovernors', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -150,7 +192,8 @@ async function getGovernors(req, res) {
 // (look-back: "who were all the governors of Britain?"), newest first.
 async function getGovernorHistory(req, res) {
   try {
-    return res.json(await shardState.listGovernorHistory(req.params.city, req.query.limit))
+    const terms = await shardState.listGovernorHistory(req.params.city, req.query.limit)
+    return res.json(await visibility.project('governors', terms, req))
   } catch (err) {
     log.error('shard.getGovernorHistory', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -161,7 +204,7 @@ async function getGovernorHistory(req, res) {
 // + per-region). Live via presence.online on the public SSE stream.
 async function getPresence(req, res) {
   try {
-    return res.json(await shardState.latestPresence())
+    return res.json(await visibility.project('presence', await shardState.latestPresence(), req))
   } catch (err) {
     log.error('shard.getPresence', err)
     return res.status(500).json({ message: 'Internal Server Error' })
@@ -185,16 +228,175 @@ async function getHouses(req, res) {
       z: h.z,
       isIdoc: true,
     }))
-    return res.json(publicHouses)
+    // Already a hand-picked safe subset; projected anyway so an admin who
+    // tightens a `houses` field rule sees it honoured on every houses surface
+    // rather than on some of them.
+    return res.json(await visibility.project('houses', publicHouses, req))
   } catch (err) {
     log.error('shard.getHouses', err)
     return res.status(500).json({ message: 'Internal Server Error' })
   }
 }
 
-// GET /public/shard/stream — public live-event SSE channel (safe kinds only).
+// GET /public/shard/ruleset — the shard's published ruleset (Protocol 3.0):
+// expansion, which optional systems are on, skill/stat caps, account and house
+// limits, champion scroll rules, the save/restart schedule. Served from our own
+// store, so it renders while the shard is down; live via world.ruleset on the
+// public SSE stream.
+//
+// `null` means the shard has never published one (an old plugin, or
+// Bridge.RulesetEnabled=false) — a real answer, distinct from a published
+// ruleset, and the page says so rather than rendering an empty one.
+//
+// Projected like every other shard read (§3.6.1's rule: a read path that returns
+// shard data and does not call projectFeature is a bug). The `connect` string is
+// the one configurable field — an operator who published a connect address may
+// still want it behind a login.
+async function getRuleset(req, res) {
+  try {
+    const ruleset = await shardState.getRuleset()
+    if (!ruleset) return res.json(null)
+    return res.json(await visibility.project('ruleset', ruleset, req))
+  } catch (err) {
+    log.error('shard.getRuleset', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// The shard keys boards by its own PointsType enum name (QueensLoyalty,
+// CleanUpBritannia, …). Constrain the path param to that shape before it reaches
+// the model: the column is VARCHAR(48), and an unbounded string here is a needless
+// query on a value that can only ever be an identifier.
+const SYSTEM_RE = /^[A-Za-z][A-Za-z0-9_]{0,47}$/
+
+// GET /public/shard/points — every points/loyalty leaderboard the shard publishes.
+// Served from our own store, so the page renders while the shard is down — which
+// matters more here than for live state: these are standings accumulated over
+// months, and blanking them during a restart would look like a data loss.
+async function getPointsBoards(req, res) {
+  try {
+    const boards = await shardState.listPointsBoards()
+    return res.json(await visibility.project('leaderboards', boards, req))
+  } catch (err) {
+    log.error('shard.getPointsBoards', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/points/:system — one system's board.
+//
+// 404 for a system the shard has never published, matching the sidecar: "no such
+// board" and "a board nobody is on yet" are different answers.
+async function getPointsBoard(req, res) {
+  const { system } = req.params
+  if (!SYSTEM_RE.test(system)) return res.status(400).json({ message: 'Invalid points system.' })
+  try {
+    const board = await shardState.getPointsBoard(system)
+    if (!board) return res.status(404).json({ message: 'Unknown points system.' })
+    return res.json(await visibility.project('leaderboards', board, req))
+  } catch (err) {
+    log.error('shard.getPointsBoard', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// ── Marketplace (Protocol 3.0 vendor.listing) ──────────────────────────────
+//
+// The shard-wide player-vendor index. Served entirely from our own tables — the
+// sidecar is never touched on this path — so shops stay browsable while the shard
+// is down, labelled with how stale they may be.
+//
+// The staleness label is not decoration. The shard sweeps vendors round-robin, so
+// a shop can legitimately be a full cycle behind; a page that implied live prices
+// would send people to a vendor whose item sold twenty minutes ago.
+
+// The serial spelling the bridge uses everywhere: "0x" and hex. Constrained
+// before it reaches the model, like SYSTEM_RE above.
+const SERIAL_RE = /^0x[0-9A-Fa-f]{1,16}$/
+
+const intParam = (value) => {
+  const n = Number.parseInt(value, 10)
+  return Number.isFinite(n) ? n : undefined
+}
+
+// GET /public/shard/market — search the index.
+//
+// Returns LISTINGS, not vendors: "who sells a vanquishing kryss and for how much"
+// is the question, and a vendor-shaped result would make every caller flatten the
+// shops back out.
+async function getMarket(req, res) {
+  try {
+    const page = await shardMarket.search({
+      q: typeof req.query.q === 'string' ? req.query.q : '',
+      minPrice: intParam(req.query.minPrice),
+      maxPrice: intParam(req.query.maxPrice),
+      itemId: intParam(req.query.itemId),
+      map: typeof req.query.map === 'string' ? req.query.map : '',
+      region: typeof req.query.region === 'string' ? req.query.region : '',
+      sort: typeof req.query.sort === 'string' ? req.query.sort : 'price_asc',
+      limit: intParam(req.query.limit) ?? 50,
+      offset: intParam(req.query.offset) ?? 0,
+    })
+    return res.json(await visibility.project('market', page, req))
+  } catch (err) {
+    log.error('shard.getMarket', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/market/meta — index size, staleness, and the filter options
+// (which facets and regions actually hold vendors). Separate from the search so
+// the page can build its filters without running a query it will throw away.
+async function getMarketMeta(req, res) {
+  try {
+    return res.json(await visibility.project('market', await shardMarket.meta(), req))
+  } catch (err) {
+    log.error('shard.getMarketMeta', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/market/vendors/:serial — one shop and its listings.
+//
+// 404 for a serial the index has never seen, which also covers a vendor that has
+// since been dismissed or hidden: to an anonymous caller "no such shop" is the
+// only honest answer, and distinguishing the two would leak that a vendor exists
+// but was hidden.
+async function getMarketVendor(req, res) {
+  const { serial } = req.params
+  if (!SERIAL_RE.test(serial)) return res.status(400).json({ message: 'Invalid vendor serial.' })
+  try {
+    const vendor = await shardMarket.getVendor(serial, {
+      limit: intParam(req.query.limit) ?? 250,
+      offset: intParam(req.query.offset) ?? 0,
+    })
+    if (!vendor) return res.status(404).json({ message: 'Unknown vendor.' })
+    return res.json(await visibility.project('market', vendor, req))
+  } catch (err) {
+    log.error('shard.getMarketVendor', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/features — the shard features THIS caller can actually see,
+// so the SPA (and the Android client) can hide nav entries instead of rendering
+// links that 403. Deliberately reports only what the viewer may reach: the list
+// itself must not disclose the existence of a feature they're gated out of.
+async function getFeatures(req, res) {
+  try {
+    const config = await visibility.getConfig()
+    const level = await visibility.viewerLevel(req)
+    return res.json({ level, features: visibility.visibleFeatures(level, config) })
+  } catch (err) {
+    log.error('shard.getFeatures', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /public/shard/stream — live-event SSE channel. What arrives depends on the
+// caller's audience rung, resolved once at subscribe time; see shardBroadcast.js.
 function stream(req, res) {
-  broadcast.subscribe(req, res, 'public')
+  return broadcast.subscribe(req, res, 'public')
 }
 
 module.exports = {
@@ -209,5 +411,12 @@ module.exports = {
   getGovernorHistory,
   getPresence,
   getHouses,
+  getRuleset,
+  getPointsBoards,
+  getPointsBoard,
+  getMarket,
+  getMarketMeta,
+  getMarketVendor,
+  getFeatures,
   stream,
 }

server/src/router/v1/public/shard.router.js

@@ -0,0 +1,253 @@
+// Public · Shard — token-free, same-origin reads of the live shard. The
+// status/feed/economy/idoc/champs/guilds/governors/presence/houses endpoints read
+// the site's own ingested data; nothing here round-trips the sidecar per request.
+//
+// Mounted at /api/v1/public/shard by public/index.js. Deliberately NOT site-mode
+// gated — shard status is useful (and wanted) while the site itself is in
+// maintenance.
+//
+// **GET /shard/stream stays anonymous.** It is consumed by logged-out browser
+// visitors *and* by the Android ShardStreamClient, neither of which sends an
+// Authorization header; adding requireAuth here blacks out the public live boards
+// on web and mobile. The sensitive kinds (staff audit, cheat detection, login
+// attempts, IPs) are withheld by utils/shardBroadcast.js, not by a route gate —
+// that per-frame filtering is the security boundary, not this file. /stream is
+// deliberately NOT wrapped in requireFeature either: it spans every feature, and
+// each frame is gated individually against the subscriber's rung.
+//
+// Every other route carries `requireFeature(<name>)` (utils/shardVisibility.js),
+// which 404s when an admin has disabled the feature and 403s when the caller sits
+// below its configured audience. Defaults reproduce pre-v3 behavior exactly, so
+// these gates are inert until an admin changes something.
+
+const express = require('express')
+const { param, query } = require('express-validator')
+
+const shard = require('./shard.controller')
+const validate = require('../../../middleware/validate')
+const { marketLimiter } = require('../../../middleware/rateLimit')
+const { requireFeature } = require('../../../utils/shardVisibility')
+
+const shardRouter = express.Router()
+
+shardRouter.get(
+  '/status',
+  requireFeature('status'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Shard connection state, online count and latest economy'
+  /* #swagger.responses[200] = { description: 'Shard status', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardStatus" } } } } */
+  shard.getStatus,
+)
+shardRouter.get(
+  '/feed',
+  requireFeature('activity'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Recent notable shard events (from the ingested log)'
+  // #swagger.description = 'The stored-history twin of /shard/stream, and it reaches the same verdict: which kinds are returned is resolved against the caller\'s audience rung under the live visibility config, and each event\'s payload is field-projected against its own kind\'s feature. Kinds the caller may not read are omitted (an explicit ?kind= for one of them returns []), and acct/webId never appear below admin.'
+  // #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale. Returns [] if the caller may not read that kind.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max rows (default 100, max 1000).' }
+  /* #swagger.responses[200] = { description: 'Events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */
+  query('kind').optional({ values: 'falsy' }).isString().isLength({ max: 48 }),
+  query('limit').optional().isInt({ min: 1, max: 1000 }),
+  validate,
+  shard.getFeed,
+)
+shardRouter.get(
+  '/economy',
+  requireFeature('status'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Gold-supply time series (oldest → newest)'
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max samples (default 100, max 1000).' }
+  /* #swagger.responses[200] = { description: 'Economy samples', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEconomyPoint" } } } } } */
+  query('limit').optional().isInt({ min: 1, max: 1000 }),
+  validate,
+  shard.getEconomy,
+)
+shardRouter.get(
+  '/online',
+  requireFeature('presence'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Staff online now (linked staff accounts; location is admin/moderator-only)'
+  /* #swagger.responses[200] = { description: 'Online players', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardOnlinePlayer" } } } } } */
+  shard.getOnline,
+)
+shardRouter.get(
+  '/idoc',
+  requireFeature('houses'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Houses currently in danger (IDOC)'
+  // #swagger.description = 'Location-level board of the houses about to collapse. Owner identity and price are gated by the `houses` feature\'s field rules (default `staff`), and the owner\'s game account is admin-only always — so an anonymous caller sees name, region and coordinates only.'
+  /* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
+  shard.getIdoc,
+)
+shardRouter.get(
+  '/champs',
+  requireFeature('champs'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Current champion-spawn board (all categories)'
+  // #swagger.description = 'The live board of every champion / mini-champ / sea-boss spawn. Update in place via the champ.update / champ.remove frames on /shard/stream.'
+  /* #swagger.responses[200] = { description: 'Champion spawns, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  shard.getChamps,
+)
+shardRouter.get(
+  '/guilds',
+  requireFeature('guilds'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Current guild board (rosters, alliances, leaders)'
+  // #swagger.description = 'The live board of every guild. Update in place via the guild.update / guild.remove / guild.join frames on /shard/stream.'
+  /* #swagger.responses[200] = { description: 'Guilds, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  shard.getGuilds,
+)
+shardRouter.get(
+  '/governors',
+  requireFeature('governors'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Current town-governor board (City Loyalty)'
+  // #swagger.description = 'One entry per city with its governor and election phase. Empty if the shard does not run the City Loyalty system. Live via city.update on /shard/stream.'
+  /* #swagger.responses[200] = { description: 'Cities, ordered by name', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  shard.getGovernors,
+)
+shardRouter.get(
+  '/governors/:city/history',
+  requireFeature('governors'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Governor term history for a city'
+  // #swagger.parameters['city'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'City name, e.g. Britain.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max terms (default 100, max 500).' }
+  /* #swagger.responses[200] = { description: 'Terms, newest first', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  param('city').isString().isLength({ min: 1, max: 40 }),
+  query('limit').optional().isInt({ min: 1, max: 500 }),
+  validate,
+  shard.getGovernorHistory,
+)
+shardRouter.get(
+  '/presence',
+  requireFeature('presence'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Online population aggregate (count + per-facet + per-region)'
+  // #swagger.description = 'The latest presence.online snapshot powering the "Players Online" widget. Live via presence.online on /shard/stream.'
+  /* #swagger.responses[200] = { description: 'Population snapshot', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  shard.getPresence,
+)
+shardRouter.get(
+  '/houses',
+  requireFeature('houses'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'House registry (owner, co-owners, price, decay)'
+  // #swagger.description = 'Every house seen via the house.update registry feed. `price` is the placement value, not a for-sale flag. Live via house.update / house.remove on /shard/stream.'
+  /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
+  shard.getHouses,
+)
+shardRouter.get(
+  '/ruleset',
+  requireFeature('ruleset'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'The shard\'s published ruleset (expansion, systems, caps, limits)'
+  // #swagger.description = 'How this shard is actually configured, published by the shard itself as one world.ruleset frame: expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules and the save/restart schedule. Served from our own store, so it renders while the shard is down; live via world.ruleset on /shard/stream. Returns `null` if the shard has never published one (an older plugin, or Bridge.RulesetEnabled=false) — distinct from a published ruleset, and the page renders it differently.'
+  /* #swagger.responses[200] = { description: 'The ruleset, or null if never published', content: { "application/json": { schema: { type: "object", nullable: true, additionalProperties: true } } } } */
+  shard.getRuleset,
+)
+shardRouter.get(
+  '/points',
+  requireFeature('leaderboards'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Points / loyalty leaderboards, one board per point system'
+  // #swagger.description = 'Every points/loyalty leaderboard the shard publishes (Queen\'s Loyalty, Void Pool, the nine city loyalties, Clean Up Britannia, …), each with its display name, max points, participant count and top N. Served from our own store, so it renders while the shard is down; live via points.board on /shard/stream. A board\'s display name may arrive as a literal (`nameString`) or a cliloc id (`nameNumber`) — resolve clilocs client-side.'
+  /* #swagger.responses[200] = { description: 'Boards, ordered by display name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardPointsBoard" } } } } } */
+  shard.getPointsBoards,
+)
+shardRouter.get(
+  '/points/:system',
+  requireFeature('leaderboards'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'One points system\'s leaderboard'
+  // #swagger.description = 'A single board by the shard\'s own PointsType name (e.g. `QueensLoyalty`, `CleanUpBritannia`). Returns 404 when the shard has never published that system — distinct from a published board that nobody has scored in yet, which returns 200 with an empty `top`.'
+  /* #swagger.parameters['system'] = { in: 'path', required: true, description: 'PointsType name, e.g. QueensLoyalty', schema: { type: 'string' } } */
+  /* #swagger.responses[200] = { description: 'The board', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardPointsBoard" } } } } */
+  /* #swagger.responses[400] = { description: 'Malformed system name' } */
+  /* #swagger.responses[404] = { description: 'The shard has never published that system' } */
+  shard.getPointsBoard,
+)
+// ── Marketplace ────────────────────────────────────────────────────────────
+//
+// Rate-limited, unlike every other route in this file. These are the first
+// genuinely expensive PUBLIC reads on the site — a LIKE scan plus a COUNT over
+// what is typically the largest shard_* table, reachable with no session.
+shardRouter.get(
+  '/market',
+  requireFeature('market'),
+  marketLimiter,
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Search the player-vendor marketplace'
+  // #swagger.description = 'Every priced listing on every player vendor the shard publishes — the same index the in-game Vendor Search gump reads, and it honours the same per-vendor opt-out, so a player who hid their shop in game is hidden here too. Results are LISTINGS, each carrying enough of its shop to be actionable. Served from the site\'s own tables (the sidecar is not touched), so it renders while the shard is down; `staleAt` is the oldest vendor row and the page must say how far behind the index can be — the shard sweeps vendors round-robin, so prices are inherently up to one full cycle old. Item names are resolved server-side against the cliloc table (docs/website/CLILOCS.md); on a shard that has not configured one, `displayName` is null and clients render the item id.'
+  // #swagger.parameters['q'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Substring match on the resolved item name or the item\'s own literal name (max 60 chars).' }
+  // #swagger.parameters['minPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Lowest price to include.' }
+  // #swagger.parameters['maxPrice'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Highest price to include.' }
+  // #swagger.parameters['itemId'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Exact ItemID (art id) match, for "more like this".' }
+  // #swagger.parameters['map'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one facet. Facet names come from the shard\'s own data; an unknown one returns an empty page.' }
+  // #swagger.parameters['region'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Limit to one named region.' }
+  // #swagger.parameters['sort'] = { in: 'query', required: false, schema: { type: 'string', enum: ['price_asc','price_desc','recent'] }, description: 'Default price_asc. `recent` orders by when the shop was last seen.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, 1..100 (default 50).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'A page of listings plus the unpaginated total and the staleness stamp', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketPage" } } } } */
+  /* #swagger.responses[403] = { description: 'The market feature is gated above this caller', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'The market feature is disabled', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[429] = { description: 'Rate limited', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  query('q').optional({ values: 'falsy' }).isString().isLength({ max: 60 }),
+  query('minPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }),
+  query('maxPrice').optional({ values: 'falsy' }).isInt({ min: 0, max: 999999999 }),
+  query('itemId').optional({ values: 'falsy' }).isInt({ min: 0, max: 65535 }),
+  query('map').optional({ values: 'falsy' }).isString().isLength({ max: 40 }),
+  query('region').optional({ values: 'falsy' }).isString().isLength({ max: 80 }),
+  query('sort').optional({ values: 'falsy' }).isIn(['price_asc', 'price_desc', 'recent']),
+  query('limit').optional().isInt({ min: 1, max: 100 }),
+  query('offset').optional().isInt({ min: 0, max: 100000 }),
+  validate,
+  shard.getMarket,
+)
+shardRouter.get(
+  '/market/meta',
+  requireFeature('market'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Marketplace size, staleness and filter options'
+  // #swagger.description = 'How many vendors and listings the index holds, how stale it may be (`staleAt` = the oldest vendor row, `freshAt` = the newest), and which facets and regions actually hold vendors — so a client can build its filters without running a search it will discard.'
+  /* #swagger.responses[200] = { description: 'Marketplace metadata', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketMeta" } } } } */
+  shard.getMarketMeta,
+)
+shardRouter.get(
+  '/market/vendors/:serial',
+  requireFeature('market'),
+  marketLimiter,
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'One player vendor and everything it is selling'
+  // #swagger.description = 'A single shop by its vendor serial, with its listings. `truncated` (and `total` exceeding `count`) means the shop holds more than the shard publishes per frame — a commodity reseller with thousands of stacks is a real thing, and the page says so rather than presenting a partial shop as complete. Returns 404 for a serial the index has never seen, which also covers a vendor since dismissed or hidden.'
+  /* #swagger.parameters['serial'] = { in: 'path', required: true, description: 'Vendor serial, e.g. 0x40001234', schema: { type: 'string' } } */
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to return, 1..500 (default 250).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Listings to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'The vendor', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardMarketVendor" } } } } */
+  /* #swagger.responses[400] = { description: 'Malformed vendor serial' } */
+  /* #swagger.responses[404] = { description: 'No such vendor in the index' } */
+  param('serial').isString().isLength({ max: 20 }),
+  query('limit').optional().isInt({ min: 1, max: 500 }),
+  query('offset').optional().isInt({ min: 0, max: 100000 }),
+  validate,
+  shard.getMarketVendor,
+)
+shardRouter.get(
+  '/features',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Shard features visible to the caller (drives client nav)'
+  // #swagger.description = 'The caller\'s audience rung plus the shard features they may reach, so a client can hide nav entries instead of rendering links that 403. Reports only what the caller can see — the list itself does not disclose gated features.'
+  /* #swagger.responses[200] = { description: 'Visible features', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardFeatures" } } } } */
+  shard.getFeatures,
+)
+shardRouter.get(
+  '/stream',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Live shard event stream (Server-Sent Events, filtered by audience)'
+  // #swagger.description = 'text/event-stream of live events. The caller\'s audience rung is resolved once at subscribe time and frozen for the connection; each frame is then gated on its feature and field-projected, so sensitive kinds and fields (staff audit, cheat detection, login attempts, IPs, acct/webId) never reach a caller below their configured rung.'
+  /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
+  shard.stream,
+)
+
+module.exports = shardRouter

server/src/router/v1/public/site.router.js

@@ -0,0 +1,67 @@
+// Public · Site — the four group-root singletons: settings, status, version and
+// contact. None of them owns a path segment that could become a prefix, so this
+// is the public group's counterpart to admin/dashboard.router.js: one file for
+// the routes that own no prefix, mounted at the group root.
+//
+// It is safe at the root **only** because this file declares no router-level
+// middleware. A bare `use(gate)` in a root-mounted router runs for every request
+// passing through toward another mount — it would gate /public/wiki and
+// /public/shard/* too. Keep gates on the individual routes here (siteMode is
+// deliberately absent: settings/status/version/contact must answer during
+// maintenance so the client can render the maintenance page and let a visitor
+// get in touch).
+//
+// Mounted at /api/v1/public by public/index.js.
+
+const express = require('express')
+const { body } = require('express-validator')
+
+const ctrl = require('./public.controller')
+const validate = require('../../../middleware/validate')
+const { contactLimiter } = require('../../../middleware/rateLimit')
+
+const siteRouter = express.Router()
+
+siteRouter.get(
+  '/settings',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Public site settings + branding'
+  // #swagger.description = 'Whitelisted, non-sensitive settings plus the per-shard brand block (name/colors/logo/hero/favicon) a client themes itself from, and derived registration / game-account-signup availability flags.'
+  /* #swagger.responses[200] = { description: 'Public settings + branding', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicSettings" } } } } */
+  ctrl.getSettings,
+)
+siteRouter.get(
+  '/status',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Site mode / status'
+  // #swagger.description = 'Current site mode (live or maintenance) so the client can show the maintenance page, plus a version block (service id + API/server versions) for a client first-run probe and version-mismatch guard.'
+  /* #swagger.responses[200] = { description: 'Site status', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicStatus" } } } } */
+  ctrl.getStatus,
+)
+siteRouter.get(
+  '/version',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Backend identity + version'
+  // #swagger.description = 'Lightweight, DB-free descriptor of this backend: a stable service id and the API/server versions. A client uses it to recognize a Runic Gateway backend on first-run and to run a version-mismatch guard. Doubles as a cheap liveness check.'
+  /* #swagger.responses[200] = { description: 'Backend version', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicVersion" } } } } */
+  ctrl.getVersion,
+)
+siteRouter.post(
+  '/contact',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Send a contact message'
+  // #swagger.description = 'Emails the site owner (or falls back to a mailto). Rate limited.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContactRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Message sent', content: { "application/json": { schema: { $ref: "#/components/schemas/Message" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[429] = { description: 'Too many messages (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[502] = { description: 'Mail delivery failed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  contactLimiter,
+  body('message').isString().trim().notEmpty().isLength({ max: 5000 }),
+  body('email').optional({ values: 'falsy' }).isEmail(),
+  body('name').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
+  validate,
+  ctrl.contact,
+)
+
+module.exports = siteRouter

server/src/router/v1/public/wiki.router.js

@@ -0,0 +1,56 @@
+// Public · Wiki — the published wiki: the page list, categories, tags and a
+// single page by slug. Read-only counterpart of admin/wiki.router.js.
+//
+// Mounted at /api/v1/public/wiki by public/index.js. No group gate; `siteMode`
+// is applied per route.
+//
+// Declaration order is load-bearing: `/categories` and `/tags` are literal paths
+// and MUST stay ahead of `/:slug`, or GET /public/wiki/categories dispatches as a
+// wiki page whose slug is "categories". routes.manifest.json sorts its entries
+// and therefore cannot catch a reordering — the same trap admin/wiki.router.js
+// carries (see docs/website/API_V2_PLAN.md § PR 3).
+
+const express = require('express')
+
+const ctrl = require('./public.controller')
+const siteMode = require('../../../middleware/siteMode')
+
+const wikiRouter = express.Router()
+
+wikiRouter.get(
+  '/',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List published wiki pages'
+  /* #swagger.responses[200] = { description: 'Published wiki pages', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiPage" } } } } } */
+  siteMode,
+  ctrl.getWikiList,
+)
+// Static paths must precede the :slug route so they aren't captured as a slug.
+wikiRouter.get(
+  '/categories',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List wiki categories'
+  /* #swagger.responses[200] = { description: 'Wiki categories', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/WikiCategory" } } } } } */
+  siteMode,
+  ctrl.getWikiCategories,
+)
+wikiRouter.get(
+  '/tags',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'List wiki tags'
+  /* #swagger.responses[200] = { description: 'Wiki tags', content: { "application/json": { schema: { type: "array", items: { type: "string" } } } } } */
+  siteMode,
+  ctrl.getWikiTags,
+)
+wikiRouter.get(
+  '/:slug',
+  // #swagger.tags = ['Public']
+  // #swagger.summary = 'Get a single published wiki page'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Wiki page slug.' }
+  /* #swagger.responses[200] = { description: 'The wiki page', content: { "application/json": { schema: { $ref: "#/components/schemas/WikiPage" } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getWikiPage,
+)
+
+module.exports = wikiRouter

server/src/router/v1/v1.router.js

@@ -2,10 +2,10 @@ const express = require('express')
 
 const v1Router = express.Router()
 
-const authRouter = require('./auth/auth.routes')
-const publicRouter = require('./public/public.routes')
+const authRouter = require('./auth')
+const publicRouter = require('./public')
 const adminRouter = require('./admin')
-const playerRouter = require('./player/player.routes')
+const playerRouter = require('./player')
 
 v1Router.use('/auth', authRouter)
 v1Router.use('/public', publicRouter)

server/src/server.js

@@ -14,6 +14,9 @@ const { seedDefaults, createInitialAdminFromEnv } = require('../db/seed')
 const settings = require('./model/settings/settings.model')
 const revokedSessions = require('./model/revokedSessions/revokedSessions.model')
 const mobileAuthBridge = require('./model/mobileAuthBridge/mobileAuthBridge.model')
+const shardAtlas = require('./model/shardAtlas/shardAtlas.model')
+const shardClilocs = require('./model/shardClilocs/shardClilocs.model')
+const shardMarket = require('./model/shardMarket/shardMarket.model')
 const createLogger = require('./utils/logger')
 const { evaluateBotInternalKey } = require('./utils/botInternalKey')
 const brand = require('./config/brand')
@@ -77,6 +80,32 @@ async function start() {
     log.warn('mobile-auth-bridge prune failed', { error: err.message })
   }
 
+  // Re-derive the spawn atlas from the shard's own ServUO tree. The shard's maps
+  // change over its lifetime — facets get added, replaced or renamed — so the
+  // atlas is rebuilt on every boot rather than shipped as a snapshot that would
+  // silently go stale. Hash-gated, so an unchanged tree costs one read pass and
+  // no database write.
+  //
+  // Best-effort by contract: no configured path, an unreadable mount or a
+  // malformed file must never stop the site coming up. A refresh that would
+  // REMOVE a facet is staged for admin approval instead of being applied.
+  await shardAtlas.refreshOnBoot()
+
+  // Refresh the cliloc table (UO's id → display-string map) from the file the
+  // operator converted out of their own client. Same contract as the atlas:
+  // hash-gated so an unchanged file costs one read, and best-effort so a missing
+  // or wrong-format file never stops the site coming up — it just means item
+  // names render as ids, which is what they did before the table existed.
+  const clilocResult = await shardClilocs.refreshOnBoot()
+
+  // A cliloc import changes what item names RESOLVE to, and the marketplace
+  // stores those names denormalized (shard_vendor_items.display_name) so it can
+  // index and search them. The shard's market sweep will not re-send an unchanged
+  // shop just because the site learned what its items are called, so the backfill
+  // has to be pulled rather than waited for. Only after an actual import — the
+  // common boot is hash-gated to a no-op and must stay one.
+  if (clilocResult && clilocResult.status === 'imported') await shardMarket.refreshDisplayNames()
+
   const mode = await settings.get('site_mode')
   log.info(`site mode: ${String(mode || 'live').toUpperCase()}`)
 

server/src/utils/auth.js

@@ -2,7 +2,7 @@
 //
 // The auth logic now lives in server/src/auth/ (token primitives, the session
 // service, and session middleware). This module stays as a thin facade so every
-// existing import site (auth.routes, admin.routes, siteMode, auth.controller)
+// existing import site (the auth/* and admin/* routers, siteMode, auth.controller)
 // keeps working with the exact same names and behavior — nothing else in the
 // codebase needs to change. New code should prefer requiring ../auth/* directly.
 

server/src/utils/clilocParse.js

@@ -0,0 +1,287 @@
+// Cliloc parsing — the pure half.
+//
+// A "cliloc" is UO's localization table: an integer id mapped to a display
+// string. Items carry a `LabelNumber` rather than a name, so without this table
+// the site can only render `id 1023721` where the game shows "quarter staff".
+// The shard already sends the id on every equipment entry (`char.profile`'s
+// `cliloc` field) and will send one per marketplace listing — the *number* was
+// never the missing piece, the *table* was.
+//
+// This module is fs-free on purpose, exactly like `spawnAtlasParse.js`: the
+// suite runs in CI where there is no UO client, so every parser here is driven
+// from inline fixtures. `clilocSource.js` is the only thing that touches disk.
+//
+// ── Two input formats, and why ─────────────────────────────────────────────
+//
+// The client's own `Cliloc.enu` is COMPRESSED (Mythic format) on any modern
+// client, and decompressing it is a bit-level port of an inverse-BWT coder that
+// nothing in this stack needs at runtime. ServUO's own bundled `Ultima.StringList`
+// cannot read it either — which is why `VendorSearch.GetItemName` is already inert
+// on such a shard and the plugin could not supply names even if we asked it to.
+//
+// So the operator converts once, from their own client, and points the site at
+// the result (see docs/website/CLILOCS.md). Two shapes are accepted because
+// different tools produce different things:
+//
+//   • PLAIN BINARY — the pre-compression cliloc layout: a 6-byte header, then
+//     records of {int32 number, byte flag, uint16 length, UTF-8 bytes}.
+//   • DELIMITED TEXT — `number<TAB|,|;>text` per line, which is what the common
+//     GUI exports emit. Quoted CSV fields and a header row are tolerated.
+//
+// Nothing derived from the client is ever committed: the converted file lives at
+// an operator-supplied path and is gitignored, the same rule the spawn atlas art
+// map already follows.
+
+/** Raised for a file we can identify but deliberately refuse to guess at. */
+class ClilocFormatError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'ClilocFormatError'
+    this.code = code
+  }
+}
+
+/**
+ * Bumped when this parser produces DIFFERENT data from an IDENTICAL source file.
+ *
+ * Stored beside the source hash so the boot path can tell "same file, but the
+ * parser moved on" from "same file, nothing to do". Without it a corrected parse
+ * would ship and never reach an install whose cliloc file never changes — the
+ * trap `spawnAtlasSource.PARSER_VERSION` documents.
+ */
+const PARSER_VERSION = 1
+
+// The plain layout's header is `02 00 00 00 01 00` — a 4-byte version and a
+// 2-byte language marker. Only the size matters for parsing; the values are
+// checked to sniff the format, not to validate it.
+const HEADER_BYTES = 6
+const RECORD_HEADER_BYTES = 7 // int32 number + byte flag + uint16 length
+
+// Every compressed cliloc file the client ships begins with a DWORD whose high
+// byte is 0x8E (the XOR key UOFiddler calls `HeaderXorKey`, 0x8E2C9A3D). That is
+// the single cheapest way to tell an operator they exported the wrong file —
+// without it, the plain parser happily reads compressed bytes as ~19k records of
+// negative ids and 60 KB "strings" before dying somewhere in the middle, and the
+// resulting error names the wrong problem.
+const MYTHIC_HIGH_BYTE = 0x8e
+
+/** True when `buffer` is a Mythic-compressed cliloc rather than the plain layout. */
+function isCompressedCliloc(buffer) {
+  return buffer.length >= 4 && buffer[3] === MYTHIC_HIGH_BYTE
+}
+
+/**
+ * Parse the plain binary cliloc layout.
+ *
+ * Strict about truncation, and that strictness is load-bearing: a half-copied or
+ * partly-written file is the realistic failure here, and it must fail loudly
+ * rather than import a silently short table that then renders half the world as
+ * `id 1023721`. A record that runs past the end of the buffer throws.
+ */
+function parseClilocBinary(buffer) {
+  if (!Buffer.isBuffer(buffer)) throw new ClilocFormatError('Not a buffer', 'NOT_BUFFER')
+  if (isCompressedCliloc(buffer)) {
+    throw new ClilocFormatError(
+      'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+        'Convert it to the plain format first — see docs/website/CLILOCS.md.',
+      'COMPRESSED',
+    )
+  }
+  if (buffer.length < HEADER_BYTES) {
+    throw new ClilocFormatError('File is shorter than a cliloc header', 'TRUNCATED')
+  }
+
+  const entries = []
+  let offset = HEADER_BYTES
+
+  while (offset < buffer.length) {
+    if (offset + RECORD_HEADER_BYTES > buffer.length) {
+      throw new ClilocFormatError(
+        `Truncated record header at byte ${offset} (${entries.length} entries read)`,
+        'TRUNCATED',
+      )
+    }
+    const number = buffer.readInt32LE(offset)
+    const flag = buffer.readUInt8(offset + 4)
+    // The length is written by the client as an unsigned 16-bit value. Reading it
+    // signed (as ServUO's own SDK does) turns any string over 32 KB into a
+    // negative length; real tables top out around 12 KB, so this has no effect on
+    // current data and costs nothing to get right.
+    const length = buffer.readUInt16LE(offset + 5)
+    offset += RECORD_HEADER_BYTES
+
+    if (offset + length > buffer.length) {
+      throw new ClilocFormatError(
+        `Truncated record body at byte ${offset} (${entries.length} entries read)`,
+        'TRUNCATED',
+      )
+    }
+    entries.push({ number, flag, text: buffer.toString('utf8', offset, offset + length) })
+    offset += length
+  }
+
+  return entries
+}
+
+// A delimited line splits on the FIRST separator only: cliloc text is full of
+// commas ("a scroll of magery, unfinished") and splitting on all of them would
+// truncate every such entry at its first comma.
+const TEXT_SEPARATORS = ['\t', ',', ';']
+
+/** Unwrap one CSV field: strip surrounding quotes and unescape doubled quotes. */
+function unquote(value) {
+  const trimmed = value.trim()
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return trimmed.slice(1, -1).replace(/""/g, '"')
+  }
+  return trimmed
+}
+
+/**
+ * Parse a delimited text export: `number<sep>text` per line.
+ *
+ * Tolerant by design — this is whatever an operator's GUI tool produced, not a
+ * format we control. A header row, blank lines, `#` comments and a trailing
+ * flags column are all ignored. A line whose first field is not an integer is
+ * skipped rather than fatal, because that is exactly what a header row is.
+ *
+ * The one thing it will NOT do is return an empty table quietly: a file that
+ * yields no entries at all is a wrong file, not an empty one.
+ */
+function parseClilocText(text) {
+  const entries = []
+  for (const line of String(text).split(/\r?\n/)) {
+    // The line is deliberately NOT trimmed before the separator search. Roughly
+    // half of a real cliloc table is empty strings (unused ids), which export as
+    // `1005008<TAB>` — and trimming eats that trailing separator, leaving a bare
+    // number that then looks like a header row and is skipped. That silently
+    // dropped 55,994 of 123,490 entries. Individual FIELDS are trimmed instead,
+    // by `unquote`.
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+
+    // Pick the separator that actually appears first, so a tab-delimited line
+    // whose text contains a comma still splits on the tab.
+    let cut = -1
+    for (const sep of TEXT_SEPARATORS) {
+      const at = line.indexOf(sep)
+      if (at !== -1 && (cut === -1 || at < cut)) cut = at
+    }
+    if (cut === -1) continue
+
+    // An EMPTY first field must not become id 0: `Number('')` is 0, not NaN, so
+    // a line that merely starts with a separator would otherwise import as a
+    // bogus cliloc 0 instead of being skipped.
+    const head = unquote(line.slice(0, cut))
+    if (head === '') continue
+    const number = Number(head)
+    if (!Number.isInteger(number)) continue // header row, or a wrapped line
+
+    let rest = line.slice(cut + 1)
+    // Some exports carry `number,flag,text`. A bare integer in the second field
+    // is a flag; anything else is the text itself (and a text field that IS just
+    // a number is indistinguishable, so it stays as the text — the safer miss).
+    let flag = 0
+    for (const sep of TEXT_SEPARATORS) {
+      const at = rest.indexOf(sep)
+      if (at === -1) continue
+      const head = unquote(rest.slice(0, at))
+      if (/^\d{1,3}$/.test(head) && rest.slice(at + 1).trim() !== '') {
+        flag = Number(head)
+        rest = rest.slice(at + 1)
+      }
+      break
+    }
+
+    entries.push({ number, flag, text: unquote(rest) })
+  }
+
+  if (entries.length === 0) {
+    throw new ClilocFormatError('No cliloc entries found in the text export', 'EMPTY')
+  }
+  return entries
+}
+
+/**
+ * Parse either supported shape, sniffing which one this is.
+ *
+ * The sniff is on the binary header rather than the file extension: operators
+ * name these things whatever they like, and an `.enu` that is really a TSV (or a
+ * `.txt` that is really binary) should still import.
+ */
+function parseCliloc(buffer) {
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer)
+
+  if (isCompressedCliloc(buf)) {
+    throw new ClilocFormatError(
+      'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+        'Convert it to the plain format first — see docs/website/CLILOCS.md.',
+      'COMPRESSED',
+    )
+  }
+
+  // The plain layout always opens with version 2 / language 1. Anything else is
+  // treated as text, which is the recoverable guess: a mis-sniffed text file
+  // yields "no entries found", while a mis-sniffed binary yields nonsense.
+  if (buf.length >= HEADER_BYTES && buf.readInt32LE(0) === 2 && buf.readUInt16LE(4) === 1) {
+    return parseClilocBinary(buf)
+  }
+  return parseClilocText(buf.toString('utf8'))
+}
+
+// ── Display ────────────────────────────────────────────────────────────────
+
+// Cliloc strings interpolate arguments the client supplies out of an item's
+// property list: `~1_val~`, `~2_NAME~`, `~1_ITEM~`. We never have those — the
+// bridge sends the id, not the packet — so a name carrying them must be reduced
+// to what is actually knowable rather than shown with the raw tokens in it.
+const PLACEHOLDER_RE = /~\d+_[^~]*~/g
+
+/**
+ * Reduce a raw cliloc string to something displayable.
+ *
+ * Placeholders are dropped and the leftover punctuation tidied, so
+ * `"[~1_stuff~]"` becomes `""` (correctly nothing — the whole string was the
+ * argument) and `"cold damage ~1_val~%"` becomes `"cold damage"`.
+ *
+ * **Punctuation is only tidied when a placeholder was actually removed.** The
+ * trailing `%` above is the unit belonging to the number we never had, and the
+ * brackets in `[~1_stuff~]` only ever wrapped the argument — but a string with
+ * no placeholder has no such debris, and trimming it anyway corrupts real names.
+ * A shard's `"Runic Gateway Sigil (v2)"` came back as `"(v2"` while this was
+ * unconditional.
+ *
+ * Returns `''` when nothing survives, which callers treat as "no name" and fall
+ * back to the item id — better than showing a bracket.
+ */
+const DEBRIS = /^[\s\-–—,.;:%[\]()]+|[\s\-–—,.;:%[\]()]+$/g
+
+function displayText(raw) {
+  if (raw == null) return ''
+  const source = String(raw)
+  const hadPlaceholder = PLACEHOLDER_RE.test(source)
+  PLACEHOLDER_RE.lastIndex = 0 // the regex is global; `test` advances it
+
+  if (!hadPlaceholder) return source.replace(/\s+/g, ' ').trim()
+
+  return source
+    .replace(PLACEHOLDER_RE, ' ')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([,.;:!?])/g, '$1')
+    .replace(DEBRIS, '')
+    .trim()
+}
+
+/** True when a raw cliloc string is nothing but interpolated arguments. */
+const isPlaceholderOnly = (raw) => raw != null && String(raw).trim() !== '' && displayText(raw) === ''
+
+module.exports = {
+  ClilocFormatError,
+  PARSER_VERSION,
+  HEADER_BYTES,
+  isCompressedCliloc,
+  parseCliloc,
+  parseClilocBinary,
+  parseClilocText,
+  displayText,
+  isPlaceholderOnly,
+}

server/src/utils/clilocSource.js

@@ -0,0 +1,316 @@
+// Cliloc table — the filesystem layer.
+//
+// `clilocParse.js` holds the pure parsers; this module is the only thing that
+// touches cliloc files on disk, and it is shared by both callers:
+//
+//   - the server, which refreshes the table on boot (`shardClilocs.model.js`)
+//   - the admin panel, which can force a reimport without a restart
+//
+// The files are the OPERATOR'S (see docs/website/CLILOCS.md). Nothing derived
+// from them is committed: the repo holds no string table, exactly as it holds no
+// map snapshot and no artwork. That rule is why this module reads a configured
+// path instead of a path inside the repo.
+//
+// ── Why this reads a SET of files, not one ────────────────────────────────
+//
+// Shards edit items and add new ones. Those carry cliloc ids that a stock client
+// table does not have — and forcing a 5 MB client re-export every time an
+// operator adds one item would be miserable enough that the table would simply
+// go stale, which is the exact failure the spawn atlas was redesigned to avoid.
+//
+// So this mirrors `spawnAtlasSource.readSources()`: a BASE table (the converted
+// client file) plus every operator-maintained OVERLAY beside it, all re-read on
+// every boot and hash-gated as a SET. Adding, editing or removing any overlay
+// counts as drift and re-imports. Later sources win, so an overlay both adds new
+// ids and overrides stock ones.
+//
+// Measured on a real shard: the script tree references 16,434 cliloc ids and only
+// 37 are absent from the stock client table. Tens of entries against a 67k base
+// is what makes the overlay the right shape rather than a second full table.
+//
+// Reading and hashing ~5 MB costs a few milliseconds and a full parse ~50 ms, so
+// the boot path hashes first and only parses when something actually changed.
+
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+
+const { ClilocFormatError, PARSER_VERSION, parseCliloc, isCompressedCliloc } = require('./clilocParse')
+
+/**
+ * Filenames looked for as the BASE table when the configured path is a directory.
+ *
+ * Ordered by how specific they are: an explicitly converted file wins over
+ * something that merely sits in a client folder, so an operator who dropped a
+ * `cliloc.plain.enu` next to the original compressed `cliloc.enu` gets the one
+ * they made rather than the one that will be rejected.
+ *
+ * Matching is case-insensitive against the real directory listing, because the
+ * client ships `Cliloc.enu` on Windows and the site usually runs on Linux, where
+ * a hardcoded lowercase open would simply miss.
+ */
+const CANDIDATE_NAMES = [
+  'clilocs.tsv',
+  'clilocs.csv',
+  'clilocs.plain',
+  'cliloc.plain',
+  'cliloc.plain.enu',
+  'cliloc.enu.plain',
+  'clilocs.txt',
+  'cliloc.enu',
+]
+
+/**
+ * Where shard-specific additions and overrides live: a `custom/` directory
+ * beside the base table.
+ *
+ * ServUO has **no server-side convention** for custom clilocs — they live in the
+ * patched client file a shard distributes to its players, and nothing in the
+ * tree declares them. There is therefore nothing to discover, and this is the
+ * one place in the cliloc pipeline that is a convention we chose rather than one
+ * the shard already has. It is a directory rather than a single file so an
+ * operator can keep additions grouped however they like (per system, per patch)
+ * without the site caring.
+ */
+const CUSTOM_DIR = 'custom'
+const CUSTOM_EXTENSIONS = ['.tsv', '.csv', '.txt', '.enu', '.plain']
+
+class ClilocSourceError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'ClilocSourceError'
+    this.code = code
+  }
+}
+
+function sha256(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex')
+}
+
+/**
+ * Resolve the configured path to `{ root, base }`.
+ *
+ * Accepts either a direct file path or a directory to search, because operators
+ * reasonably supply both — "here is the file" and "here is the folder I put it
+ * in" are equally natural answers to the admin panel's prompt. When it is a
+ * file, `root` is the directory CONTAINING it, so overlays work either way: an
+ * operator who pointed at a file should not have to re-point at its folder just
+ * to add a `custom/` directory next to it.
+ */
+function resolveBase(configured) {
+  if (!configured || String(configured).trim() === '') {
+    throw new ClilocSourceError('No cliloc path configured', 'NO_PATH')
+  }
+  const target = String(configured).trim()
+
+  let stat
+  try {
+    stat = fs.statSync(target)
+  } catch {
+    throw new ClilocSourceError(`Cliloc path does not exist: ${target}`, 'NOT_FOUND')
+  }
+
+  if (stat.isFile()) return { root: path.dirname(target), base: target }
+
+  if (!stat.isDirectory()) {
+    throw new ClilocSourceError(`Cliloc path is neither a file nor a directory: ${target}`, 'NOT_FOUND')
+  }
+
+  let listing
+  try {
+    listing = fs.readdirSync(target)
+  } catch {
+    throw new ClilocSourceError(`Cliloc directory is not readable: ${target}`, 'NOT_FOUND')
+  }
+
+  const byLower = new Map(listing.map((name) => [name.toLowerCase(), name]))
+  for (const candidate of CANDIDATE_NAMES) {
+    const actual = byLower.get(candidate)
+    if (actual) return { root: target, base: path.join(target, actual) }
+  }
+
+  throw new ClilocSourceError(
+    `No cliloc file found in ${target} (looked for ${CANDIDATE_NAMES.join(', ')})`,
+    'NO_FILE',
+  )
+}
+
+/** Overlay files under `<root>/custom/`, sorted so precedence is deterministic. */
+function listCustom(root) {
+  const dir = path.join(root, CUSTOM_DIR)
+  let listing
+  try {
+    listing = fs.readdirSync(dir, { withFileTypes: true })
+  } catch (err) {
+    // No overlay directory is the normal case, not an error.
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return []
+    throw new ClilocSourceError(`Cliloc overlay directory is not readable: ${dir}`, 'UNREADABLE')
+  }
+  return listing
+    .filter((e) => e.isFile() && CUSTOM_EXTENSIONS.includes(path.extname(e.name).toLowerCase()))
+    .map((e) => e.name)
+    .sort()
+    .map((name) => path.join(dir, name))
+}
+
+function readFileOrThrow(file) {
+  try {
+    return fs.readFileSync(file)
+  } catch {
+    throw new ClilocSourceError(`Cliloc file is not readable: ${file}`, 'UNREADABLE')
+  }
+}
+
+/**
+ * Read every cliloc source under the configured path.
+ *
+ * Returns `{ root, files: [{ label, kind, file, buffer, sha256, bytes, compressed }] }`
+ * with the base first and overlays after, in the order they must be merged.
+ *
+ * Labels are root-relative and forward-slashed so a hash map compares equal
+ * across platforms — the same directory read on Windows and Linux must produce
+ * the same fingerprint, or every boot would look like a change. (The same
+ * reasoning, and the same bug, as `spawnAtlasSource.readSources`.)
+ */
+function readSources(configured) {
+  const { root, base } = resolveBase(configured)
+
+  const describe = (file, kind) => {
+    const buffer = readFileOrThrow(file)
+    return {
+      label: path.relative(root, file).split(path.sep).join('/'),
+      kind,
+      file,
+      buffer,
+      sha256: sha256(buffer),
+      bytes: buffer.length,
+      compressed: isCompressedCliloc(buffer),
+    }
+  }
+
+  const files = [describe(base, 'base')]
+  for (const overlay of listCustom(root)) files.push(describe(overlay, 'custom'))
+
+  return { root, files }
+}
+
+/**
+ * A fingerprint of every source: `{ "<label>": "<sha256>" }`, plus the base's
+ * details for the admin panel.
+ *
+ * `compressed` is reported here rather than left to the parse because the admin
+ * panel calls this and NOT `readCliloc` (parsing 5 MB on every status poll would
+ * be wasteful). Without it, pointing the setting at an unconverted client
+ * directory reports a perfectly readable file with pending drift — "ready to
+ * import" — and the operator only learns otherwise when the import fails. The
+ * check is four bytes of a buffer already in hand.
+ */
+function hashSources(configured) {
+  const { root, files } = readSources(configured)
+  const hashes = {}
+  for (const file of files) hashes[file.label] = file.sha256
+  const base = files[0]
+  return {
+    root,
+    hashes,
+    file: base.file,
+    bytes: base.bytes,
+    compressed: files.some((f) => f.compressed),
+    customCount: files.length - 1,
+  }
+}
+
+/** True when two source fingerprints describe the same set of files. */
+function sameSources(a, b) {
+  if (!a || !b) return false
+  const aKeys = Object.keys(a).sort()
+  const bKeys = Object.keys(b).sort()
+  if (aKeys.length !== bKeys.length) return false
+  return aKeys.every((key, i) => key === bKeys[i] && a[key] === b[key])
+}
+
+/**
+ * Labels present in `loaded` that are absent from `current`.
+ *
+ * This is the multi-source hazard that a single file did not have. One corrupt
+ * file fails the parse loudly, but a source that has simply VANISHED — an
+ * unmounted volume, a half-copied deploy — parses perfectly and imports a table
+ * quietly missing everything that file contributed. That is the same ambiguity
+ * the spawn atlas escalates for a disappearing facet, so it is escalated here
+ * too rather than applied.
+ */
+function missingSources(current, loaded) {
+  if (!loaded) return []
+  return Object.keys(loaded).filter((label) => !Object.hasOwn(current, label))
+}
+
+/**
+ * Read and parse every source, merged into one entry list.
+ *
+ * Later sources win: the base client table first, then each overlay in sorted
+ * order, so an overlay both ADDS ids the client never had and OVERRIDES stock
+ * ones the shard has re-purposed.
+ *
+ * Returns `{ entries, source }`. Throws `ClilocSourceError` for anything about
+ * the paths and `ClilocFormatError` for anything about the contents — different
+ * problems for an operator (wrong place vs wrong file), and the admin panel says
+ * which. A format error names the file it came from, because "which of my six
+ * overlay files is malformed" is otherwise a guessing game.
+ */
+function readCliloc(configured) {
+  const { root, files } = readSources(configured)
+
+  const merged = new Map()
+  const perSource = []
+
+  for (const file of files) {
+    let entries
+    try {
+      entries = parseCliloc(file.buffer)
+    } catch (err) {
+      if (err instanceof ClilocFormatError) {
+        throw new ClilocFormatError(`${file.label}: ${err.message}`, err.code)
+      }
+      throw err
+    }
+
+    let added = 0
+    let overrode = 0
+    for (const entry of entries) {
+      if (!Number.isInteger(entry.number)) continue
+      if (merged.has(entry.number)) overrode++
+      else added++
+      merged.set(entry.number, entry)
+    }
+    perSource.push({ label: file.label, kind: file.kind, entries: entries.length, added, overrode })
+  }
+
+  return {
+    entries: [...merged.values()],
+    source: {
+      root,
+      file: files[0].file,
+      sha256: files[0].sha256,
+      bytes: files[0].bytes,
+      hashes: Object.fromEntries(files.map((f) => [f.label, f.sha256])),
+      parserVersion: PARSER_VERSION,
+      sources: perSource,
+    },
+  }
+}
+
+module.exports = {
+  ClilocFormatError,
+  ClilocSourceError,
+  PARSER_VERSION,
+  CANDIDATE_NAMES,
+  CUSTOM_DIR,
+  CUSTOM_EXTENSIONS,
+  resolveBase,
+  listCustom,
+  readSources,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+}

server/src/utils/shardBroadcast.js

@@ -2,67 +2,66 @@
 //
 // The browser can't talk to the sidecar's WebSocket directly (the token must
 // never reach it, and the WS may be on another host). Instead the server ingests
-// the WS feed and re-broadcasts curated events to browsers over Server-Sent
-// Events (plain HTTP — works through any reverse proxy).
+// the WS feed and re-broadcasts events to browsers over Server-Sent Events
+// (plain HTTP — works through any reverse proxy).
 //
-// Two channels:
-//   • public — safe kinds only (sales, deaths, IDOC, logins, economy). No IPs,
-//     no account-login attempts, no staff audit / cheat events.
-//   • admin  — everything, including the sensitive kinds above.
+// Since Protocol 3.0 the split is no longer "one public channel with a static
+// allowlist plus one admin channel". Each subscriber carries the audience rung
+// it resolved to at subscribe time, and every frame is
+//
+//   1. mapped kind → feature (an UNMAPPED kind reaches nobody below admin —
+//      fail closed; see utils/shardVisibility.js rule 2),
+//   2. gated on that feature being enabled, streamed, and within the viewer's
+//      rung, and
+//   3. passed through field projection, so `acct` / `webId` and any field an
+//      admin has re-gated are stripped per viewer.
+//
+// **This is the security boundary.** It used to be the PUBLIC_KINDS set in this
+// file; it is now the kind map plus the visibility config. PUBLIC_KINDS still
+// exists and is still exported, but it is now DERIVED from the kind map (see
+// shardVisibility.js) so the two can no longer drift.
 //
 // shardIngest calls broadcast(event) for each ingested event; the public/admin
 // SSE route handlers call subscribe(req, res, channel).
 
+const visibility = require('./shardVisibility')
 const log = require('./logger')('shard-broadcast')
 
-// Kinds safe to expose to unauthenticated browsers. Note: vendor.sale is
-// deliberately NOT here — sales are owner-private (a linked player sees only
-// their own, via /player/shard/sales).
-const PUBLIC_KINDS = new Set([
-  'player.death',
-  'player.murdered',
-  'mob.killed',
-  'house.decay',
-  'quest.complete',
-  'skill.gain',
-  'fame.change',
-  'karma.change',
-  'mob.login',
-  'mob.logout',
-  'economy.supply',
-  'server.hello',
-  'server.shutdown',
-  'server.crashed',
-  // Champion-spawn board deltas — the public Champions page renders these live.
-  'champ.update',
-  'champ.remove',
-  // Protocol 2.0 boards — public, rendered live on their respective pages.
-  'guild.update',
-  'guild.remove',
-  'guild.join',
-  'city.update',
-  'presence.online',
-  'region.enter',
-  // NOTE: house.update / house.remove (the full registry — owner, price, co-owners)
-  // are deliberately NOT public. The public Houses page shows only IDOC houses (via
-  // house.decay, which is public above) with location only; the full registry is
-  // staff-only and rides the admin SSE channel. See public/shard.controller getHouses.
-])
+// Re-exported for back-compat: shardEvents `/feed` filtering and
+// config/notificationStreams.js both ask "is this kind public-safe?".
+const { PUBLIC_KINDS } = visibility
 
-// Open response streams per channel.
+// Open streams. Each entry is { res, level }. The admin bucket is kept separate
+// because it is unconditional and must not depend on a config read.
 const clients = { public: new Set(), admin: new Set() }
 
 const KEEPALIVE_MS = 25000
 
 // Register an SSE stream on a channel. Sets the SSE headers, sends an initial
 // comment, keeps the connection warm with periodic pings, and cleans up on close.
-function subscribe(req, res, channel) {
+//
+// The viewer's rung is resolved ONCE, here, and frozen for the life of the
+// connection — a long-lived stream must not silently gain privilege because the
+// caller's session changed underneath it. (Config changes, by contrast, DO take
+// effect live: the config is read per broadcast, cached ~5s.)
+async function subscribe(req, res, channel) {
   const bucket = clients[channel]
   if (!bucket) {
     res.status(400).end()
     return
   }
 
+  let level = 'admin'
+  if (channel === 'public') {
+    try {
+      level = await visibility.viewerLevel(req)
+    } catch (err) {
+      // Fail closed: an unresolvable viewer is anonymous, not privileged.
+      log.warn('viewerLevel failed on subscribe; treating as anonymous', { message: err.message })
+      level = 'anonymous'
+    }
+  }
+
   res.writeHead(200, {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache, no-transform',
@@ -72,9 +71,10 @@ function subscribe(req, res, channel) {
   res.write('retry: 5000\n\n') // tell EventSource to reconnect after 5s if dropped
   res.write(': connected\n\n')
 
-  bucket.add(res)
+  const client = { res, level, ping: null }
+  bucket.add(client)
 
-  const ping = setInterval(() => {
+  client.ping = setInterval(() => {
     try {
       res.write(': ping\n\n')
     } catch {
@@ -82,45 +82,80 @@ function subscribe(req, res, channel) {
     }
   }, KEEPALIVE_MS)
 
-  const cleanup = () => {
-    clearInterval(ping)
-    bucket.delete(res)
-  }
+  const cleanup = () => drop(bucket, client)
   req.on('close', cleanup)
   res.on('error', cleanup)
 }
 
-function writeTo(bucket, payload) {
-  for (const res of bucket) {
+// The ONLY way a client leaves a bucket. Clearing the keepalive here (rather
+// than only in the close handler) matters: a client dropped because its write
+// threw never fires `req.close`, so its interval would otherwise keep firing on
+// a dead socket for the life of the process.
+function drop(bucket, client) {
+  clearInterval(client.ping)
+  bucket.delete(client)
+}
+
+function writeTo(bucket, client, payload) {
   try {
-      res.write(payload)
+    client.res.write(payload)
   } catch (err) {
     log.warn('sse write failed; dropping client', { message: err.message })
-      bucket.delete(res)
-    }
+    drop(bucket, client)
   }
 }
 
-// Fan an ingested event out to the admin channel (always) and the public
-// channel (safe kinds only). A no-op when nobody is subscribed.
-function broadcast(event) {
+// Fan an ingested event out. The admin channel gets it verbatim, always. Public
+// subscribers are filtered and projected per their own rung — so two viewers on
+// the same channel can legitimately receive different versions of one frame, or
+// one of them nothing at all.
+async function broadcast(event) {
   if (!event || !event.kind) return
+
+  if (clients.admin.size) {
     const frame = `data: ${JSON.stringify(event)}\n\n`
-  if (clients.admin.size) writeTo(clients.admin, frame)
-  if (clients.public.size && PUBLIC_KINDS.has(event.kind)) writeTo(clients.public, frame)
+    for (const client of [...clients.admin]) writeTo(clients.admin, client, frame)
   }
 
-// Close every open stream (graceful shutdown).
-function closeAll() {
-  for (const channel of Object.values(clients)) {
-    for (const res of channel) {
+  if (!clients.public.size) return
+
+  let config
   try {
-        res.end()
+    config = await visibility.getConfig()
+  } catch (err) {
+    // Fail closed: without a config we cannot prove a frame is safe to send.
+    log.error('visibility config unavailable; withholding public frame', err)
+    return
+  }
+
+  // Most frames land on one rung set, so cache the serialised payload per level
+  // instead of re-projecting and re-stringifying for every subscriber.
+  const byLevel = new Map()
+  for (const client of [...clients.public]) {
+    let frame = byLevel.get(client.level)
+    if (frame === undefined) {
+      frame = visibility.kindVisibleTo(event.kind, client.level, config)
+        ? `data: ${JSON.stringify(visibility.projectFeature(visibility.KIND_FEATURE.get(event.kind), event, client.level, config))}\n\n`
+        : null
+      byLevel.set(client.level, frame)
+    }
+    if (frame) writeTo(clients.public, client, frame)
+  }
+}
+
+// Close every open stream (graceful shutdown). Clears each keepalive timer too —
+// without that the intervals keep the event loop alive after the streams are
+// gone, and the process won't exit.
+function closeAll() {
+  for (const bucket of Object.values(clients)) {
+    for (const client of [...bucket]) {
+      drop(bucket, client)
+      try {
+        client.res.end()
       } catch {
         /* ignore */
       }
     }
-    channel.clear()
   }
 }
 

server/src/utils/shardIngest.js

@@ -15,7 +15,9 @@
 const shardEventsModel = require('../model/shardEvents/shardEvents.model')
 const shardStateModel = require('../model/shardState/shardState.model')
 const shardLinksModel = require('../model/shardLinks/shardLinks.model')
+const shardMarketModel = require('../model/shardMarket/shardMarket.model')
 const uoLinkConfigModel = require('../model/uoLinkConfig/uoLinkConfig.model')
+const settingsModel = require('../model/settings/settings.model')
 const broadcaster = require('./shardBroadcast')
 const pushDispatch = require('./pushDispatch')
 const defaultLog = require('./logger')('shard-ingest')
@@ -62,6 +64,31 @@ function shouldLog(event) {
   return LOGGED_KINDS.has(event.kind)
 }
 
+// ServUO's stock Server.cfg name. An operator who never set one publishes this
+// verbatim, so it carries no more information than a blank — matched
+// case-insensitively and trim-tolerantly, but ONLY as an exact whole value: a
+// shard genuinely called "My Shard Reborn" keeps its name.
+const STOCK_SHARD_NAME = 'my shard'
+
+/**
+ * The name to publish for the shard: its own, or this instance's when it has
+ * effectively not given one.
+ *
+ * Deliberately not a general "blank means brand" rule applied across the wire —
+ * it is scoped to this one field, where the two names denote the same thing.
+ */
+async function resolveShardName(shard, deps) {
+  const given = String(shard ?? '').trim()
+  if (given !== '' && given.toLowerCase() !== STOCK_SHARD_NAME) return given
+  try {
+    return (await deps.settings.getInstanceName()) || given
+  } catch {
+    // A ruleset that publishes the stock name is still better than one that
+    // fails to store because the settings read hiccuped.
+    return given
+  }
+}
+
 // Apply the state-change side effect for a kind (if any). Returns a promise.
 async function applyStateChange(event, deps) {
   const { shardState, uoLinkConfig, log } = deps
@@ -173,6 +200,42 @@ async function applyStateChange(event, deps) {
     case 'house.remove':
       await shardState.removeHouse(event.serial)
       return
+    // ── Protocol 3.0 ─────────────────────────────────────────────────────
+    // The shard re-emits its whole ruleset on every sidecar connect, so this is
+    // an overwrite, not an append — and deliberately NOT in LOGGED_KINDS: it
+    // would put a duplicate row in the event log on every reconnect, and
+    // server.hello already marks each of those.
+    case 'world.ruleset':
+      // A shard whose operator never edited Server.cfg publishes ServUO's stock
+      // "My Shard". That is the shard saying *unnamed*, not a name, so the site
+      // answers with its own — the rules page reading "My Shard" under a header
+      // reading UOMysticmoon is the shard failing to introduce itself.
+      //
+      // Normalized HERE rather than on read because the ruleset is also live: the
+      // same `event` object is handed to the SSE broadcast a few lines below, and
+      // a read-time fix would be undone by the next reconnect's frame.
+      event.shard = await resolveShardName(event.shard, deps)
+      await shardState.setRuleset(event)
+      return
+    // Board state, like guild.update — the newest frame for a system replaces the
+    // previous one, so it is NOT in LOGGED_KINDS. Logging would append a row every
+    // time anyone's score moved the top ten, which is a board, not an event.
+    case 'points.board':
+      await shardState.upsertPointsBoard(event)
+      return
+    // Player-vendor market index. Each frame is authoritative for one shop, so
+    // the model replaces that vendor's whole listing set rather than merging.
+    //
+    // NOT in LOGGED_KINDS, and this is the strongest case of the three v3 kinds:
+    // one frame carries up to 250 listings, the sweep re-emits a shop on any
+    // price change, and appending each of those to the event log would make
+    // shard_events mostly a price history nobody reads. The market IS the state.
+    case 'vendor.listing':
+      await deps.shardMarket.upsertVendor(event)
+      return
+    case 'vendor.listing.remove':
+      await deps.shardMarket.removeVendor(event.serial)
+      return
     case 'account.unlinked':
       // A player ran [unlink in game (or a site-side unlink echoed back) — drop
       // our local link mirror so attribution stops immediately.
@@ -195,7 +258,9 @@ function resolveDeps(deps) {
     shardEvents: deps.shardEvents || shardEventsModel,
     shardState: deps.shardState || shardStateModel,
     shardLinks: deps.shardLinks || shardLinksModel,
+    shardMarket: deps.shardMarket || shardMarketModel,
     uoLinkConfig: deps.uoLinkConfig || uoLinkConfigModel,
+    settings: deps.settings || settingsModel,
     broadcast: deps.broadcast || broadcaster.broadcast,
     pushDispatch: deps.pushDispatch || pushDispatch.fromShardEvent,
     log: deps.log || defaultLog,
@@ -229,11 +294,12 @@ async function ingest(event, deps = {}) {
   }
 
   if (!deps.fromBackfill) {
-    try {
-      d.broadcast(event)
-    } catch (err) {
-      d.log.warn('broadcast failed', { kind: event.kind, message: err.message })
-    }
+    // Broadcast is async since v3 (it reads the visibility config to decide what
+    // each subscriber may see). Fire-and-forget, like the push fan-out below: a
+    // slow config read must never delay or fail ingest.
+    Promise.resolve(d.broadcast(event)).catch((err) =>
+      d.log.warn('broadcast failed', { kind: event.kind, message: err.message }),
+    )
     // Opt-in push fan-out, off the same event source as the SSE broadcast.
     // Fire-and-forget (a slow/dead ntfy relay must never delay or fail ingest);
     // fromShardEvent is self-guarding, but .catch() covers any lookup rejection.

server/src/utils/shardVisibility.js

@@ -0,0 +1,435 @@
+// ── Shard feature visibility ───────────────────────────────────────────────
+//
+// Admin-configurable, per-feature and per-field audience control over every
+// shard-derived surface on the site. Replaces the hardcoded split that used to
+// live in two places (the PUBLIC_KINDS allowlist in shardBroadcast.js, and the
+// ad-hoc `canSeeStaffLocation` style checks in the public controllers).
+//
+// Design rules (docs/link/v3.md §3):
+//
+//   • Visibility lives HERE, on the website — never in the sidecar. The sidecar
+//     is a dumb forwarder: it accepts frames, stores them, forwards them
+//     verbatim, and serves store-backed reads. It defines no audiences.
+//   • Every default reproduces the behavior that shipped before this module, so
+//     installing it changes nothing until an admin edits the config.
+//   • Two rules an admin CANNOT override:
+//       1. `acct` / `webId` are admin-only, always. They are not in-game
+//          visible (unlike a character name) and are not configurable fields.
+//       2. A kind absent from KIND_FEATURE is never broadcast below `admin`.
+//          Fail closed — this is what keeps the kind map a security boundary
+//          rather than a convenience filter.
+//
+// The audience ladder is ordered; each rung implies the ones below it.
+
+const db = require('../model/shardVisibility/shardVisibility.model')
+const shardLinks = require('../model/shardLinks/shardLinks.model')
+const auth = require('./auth')
+const log = require('./logger')('shard-visibility')
+
+// ── The ladder ─────────────────────────────────────────────────────────────
+
+const LADDER = ['anonymous', 'logged_in', 'player', 'staff', 'admin']
+const RANK = new Map(LADDER.map((level, i) => [level, i]))
+
+const isLevel = (level) => RANK.has(level)
+
+// The two fallbacks are deliberately ASYMMETRIC, and the asymmetry is the whole
+// point: an unrecognised value must always lose. A single shared fallback cannot
+// do that — whichever direction it picks, it fails open on one side. So:
+//
+//   • an unknown VIEWER level floors to the bottom rung (grants nothing), and
+//   • an unknown REQUIREMENT ceils to the top rung (satisfied by nobody but admin).
+//
+// With one `rank()` defaulting to admin, a viewer level that fell through (a
+// typo, a future rung this build doesn't know, a value from a caller that
+// skipped viewerLevel) would have been treated as an ADMIN and passed every gate.
+const viewerRank = (level) => RANK.get(level) ?? 0
+const requiredRank = (level) => RANK.get(level) ?? RANK.get('admin')
+
+// True when a viewer at `viewer` satisfies a requirement of `required`.
+const meets = (viewer, required) => viewerRank(viewer) >= requiredRank(required)
+
+// Exported for tests/diagnostics; `meets` is what callers should use.
+const rank = viewerRank
+
+// ── Features ───────────────────────────────────────────────────────────────
+//
+// All ten shard surfaces: the six that shipped before v3 plus the four v3 adds.
+// `fields` lists only the SENSITIVE fields — those an admin may re-gate. A field
+// not listed here is visible whenever the feature itself is.
+//
+// LOCKED_FIELDS are exempt from configuration entirely (rule 1 above).
+
+const LOCKED_FIELDS = { acct: 'admin', webId: 'admin' }
+
+// Rule 1 matches on the FIELD'S MEANING, not on one exact spelling. The wire
+// frames nest actors (`leader.acct`), but several read models flatten them
+// instead (`shapeHouse` emits `ownerAcct`, `shapeGuild`'s fallback emits
+// `leaderAcct`/`leaderWebId`), and an exact-key check silently missed every
+// flattened one — which is how `GET /public/shard/idoc` served `ownerAcct` to
+// anonymous callers while the same account name was correctly stripped from the
+// live `house.decay` frame.
+//
+// So a key is locked when it IS `acct`/`webId` or ENDS in one, case-insensitively
+// (`ownerAcct`, `leaderWebId`, `governorAcct`). Suffix matching is what makes this
+// fail closed for shapes nobody has written yet.
+const LOCKED_SUFFIXES = ['acct', 'webid']
+const isLockedField = (key) => {
+  const k = String(key).toLowerCase()
+  return LOCKED_SUFFIXES.some((suffix) => k === suffix || k.endsWith(suffix))
+}
+
+const FEATURES = {
+  // ── Shipped before v3. Defaults reproduce the previous hardcoded behavior. ──
+  status: { audience: 'anonymous', fields: {} },
+  activity: { audience: 'anonymous', fields: {} },
+  champs: { audience: 'anonymous', fields: {} },
+  guilds: { audience: 'anonymous', fields: {} },
+  governors: { audience: 'anonymous', fields: {} },
+  // The public Houses page showed IDOC location only; owner/price were staff.
+  // `owner` is the actor object on the house.decay/house.update frames;
+  // `ownerName`/`ownerSerial` are the flattened spellings shapeHouse emits on the
+  // REST read models. Both are listed so one rule covers the wire and the read
+  // model — the flattened `ownerAcct` needs no entry, being locked by rule 1.
+  houses: {
+    audience: 'anonymous',
+    fields: { owner: 'staff', ownerName: 'staff', ownerSerial: 'staff', price: 'staff' },
+  },
+  // /public/shard/online listed linked staff to everyone but gated location to
+  // admin+moderator — which is exactly the `staff` rung.
+  presence: { audience: 'anonymous', fields: { location: 'staff' } },
+
+  // ── New in v3. ──
+  ruleset: { audience: 'anonymous', fields: { connect: 'anonymous' } },
+  atlas: { audience: 'anonymous', fields: {} },
+  // `name` is the ranked character's name inside points.board's `top` entries, and
+  // it is spelled the way the WIRE spells it, not the way v3.md §7.4 describes it
+  // ("characterName"). projectValue matches on the literal JSON key, so a rule
+  // named for the field's meaning rather than its key silently does nothing — the
+  // same failure §3.6.1 records for the flattened `ownerAcct` spelling. Within a
+  // leaderboards payload `name` can only be a character name: the board's own
+  // display name arrives as `nameString`/`nameNumber`.
+  leaderboards: { audience: 'anonymous', fields: { name: 'anonymous' } },
+  // Shop name, owner character name and vendor location are already globally
+  // visible in-game via the stock Vendor Search gump, so publishing them is not
+  // a new disclosure — but they stay configurable so an admin can tighten them.
+  //
+  // `ownerName` and `location` were pre-wired here by Part A, before the frame
+  // existed; both were re-checked against the real `vendor.listing` and both are
+  // genuine keys on it (unlike leaderboards' `characterName`, which was inert).
+  // `location` is a NESTED object on the wire and on the read model precisely so
+  // that one rule hides map, coordinates, region and house together — five flat
+  // keys would be five rules that drift apart.
+  //
+  // `ownerSerial` is listed alongside `ownerName` for the same reason `houses`
+  // lists both: an admin who hides the owner's name and is left with a serial
+  // that every other board resolves back to that name has not hidden anything.
+  market: {
+    audience: 'anonymous',
+    fields: { ownerName: 'anonymous', ownerSerial: 'anonymous', location: 'anonymous' },
+  },
+}
+
+const FEATURE_NAMES = Object.keys(FEATURES)
+const isFeature = (name) => Object.hasOwn(FEATURES, name)
+
+// ── Kind → feature ─────────────────────────────────────────────────────────
+//
+// Every event kind that may ever leave the admin channel must appear here.
+// Anything else is admin-only by omission (rule 2). This map is seeded from
+// what PUBLIC_KINDS listed before v3, so the public stream carries exactly the
+// same kinds it did — now attributed to a feature that an admin can re-gate.
+
+const KIND_FEATURE = new Map(
+  Object.entries({
+    // status / lifecycle
+    'server.hello': 'status',
+    'server.shutdown': 'status',
+    'server.crashed': 'status',
+    'economy.supply': 'status',
+    // activity feed
+    'player.death': 'activity',
+    'player.murdered': 'activity',
+    'mob.killed': 'activity',
+    'quest.complete': 'activity',
+    'skill.gain': 'activity',
+    'fame.change': 'activity',
+    'karma.change': 'activity',
+    'mob.login': 'activity',
+    'mob.logout': 'activity',
+    // boards
+    'champ.update': 'champs',
+    'champ.remove': 'champs',
+    'guild.update': 'guilds',
+    'guild.remove': 'guilds',
+    'guild.join': 'guilds',
+    'city.update': 'governors',
+    'presence.online': 'presence',
+    'region.enter': 'presence',
+    // house.decay is the IDOC signal the public Houses page renders. The full
+    // registry (house.update / house.remove — owner, price, co-owners) stays
+    // off the map deliberately, so it remains admin-only exactly as before.
+    'house.decay': 'houses',
+    // v3
+    'world.ruleset': 'ruleset',
+    'points.board': 'leaderboards',
+    // vendor.listing IS mapped, but the market feature ships with its stream
+    // disabled (see DEFAULT_STREAM_OFF): a live firehose of full vendor
+    // inventories would be the site's biggest bandwidth consumer and no page
+    // needs it live. An admin can turn it on.
+    'vendor.listing': 'market',
+    'vendor.listing.remove': 'market',
+  }),
+)
+
+// Features whose SSE fan-out is off unless an admin enables it. The REST reads
+// are unaffected; only the live stream is suppressed.
+const DEFAULT_STREAM_OFF = new Set(['market'])
+
+// Back-compat: the set of kinds that reach an anonymous viewer under the default
+// config. shardEvents `/feed` filtering and notificationStreams.js both consume
+// this. Derived from the map above rather than hand-maintained, so the two can
+// no longer drift.
+const PUBLIC_KINDS = new Set(
+  [...KIND_FEATURE.entries()]
+    .filter(([, feature]) => {
+      if (DEFAULT_STREAM_OFF.has(feature)) return false
+      return FEATURES[feature].audience === 'anonymous'
+    })
+    .map(([kind]) => kind),
+)
+
+// ── Config (DB-backed, cached) ─────────────────────────────────────────────
+
+const CONFIG_TTL_MS = 5000
+let cache = null
+let cachedAt = 0
+
+// Merge a stored row over its compiled default. Unknown feature names in the DB
+// are ignored (a stale row from a removed feature must not resurrect it), and an
+// invalid rung falls back to the default rather than failing open.
+function applyRow(name, row) {
+  const base = FEATURES[name]
+  const audience = isLevel(row?.audience) ? row.audience : base.audience
+  const fields = { ...base.fields }
+  for (const [field, level] of Object.entries(row?.fieldRules || {})) {
+    if (isLockedField(field)) continue // rule 1: not configurable
+    if (isLevel(level)) fields[field] = level
+  }
+  return {
+    enabled: row ? !!row.enabled : true,
+    audience,
+    fields,
+    stream: row?.stream == null ? !DEFAULT_STREAM_OFF.has(name) : !!row.stream,
+  }
+}
+
+function compileDefaults() {
+  const out = {}
+  for (const name of FEATURE_NAMES) out[name] = applyRow(name, null)
+  return out
+}
+
+// Read the config, cached briefly. Falls back to compiled defaults if the DB is
+// unreachable — the defaults reproduce pre-v3 behavior, so a DB blip degrades to
+// "what the site did before" rather than to "everything is public".
+async function getConfig() {
+  const now = Date.now()
+  if (cache && now - cachedAt < CONFIG_TTL_MS) return cache
+  try {
+    const rows = await db.listAll()
+    const byName = new Map(rows.map((r) => [r.feature, r]))
+    const out = {}
+    for (const name of FEATURE_NAMES) out[name] = applyRow(name, byName.get(name))
+    cache = out
+    cachedAt = now
+  } catch (err) {
+    log.error('getConfig; falling back to defaults', err)
+    cache = cache || compileDefaults()
+    cachedAt = now
+  }
+  return cache
+}
+
+const invalidate = () => {
+  cache = null
+  cachedAt = 0
+}
+
+// ── Viewer level ───────────────────────────────────────────────────────────
+//
+// anonymous  no session
+// logged_in  authenticated, no linked game account
+// player     authenticated with a linked game account
+// staff      admin | moderator — the same set as the existing `modAccess` gate.
+//            `editor` is a CONTENT role with no shard privilege today, so it
+//            resolves by link status like any other member; mapping it to staff
+//            here would silently widen what editors can see.
+// admin      admin
+//
+// Staff always satisfy the `player` rung (rank order guarantees it) even without
+// a linked account, matching the existing rule that /player/* is role-agnostic
+// self-service.
+
+// Same TTL as the config cache: this decides a privilege rung, so an unlinked
+// (or newly relinked) account must not keep the old answer for long. Anonymous,
+// staff and admin callers short-circuit before this runs, so the lookup only
+// costs a query on the logged-in-member path.
+const LINK_TTL_MS = CONFIG_TTL_MS
+const linkCache = new Map() // userId → { hasLink, at }
+
+async function hasLinkedAccount(userId) {
+  const hit = linkCache.get(userId)
+  const now = Date.now()
+  if (hit && now - hit.at < LINK_TTL_MS) return hit.hasLink
+  let hasLink = false
+  try {
+    const links = await shardLinks.listForUser(userId)
+    hasLink = Array.isArray(links) && links.length > 0
+  } catch (err) {
+    log.warn('hasLinkedAccount failed; treating as unlinked', { message: err.message })
+  }
+  linkCache.set(userId, { hasLink, at: now })
+  return hasLink
+}
+
+// Drop a user's cached link status (called when a link is created or removed so
+// the rung takes effect immediately rather than up to LINK_TTL_MS later).
+const forgetUser = (userId) => linkCache.delete(userId)
+
+async function viewerLevel(req) {
+  const viewer = req.user || auth.getUserFromRequest(req)
+  if (!viewer) return 'anonymous'
+  if (viewer.role === 'admin') return 'admin'
+  if (viewer.role === 'moderator') return 'staff'
+  return (await hasLinkedAccount(viewer.id)) ? 'player' : 'logged_in'
+}
+
+// ── Enforcement ────────────────────────────────────────────────────────────
+
+// Route gate. 404 when the feature is disabled (do not leak that it exists);
+// 403 when it exists but the viewer sits below its audience. Stashes the
+// resolved level on the request so controllers can project without re-resolving.
+function requireFeature(name) {
+  return async (req, res, next) => {
+    try {
+      const config = await getConfig()
+      const feature = config[name]
+      if (!feature || !feature.enabled) return res.status(404).json({ message: 'Not Found' })
+      const level = await viewerLevel(req)
+      req.viewerLevel = level
+      if (!meets(level, feature.audience)) return res.status(403).json({ message: 'Forbidden' })
+      return next()
+    } catch (err) {
+      log.error(`requireFeature(${name})`, err)
+      return res.status(500).json({ message: 'Internal Server Error' })
+    }
+  }
+}
+
+// Strip the fields a viewer at `level` may not see. Applies the locked rules
+// first (so acct/webId can never survive below admin), then the feature's
+// configured field rules. Recurses into arrays and nested objects because the
+// sensitive fields sit inside actor sub-objects (guild.leader, city.governor).
+// Only ARRAYS and PLAIN objects are walked. A Date, Buffer or other class
+// instance is a value, not a bag of fields: rebuilding one key-by-key would
+// return `{}` (a Date has no enumerable own properties), which is how the DB-
+// backed read models — whose rows carry real Date columns — differ from the
+// pure-JSON wire frames the projection was first written against.
+const isPlainObject = (v) => {
+  if (v === null || typeof v !== 'object') return false
+  const proto = Object.getPrototypeOf(v)
+  return proto === Object.prototype || proto === null
+}
+
+function projectValue(value, rules, level) {
+  if (Array.isArray(value)) return value.map((v) => projectValue(v, rules, level))
+  if (!isPlainObject(value)) return value
+  const out = {}
+  for (const [key, v] of Object.entries(value)) {
+    // Locked fields are checked by meaning first, so no configured rule (and no
+    // flattened spelling) can widen them past `admin`.
+    const required = isLockedField(key) ? 'admin' : rules[key]
+    if (required && !meets(level, required)) continue
+    out[key] = projectValue(v, rules, level)
+  }
+  return out
+}
+
+// Project a payload for one feature. `level` defaults to admin-equivalent only
+// when explicitly passed; callers should always pass a resolved level.
+function projectFeature(name, payload, level, config) {
+  const feature = config?.[name]
+  const rules = { ...LOCKED_FIELDS, ...(feature ? feature.fields : {}) }
+  return projectValue(payload, rules, level)
+}
+
+// Convenience for controllers: resolve config once, project, return.
+async function project(name, payload, req) {
+  const config = await getConfig()
+  const level = req.viewerLevel || (await viewerLevel(req))
+  return projectFeature(name, payload, level, config)
+}
+
+// Is this event kind allowed to reach a viewer at `level`? Fail closed on an
+// unmapped kind (rule 2), and honour both the feature gate and its stream flag.
+function kindVisibleTo(kind, level, config) {
+  if (level === 'admin') return true
+  const name = KIND_FEATURE.get(kind)
+  if (!name) return false // rule 2: unmapped ⇒ admin-only
+  const feature = config?.[name]
+  if (!feature || !feature.enabled || !feature.stream) return false
+  return meets(level, feature.audience)
+}
+
+// The event kinds a viewer at `level` may read under the CURRENT config. This is
+// the live counterpart of PUBLIC_KINDS, which is a module-load constant derived
+// from the compiled DEFAULTS and therefore cannot answer "may THIS viewer see
+// this kind, given what the admin has configured?".
+//
+// Deliberately ignores the `stream` flag: that governs SSE fan-out only, so a
+// feature whose live firehose is off (market) is still readable from the stored
+// history. Unmapped kinds are absent by construction (rule 2).
+function visibleKinds(level, config) {
+  return [...KIND_FEATURE.entries()]
+    .filter(([, name]) => {
+      const feature = config?.[name]
+      return !!feature && feature.enabled && meets(level, feature.audience)
+    })
+    .map(([kind]) => kind)
+}
+
+// The features a viewer at `level` can actually see — drives SPA nav so it never
+// renders a link that would 403.
+function visibleFeatures(level, config) {
+  return FEATURE_NAMES.filter((name) => {
+    const feature = config[name]
+    return feature.enabled && meets(level, feature.audience)
+  })
+}
+
+module.exports = {
+  LADDER,
+  FEATURES,
+  FEATURE_NAMES,
+  LOCKED_FIELDS,
+  KIND_FEATURE,
+  PUBLIC_KINDS,
+  DEFAULT_STREAM_OFF,
+  isLevel,
+  isFeature,
+  isLockedField,
+  rank,
+  meets,
+  getConfig,
+  invalidate,
+  compileDefaults,
+  viewerLevel,
+  forgetUser,
+  requireFeature,
+  projectFeature,
+  project,
+  kindVisibleTo,
+  visibleKinds,
+  visibleFeatures,
+}