feat(teams): the Team read API, the moderation routes, and Admin -> Teams

The eighteen routes of docs/website/TEAMS.md §2.11, their OpenAPI annotations,
and the staff screen that drives them.

Two rules shape the read model. Hidden means absent from every public surface --
the index, the lookup and the roster alike, and a hidden Team 404s
indistinguishably from one that does not exist, because "absent" includes not
confirming it is there. And staleness is surfaced rather than silent: every
public payload carries { configured, stale, lastSyncAt }, so a page can say how
recently the projection was confirmed instead of presenting stale data as
current.

The public roster withholds both the member key and the user id -- one is a
game-internal identifier, the other names a site account. `linked` answers the
only question a public page has without publishing which account. The module's
per-audience field projection is phase 3's; this is a conservative core one.

The §2.9 gate is enforced per REQUEST, not per route. A moderator may call all
eighteen; three of them mean something different when they do, and the server
decides from the role it re-validates on every request rather than from a token
claim. The client has no "file as request" argument to get wrong.

Found by booting the real server against the real database, and not by any test:
**the index and the by-slug lookup disagreed about what exists.** listPublic was
keyed on a registered team provider while findBySlug is not, so with no module
installed `/teams` returned an empty list while `/teams/:slug/members` served a
full roster -- the index denying a Team that direct URLs answered for in full.
The rows are core's and they outlive the module that filled them: an uninstalled
module leaves a projection that is unmaintained, not one that stopped existing,
and `configured: false` is how a client learns that. The read side no longer
takes the provider into account at all. There is now a test named for the
property.

Also verified live: the public routes answer anonymously, an unknown and a hidden
slug both 404, the player and admin tiers 401 an anonymous caller, a seeded
roster projects correctly, and the reconciler logs that it is staying idle with
no provider registered rather than failing a boot.

