feat(release): ship an OpenAPI fragment, a frozen manifest and a bundle (phase 3, slice 5)

The three artifacts that make this module installable and checkable, closing
phase 3's extraction. Nothing about what the module serves changes: the same 72
URLs, the same behaviour.

**The OpenAPI fragment (MODULE_API.md §2.8, §6.1a) was never built, on either
side.** The 417 `#swagger` annotations came across in slice 1 and went nowhere,
and core's /api/docs.json merged nothing — so every route this module serves was
in no spec at all, which is core's standing rule ("never ship a route that isn't
in the spec") being broken by the extraction rather than by a route.

`server/scripts/swaggerFragment.js` generates it. The prefixes are DERIVED: the
script runs the module's own `register()` against a recording api and asks
`require.cache` which file each router came from, so a mount prefix exists in one
place — `server/index.js` — and not in a table beside it. The 31 schemas moved
here from core's swagger.js, namespaced `Uo…` because core wins every key
collision in the merge; `Error` and `ValidationError` stay referenced by core's
names, since they resolve in the merged document.

**The frozen route manifest (§5.3)** is derived too, and by subtraction: CI
clones core at the ref pinned in ci/core-ref.json, generates its manifest without
this module and then with it, and the difference is what this module serves. That
buys the half of §5.3 that matters most for free — a module that shadowed or
displaced one of core's routes shows up as a REMOVAL, not merely as an addition
elsewhere. The same job checks the fragment against ground truth: every route
must have an operation and every operation must be a route.

**The release workflow** publishes `module-uo-<version>.tar.gz` plus a manifest
carrying its sha256. The version is declared in module.json rather than computed
from commit subjects, and the workflow never writes to a branch — it tags and
publishes — so `main` needs no push exception. The bundle is assembled from an
include list, because an exclude list ships whatever it forgot.

Four annotation defects, inherited from core and never visible until something
generated a spec from these files: two `requestBody` literals a brace short (the
route documented with an empty body), and two descriptions whose inner quoting
swagger-autogen cannot survive — it re-quotes `"` and a backtick to `'` before
evaluating, so either inside a single-quoted description ends the string early
and the annotation is dropped. It reports each one and then prints Success in
green, so the generator now captures its diagnostics and makes them fatal.

Also fixed while writing it: passing one shared `doc` to swagger-autogen six
times. It renders components.schemas from an EXAMPLE object and writes the result
back into what it was handed, so each pass re-wrapped the last and the fragment
came out at 484 MB.

- 409 server tests (+21), 40 client tests unchanged
- swagger-fragment.json: 69 paths covering all 72 routes
- routes.manifest.json: 72 routes; core's own surface unchanged, 0 removals
- verified end to end by assembling the bundle exactly as CI will, unpacking it
  into a real core and regenerating the manifest

Refs: docs/website/MODULE_SYSTEM.md §2.7.1, MODULE_API.md §2.8, §5.3, §6.1a

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

server/swagger/doc.js

