feat(server): register the routes, the slot, the leg and the boot hooks

The entry point becomes real: five mount prefixes, the admin.users.detail
extension slot, the shard push catalog, the town-crier announce leg and both
lifecycle hooks. module.json declares all of it and the loader checks the
declaration against what register() actually registers, in both directions.

The URLs are byte-identical to the ones core served before the extraction. That
is the whole point of moving the code and not the paths: the shipped Android app
calls POST /api/v1/admin/shard/kick and the Discord bot reads
/api/v1/public/shard/*, and neither knows a module answers now.

Require order is load-bearing and the requires are inside register() because of
it. Every ported file reaches core through ./core, whose members resolve ctx
when called -- but a router does `const express = core.express` at ITS file
scope, which runs the moment it is required. Hoisting these to the top of the
file breaks the module with an error about ctx being missing, from a file that
never mentions it.

boot.js takes the eight UO call sites out of core's server.js. One behavioural
change, deliberate: uoLinkSocket.start() and the sidecar health probe used to
run AFTER the listener bound and now run before it, because onBoot does. start()
returns as soon as the reconnecting client is armed, but the probe is a real
HTTP call, so it is fired and NOT awaited -- an unreachable sidecar must not
hold the site closed. Reporting that the bridge is down is diagnostics; being up
is not a precondition for serving a page.

router/rateLimits.js builds the market limiter through ctx.middleware.rateLimit,
core's factory. The policy is the module's -- only the module knows what its
endpoints cost -- and the plumbing is core's, so there is one express-rate-limit
in the process and one place a breach is logged.

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

server/router/admin/shard.router.js

@@ -0,0 +1,387 @@
+// 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 core = require('../../core')
+
+const express = core.express
+const { body, param } = core.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, validate } = core.middleware
+
+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/router/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('../../core')
+
+const log = require('../../core').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/router/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('../../core')
+
+const log = require('../../core').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/router/admin/shardOps.controller.js

@@ -0,0 +1,171 @@
+// ── Admin: in-game staff operations (uo-link write plane + support queue) ────
+//
+// The privileged "write plane" (§6 of the sidecar guide): kick / ban / unban /
+// broadcast against the live shard, plus the help-page (support ticket) queue.
+// Gated admin+moderator at the route (modAccess) — the sidecar trusts the
+// loopback socket, so authorization is entirely the site's responsibility.
+//
+// SECURITY: `actor` (who is taking the action) is ALWAYS set here from the
+// authenticated session (req.user.username), never from the request body, so an
+// action can't be attributed to someone else. The shard records it in its console
+// log, the ban's BanDealer tag, and the admin.audit event it echoes back.
+
+const uoLinkClient = require('../../utils/uoLinkClient')
+const shardState = require('../../model/shardState/shardState.model')
+const shardEvents = require('../../model/shardEvents/shardEvents.model')
+const { activity } = require('../../core')
+
+const log = require('../../core').logger('admin-shard-ops')
+
+// Map a never-throw uoLinkClient result onto an HTTP response. `okData` shapes the
+// success body. Mirrors the sidecar's documented status codes so the UI can tell a
+// transient outage (503/504 — retry) from a real rejection (403/404).
+function relay(res, result, okData) {
+  if (result.ok) return res.json(okData(result.data))
+  switch (result.status) {
+    case 400:
+      return res.status(400).json({ message: (result.data && result.data.error) || 'The shard rejected that request.' })
+    case 403:
+      return res.status(403).json({
+        message:
+          (result.data && result.data.error) ||
+          'That action was refused — the target is protected, or the write plane is disabled on the shard.',
+      })
+    case 404:
+      return res.status(404).json({ message: 'No such account or target on the shard.' })
+    case 503:
+    case 504:
+    case 0:
+      return res.status(503).json({ message: 'The shard is unavailable right now — try again shortly.' })
+    default:
+      return res.status(502).json({ message: 'Could not reach the shard.' })
+  }
+}
+
+// POST /admin/shard/kick — disconnect every live session of an account (or serial).
+async function kick(req, res) {
+  const { account, serial } = req.body
+  const actor = req.user.username
+  try {
+    const result = await uoLinkClient.adminKick({ actor, account, serial })
+    if (result.ok) await activity.log({ req, action: 'shard.kick', detail: { account, serial } })
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.kick', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/ban — ban an account (works offline); durationSec 0/absent = indefinite.
+async function ban(req, res) {
+  const { account, serial, durationSec, reason } = req.body
+  const actor = req.user.username
+  try {
+    const result = await uoLinkClient.adminBan({ actor, account, serial, durationSec, reason })
+    if (result.ok) await activity.log({ req, action: 'shard.ban', detail: { account, serial, durationSec, reason } })
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.ban', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/unban — clear an account's ban.
+async function unban(req, res) {
+  const { account } = req.body
+  const actor = req.user.username
+  try {
+    const result = await uoLinkClient.adminUnban({ actor, account })
+    if (result.ok) await activity.log({ req, action: 'shard.unban', detail: { account } })
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.unban', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/broadcast — a system message to everyone online.
+async function broadcast(req, res) {
+  const { text, hue } = req.body
+  const actor = req.user.username
+  try {
+    const result = await uoLinkClient.adminBroadcast({ actor, text, hue })
+    if (result.ok) await activity.log({ req, action: 'shard.broadcast', detail: { text } })
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.broadcast', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/shard/pages — the open help-page (support) queue, from our store.
+async function listPages(req, res) {
+  try {
+    return res.json(await shardState.listPages())
+  } catch (err) {
+    log.error('shardOps.listPages', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/pages/:id/respond — reply to a player (optionally close).
+async function respondPage(req, res) {
+  const { id } = req.params
+  const { message, close } = req.body
+  try {
+    const result = await uoLinkClient.respondPage(id, { message, close: Boolean(close) })
+    if (result.ok) {
+      await activity.log({ req, action: 'shard.page.respond', detail: { pageId: id, close: Boolean(close) } })
+      // Close removes the page from the queue; reflect it locally at once (the
+      // page.closed event will confirm it, but the UI shouldn't wait a poll cycle).
+      if (close) await shardState.removePage(id).catch(() => {})
+    }
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.respondPage', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/shard/pages/:id/close — resolve a page without a reply.
+async function closePage(req, res) {
+  const { id } = req.params
+  try {
+    const result = await uoLinkClient.closePage(id)
+    if (result.ok) {
+      await activity.log({ req, action: 'shard.page.close', detail: { pageId: id } })
+      await shardState.removePage(id).catch(() => {})
+    }
+    return relay(res, result, (d) => d || { ok: true })
+  } catch (err) {
+    log.error('shardOps.closePage', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/shard/audit — recent moderation audit events (admin.audit), from the
+// ingested event log. Seeds the live audit log the panel keeps current over SSE.
+async function listAudit(req, res) {
+  try {
+    const limit = req.query.limit
+    return res.json(await shardEvents.list({ kind: 'admin.audit', limit }))
+  } catch (err) {
+    log.error('shardOps.listAudit', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/shard/houses — the FULL house registry (owner, price, co-owners,
+// decay), staff-only (modAccess). The public /public/shard/houses shows only IDOC
+// houses with location; this is the complete board, kept live for staff on the
+// admin SSE channel (house.update / house.remove).
+async function listHouses(req, res) {
+  try {
+    return res.json(await shardState.listHouses())
+  } catch (err) {
+    log.error('shardOps.listHouses', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { kick, ban, unban, broadcast, listPages, respondPage, closePage, listAudit, listHouses }

server/router/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('../../core').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/router/admin/uoLink.controller.js

@@ -0,0 +1,123 @@
+// ── Admin: uo-link sidecar control ─────────────────────────────────────────
+//
+// Configure the connection to the uo-link sidecar (base/ws URL, shared-secret
+// token, protocol pin, enabled) and drive the town crier. SECURITY: the token
+// is write-only over this API — stored encrypted, NEVER returned; responses
+// expose only `hasToken` (same convention as the Discord bot token). Saving
+// (re)starts the WS ingest client so a change takes effect with no redeploy.
+
+const uoLinkConfig = require('../../model/uoLinkConfig/uoLinkConfig.model')
+const uoLinkClient = require('../../utils/uoLinkClient')
+const uoLinkSocket = require('../../utils/uoLinkSocket')
+const shardBroadcast = require('../../utils/shardBroadcast')
+const { activity } = require('../../core')
+
+const log = require('../../core').logger('admin-uolink')
+
+// Assemble the masked config + live health + ingestion stats for the panel.
+async function buildStatus() {
+  const config = await uoLinkConfig.getSafe()
+  const health = await uoLinkClient.health()
+  return {
+    ...config,
+    health: health.ok ? health.data : { ok: false, error: health.error || `status ${health.status}` },
+    ingest: uoLinkSocket.getState(),
+    sse: shardBroadcast.stats(),
+  }
+}
+
+// GET /admin/uo-link/config — masked config + live status + ingestion stats.
+async function getConfig(req, res) {
+  try {
+    return res.json(await buildStatus())
+  } catch (err) {
+    log.error('uoLink.getConfig', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// PUT /admin/uo-link/config — save connection settings + (re)start the socket.
+async function saveConfig(req, res) {
+  const { baseUrl, wsUrl, token, protocol, enabled } = req.body
+  try {
+    const current = await uoLinkConfig.getSafe()
+    const willHaveToken = Boolean(token) || current.hasToken
+    if (enabled && !willHaveToken) {
+      return res.status(400).json({ message: 'An auth token is required before enabling.' })
+    }
+
+    await uoLinkConfig.save({
+      baseUrl,
+      wsUrl,
+      token,
+      protocol: protocol !== undefined ? Number(protocol) : undefined,
+      enabled,
+      updatedBy: req.user.id,
+    })
+    // Drop the client's cached config so the health check below uses the new values.
+    uoLinkClient.invalidateConfig()
+
+    // (Re)start or stop the ingest socket to match the new enabled/URL/token.
+    const saved = await uoLinkConfig.getSafe()
+    if (saved.enabled && saved.hasToken) {
+      await uoLinkSocket.start()
+    } else {
+      uoLinkSocket.stop()
+      await uoLinkConfig.recordStatus({ status: 'disconnected', pluginConnected: false })
+    }
+
+    await activity.log({ req, action: 'uoLink.config.update', detail: { baseUrl: saved.baseUrl, enabled: saved.enabled } })
+    log.info('uo-link config updated', { by: req.user.username, enabled: saved.enabled })
+    return res.json(await buildStatus())
+  } catch (err) {
+    log.error('uoLink.saveConfig', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// POST /admin/uo-link/towncrier — publish/replace a town-crier message.
+async function postTownCrier(req, res) {
+  const { id, lines, durationSec } = req.body
+  try {
+    const result = await uoLinkClient.postTownCrier({ id, lines, durationSec })
+    if (result.ok) {
+      await activity.log({ req, action: 'uoLink.towncrier.post', detail: { id } })
+      return res.json(result.data || { ok: true, id })
+    }
+    if (result.status === 400) return res.status(400).json({ message: 'The shard rejected that message (over the line/duration caps?).' })
+    if (result.status === 503 || result.status === 0) {
+      return res.status(503).json({ message: 'The shard is unavailable right now.' })
+    }
+    return res.status(502).json({ message: 'Could not reach the shard.' })
+  } catch (err) {
+    log.error('uoLink.postTownCrier', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// DELETE /admin/uo-link/towncrier/:id — remove a town-crier message.
+async function deleteTownCrier(req, res) {
+  const { id } = req.params
+  try {
+    const result = await uoLinkClient.deleteTownCrier(id)
+    if (result.ok) {
+      await activity.log({ req, action: 'uoLink.towncrier.delete', detail: { id } })
+      return res.json(result.data || { ok: true, id })
+    }
+    if (result.status === 404) return res.status(404).json({ message: 'No town-crier message with that id.' })
+    if (result.status === 503 || result.status === 0) {
+      return res.status(503).json({ message: 'The shard is unavailable right now.' })
+    }
+    return res.status(502).json({ message: 'Could not reach the shard.' })
+  } catch (err) {
+    log.error('uoLink.deleteTownCrier', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/uo-link/stream — the full live feed (incl. audit/cheat), staff only.
+function stream(req, res) {
+  shardBroadcast.subscribe(req, res, 'admin')
+}
+
+module.exports = { getConfig, saveConfig, postTownCrier, deleteTownCrier, stream }

server/router/admin/uoLink.router.js

@@ -0,0 +1,100 @@
+// 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 core = require('../../core')
+
+const express = core.express
+const { body, param } = core.validator
+
+const uoLink = require('./uoLink.controller')
+const { requireRole, validate } = core.middleware
+
+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/router/admin/usersShard.controller.js

@@ -0,0 +1,129 @@
+// ── Admin: a single user's shard (uo-link) footprint ──────────────────────────
+//
+// Backs the /admin/users/:id detail page. Every read is scoped to the target
+// user's linked game accounts (from the local shard_account_links mirror): their
+// vendor sales, houses, and currently-online characters. The live character
+// rosters are fetched separately by the client through the existing admin-bypass
+// /admin/shard/* endpoints, so nothing here round-trips the sidecar — these are
+// fast, DB-backed reads. Admin-only (registered under adminOnly in the router).
+
+const { users, activity } = require('../../core')
+const shardLinks = require('../../model/shardLinks/shardLinks.model')
+const shardState = require('../../model/shardState/shardState.model')
+const uoLinkClient = require('../../utils/uoLinkClient')
+const { salesForAccounts } = require('../../utils/shardSales')
+
+const log = require('../../core').logger('admin-user-shard')
+
+// Resolve the target user's linked game accounts, or null if the user id is
+// unknown (so the handler can 404 rather than silently returning an empty set).
+async function accountsForUser(id) {
+  const user = await users.getById(id)
+  if (!user) return null
+  const links = await shardLinks.listForUser(id)
+  return { user, links, accounts: links.map((l) => l.account) }
+}
+
+// GET /admin/users/:id/shard/accounts — the user's linked game accounts.
+async function listAccounts(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(ctx.links)
+  } catch (err) {
+    log.error('listAccounts', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/sales — recent vendor sales on the user's accounts.
+async function getSales(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await salesForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getSales', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/houses — houses owned by the user's accounts.
+async function getHouses(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await shardState.listHousesForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getHouses', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/online — the user's characters currently online.
+async function getOnline(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    return res.json(await shardState.listOnlineForAccounts(ctx.accounts))
+  } catch (err) {
+    log.error('getOnline', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// GET /admin/users/:id/shard/standing — the user's shard "standing" cross-links:
+// city governorships they currently hold and guilds they lead. Both are reliable
+// current-state lookups on the user's linked accounts.
+async function getStanding(req, res) {
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    const [governorOf, guildsLed] = await Promise.all([
+      shardState.listGovernorshipsForAccounts(ctx.accounts),
+      shardState.listGuildsLedForAccounts(ctx.accounts),
+    ])
+    return res.json({ governorOf, guildsLed })
+  } catch (err) {
+    log.error('getStanding', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+// DELETE /admin/users/:id/shard/link/:account — unlink a game account from this
+// user, site-side. `actor` is stamped from the session (never the browser). On
+// success the sidecar clears the WebsiteUserId tag on the shard and we drop the
+// local mirror so attribution stops immediately.
+async function unlinkAccount(req, res) {
+  const { account } = req.params
+  try {
+    const ctx = await accountsForUser(Number(req.params.id))
+    if (!ctx) return res.status(404).json({ message: 'Not found' })
+    // Only unlink an account actually linked to THIS user (avoid cross-user unlink).
+    if (!ctx.accounts.includes(account)) {
+      return res.status(404).json({ message: 'That account is not linked to this user.' })
+    }
+    const result = await uoLinkClient.unlinkAccount({ actor: req.user.username, account })
+    if (result.ok) {
+      await shardLinks.removeByAccount(account)
+      await activity.log({ req, userId: ctx.user.id, action: 'shard.account.unlink', detail: { account } })
+      log.info('game account unlinked', { account, userId: ctx.user.id, actor: req.user.username })
+      return res.json({ account, unlinked: true })
+    }
+    if (result.status === 403) return res.status(403).json({ message: 'That account is protected and cannot be unlinked.' })
+    if (result.status === 404) {
+      // Not linked on the shard — reconcile our mirror anyway so the two agree.
+      await shardLinks.removeByAccount(account)
+      return res.status(404).json({ message: 'That account is not linked.' })
+    }
+    if (result.status === 503 || result.status === 0) {
+      return res.status(503).json({ message: 'The game server is unavailable — try again shortly.' })
+    }
+    return res.status(502).json({ message: 'Could not reach the shard to unlink the account.' })
+  } catch (err) {
+    log.error('unlinkAccount', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { listAccounts, getSales, getHouses, getOnline, getStanding, unlinkAccount }

server/router/admin/usersShard.router.js

@@ -0,0 +1,113 @@
+// ── The `admin.users.detail` extension slot's contents ─────────────────────
+//
+// MODULE-UO CONTENT, still living in core. MODULE_SYSTEM.md §1.9 named the
+// fourth mount shape: module routes hanging off a CORE resource. These six paths
+// are shard reads on `/admin/users/:id`, a user-management URL core owns, so
+// they cannot move with a prefix and cannot stay where they are either.
+//
+// The resolution is an extension SLOT. `users.router.js` declares
+// `admin.users.detail` and mounts its router at `/:id`; this file is what fills
+// it, registered through modules/registries.js like a module would
+// (registerCore() → `api.registerExtension('admin.users.detail', …)`). Phase 3
+// moves this file to module-uo and changes nothing else — the six URLs are
+// identical either way, and core never learns what "shard" means.
+//
+// `mergeParams` comes from the slot's router, so `req.params.id` is the parent's
+// user id. Core's own routes on the resource are declared BEFORE the slot is
+// mounted, so core always wins a path conflict (MODULE_API.md §2.4).
+
+const core = require('../../core')
+
+const express = core.express
+const { param } = core.validator
+
+const usersShard = require('./usersShard.controller')
+const { validate } = core.middleware
+
+// Same shape the shard routes validate account names with.
+const SHARD_ACCOUNT_RE = /^[A-Za-z0-9_.-]{1,120}$/
+
+const shardRouter = express.Router({ mergeParams: true })
+
+// Backs the /admin/users/:id detail page: a user's linked game accounts and,
+// scoped to those accounts, their vendor sales / houses / online characters.
+// Live character rosters are fetched by the client through /admin/shard/* (which
+// already grants admins a bypass to any account), so no routes for them here.
+shardRouter.get(
+  '/shard/accounts',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'A user’s linked game accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Linked accounts', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardLink" } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.listAccounts,
+)
+shardRouter.get(
+  '/shard/sales',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Recent vendor sales on a user’s accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Vendor sales', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardVendorSale" } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getSales,
+)
+shardRouter.get(
+  '/shard/houses',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Houses owned by a user’s accounts (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Houses (IDOC first)', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getHouses,
+)
+shardRouter.get(
+  '/shard/online',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'A user’s characters currently online (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Online characters', content: { "application/json": { schema: { type: "array", items: { type: "object", additionalProperties: true } } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getOnline,
+)
+shardRouter.get(
+  '/shard/standing',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'A user’s shard standing — governorships held and guilds led (admin only)'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  /* #swagger.responses[200] = { description: 'Standing { governorOf, guildsLed }', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[404] = { description: 'Not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  validate,
+  usersShard.getStanding,
+)
+shardRouter.delete(
+  '/shard/link/:account',
+  // #swagger.tags = ['Admin · Users']
+  // #swagger.summary = 'Unlink a game account from this user (admin only)'
+  // #swagger.description = 'Severs a game account’s tie to the website user from the site side (sidecar DELETE /link/{account}) and drops the local mirror. actor is stamped from the session.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'User id.' }
+  // #swagger.parameters['account'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Game account to unlink.' }
+  /* #swagger.responses[200] = { description: 'Unlinked', content: { "application/json": { schema: { type: "object", properties: { account: { type: "string" }, unlinked: { type: "boolean" } } } } } } */
+  /* #swagger.responses[403] = { description: 'Protected staff account (refused by shard)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Not linked', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt(),
+  param('account').matches(SHARD_ACCOUNT_RE),
+  validate,
+  usersShard.unlinkAccount,
+)
+
+module.exports = shardRouter