Process obligations, all done: #swagger.* annotations on every route, `npm run
swagger` regenerated (18 paths in the spec, no dangling $refs, and the schemas
they reference added), `npm run routes:manifest` regenerated -- additions only,
184 public routes -- and BACKEND_DESIGN.md updated across the schema section and
all three tier tables.

Admin -> Teams follows the ModulesAdmin precedent: everything that decides what a
row SAYS lives in lib/teamAdmin.js, which is plain JS with tests, and the view
renders it. That split earns itself here specifically -- the screen's job is to
make "the shard has no Teams" and "core has not been able to ask for two hours"
impossible to confuse, and those two produce the same empty table. The four
freshness states are named and tested for exactly that reason, and the last
provider error is shown verbatim rather than paraphrased.

The button labels follow the caller's role: a moderator sees "Request publish",
so the pending result is not a surprise. Hiding is offered to everyone with no
gate, matching the server.

Server 894 passed, client 206 passed, client build clean. 17 route tests, 20
client display tests.

Refs docs/website/TEAMS.md §2.11, Part 12 phase 2

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

server/src/model/teams/teams.db.js

@@ -24,6 +24,20 @@ async function activeByModule(moduleId) {
   )
 }
 
+/**
+ * Every ACTIVE team, whichever module owns it.
+ *
+ * For the READ side, which must not be keyed on a provider being registered. The
+ * rows are core's and they outlive the module that filled them — a module
+ * uninstalled or disabled leaves a projection that is unmaintained, not one that
+ * stopped existing. Listing by provider made `/teams` empty while
+ * `/teams/:slug/members` still answered in full, since the lookup goes by slug:
+ * the index denied a Team that direct URLs served.
+ */
+async function allActive() {
+  return query(`SELECT ${TEAM_COLUMNS} FROM teams WHERE status = 'active' ORDER BY id`)
+}
+
 /** The ACTIVE row for an external id, or undefined. At most one, by uq_teams_active. */
 async function findActive(moduleId, externalId) {
   const rows = await query(
@@ -270,6 +284,7 @@ async function setPendingEmpty(moduleId, since) {
 
 module.exports = {
   activeByModule,
+  allActive,
   findActive,
   findById,
   findBySlug,

server/src/model/teams/teams.model.js

@@ -0,0 +1,296 @@
+// ── The Team read model ────────────────────────────────────────────────────
+//
+// What the three API tiers are allowed to see (TEAMS.md §2.11), assembled from
+// the projection, the resolver and the sync state.
+//
+// **Two rules shape every function here.**
+//
+// 1. *Hidden means absent from every public surface* (§2.8.3) — the index, the
+//    lookup, the roster. Not archived, not deleted, and completely functional for
+//    its own members. A hidden Team that 404s publicly but answers for a member
+//    is the intended behaviour, not an inconsistency.
+//
+// 2. *Staleness is surfaced, never silent* (§2.4). Every public payload carries
+//    `{ stale, lastSyncAt }`, so a page can say "roster last confirmed 14 minutes
+//    ago" rather than presenting a stale roster as current. A projection nobody
+//    can tell is stale is worse than one that is obviously old.
+//
+// The per-audience FIELD projection of a roster row is the module's, not core's
+// (§10.5, §3.3) — the visibility framework and its config are module-owned. This
+// phase serves a conservative core projection: a public roster carries in-game
+// display names and never a site account id or a game member key. The module's
+// rung-aware projection lands with the Team pages in phase 3.
+
+const teamsDb = require('./teams.db')
+const teamProvider = require('./teamProvider')
+const access = require('./teamAccess.model')
+const teamSync = require('./teamSync.model')
+
+// Past this multiple of the poll interval a projection is reported stale. Two
+// intervals rather than one, so an ordinary late poll does not make every page
+// cry wolf — the threshold has to mean "something is wrong", not "a run is due".
+const STALE_INTERVALS = 2
+
+/** The public shape of a Team. Deliberately small. */
+function publicTeam(row) {
+  return {
+    slug: row.slug,
+    // What is DISPLAYED may have been overridden by staff; what the row IS never
+    // changes (§2.2, §2.8.3). Public callers only ever see the former.
+    name: row.display_name_override || row.name,
+    abbr: row.abbr,
+    memberCount: row.member_count,
+    linkedCount: row.linked_count,
+    onlineCount: row.online_count,
+    meta: row.meta ?? null,
+    status: row.status,
+    createdAt: row.created_at,
+    rosterSyncedAt: row.roster_synced_at,
+    ...(row.status === 'archived' ? { archivedAt: row.archived_at, archivedReason: row.archived_reason } : {}),
+  }
+}
+
+/**
+ * The public shape of a roster row.
+ *
+ * `member_key` and `user_id` are both withheld: the first is a game-internal
+ * identifier and the second names a site account. `linked` answers the only
+ * question a public page has — whether this character has an account behind it —
+ * without publishing which one.
+ */
+function publicMember(row) {
+  return {
+    displayName: row.display_name,
+    rankLabel: row.rank_label,
+    isLeader: Boolean(row.is_leader),
+    online: Boolean(row.online),
+    linked: row.user_id != null,
+  }
+}
+
+/** The admin shape: everything, including what a decision overrode. */
+function adminTeam(row) {
+  return {
+    id: row.id,
+    moduleId: row.module_id,
+    externalId: row.external_id,
+    slug: row.slug,
+    name: row.name,
+    displayName: row.display_name_override || row.name,
+    displayNameOverride: row.display_name_override,
+    abbr: row.abbr,
+    status: row.status,
+    hidden: Boolean(row.hidden),
+    hiddenReason: row.hidden_reason,
+    hiddenTerm: row.hidden_term,
+    nameReviewedAt: row.name_reviewed_at,
+    memberCount: row.member_count,
+    linkedCount: row.linked_count,
+    onlineCount: row.online_count,
+    rosterSyncedAt: row.roster_synced_at,
+    membersEmptySince: row.members_empty_since,
+    succeededBy: row.succeeded_by,
+    createdAt: row.created_at,
+    archivedAt: row.archived_at,
+    archivedReason: row.archived_reason,
+    meta: row.meta ?? null,
+  }
+}
+
+function adminMember(row) {
+  return {
+    memberKey: row.member_key,
+    displayName: row.display_name,
+    userId: row.user_id,
+    rankLabel: row.rank_label,
+    isLeader: Boolean(row.is_leader),
+    isLeaderSynced: Boolean(row.is_leader_synced),
+    leaderOverride: row.leader_override || null,
+    online: Boolean(row.online),
+    status: row.status,
+    firstSeenAt: row.first_seen_at,
+    lastSeenAt: row.last_seen_at,
+    departedAt: row.departed_at,
+  }
+}
+
+/**
+ * Freshness, as every public payload reports it.
+ *
+ * With no provider registered there is nothing to be stale ABOUT, so this reports
+ * `stale: false` and a null timestamp rather than "very stale" — a deployment
+ * with no game module is not a broken one.
+ */
+async function syncStatus() {
+  const moduleId = teamProvider.providerModuleId()
+  if (!moduleId) return { stale: false, lastSyncAt: null, configured: false }
+
+  const [state, intervalS] = await Promise.all([
+    teamsDb.syncState(moduleId),
+    teamSync.intervalSeconds(),
+  ])
+  const lastSyncAt = state ? state.last_success_at : null
+  const ageS = lastSyncAt ? (Date.now() - new Date(lastSyncAt).getTime()) / 1000 : Infinity
+  return {
+    configured: true,
+    lastSyncAt,
+    // Never synced at all is stale: a page must not present an empty projection
+    // as a confirmed empty shard.
+    stale: ageS > intervalS * STALE_INTERVALS,
+    consecutiveFailures: state ? state.consecutive_failures : 0,
+  }
+}
+
+// ── Public ─────────────────────────────────────────────────────────────────
+
+async function listPublic({ limit = 50, offset = 0 } = {}) {
+  // Every active Team, not just the registered provider's. The rows are core's
+  // and they outlive the module that filled them: keying the index on a provider
+  // made an uninstalled module's Teams vanish from /teams while
+  // /teams/:slug/members still served them in full, because the lookup goes by
+  // slug. `configured: false` is how a client learns the projection is no longer
+  // being maintained -- an empty list would have said something untrue instead.
+  const [rows, sync] = await Promise.all([teamsDb.allActive(), syncStatus()])
+  const visible = rows.filter((r) => !r.hidden)
+  return {
+    teams: visible.slice(offset, offset + limit).map(publicTeam),
+    total: visible.length,
+    ...sync,
+  }
+}
+
+/**
+ * One Team by slug, for a public caller.
+ *
+ * An ARCHIVED Team resolves rather than 404ing (§2.2): a bookmark or a Discord
+ * link from before a rename must land somewhere that explains itself. A HIDDEN
+ * one does not resolve at all — that is the difference between retired and
+ * suppressed.
+ */
+async function getPublic(slug) {
+  const row = await teamsDb.findBySlug(slug)
+  if (!row || row.hidden) return null
+  const sync = await syncStatus()
+  const successor = row.succeeded_by ? await teamsDb.findById(row.succeeded_by) : null
+  return {
+    ...publicTeam(row),
+    ...sync,
+    successor: successor && !successor.hidden
+      ? { slug: successor.slug, name: successor.display_name_override || successor.name }
+      : null,
+  }
+}
+
+async function rosterPublic(slug) {
+  const row = await teamsDb.findBySlug(slug)
+  if (!row || row.hidden) return null
+  const [members, sync] = await Promise.all([
+    access.rosterWithOverrides(row.id),
+    syncStatus(),
+  ])
+  return { members: members.map(publicMember), ...sync, rosterSyncedAt: row.roster_synced_at }
+}
+
+// ── Player ─────────────────────────────────────────────────────────────────
+
+/**
+ * The caller's Teams — membership and grants — each with the REASON it is listed.
+ *
+ * The two are read from their own tables and merged here rather than by a query
+ * that unions them, so the reason survives into the payload. `both` is a real
+ * state and the UI needs it: a member who also holds a historical grant should
+ * see membership as the current reason without the grant vanishing.
+ *
+ * A hidden Team IS listed here. Suppression is a public-surface rule; a member is
+ * not a member of the public.
+ */
+async function listForUser(userId) {
+  const memberships = await teamsDb.activeTeamsForUser(userId)
+  const byId = new Map()
+
+  for (const row of memberships) {
+    byId.set(row.id, { ...publicTeam(row), reason: 'membership', isLeader: Boolean(row.is_leader) })
+  }
+
+  // Grants are per Team, so the visible set is walked rather than queried the
+  // other way round; the population is small (a user's Teams), and it keeps path
+  // 3's read on path 3's table.
+  const all = await teamsDb.allActive()
+  for (const row of all) {
+    // eslint-disable-next-line no-await-in-loop
+    const resolved = await access.forumAccess(row.id, userId)
+    if (!resolved.viaGrant) continue
+    const existing = byId.get(row.id)
+    if (existing) existing.reason = 'both'
+    else byId.set(row.id, { ...publicTeam(row), reason: 'grant', isLeader: false })
+  }
+
+  return { teams: [...byId.values()], ...(await syncStatus()) }
+}
+
+/** The caller's own resolved access on one Team. */
+async function accessForUser(slug, userId) {
+  const row = await teamsDb.findBySlug(slug)
+  if (!row) return null
+  const resolved = await access.forumAccess(row.id, userId)
+  return { slug: row.slug, ...resolved }
+}
+
+// ── Admin ──────────────────────────────────────────────────────────────────
+
+async function listAdmin({ includeArchived = false } = {}) {
+  const moduleId = teamProvider.providerModuleId()
+  const rows = await teamsDb.allActive()
+  const sync = await syncStatus()
+  const state = moduleId ? await teamsDb.syncState(moduleId) : null
+  return {
+    teams: rows.map(adminTeam),
+    ...sync,
+    // Shown verbatim on Admin → Teams, including the last error: an operator
+    // debugging a stale projection needs what the provider actually said.
+    syncState: state
+      ? {
+        moduleId: state.module_id,
+        lastAttemptAt: state.last_attempt_at,
+        lastSuccessAt: state.last_success_at,
+        consecutiveFailures: state.consecutive_failures,
+        lastError: state.last_error,
+        pendingEmptySince: state.pending_empty_since,
+      }
+      : null,
+    includeArchived,
+  }
+}
+
+async function getAdmin(id) {
+  const row = await teamsDb.findById(id)
+  if (!row) return null
+  const [members, grants, pending] = await Promise.all([
+    access.rosterWithOverrides(row.id, { includeDeparted: true }),
+    access.grantLedger(row.id),
+    // eslint-disable-next-line global-require
+    require('./teamModeration.model').pendingForTeam(row.id),
+  ])
+  return {
+    ...adminTeam(row),
+    members: members.map(adminMember),
+    grants,
+    pendingRequests: pending,
+  }
+}
+
+module.exports = {
+  listPublic,
+  getPublic,
+  rosterPublic,
+  listForUser,
+  accessForUser,
+  listAdmin,
+  getAdmin,
+  syncStatus,
+  publicTeam,
+  publicMember,
+  adminTeam,
+  adminMember,
+  STALE_INTERVALS,
+}

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

@@ -31,6 +31,7 @@ const emailRouter = require('./email.router')
 const discordBotRouter = require('./discordBot.router')
 const settingsRouter = require('./settings.router')
 const modulesRouter = require('./modules.router')
+const teamsRouter = require('./teams.router')
 const dashboardRouter = require('./dashboard.router')
 
 const adminRouter = express.Router()
@@ -79,6 +80,11 @@ adminRouter.use('/settings', settingsRouter)
 // here alongside the other configuration capabilities, and admin-only per route
 // rather than at this line, so the gate sits next to what it is guarding.
 adminRouter.use('/modules', modulesRouter)
+// Teams. Staff-wide, like /activity: a moderator runs the reserved-name review
+// queue. The three actions that PUBLISH untrusted game-sourced strings are gated
+// per request inside the controller, not per route — a moderator may call them,
+// and calling them files a request rather than applying one (TEAMS.md §2.9).
+adminRouter.use('/teams', teamsRouter)
 
 // The two singletons that own no path segment of their own: GET /dashboard and
 // PUT /site-mode. Mounted at the group root, last, exactly where the residual

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

@@ -0,0 +1,211 @@
+// Admin · Teams — the staff surface (TEAMS.md §2.11).
+//
+// The role split inside this file is the §2.9 gate, and it is enforced HERE
+// rather than in the router, because it is not a matter of which routes a role
+// may call: a moderator may call all of them, and three of them mean something
+// different when they do. `requestOrApply` is what decides, from the caller's
+// live role, whether an action applies or is filed for approval.
+
+const teams = require('../../../model/teams/teams.model')
+const moderation = require('../../../model/teams/teamModeration.model')
+const access = require('../../../model/teams/teamAccess.model')
+const teamSync = require('../../../model/teams/teamSync.model')
+const teamsDb = require('../../../model/teams/teams.db')
+const activity = require('../../../model/activity/activity.model')
+
+const log = require('../../../utils/logger')('teams')
+
+const fail = (res, err, what) => {
+  log.error(`admin teams: ${what} failed`, { message: err.message })
+  return res.status(500).json({ message: 'Internal Server Error' })
+}
+
+/** Translate a model result's { ok, status, error } into a response. */
+const send = (res, result, body = { ok: true }) =>
+  (result.ok ? res.json({ ...body, ...result }) : res.status(result.status || 400).json({ message: result.error }))
+
+async function listTeams(req, res) {
+  try {
+    return res.json(await teams.listAdmin({ includeArchived: req.query.archived === '1' }))
+  } catch (err) {
+    return fail(res, err, 'list')
+  }
+}
+
+async function getTeam(req, res) {
+  try {
+    const team = await teams.getAdmin(Number(req.params.id))
+    if (!team) return res.status(404).json({ message: 'Team not found' })
+    return res.json(team)
+  } catch (err) {
+    return fail(res, err, 'get')
+  }
+}
+
+/**
+ * The operator's escape hatch.
+ *
+ * Awaited rather than fire-and-forget: someone who pressed a button is owed the
+ * outcome, including the provider's error when it refused. `ctx.teams.reconcile()`
+ * is the debounced, unawaited path — this is not that.
+ */
+async function resync(req, res) {
+  try {
+    const result = await teamSync.reconcileNow('admin')
+    await activity.log({ req, action: 'team.resync', detail: `${req.user.username} (#${req.user.id}) ran a Team resync` })
+    return res.json(result)
+  } catch (err) {
+    return fail(res, err, 'resync')
+  }
+}
+
+async function archive(req, res) {
+  try {
+    const id = Number(req.params.id)
+    const team = await teamsDb.findById(id)
+    if (!team) return res.status(404).json({ message: 'Team not found' })
+    await teamsDb.archiveTeam(id, 'staff')
+    await activity.log({
+      req,
+      action: 'team.archive',
+      detail: `${req.user.username} (#${req.user.id}) archived team "${team.name}" (#${id})`
+        + `${req.body.reason ? `: "${req.body.reason}"` : ''}`,
+    })
+    return res.json({ ok: true })
+  } catch (err) {
+    return fail(res, err, 'archive')
+  }
+}
+
+async function grants(req, res) {
+  try {
+    return res.json({ grants: await access.grantLedger(Number(req.params.id)) })
+  } catch (err) {
+    return fail(res, err, 'grants')
+  }
+}
+
+// ── Leadership overrides (§2.5.1) — NOT gated ─────────────────────────────
+
+async function setLeaderOverride(req, res) {
+  try {
+    const id = Number(req.params.id)
+    const team = await teamsDb.findById(id)
+    if (!team) return res.status(404).json({ message: 'Team not found' })
+
+    const { memberKey, effect, reason } = req.body
+    await access.setLeaderOverride({
+      teamId: id,
+      memberKey,
+      effect,
+      actorUserId: req.user.id,
+      actorUsername: req.user.username,
+      reason: reason || null,
+    })
+    await activity.log({
+      req,
+      action: 'team.leader.override',
+      detail: `${req.user.username} (#${req.user.id}) set a "${effect}" leadership override on `
+        + `${memberKey} in team "${team.name}" (#${id})${reason ? `: "${reason}"` : ''}`,
+    })
+    return res.json({ ok: true })
+  } catch (err) {
+    return fail(res, err, 'leader-override')
+  }
+}
+
+async function clearLeaderOverride(req, res) {
+  try {
+    const id = Number(req.params.id)
+    const removed = await access.clearLeaderOverride(id, req.params.memberKey)
+    if (!removed) return res.status(404).json({ message: 'No such override' })
+    await activity.log({
+      req,
+      action: 'team.leader.override',
+      detail: `${req.user.username} (#${req.user.id}) cleared the leadership override on `
+        + `${req.params.memberKey} in team #${id}`,
+    })
+    return res.json({ ok: true })
+  } catch (err) {
+    return fail(res, err, 'leader-override')
+  }
+}
+
+// ── The three gated actions, plus the ungated hide (§2.9) ─────────────────
+
+async function unhide(req, res) {
+  try {
+    return send(res, await moderation.requestOrApply({
+      req, actor: req.user, teamId: Number(req.params.id), action: 'unhide', reason: req.body.reason,
+    }))
+  } catch (err) {
+    return fail(res, err, 'unhide')
+  }
+}
+
+async function hide(req, res) {
+  try {
+    return send(res, await moderation.hide({
+      req, actor: req.user, teamId: Number(req.params.id), reason: req.body.reason,
+    }))
+  } catch (err) {
+    return fail(res, err, 'hide')
+  }
+}
+
+async function displayName(req, res) {
+  try {
+    const { displayName: value, reason } = req.body
+    // An empty string is how a UI says "clear it", and clearing is its own gated
+    // action rather than an override set to nothing — otherwise the audit line
+    // would read as though someone published a blank name.
+    const action = value ? 'display_name_override' : 'clear_display_name_override'
+    return send(res, await moderation.requestOrApply({
+      req, actor: req.user, teamId: Number(req.params.id), action, payload: { displayName: value || null }, reason,
+    }))
+  } catch (err) {
+    return fail(res, err, 'display-name')
+  }
+}
+
+async function reviewQueue(req, res) {
+  try {
+    return res.json({ teams: await moderation.reviewQueue() })
+  } catch (err) {
+    return fail(res, err, 'review queue')
+  }
+}
+
+async function listRequests(req, res) {
+  try {
+    return res.json({ requests: await moderation.listRequests({ status: req.query.status || 'pending' }) })
+  } catch (err) {
+    return fail(res, err, 'requests')
+  }
+}
+
+async function decideRequest(req, res) {
+  try {
+    return send(res, await moderation.decide({
+      req, actor: req.user, requestId: Number(req.params.id), status: req.body.status, note: req.body.note,
+    }))
+  } catch (err) {
+    return fail(res, err, 'decide')
+  }
+}
+
+module.exports = {
+  listTeams,
+  getTeam,
+  resync,
+  archive,
+  grants,
+  setLeaderOverride,
+  clearLeaderOverride,
+  unhide,
+  hide,
+  displayName,
+  reviewQueue,
+  listRequests,
+  decideRequest,
+}

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