@@ -0,0 +1,621 @@
+// ── module-uo's OpenAPI fragment: the shared half ──────────────────────────
+//
+// The tags and component schemas every `#swagger.*` annotation under
+// `server/router/**` refers to. `scripts/swaggerFragment.js` feeds this to
+// swagger-autogen; the per-endpoint detail lives beside each route, exactly as
+// it does in core.
+//
+// These 31 schemas were core's until phase 3 — they sat in
+// `website/server/swagger/swagger.js` describing routes core no longer serves,
+// which is what an extraction leaves behind if nobody looks (the inert-leaf
+// class slice 4 found in `api/client.js`). They moved with the routes.
+//
+// **Two rules about names, and both are the merged document's, not this file's**
+// (docs/website/MODULE_API.md §6.1a):
+//
+//   • **What this module DEFINES is namespaced `Uo…`.** Core merges started
+//     modules' fragments into one `/api/docs.json`, and core wins every key
+//     collision — so an un-namespaced `ShardStatus` from a second game's module
+//     would silently lose to, or clobber, this one. The prefix is what makes two
+//     modules able to describe the same idea.
+//   • **What core defines is referenced by CORE's name.** The annotations point
+//     at `#/components/schemas/Error` and `ValidationError` and this file does
+//     not redefine them: they resolve in the merged spec, where core's
+//     definitions are. Shipping our own copy would be a collision core drops,
+//     which is the correct outcome arrived at the expensive way.
+//
+// Tag NAMES are core's originals (`Public · Shard`, not `Uo · Shard`). A tag is
+// how the docs UI groups operations, and core stopped declaring these four in
+// the same slice this file started — nothing collides, and renaming them would
+// churn every reader's bookmark for no gain.
+
+module.exports = {
+  tags: [
+    { name: 'Public · Shard', description: 'Live shard data ingested from the uo-link sidecar (status, feed, economy, IDOC, characters)' },
+    { name: 'Public · Atlas', description: 'Spawn atlas / bestiary — static shard content parsed from the shard\'s own ServUO tree, independent of the sidecar' },
+    { name: 'Player · Shard', description: 'Link an in-game account and read its roster / vendors (uo-link)' },
+    { name: 'Admin · Shard', description: 'uo-link sidecar connection config, live status and town crier (admin only)' },
+  ],
+  components: {
+    schemas: {
+      // ── uo-link shard data ──────────────────────────────────────────────
+      UoShardStatus: {
+        type: 'object',
+        description: 'Public shard status (GET /public/shard/status).',
+        properties: {
+          enabled: { type: 'boolean', example: true },
+          status: { type: 'string', example: 'connected', description: 'connected | reconnecting | disconnected | error' },
+          pluginConnected: { type: 'boolean', description: 'Is the shard link up right now?', example: true },
+          lastEventAt: { type: 'string', format: 'date-time', nullable: true },
+          onlineCount: { type: 'integer', example: 12 },
+          economy: { $ref: '#/components/schemas/UoShardEconomyPoint' },
+        },
+      },
+      UoShardEvent: {
+        type: 'object',
+        description: 'A logged shard event.',
+        properties: {
+          id: { type: 'integer', example: 4821 },
+          kind: { type: 'string', example: 'vendor.sale' },
+          t: { type: 'integer', description: 'Event time, epoch ms.', example: 1783720195626 },
+          bootId: { type: 'string', nullable: true, example: 'boot-abc123' },
+          payload: { type: 'object', additionalProperties: true, description: 'The full event object.' },
+          createdAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      UoShardEconomyPoint: {
+        type: 'object',
+        nullable: true,
+        description: 'One gold-supply sample.',
+        properties: {
+          accounts: { type: 'integer', nullable: true, example: 240 },
+          gold: { type: 'integer', nullable: true, example: 1028983421 },
+          t: { type: 'integer', description: 'Sample time, epoch ms.', example: 1783720000000 },
+        },
+      },
+      UoShardOnlinePlayer: {
+        type: 'object',
+        description: 'A LINKED player online now (only accounts linked to a website user are listed).',
+        properties: {
+          serial: { type: 'string', example: '0x24C' },
+          name: { type: 'string', example: 'Darrow' },
+          map: { type: 'string', nullable: true, example: 'Trammel' },
+          x: { type: 'integer', nullable: true, example: 1402 },
+          y: { type: 'integer', nullable: true, example: 1604 },
+          z: { type: 'integer', nullable: true, example: 0 },
+        },
+      },
+      UoShardVendorSale: {
+        type: 'object',
+        description: 'A player-vendor sale (visible only to the linked owner).',
+        properties: {
+          t: { type: 'integer', description: 'Sale time, epoch ms.', example: 1783720195626 },
+          itemType: { type: 'string', example: 'Longsword' },
+          amount: { type: 'integer', example: 1 },
+          price: { type: 'integer', example: 100 },
+          commission: { type: 'integer', nullable: true, example: 5 },
+          ownerAcct: { type: 'string', example: 'whitlocktech' },
+        },
+      },
+      UoShardHouse: {
+        type: 'object',
+        description: 'A house at its current decay stage.',
+        properties: {
+          serial: { type: 'string', example: '0x4004705F' },
+          stage: { type: 'string', example: 'IDOC' },
+          map: { type: 'string', nullable: true, example: 'Trammel' },
+          x: { type: 'integer', nullable: true },
+          y: { type: 'integer', nullable: true },
+          z: { type: 'integer', nullable: true },
+          region: { type: 'string', nullable: true },
+          name: { type: 'string', nullable: true, example: 'An Unnamed House' },
+          ownerSerial: { type: 'string', nullable: true },
+          ownerAcct: { type: 'string', nullable: true },
+          builtOn: { type: 'string', format: 'date-time', nullable: true },
+          lastRefreshed: { type: 'string', format: 'date-time', nullable: true },
+          isIdoc: { type: 'boolean', example: true },
+          updatedAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      UoShardPointsBoard: {
+        type: 'object',
+        description:
+          "One point system's leaderboard (Protocol 3.0 points.board). The shard carries ~25 separate point currencies; each publishes its own board. The display name may arrive as a literal string, a cliloc id, or both — resolve clilocs client-side.",
+        properties: {
+          system: { type: 'string', example: 'QueensLoyalty', description: "The shard's PointsType name; the board's stable key." },
+          nameString: { type: 'string', nullable: true, example: "Queen's Loyalty" },
+          nameNumber: { type: 'integer', nullable: true, example: 1114938, description: 'Cliloc id, 0 when the name is a literal.' },
+          maxPoints: { type: 'integer', nullable: true, example: 30000 },
+          players: { type: 'integer', nullable: true, example: 842, description: 'Players actually holding points in this system.' },
+          showOnGump: { type: 'boolean', example: true, description: "The shard's own 'is this player-facing?' flag." },
+          top: {
+            type: 'array',
+            description: 'The ranked players, best first. Capped by the shard (10 by default). Empty when nobody has scored yet.',
+            items: {
+              type: 'object',
+              properties: {
+                rank: { type: 'integer', example: 1 },
+                serial: { type: 'string', example: '0x1A2B' },
+                name: { type: 'string', example: 'Darrow', description: 'Omitted when the leaderboards `name` field is gated above the caller.' },
+                points: { type: 'integer', example: 29500 },
+              },
+            },
+          },
+          t: { type: 'integer', nullable: true, description: 'Frame time, epoch ms.' },
+          updatedAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      UoShardMarketLocation: {
+        type: 'object',
+        nullable: true,
+        description:
+          "Where a vendor is standing. ONE nested object rather than flat map/x/y/region because it is one admin-configurable field (`market.location`) — the whole object is omitted when that field is gated above the caller.",
+        properties: {
+          map: { type: 'string', nullable: true, example: 'Trammel' },
+          x: { type: 'integer', nullable: true, example: 1421 },
+          y: { type: 'integer', nullable: true, example: 1699 },
+          z: { type: 'integer', nullable: true, example: 0 },
+          region: { type: 'string', nullable: true, example: 'Britain' },
+          house: { type: 'string', nullable: true, example: "Darrow's Villa", description: "The house SIGN's name, not the house type. Null for a vendor standing outside one." },
+        },
+      },
+      UoShardMarketListing: {
+        type: 'object',
+        description:
+          'One priced listing on a player vendor, carrying enough of its shop to be actionable without a second request.',
+        properties: {
+          serial: { type: 'string', example: '0x40012ABC' },
+          itemId: { type: 'integer', example: 3922, description: 'ItemID (the art/graphic id).' },
+          hue: { type: 'integer', example: 0 },
+          amount: { type: 'integer', example: 1 },
+          price: { type: 'integer', example: 25000 },
+          name: { type: 'string', nullable: true, description: "The item's own literal name, set by a player. Null for most items." },
+          cliloc: { type: 'integer', nullable: true, example: 1023721, description: "The item's LabelNumber." },
+          displayName: {
+            type: 'string',
+            nullable: true,
+            example: 'quarter staff',
+            description: 'Resolved server-side from `name` (preferred, being player-set and more specific) else `cliloc`. Null on a shard with no cliloc table configured — render the item id.',
+          },
+          child: { type: 'boolean', example: false, description: 'Priced by an enclosing container rather than itself, exactly as the in-game Vendor Search reports it.' },
+          vendor: {
+            type: 'object',
+            properties: {
+              serial: { type: 'string', example: '0x40001234' },
+              shopName: { type: 'string', nullable: true, example: "Darrow's Bargains" },
+              ownerSerial: { type: 'string', nullable: true, example: '0x1A2B', description: 'Omitted when the market `ownerSerial` field is gated above the caller.' },
+              ownerName: { type: 'string', nullable: true, example: 'Darrow', description: 'Omitted when the market `ownerName` field is gated above the caller.' },
+              location: { $ref: '#/components/schemas/UoShardMarketLocation' },
+              updatedAt: { type: 'string', format: 'date-time', description: 'When the shard last published this shop.' },
+            },
+          },
+        },
+      },
+      UoShardMarketPage: {
+        type: 'object',
+        description: 'A page of marketplace listings plus the unpaginated total and the staleness stamp.',
+        properties: {
+          listings: { type: 'array', items: { $ref: '#/components/schemas/UoShardMarketListing' } },
+          total: { type: 'integer', example: 1284, description: 'Matching listings, ignoring paging.' },
+          limit: { type: 'integer', example: 50 },
+          offset: { type: 'integer', example: 0 },
+          vendors: { type: 'integer', example: 137, description: 'Vendors in the whole index.' },
+          staleAt: {
+            type: 'string',
+            format: 'date-time',
+            nullable: true,
+            description: 'The OLDEST vendor row. The shard sweeps vendors round-robin, so the index can be a full cycle behind and a client must say so rather than implying live prices.',
+          },
+        },
+      },
+      UoShardMarketVendor: {
+        type: 'object',
+        description: 'One player vendor and its listings.',
+        properties: {
+          serial: { type: 'string', example: '0x40001234' },
+          shopName: { type: 'string', nullable: true, example: "Darrow's Bargains" },
+          ownerSerial: { type: 'string', nullable: true },
+          ownerName: { type: 'string', nullable: true, example: 'Darrow' },
+          location: { $ref: '#/components/schemas/UoShardMarketLocation' },
+          count: { type: 'integer', example: 250, description: 'Listings the shard published for this shop.' },
+          total: { type: 'integer', example: 3104, description: 'Listings the shop actually holds.' },
+          truncated: { type: 'boolean', example: true, description: '`total` exceeds `count` — the shop holds more than the shard publishes per frame.' },
+          updatedAt: { type: 'string', format: 'date-time' },
+          items: { type: 'array', items: { $ref: '#/components/schemas/UoShardMarketListing' } },
+        },
+      },
+      UoShardMarketMeta: {
+        type: 'object',
+        description: 'Marketplace size, staleness and the filter options a client needs to build its UI.',
+        properties: {
+          vendors: { type: 'integer', example: 137 },
+          items: { type: 'integer', example: 18422 },
+          staleAt: { type: 'string', format: 'date-time', nullable: true },
+          freshAt: { type: 'string', format: 'date-time', nullable: true },
+          maps: { type: 'array', items: { type: 'string' }, example: ['Felucca', 'Trammel'], description: "Facets that actually hold vendors. From the shard's own data — never a hardcoded list." },
+          regions: { type: 'array', items: { type: 'string' }, example: ['Britain', 'Luna'] },
+        },
+      },
+      UoShardFeatures: {
+        type: 'object',
+        description:
+          "The shard features the caller may reach, plus the audience rung they resolved to. Drives client nav so it never renders a link that would 403.",
+        properties: {
+          level: {
+            type: 'string',
+            enum: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
+            example: 'anonymous',
+          },
+          features: {
+            type: 'array',
+            items: { type: 'string' },
+            example: ['status', 'activity', 'champs', 'guilds', 'governors', 'houses', 'presence'],
+          },
+        },
+      },
+      UoShardFeatureVisibility: {
+        type: 'object',
+        description: 'Visibility settings for one shard feature.',
+        properties: {
+          enabled: { type: 'boolean', example: true },
+          audience: {
+            type: 'string',
+            enum: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
+            description: 'Minimum rung that may reach this feature. Each rung implies the ones below it.',
+            example: 'anonymous',
+          },
+          stream: {
+            type: 'boolean',
+            description: "Whether this feature's event kinds fan out over SSE at all.",
+            example: true,
+          },
+          fieldRules: {
+            type: 'object',
+            additionalProperties: { type: 'string' },
+            description:
+              'Per-field rung overrides for the sensitive fields this feature exposes. acct / webId are admin-only always and are rejected here.',
+            example: { location: 'staff' },
+          },
+        },
+      },
+      UoShardVisibilityConfig: {
+        type: 'object',
+        properties: {
+          ladder: {
+            type: 'array',
+            items: { type: 'string' },
+            example: ['anonymous', 'logged_in', 'player', 'staff', 'admin'],
+          },
+          lockedFields: { type: 'array', items: { type: 'string' }, example: ['acct', 'webId'] },
+          defaults: {
+            type: 'object',
+            additionalProperties: { $ref: '#/components/schemas/UoShardFeatureVisibility' },
+          },
+          features: {
+            type: 'object',
+            additionalProperties: { $ref: '#/components/schemas/UoShardFeatureVisibility' },
+          },
+        },
+      },
+      UoShardVisibilityUpdate: {
+        type: 'object',
+        required: ['features'],
+        properties: {
+          features: {
+            type: 'object',
+            additionalProperties: { $ref: '#/components/schemas/UoShardFeatureVisibility' },
+            example: { market: { enabled: true, audience: 'player', stream: false, fieldRules: { ownerName: 'player' } } },
+          },
+        },
+      },
+      // ── Spawn atlas (Protocol 3.0 Part C) ────────────────────────────────
+      // Static shard content, parsed from the shard's own ServUO tree. Nothing
+      // here comes from the sidecar, so it stays populated while the shard is
+      // down. Facet names are whatever the shard's files declare — the examples
+      // below are stock ServUO, not a fixed list.
+      UoAtlasCreature: {
+        type: 'object',
+        description: 'A creature in the bestiary. `places`/`points`/`alsoHere` are present only on the single-creature route.',
+        properties: {
+          slug: { type: 'string', example: 'lizardman' },
+          name: { type: 'string', example: 'Lizardman' },
+          total: { type: 'integer', description: 'How many can be alive at once, summed across every spawner.', example: 214 },
+          points: { type: 'integer', description: 'How many spawners mention this creature.', example: 62 },
+          facets: {
+            type: 'object',
+            additionalProperties: { type: 'integer' },
+            description: "This creature's share per facet.",
+            example: { Felucca: 96, Trammel: 88, Tokuno: 30 },
+          },
+          art: { type: 'string', nullable: true, description: 'Operator-supplied art under uploads/atlas/. NULL on a fresh import — the repo ships no creature art.' },
+          places: {
+            type: 'array',
+            description: 'Where it spawns, aggregated by resolved place. The answer the atlas exists to give.',
+            items: {
+              type: 'object',
+              properties: {
+                facet: { type: 'string', example: 'Trammel' },
+                label: { type: 'string', description: 'Resolved region, else nearest landmark group, else "Wilderness".', example: 'Shrines' },
+                spawners: { type: 'integer', example: 7 },
+                maxAlive: { type: 'integer', example: 21 },
+              },
+            },
+          },
+          spawners: {
+            type: 'array',
+            description: 'The individual spawners. Named separately from `points` (the count) so one key never means two things.',
+            items: { $ref: '#/components/schemas/UoAtlasSpawner' },
+          },
+          spawnersTruncated: { type: 'boolean', description: 'True when the spawner list was cut at the requested bound.', example: false },
+          alsoHere: {
+            type: 'array',
+            description: 'Creatures sharing a spawner with this one.',
+            items: {
+              type: 'object',
+              properties: {
+                slug: { type: 'string', example: 'lizardman-warrior' },
+                name: { type: 'string', example: 'Lizardman Warrior' },
+                shared: { type: 'integer', example: 12 },
+              },
+            },
+          },
+        },
+      },
+      UoAtlasSpawner: {
+        type: 'object',
+        description: 'One ServUO spawner, with the place its coordinates resolved to.',
+        properties: {
+          id: { type: 'integer' },
+          facet: { type: 'string', example: 'Felucca' },
+          name: { type: 'string', nullable: true, description: "The spawner's own name in the ServUO file." },
+          x: { type: 'integer', example: 5411 },
+          y: { type: 'integer', example: 1234 },
+          width: { type: 'integer' },
+          height: { type: 'integer' },
+          range: { type: 'integer', description: 'Spawn radius.' },
+          maxCount: { type: 'integer', description: 'How many of THIS creature this spawner keeps alive.', example: 3 },
+          minDelay: { type: 'integer', description: 'Respawn window, in SECONDS. Normalised at parse time — the source stores minutes or seconds per record, decided by its own DelayInSec flag.', example: 300 },
+          maxDelay: { type: 'integer', example: 600 },
+          todStart: { type: 'integer', description: 'Meaningless unless todMode is non-zero.' },
+          todEnd: { type: 'integer' },
+          todMode: { type: 'integer' },
+          region: { type: 'string', nullable: true, example: 'Despise' },
+          landmark: { type: 'string', nullable: true, example: 'Covetous' },
+          label: { type: 'string', description: 'Region, else landmark group, else "Wilderness".', example: 'Despise' },
+        },
+      },
+      UoAtlasCreaturePage: {
+        type: 'object',
+        properties: {
+          total: { type: 'integer', description: 'Matching creatures before pagination.', example: 800 },
+          limit: { type: 'integer', example: 50 },
+          offset: { type: 'integer', example: 0 },
+          creatures: { type: 'array', items: { $ref: '#/components/schemas/UoAtlasCreature' } },
+        },
+      },
+      UoAtlasRegion: {
+        type: 'object',
+        description: 'A named region, flattened out of the shard\'s nested Regions.xml.',
+        properties: {
+          facet: { type: 'string', example: 'Felucca' },
+          name: { type: 'string', example: 'Despise' },
+          type: { type: 'string', nullable: true, description: 'ServUO region class.', example: 'DungeonRegion' },
+          priority: { type: 'integer', example: 50 },
+          parent: { type: 'string', nullable: true, example: 'Britain' },
+          rects: {
+            type: 'array',
+            description: 'The rectangles that placed each spawn point.',
+            items: { type: 'object', additionalProperties: true },
+          },
+        },
+      },
+      UoAtlasLandmark: {
+        type: 'object',
+        properties: {
+          facet: { type: 'string', example: 'Trammel' },
+          name: { type: 'string', example: 'Level 1' },
+          group: { type: 'string', nullable: true, description: 'Innermost enclosing parent — the label worth showing.', example: 'Covetous' },
+          x: { type: 'integer', example: 5411 },
+          y: { type: 'integer', example: 1234 },
+          z: { type: 'integer', example: 0 },
+        },
+      },
+      UoAtlasChampion: {
+        type: 'object',
+        description: 'A CONFIGURED champion altar. Not the live board — see GET /public/shard/champs for that.',
+        properties: {
+          slug: { type: 'string', example: 'felucca-deceit' },
+          name: { type: 'string', example: 'Deceit' },
+          group: { type: 'string', nullable: true, description: 'Spawn group; one altar active per group.', example: 'Dungeons' },
+          type: { type: 'string', nullable: true, description: 'NULL when the champion is drawn at activation.', example: 'UnholyTerror' },
+          randomType: { type: 'boolean', example: false },
+          facet: { type: 'string', example: 'Felucca' },
+          x: { type: 'integer' },
+          y: { type: 'integer' },
+          z: { type: 'integer' },
+          radius: { type: 'integer', example: 60 },
+          label: { type: 'string', nullable: true, example: 'Deceit' },
+        },
+      },
+      UoAtlasMeta: {
+        type: 'object',
+        description: 'What atlas is loaded. Game-world facts only: the ServUO path, source hashes and any pending refresh are operator detail and live on the admin status route.',
+        properties: {
+          importedAt: { type: 'string', format: 'date-time', nullable: true },
+          generatedAt: { type: 'string', format: 'date-time', nullable: true },
+          counts: {
+            type: 'object',
+            nullable: true,
+            additionalProperties: true,
+            example: { facets: 6, points: 6455, creatures: 800, regions: 387, landmarks: 558, champions: 25, unresolvedPoints: 1086 },
+          },
+          facets: { type: 'array', items: { type: 'string' }, example: ['Felucca', 'Ilshenar', 'Malas', 'TerMur', 'Tokuno', 'Trammel'] },
+        },
+      },
+      UoAtlasStatus: {
+        type: 'object',
+        description: 'Admin view of atlas state: where the tree is, whether it is readable, whether it has drifted from what is loaded, and any refresh staged for review.',
+        properties: {
+          configured: { type: 'boolean', example: true },
+          path: { type: 'string', example: '/srv/servuo' },
+          treeReadable: { type: 'boolean', example: true },
+          drift: { type: 'boolean', nullable: true, description: 'True when the tree\'s source hashes differ from the loaded atlas. NULL when the tree could not be read.', example: false },
+          facets: { type: 'array', items: { type: 'string' } },
+          importedAt: { type: 'string', format: 'date-time', nullable: true },
+          counts: { type: 'object', nullable: true, additionalProperties: true },
+          pending: {
+            type: 'object',
+            nullable: true,
+            description: 'A refresh that was parsed but NOT applied because it would remove a facet. `status` is pending or rejected.',
+            additionalProperties: true,
+          },
+        },
+      },
+      UoAtlasRefreshResult: {
+        type: 'object',
+        description: 'Outcome of a refresh. Reported rather than thrown, so an unreadable tree is an answer and not a 500.',
+        properties: {
+          status: {
+            type: 'string',
+            enum: ['skipped', 'unavailable', 'unchanged', 'imported', 'needsReview', 'failed', 'rejected', 'none'],
+            example: 'imported',
+          },
+          reason: { type: 'string', nullable: true },
+          path: { type: 'string', nullable: true },
+          counts: { type: 'object', nullable: true, additionalProperties: true },
+          addedFacets: { type: 'array', items: { type: 'string' } },
+          removedFacets: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      UoClilocStatus: {
+        type: 'object',
+        description:
+          'Admin view of cliloc state: where the converted file is, whether it is readable, how many entries are loaded, and whether the file has drifted from them. `configured: false` is a supported state — item names then render as ids.',
+        properties: {
+          configured: { type: 'boolean', example: true },
+          path: { type: 'string', example: '/srv/uo-client' },
+          file: { type: 'string', nullable: true, description: 'The file actually resolved, when the path is a directory.', example: '/srv/uo-client/clilocs.tsv' },
+          fileReadable: { type: 'boolean', example: true },
+          problem: { type: 'string', nullable: true, description: 'Why the file cannot be used, when it cannot. Set (with code COMPRESSED) for a readable-but-unconverted client file.', example: null },
+          code: { type: 'string', nullable: true, description: 'Machine-readable cause of `problem`.', enum: ['NO_PATH', 'NOT_FOUND', 'NO_FILE', 'UNREADABLE', 'COMPRESSED'] },
+          drift: { type: 'boolean', nullable: true, description: 'True when any source hash differs from the loaded table. NULL when the sources could not be read or are not usable.', example: false },
+          count: { type: 'integer', description: 'Entries currently loaded.', example: 67496 },
+          sources: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Every source found now, root-relative, base first then overlays in merge order.',
+            example: ['clilocs.plain', 'custom/uomysticmoon.tsv'],
+          },
+          loadedSources: {
+            type: 'array',
+            nullable: true,
+            description: 'What each source contributed at the last import.',
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string', example: 'custom/uomysticmoon.tsv' },
+                kind: { type: 'string', enum: ['base', 'custom'], example: 'custom' },
+                entries: { type: 'integer', example: 37 },
+                added: { type: 'integer', description: 'Ids this source introduced.', example: 25 },
+                overrode: { type: 'integer', description: 'Ids it replaced from an earlier source.', example: 12 },
+              },
+            },
+          },
+          missingSources: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Sources loaded previously and now absent. An import refuses these without `approve`.',
+            example: [],
+          },
+          importedAt: { type: 'string', format: 'date-time', nullable: true },
+          sourceBytes: { type: 'integer', nullable: true, example: 4973525 },
+        },
+      },
+      UoClilocRefreshResult: {
+        type: 'object',
+        description:
+          'Outcome of a cliloc refresh. Reported rather than thrown, so a missing or compressed file is an answer and not a 500.',
+        properties: {
+          status: {
+            type: 'string',
+            enum: ['skipped', 'unavailable', 'unchanged', 'imported', 'needsReview', 'failed'],
+            description: '`needsReview` means a previously-loaded source has vanished and nothing was applied; re-run with `approve` to accept it.',
+            example: 'imported',
+          },
+          reason: { type: 'string', nullable: true },
+          code: {
+            type: 'string',
+            nullable: true,
+            description: 'Machine-readable cause. `COMPRESSED` means the client\'s own Cliloc.enu was supplied instead of a converted one.',
+            enum: ['NO_PATH', 'NOT_FOUND', 'NO_FILE', 'UNREADABLE', 'COMPRESSED', 'TRUNCATED', 'EMPTY', 'NOT_BUFFER'],
+          },
+          path: { type: 'string', nullable: true },
+          file: { type: 'string', nullable: true },
+          count: { type: 'integer', nullable: true, description: 'Entries stored (blank strings are dropped).', example: 67496 },
+          parsed: { type: 'integer', nullable: true, description: 'Entries read across every source before blanks were dropped.', example: 123527 },
+          blank: { type: 'integer', nullable: true, example: 55994 },
+          sources: {
+            type: 'array',
+            nullable: true,
+            description: 'Per-source breakdown: what each file contributed and how much of it overrode an earlier source.',
+            items: {
+              type: 'object',
+              properties: {
+                label: { type: 'string' },
+                kind: { type: 'string', enum: ['base', 'custom'] },
+                entries: { type: 'integer' },
+                added: { type: 'integer' },
+                overrode: { type: 'integer' },
+              },
+            },
+          },
+          missingSources: {
+            type: 'array',
+            nullable: true,
+            items: { type: 'string' },
+            description: 'On `needsReview`: the sources that vanished. Nothing was applied.',
+          },
+          acceptedMissing: {
+            type: 'array',
+            nullable: true,
+            items: { type: 'string' },
+            description: 'On `imported` with `approve`: the vanished sources the admin accepted.',
+          },
+        },
+      },
+      UoShardLinkRequest: {
+        type: 'object',
+        required: ['code'],
+        properties: {
+          code: { type: 'string', description: 'The one-time code shown by [link in game.', example: 'AB12CD' },
+        },
+      },
+      UoShardLinkResult: {
+        type: 'object',
+        properties: {
+          linked: { type: 'boolean', example: true },
+          account: { type: 'string', example: 'whitlocktech' },
+        },
+      },
+      UoShardLink: {
+        type: 'object',
+        description: 'A linked in-game account (GET /player/shard/accounts).',
+        properties: {
+          account: { type: 'string', example: 'whitlocktech' },
+          userId: { type: 'integer', example: 42 },
+          charName: { type: 'string', nullable: true, example: 'Darrow' },
+          linkedAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      UoTownCrierRequest: {
+        type: 'object',
+        required: ['id', 'lines'],
+        properties: {
+          id: { type: 'string', maxLength: 64, description: 'Re-posting the same id replaces the prior entry.', example: 'news-42' },
+          lines: { type: 'array', items: { type: 'string', maxLength: 200 }, example: ['Hear ye!', 'Market tax is now 5%.'] },
+          durationSec: { type: 'integer', minimum: 1, maximum: 86400, example: 3600 },
+        },
+      },
+    },
+  },
+}