@@ -0,0 +1,223 @@
+// Admin · Teams — sync state, the review queue, the approval queue, and the staff
+// actions on a Team (TEAMS.md §2.11).
+//
+// Mounted at /api/v1/admin/teams by admin/index.js, which already applied
+// `noindex, isLoggedIn, staffOnly`. Staff-wide, like /admin/activity: a moderator
+// runs the review queue, and the three actions that PUBLISH untrusted
+// game-sourced strings are gated per request inside the controller rather than
+// per route here — a moderator may call them, and calling them files a request
+// instead of applying one.
+//
+// **Declaration order matters in this file.** `/review`, `/requests` and `/resync`
+// are literal paths that would otherwise be captured by `/:id`, so every literal
+// route is declared before the first :param route. Express is first-match-wins and
+// a `/:id` ahead of `/review` would silently turn a queue into a lookup for a Team
+// whose id is "review".
+
+const express = require('express')
+const { body, param, query } = require('express-validator')
+
+const ctrl = require('./teams.controller')
+const validate = require('../../../middleware/validate')
+
+const teamsRouter = express.Router()
+
+// ── Literal paths, first ───────────────────────────────────────────────────
+
+teamsRouter.get(
+  '/',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'List Teams with sync state'
+  // #swagger.description = 'Includes hidden Teams and the module’s sync state verbatim — last attempt, last success, consecutive failures and the last error — which is what an operator debugging a stale projection needs.'
+  // #swagger.parameters['archived'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Set to 1 to include archived Teams.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Teams and sync state', content: { "application/json": { schema: { $ref: "#/components/schemas/AdminTeamList" } } } } */
+  query('archived').optional().isIn(['0', '1']),
+  validate,
+  ctrl.listTeams,
+)
+
+teamsRouter.post(
+  '/resync',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Run a reconciliation now'
+  // #swagger.description = 'Awaited, so the response carries the outcome including the provider’s own error when it refused. The four refusal gates still apply — a manual resync cannot make core act on an answer it does not trust.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The reconciliation result', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamResyncResult" } } } } */
+  ctrl.resync,
+)
+
+teamsRouter.get(
+  '/review',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'The reserved-name review queue'
+  // #swagger.description = 'Teams auto-hidden because their name matched a reserved term, each showing which term matched. A Team a human has already ruled on leaves the queue and is never re-hidden by a later sweep.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Auto-hidden Teams awaiting review', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamReviewQueue" } } } } */
+  ctrl.reviewQueue,
+)
+
+teamsRouter.get(
+  '/requests',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'The moderation approval queue'
+  // #swagger.description = 'Requests filed by moderators for the three actions that publish untrusted game-sourced strings. Decided rows are kept — the record that a moderator asked to publish a name and an admin refused is the part worth having.'
+  // #swagger.parameters['status'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'pending (default) | approved | rejected | withdrawn | all' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Moderation requests', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamRequestQueue" } } } } */
+  query('status').optional().isIn(['pending', 'approved', 'rejected', 'withdrawn', 'all']),
+  validate,
+  ctrl.listRequests,
+)
+
+teamsRouter.post(
+  '/requests/:id/decide',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Approve or reject a moderation request (admin only)'
+  // #swagger.description = 'Admin only, checked live against the database rather than from a token claim. Approving applies the action; rejecting keeps the row and changes nothing. A request already decided returns 409, so two admins deciding at once cannot double-apply.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Request id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamDecideRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Decided', content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[403] = { description: 'Only an admin may decide a request', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'No such request', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[409] = { description: 'Already decided', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('status').isIn(['approved', 'rejected']),
+  body('note').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.decideRequest,
+)
+
+// ── :id paths ──────────────────────────────────────────────────────────────
+
+teamsRouter.get(
+  '/:id',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Get one Team, with its roster, grant ledger and pending requests'
+  // #swagger.description = 'The roster carries the resolved leadership and what the game actually said, so an override is visible as a decision rather than presented as fact. Departed members are included.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The Team', content: { "application/json": { schema: { $ref: "#/components/schemas/AdminTeam" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  validate,
+  ctrl.getTeam,
+)
+
+teamsRouter.get(
+  '/:id/grants',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'The full forum-grant ledger for a Team, revoked rows included'
+  // #swagger.description = 'The structured record the access resolver reads. The grant/revoke flow itself lands in the forum phase; this is the read side.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The grant ledger', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamGrantLedger" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  validate,
+  ctrl.grants,
+)
+
+teamsRouter.post(
+  '/:id/archive',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Archive a Team (staff)'
+  // #swagger.description = 'Not gated: archiving withdraws a Team from public surfaces rather than publishing anything.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamReasonRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Archived', content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('reason').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.archive,
+)
+
+teamsRouter.post(
+  '/:id/hide',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Hide a Team from public surfaces (staff)'
+  // #swagger.description = 'Deliberately NOT gated. Publishing untrusted data needs a second pair of eyes; withdrawing it needs to be possible at once, by whoever is on duty.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamReasonRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Hidden', content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('reason').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.hide,
+)
+
+teamsRouter.post(
+  '/:id/unhide',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Un-hide a Team — admin applies, moderator requests'
+  // #swagger.description = 'One of the three gated actions: it publishes a name that tripped the impersonation list. An admin applies it at once; a moderator files a pending request and nothing changes publicly until an admin approves.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: false, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamReasonRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Applied, or filed for approval — see `pending`', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamModerationResult" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('reason').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.unhide,
+)
+
+teamsRouter.post(
+  '/:id/display-name',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Set or clear a Team’s display name — admin applies, moderator requests'
+  // #swagger.description = 'Gated for the same reason as un-hiding: it substitutes free text into the same public surfaces. Identity is untouched — the Team’s `name` stays frozen for the life of the row, and only what is rendered changes. An empty displayName clears the override.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamDisplayNameRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Applied, or filed for approval — see `pending`', content: { "application/json": { schema: { $ref: "#/components/schemas/TeamModerationResult" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('displayName').optional({ nullable: true }).isString().trim().isLength({ max: 160 }),
+  body('reason').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.displayName,
+)
+
+teamsRouter.post(
+  '/:id/leader-override',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Grant or deny leadership for one member (staff)'
+  // #swagger.description = 'Applied on top of the synced value at READ time; the projection is never mutated. That is what makes an override survive a resync — one written into team_members would be undone by the next reconciliation. Not gated: it publishes no game-sourced string.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/TeamLeaderOverrideRequest" } } } } */
+  /* #swagger.responses[200] = { description: 'Override set', content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } } } */
+  /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  body('memberKey').isString().trim().isLength({ min: 1, max: 191 }),
+  body('effect').isIn(['grant', 'deny']),
+  body('reason').optional().isString().trim().isLength({ max: 255 }),
+  validate,
+  ctrl.setLeaderOverride,
+)
+
+teamsRouter.delete(
+  '/:id/leader-override/:memberKey',
+  // #swagger.tags = ['Admin · Teams']
+  // #swagger.summary = 'Clear a leadership override (staff)'
+  // #swagger.description = 'The member reverts to whatever the game says at the next read; nothing in the projection changes, because nothing in it was ever changed.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, schema: { type: 'integer' }, description: 'Team id.' }
+  // #swagger.parameters['memberKey'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The module’s member key.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'Override cleared', content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } } } */
+  /* #swagger.responses[404] = { description: 'No such override', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('id').isInt({ min: 1 }).toInt(),
+  param('memberKey').isString().trim().isLength({ min: 1, max: 191 }),
+  validate,
+  ctrl.clearLeaderOverride,
+)
+
+module.exports = teamsRouter

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

@@ -26,6 +26,7 @@ const noindex = require('../../../middleware/noindex')
 
 const accountRouter = require('./account.router')
 const appealsRouter = require('./appeals.router')
+const teamsRouter = require('./teams.router')
 
 const playerRouter = express.Router()
 
@@ -39,5 +40,6 @@ playerRouter.use(noindex, requireAuth)
 
 playerRouter.use('/account', accountRouter)
 playerRouter.use('/appeals', appealsRouter)
+playerRouter.use('/teams', teamsRouter)
 
 module.exports = playerRouter

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

@@ -0,0 +1,28 @@
+// Player · Teams — self-scoped reads. Neither handler takes an identity from the
+// caller; both use req.user.id, which the tier's requireAuth has already proved.
+
+const teams = require('../../../model/teams/teams.model')
+
+const log = require('../../../utils/logger')('teams')
+
+async function listMine(req, res) {
+  try {
+    return res.json(await teams.listForUser(req.user.id))
+  } catch (err) {
+    log.error('player teams: list failed', { message: err.message })
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+async function getMyAccess(req, res) {
+  try {
+    const resolved = await teams.accessForUser(req.params.slug, req.user.id)
+    if (!resolved) return res.status(404).json({ message: 'Team not found' })
+    return res.json(resolved)
+  } catch (err) {
+    log.error('player teams: access failed', { message: err.message })
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
+module.exports = { listMine, getMyAccess }

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

@@ -0,0 +1,46 @@
+// Player · Teams — the caller's own Teams and their own access on one.
+//
+// Mounted at /api/v1/player/teams by player/index.js, which already applied
+// `noindex, requireAuth`. No extra gate: both handlers are self-scoped to
+// req.user.id and neither takes a user id from the caller.
+//
+// **Staff are a superset of players.** This group is open to any authenticated
+// account, not just role 'player' — a moderator is in guilds too, and gating on
+// the role would 403 them off their own Teams. That mistake has been made here
+// once already (see player/index.js).
+//
+// Leader-exercised actions — granting forum access — land in phase 4 and will
+// live under this same prefix rather than under /admin: a leader is a player, and
+// the /admin tier gate is requireRole('admin','editor','moderator'), so putting a
+// leader endpoint behind it would mean widening that gate.
+
+const express = require('express')
+
+const ctrl = require('./teams.controller')
+
+const teamsRouter = express.Router()
+
+teamsRouter.get(
+  '/',
+  // #swagger.tags = ['Player · Teams']
+  // #swagger.summary = 'List the caller’s Teams, with the reason for each'
+  // #swagger.description = 'Membership and forum grants are separate authority paths, so each Team carries `reason`: membership | grant | both. A Team hidden from public surfaces is still listed here — suppression is a public-surface rule, and a member is not a member of the public.'
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The caller’s Teams', content: { "application/json": { schema: { $ref: "#/components/schemas/PlayerTeamList" } } } } */
+  /* #swagger.responses[403] = { description: 'Account not active (disabled/banned)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.listMine,
+)
+
+teamsRouter.get(
+  '/:slug/access',
+  // #swagger.tags = ['Player · Teams']
+  // #swagger.summary = 'The caller’s own resolved access on one Team'
+  // #swagger.description = 'Reports viaMembership and viaGrant separately, and keeps both when both hold: the UI presents membership as the current reason while the grant survives as audit history.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The Team slug.' }
+  // #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
+  /* #swagger.responses[200] = { description: 'The caller’s access', content: { "application/json": { schema: { $ref: "#/components/schemas/PlayerTeamAccess" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  ctrl.getMyAccess,
+)
+
+module.exports = teamsRouter

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

@@ -21,6 +21,7 @@ const postsRouter = require('./posts.router')
 const wikiRouter = require('./wiki.router')
 const pagesRouter = require('./pages.router')
 const modulesRouter = require('./modules.router')
+const teamsRouter = require('./teams.router')
 const siteRouter = require('./site.router')
 
 const publicRouter = express.Router()
@@ -36,6 +37,10 @@ publicRouter.use('/pages', pagesRouter)
 // /modules unclaimable by a module. Never site-mode gated: a client must be able
 // to feature-detect while the site is in maintenance.
 publicRouter.use('/modules', modulesRouter)
+// Teams. A core prefix, not a module's: the entity is core's even though a module
+// is what populates it (TEAMS.md §10.3). Site-mode gated per route, like the
+// content above it.
+publicRouter.use('/teams', teamsRouter)
 
 // The four singletons that own no path segment of their own: /settings, /status,
 // /version and /contact. Mounted at the group root, last — safe only because

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

@@ -0,0 +1,48 @@
+// Public · Teams — the anonymous read surface (TEAMS.md §2.11).
+//
+// Every handler here is a projection over core's own tables; nothing calls the
+// module. A Team page must render while the shard is down, showing a roster
+// marked stale, because that is what the projection is for.
+
+const teams = require('../../../model/teams/teams.model')
+
+const log = require('../../../utils/logger')('teams')
+
+const fail = (res, err, what) => {
+  log.error(`public teams: ${what} failed`, { message: err.message })
+  return res.status(500).json({ message: 'Internal Server Error' })
+}
+
+async function listTeams(req, res) {
+  try {
+    const limit = Math.min(Number.parseInt(req.query.limit, 10) || 50, 200)
+    const offset = Math.max(Number.parseInt(req.query.offset, 10) || 0, 0)
+    return res.json(await teams.listPublic({ limit, offset }))
+  } catch (err) {
+    return fail(res, err, 'list')
+  }
+}
+
+async function getTeam(req, res) {
+  try {
+    const team = await teams.getPublic(req.params.slug)
+    // A hidden Team is indistinguishable from a missing one here, deliberately:
+    // "absent from every public surface" includes not confirming it exists.
+    if (!team) return res.status(404).json({ message: 'Team not found' })
+    return res.json(team)
+  } catch (err) {
+    return fail(res, err, 'get')
+  }
+}
+
+async function getRoster(req, res) {
+  try {
+    const roster = await teams.rosterPublic(req.params.slug)
+    if (!roster) return res.status(404).json({ message: 'Team not found' })
+    return res.json(roster)
+  } catch (err) {
+    return fail(res, err, 'roster')
+  }
+}
+
+module.exports = { listTeams, getTeam, getRoster }

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

@@ -0,0 +1,54 @@
+// Public · Teams — the anonymous Team surface (TEAMS.md §2.11).
+//
+// Mounted at /api/v1/public/teams by public/index.js. No group gate: this is the
+// anonymous surface, and `siteMode` is applied per route as everywhere else in
+// this tier — during maintenance only an admin with a valid session sees content.
+//
+// Declaration order: '/' is literal and precedes the two :slug routes, and
+// '/:slug/members' is deeper than '/:slug', so nothing here can shadow anything
+// else.
+
+const express = require('express')
+
+const ctrl = require('./teams.controller')
+const siteMode = require('../../../middleware/siteMode')
+
+const teamsRouter = express.Router()
+
+teamsRouter.get(
+  '/',
+  // #swagger.tags = ['Public · Teams']
+  // #swagger.summary = 'List active, publicly visible Teams'
+  // #swagger.description = 'Teams hidden by reserved-name screening or by staff are absent. The response carries { stale, lastSyncAt } so a client can say how recently the projection was confirmed against the game.'
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Page size, max 200 (default 50).' }
+  // #swagger.parameters['offset'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Rows to skip (default 0).' }
+  /* #swagger.responses[200] = { description: 'Publicly visible Teams, with sync freshness', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicTeamList" } } } } */
+  siteMode,
+  ctrl.listTeams,
+)
+
+teamsRouter.get(
+  '/:slug',
+  // #swagger.tags = ['Public · Teams']
+  // #swagger.summary = 'Get one Team by slug'
+  // #swagger.description = 'An archived Team still resolves, read-only, and names its successor when it was renamed — an old bookmark or Discord link lands somewhere that explains itself. A hidden Team returns 404, indistinguishable from one that does not exist.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The Team slug.' }
+  /* #swagger.responses[200] = { description: 'The Team', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicTeam" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team, or it is hidden', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getTeam,
+)
+
+teamsRouter.get(
+  '/:slug/members',
+  // #swagger.tags = ['Public · Teams']
+  // #swagger.summary = 'Get a Team roster'
+  // #swagger.description = 'In-game display names only. A member key is a game-internal identifier and a user id names a site account; neither is published. `linked` answers whether a character has an account behind it without saying which.'
+  // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The Team slug.' }
+  /* #swagger.responses[200] = { description: 'The roster, with sync freshness', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicTeamRoster" } } } } */
+  /* #swagger.responses[404] = { description: 'No such Team, or it is hidden', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  siteMode,
+  ctrl.getRoster,
+)
+
+module.exports = teamsRouter