@bongos/core 1.17.0

package/src/bongos/serve-internal.js

@@ -0,0 +1,889 @@
+// src/bongos/serve-internal.js — the shared INTERNAL web surface (ADR 0062 R51, task 1190).
+//
+// Mounts every non-game surface the platform serves onto an Express app:
+//   * /healthz + /version          — liveness + deployed-build info
+//   * /api/gds/*                    — the GDS API (buildGdsRouter)
+//   * /downloads/devbox/*           — Dev Box installer redirect surface (#904)
+//   * generic module web-surface   — each enabled module's contributes.webSurfaces
+//     hosts                          served on its Host prefix by ONE generic static
+//                                     loop (the status dashboard at status.<apex>,
+//                                     BV1.R84). The hall declares a webSurface too
+//                                     but is partitioned OUT of this loop — it has
+//                                     the dedicated richer serving below.
+//   * the builders' hall host       — modules/hall-ui/public/ (builders.<apex>, the
+//                                     hall-ui module's web surface carved in BV1.R85)
+//                                     + the apex /builders/* tree, with the subdomain
+//                                     shim, the Archon/citizen page gates, the
+//                                     asset-stamped HTML, and the primer/diagram
+//                                     static mounts.
+//
+// WHY THIS MODULE EXISTS: the game boot (server.js) and the GDS-only boot
+// (src/platform-server.js, R51) must serve these surfaces IDENTICALLY. Rather
+// than copy-paste the ~330 lines of host routing into both — which would drift
+// the moment one entrypoint changed — both call mountInternalSurfaces(app). This
+// mirrors the registerGameRooms() pattern that keeps server.js and
+// preview-server.js from drifting on the game-room list (ADR 0052).
+//
+// CORE-SAFE: this file lives under src/bongos/ and so is held to the core↔host
+// import boundary (scripts/gds/fitness.js §1) — it imports nothing from the host
+// game runtime (no src/db.js, no src/rooms/, no src/world/, no Colyseus). It
+// serves only static files + the GDS router, so a non-game Cloud Bongos instance
+// runs it unchanged. (The /downloads/devbox/* surface is an instance feature that
+// R54's module system, task 1193, will gate per-instance; it is benign on a
+// vanilla boot — it only redirects to whatever config/devbox-app.json names.)
+
+const path = require('path');
+const fs = require('fs');
+const express = require('express');
+
+const { buildGdsRouter } = require('./routes');
+const { attachFail } = require('./middleware/error-envelope');
+const metrics = require('./metrics');
+const gdsAuth = require('./auth');
+const { buildStampedHtml } = require('../asset-version');
+const { buildInfo } = require('../build-info');
+const { buildDevboxDownloads } = require('../devbox-downloads');
+const { buildBongosDownloads } = require('../bongos-downloads');
+const { clientBranding, branding } = require('../branding');
+const { clientModules, isModuleEnabled } = require('../modules');
+const { hallWidgetScripts, moduleWebSurfaces } = require('../module-loader/loader');
+const { resolveCoreRoot } = require('../instance-config');
+const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_API_PREFIXES } = require('./api-prefix');
+
+// ADR 0108 §1: every use of ROOT below (infra/ installers, modules/, docs/) is
+// core package content. resolveCoreRoot() returns the repo root today, so this
+// is byte-identical for the live instance.
+const ROOT = resolveCoreRoot();
+
+// Instance-only RELEASE config (config/devbox-app.json, config/bongos-cli.json) is
+// boundary-excluded from the portable core (publish-manifest INSTANCE_EXCLUDE), so a
+// vanilla self-host boot ships without it. Requiring it hard used to CRASH the boot
+// (task 1824). Guard the require so an absent config makes its download surface simply
+// not mount (fail-to-vanilla, like branding/modules) rather than take the server down.
+// A malformed config (JSON parse error, etc.) still throws — only a MISSING file is
+// tolerated. A branded instance that ships the config gets the routes exactly as before.
+function tryRequireConfig(relPath) {
+  try { return require(relPath); }
+  catch (e) { if (e && e.code === 'MODULE_NOT_FOUND') return null; throw e; }
+}
+
+// Map the pack's camelCase theme color keys → the kebab-case CSS custom
+// properties the hall/status stylesheets read (public-{builders,status}/style.css
+// :root). R57 (task 1196).
+const COLOR_VARS = {
+  bg: '--bg', bgCard: '--bg-card', bgDeep: '--bg-deep', bgFrame: '--bg-frame',
+  ink: '--ink', inkSoft: '--ink-soft', inkFaint: '--ink-faint',
+  rule: '--rule', ruleSoft: '--rule-soft',
+  accent: '--accent', accentDeep: '--accent-deep', sea: '--sea', terracotta: '--terracotta',
+};
+
+// Build the THEME markup for a served page from the client-safe pack's theme:
+// a <style> overriding the :root palette + font-family vars, the web-font <link>s,
+// and the favicon <link>. Returns '' when the pack carries no theme (so a pack
+// without a `theme.ui` block is a no-op and the stylesheet's own defaults stand).
+// The <style> is emitted so it lands AFTER the page's own stylesheet <link>
+// (which sits earlier in <head>) — equal specificity, later wins — making the
+// pack authoritative over style.css. For OTB the values equal style.css's
+// parchment defaults, so the render is byte-identical; a neutral instance gets
+// its plain palette + system fonts. R57 (task 1196, ADR 0062 §3).
+function themeMarkup(theme) {
+  if (!theme) return '';
+  const decls = [];
+  for (const [key, cssVar] of Object.entries(COLOR_VARS)) {
+    const v = theme.colors?.[key];
+    if (v) decls.push(`${cssVar}:${v};`);
+  }
+  if (theme.fonts?.display) decls.push(`--font-display:${theme.fonts.display};`);
+  if (theme.fonts?.body) decls.push(`--font-body:${theme.fonts.body};`);
+  let out = '';
+  for (const href of theme.fonts?.links || []) {
+    out += `<link rel="stylesheet" href="${href}">`;
+  }
+  // `backdrop` paints the page background (e.g. the Cloud Bongos sunrise gradient,
+  // ADR 0064 / R74) over the flat var(--bg); omitted packs (OTB) keep --bg.
+  const css = [];
+  if (decls.length) css.push(`:root{${decls.join('')}}`);
+  if (theme.backdrop) css.push(`body{background:${theme.backdrop};}`);
+  if (css.length) out += `<style>${css.join('')}</style>`;
+  if (theme.favicon) out += `<link rel="icon" href="${theme.favicon}">`;
+  return out;
+}
+
+// Inject the client-safe branding pack into a served HTML document (R56 task 1195
+// + R57 task 1196, ADR 0062 §3):
+//   * `window.__BRANDING__` — a synchronous global so every hall/status script
+//     reads instance strings (currency, identity, copy, rank labels) from config
+//     with NO fetch, NO race, NO flash-of-default.
+//   * the THEME markup — a :root palette/font override <style>, the web-font
+//     <link>s, and the favicon <link>, so the LOOK comes from config too.
+// Everything lands at the END of <head>: the script before any deferred page
+// script runs, and the theme <style>/favicon AFTER the page's own stylesheet so
+// the pack wins. Applied to the boot-time stamped HTML maps (the pack is a
+// boot-time singleton, computed once). Off-box surfaces that can't be
+// server-injected (the GitHub-Pages status page) read the same projection from
+// GET /api/gds/public/branding. Pure + exported for the unit test.
+function injectBrandingGlobal(html, brand = clientBranding(), mods = clientModules()) {
+  // window.__MODULES__ — the enabled feature-module set (R54 task 1193, ADR 0062
+  // §4), injected the same way as __BRANDING__ so hall/status scripts can hide
+  // UI sections for off modules synchronously (no fetch, no race). R60 wires the
+  // actual section-hiding; this exposes the data.
+  const stamped = applyBrandTokens(html, brand);
+  const tag = `${clientBundleScriptTag()}<script>window.__BRANDING__=${JSON.stringify(brand)};window.__MODULES__=${JSON.stringify(mods)};</script>${themeMarkup(brand.theme)}`;
+  return stamped.includes('</head>') ? stamped.replace('</head>', `${tag}</head>`) : tag + stamped;
+}
+
+// Server-side stamp of instance-identity TOKENS into served HTML (task 1705, ADR
+// 0062 §3). A page's static markup carries neutral placeholders instead of a
+// hardcoded host brand, and this replaces them at serve time with the instance's
+// own strings — so a non-OTB instance's <title>/copy render its own name, the
+// no-JS path still works (server-rendered, not client-stamped), and the source
+// stays brand-free (the fitness identity gate). Runs BEFORE the __BRANDING__
+// script is inserted; the injected JSON holds resolved values (never tokens), so
+// order is immaterial. Tokens: {{worldName}} {{productName}} {{currency}}
+// (lowercase label) {{Currency}} (Capitalized) {{publicOrigin}} (the apex origin,
+// for the one functional cross-instance link — sourced from the FULL pack's
+// domains, which clientBranding deliberately omits). Pure + exported for the test;
+// `origin` is injectable so the test drives it with zero I/O.
+function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOrigin()) {
+  const world = (brand.identity && brand.identity.worldName) || '';
+  const product = (brand.identity && brand.identity.productName) || '';
+  const cur = (brand.currency && brand.currency.label) || 'credits';
+  const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
+  return String(html == null ? '' : html)
+    .split('{{worldName}}').join(world)
+    .split('{{productName}}').join(product)
+    .split('{{Currency}}').join(Cur)
+    .split('{{currency}}').join(cur)
+    .split('{{publicOrigin}}').join(origin || '');
+}
+// The instance apex origin from the full branding pack (domains is server-only,
+// so it never rides clientBranding). Best-effort so a branding hiccup can't crash
+// serving.
+function safePublicOrigin() {
+  try { return branding().domains.publicOrigin || ''; } catch { return ''; }
+}
+// Instance product/world name for the API-discovery index (task 1918). Best-effort:
+// a branding hiccup must not break the JSON response.
+function safeProductName() {
+  try {
+    const b = branding();
+    return (b.identity && (b.identity.productName || b.identity.worldName)) || 'Cloud Bongos';
+  } catch { return 'Cloud Bongos'; }
+}
+
+// Apply injectBrandingGlobal across a whole stamped-HTML map ({ basename: html }).
+function injectBrandingInto(stamped, brand = clientBranding()) {
+  const out = {};
+  for (const [name, html] of Object.entries(stamped)) out[name] = injectBrandingGlobal(html, brand);
+  return out;
+}
+
+// The rendered API-docs page (task 1918) — public-docs/index.html wrapped with the
+// instance branding (title/theme/favicon), memoized once at boot like the apex
+// landing. '' when the instance ships no docs page (then /docs falls through to 404).
+let _docsHtml;
+function docsIndexHtml() {
+  if (_docsHtml === undefined) {
+    try {
+      _docsHtml = injectBrandingGlobal(fs.readFileSync(path.join(ROOT, 'public-docs/index.html'), 'utf8'));
+    } catch {
+      _docsHtml = '';
+    }
+  }
+  return _docsHtml;
+}
+
+// The browser-global build of the generated typed client (task 1996 / R09),
+// served at /lib/bongos-client.js so classic <script> web pages can consume the
+// same generated client the CLI uses (window.BongosClient). Read once at boot
+// from clients/bongos-client/bongos-client.global.js — the SAME committed file
+// the freshness test guards, so the browser can never drift from the spec. ''
+// (→ 404) if the build is somehow absent, so a missing file fails loudly per page.
+let _clientBundle;
+function clientBundleJs() {
+  if (_clientBundle === undefined) {
+    try {
+      _clientBundle = fs.readFileSync(path.join(ROOT, 'clients/bongos-client/bongos-client.global.js'), 'utf8');
+    } catch {
+      _clientBundle = '';
+    }
+  }
+  return _clientBundle;
+}
+
+// The <script> tag that loads the generated client on every internal page (task
+// 1996 / R09), content-hashed so a client change busts the browser/Cloudflare
+// cache exactly like the ?v= stamps on the hall's own scripts. Injected into
+// <head> by injectBrandingGlobal so window.BongosClient is defined before any
+// body-end page script runs. '' when the build is absent (pages then have no
+// client and fail loudly on first use, same as a missing script anywhere).
+let _clientBundleTag;
+function clientBundleScriptTag() {
+  if (_clientBundleTag === undefined) {
+    const js = clientBundleJs();
+    _clientBundleTag = js
+      ? `<script src="/lib/bongos-client.js?v=${require('node:crypto').createHash('sha256').update(js).digest('hex').slice(0, 8)}"></script>`
+      : '';
+  }
+  return _clientBundleTag;
+}
+
+// Inject each ENABLED module's hall-widget client <script> into the hall index HTML
+// (BV1.R75, ADR 0062 §4). The script must load BEFORE builders.js (which mounts the
+// registered widgets) but AFTER hall-widgets.js/dom-utils.js (which define the
+// registry) — so we insert just before the existing builders.js <script>. A disabled
+// module's widget is never injected (it vanishes); contributeHallWidget is the second
+// gate (it no-ops a widget whose module is off). `scripts` is the loader projection
+// [{ key, src }]; default reads the live enabled set. Pure + exported for the test.
+function injectModuleHallWidgets(html, scripts = hallWidgetScripts({ isEnabled: isModuleEnabled })) {
+  if (!Array.isArray(scripts) || scripts.length === 0) return html;
+  const tags = scripts
+    .map((s) => `<script src="${s.src}" defer></script>`)
+    .join('');
+  // Anchor on builders.js's <script> regardless of its ?v= stamp so the module
+  // widgets always land immediately before the consumer that mounts them.
+  const anchor = html.match(/<script src="\/builders\/builders\.js[^"]*"[^>]*><\/script>/);
+  if (anchor) return html.replace(anchor[0], tags + anchor[0]);
+  return html.includes('</body>') ? html.replace('</body>', `${tags}</body>`) : html + tags;
+}
+
+// Host-based routing. status.<apex> gets the public dashboard (served by the
+// status-ui MODULE's web surface, BV1.R84 — the generic webSurfaces loop below);
+// builders.<apex> gets the builder surface (served by the hall-ui MODULE's web
+// surface, BV1.R85 — its DEDICATED block below); the apex host gets the game
+// (server.js) or — on a game-less instance — a plain 404 (platform-server.js). All
+// share the same process + the same /api/gds/* surface (mounted host-agnostically
+// below). The prefix checks are apex-agnostic (any domain), so no brand string lives
+// here. isStatusHost + isBuildersHost stay the literal "status."/"builders."
+// predicates the entrypoints (server.js/platform-server.js) use to keep their apex
+// tail off those hosts; inside mountInternalSurfaces the GENERIC isModuleSurfaceHost
+// (any enabled GENERIC web-surface host) is used to skip the status-style surfaces,
+// while the builders host keeps its own isBuildersHost guard (it's served by the
+// richer dedicated block, not the generic loop).
+function isStatusHost(req) {
+  const host = (req.headers.host || '').toLowerCase().split(':')[0];
+  return host.startsWith('status.');
+}
+// A single-host instance — one with no dedicated builders.<apex> subdomain, e.g. a
+// co-located instance on a one-level subdomain like emersonian-circles.cloudbongos.com
+// (where free-plan TLS can't cover a two-level builders.<sub>.<apex>) — serves the hall
+// on its OWN configured buildersOrigin host. Treating that configured host as a builders
+// host makes the hall, not the apex landing, its front door (so /builders no longer
+// 301s to a builders.<host> that was never provisioned). Back-compat: an instance whose
+// buildersOrigin is the conventional builders.<apex> already matches the
+// startsWith('builders.') branch, so its routing is byte-identical; the second branch
+// only ever fires for an instance that deliberately points buildersOrigin at a
+// non-"builders." host (the configurable-root / hosting-module direction — ADR 0108,
+// tasks 1917/1485).
+function configuredBuildersHost() {
+  try {
+    const bo = (branding().domains || {}).buildersOrigin || '';
+    return bo ? new URL(bo).host.toLowerCase().split(':')[0] : '';
+  } catch { return ''; }
+}
+function isBuildersHost(req) {
+  const host = (req.headers.host || '').toLowerCase().split(':')[0];
+  if (host.startsWith('builders.')) return true;
+  const cfg = configuredBuildersHost();
+  return cfg !== '' && host === cfg;
+}
+
+// Mount the internal web surfaces onto `app`, in the exact order server.js used.
+// Call this ONCE, right after app setup (trust proxy etc.) and BEFORE any
+// entrypoint-specific tail (the game static + themed 404 in server.js; the plain
+// 404 in platform-server.js).
+function mountInternalSurfaces(app) {
+  // Prometheus instrumentation (task #1680, V4.R28a). The counting middleware
+  // mounts FIRST so it wraps every surface registered below (and, since
+  // mountInternalSurfaces runs before the game host blocks in server.js, the
+  // game routes too) — it records on res 'finish' regardless of which handler
+  // answers. The /metrics scrape endpoint is access-gated (loopback Prometheus
+  // or Bearer METRICS_TOKEN; see metrics.authorizeScrape).
+  app.use(metrics.httpMiddleware());
+  app.get('/metrics', metrics.metricsHandler());
+
+  // res.fail() decorator at the APP level (BV1 R04 / task 1991 / ADR 0116). The
+  // GDS router mounts its own attachFail, but a few app-level routes here (the
+  // /downloads/* redirect surface) also emit the error envelope via res.fail, and
+  // they run OUTSIDE that router — so decorate every response here too. Idempotent
+  // with the router's copy (it just re-installs the same method).
+  app.use(attachFail);
+
+  app.get('/healthz', (_req, res) => {
+    res.type('text/plain').send('ok');
+  });
+
+  // Deployed build info (#858, ADR 0042). Public + read-only — exposes the git
+  // commit the running process was deployed from, so ship.js's ci-mode deploy
+  // confirmation can commit-PIN (deployedCommit === mergeCommit) rather than only
+  // checking liveness via /healthz. Low-sensitivity (a public commit sha).
+  app.get('/version', (_req, res) => {
+    res.json(buildInfo());
+  });
+
+  // Generated typed client for classic <script> web pages (task 1996 / R09).
+  // Host-agnostic and registered early so it wins over the host-routed surface
+  // middleware; every internal surface (hall, status) can load window.BongosClient
+  // from this one path. A short max-age + the page-side ?v= query bust the cache
+  // on client updates (the bytes are content-stable per deploy).
+  app.get('/lib/bongos-client.js', (_req, res) => {
+    const js = clientBundleJs();
+    if (!js) return res.status(404).type('text/plain').send('// bongos-client bundle not found on the server');
+    res.type('application/javascript');
+    res.set('Cache-Control', 'public, max-age=300');
+    res.send(js);
+  });
+
+  // GDS API (game development system; renamed from PMS in V3.R01). See
+  // docs/adr/0010-pms-architecture.md and limitations/pms-v1-shipped.md for
+  // the historical context (when the surface was still /api/pms).
+  //
+  // The transitional /api/pms/* → /api/gds/* redirect surface was removed in
+  // V3.R01-followup (#308, 2026-05-13) after a repo audit confirmed no caller
+  // still hits the legacy path. Read-side back-compat for the `pms_session`
+  // cookie, the `PMS_GITHUB_*` env vars, and the `~/.config/otb/pms-session.json`
+  // file path continues to live in src/bongos/auth.js + scripts/gds/cli-lib.js —
+  // those are independent of the URL surface and protect existing local
+  // sessions during the rollout.
+  // Machine-discovery index (task 1918): a bare GET on the API root answers with a
+  // small JSON map to the contract (the rendered docs + the OpenAPI spec) instead
+  // of a 404 — so an AI agent or a curious client that hits the base path finds the
+  // reference on its own. CORS-open + no auth (it names only public locations).
+  //
+  // Dual-mount (task 1919): the router + this discovery index are mounted at the
+  // canonical API_PREFIX (/api/bongos) AND every LEGACY_API_PREFIXES entry
+  // (/api/gds) — the legacy alias stays FOREVER so shipped Dev Box binaries, the
+  // cached status mirror, and live boxes keep working (src/bongos/api-prefix.js). The
+  // SAME router instance is mounted at each path. Each discovery GET is registered
+  // BEFORE its router mount so the exact base-path GET wins; every other
+  // method/subpath falls through to the router.
+  const gdsRouter = buildGdsRouter();
+  const discoveryIndex = (req, res) => {
+    res.set('Access-Control-Allow-Origin', '*');
+    res.set('Cache-Control', 'public, max-age=300');
+    // Docs-discovery contract (ADR 0114): advertise the instance's doc surfaces —
+    // the hall (canonical doc-reading surface), the status page (outage fallback),
+    // and the public origin — sourced from branding().domains, so a second instance
+    // resolves its own surfaces with no hard-coded host. null when unset.
+    const domains = (() => { try { return branding().domains || {}; } catch { return {}; } })();
+    res.json({
+      name: `${safeProductName()} — Bongos API`,
+      api_base: API_PREFIX, // unversioned canonical alias — always resolves to the current version, never breaks
+      api_version: API_VERSION, // the explicit CONTRACT version (ADR 0117)
+      api_base_versioned: VERSIONED_API_PREFIX, // '/api/bongos/v1' — pin here for a stable contract
+      docs: '/docs',
+      openapi: '/docs/openapi.json',
+      reference: 'docs/api-reference.md',
+      hall: domains.buildersOrigin || null,
+      status: domains.statusOrigin || null,
+      public: domains.publicOrigin || null,
+      ranks: ['public', 'any-builder', 'metic+archon', 'archon'],
+      note: 'Ranks are enforced server-side per request (ADR 0016). Open /docs for the full reference. The unversioned base + /api/gds are permanent aliases pinned to the current version (ADR 0117).',
+    });
+  };
+  // Mount the router + discovery index at EVERY prefix, most-specific first
+  // (ALL_API_PREFIXES: /api/bongos/v1, then /api/bongos, then /api/gds) so the
+  // versioned path is matched before the bare one (BV1 R06 / ADR 0117). The SAME
+  // router serves all three — the unversioned + legacy paths are permanent aliases
+  // pinned to v1.
+  for (const prefix of ALL_API_PREFIXES) {
+    app.get(prefix, discoveryIndex);
+    app.use(prefix, gdsRouter);
+  }
+
+  // Dev Box desktop app downloads (#904, ADR 0045). Branded redirect surface:
+  // the installers live as release assets on the public releases repo (they
+  // can't ride the git deploy — see src/devbox-downloads.js), and these routes
+  // keep every builder-facing URL on the apex. Mounted right after the API and
+  // BEFORE the host shims so the same paths work on the apex AND on
+  // builders.<apex> (the builders rewrite shim below only prefixes non-/api
+  // paths, so without this placement /downloads/* would be rewritten to
+  // /builders/downloads/* and 404).
+  const devboxCfg = tryRequireConfig('../../config/devbox-app.json');
+  if (devboxCfg) {
+    const devboxDownloads = buildDevboxDownloads(devboxCfg);
+    app.get('/downloads/devbox/latest.json', (_req, res) => {
+      // Short TTL: a release bump (config change + deploy) is visible within a
+      // minute, same posture as the hall's HTML.
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json(devboxDownloads.latestJson());
+    });
+    // #924: the lightweight update-check endpoint the Dev Box app polls + the hall
+    // /settings courtesy line reads. MUST be registered before the `:target` route
+    // below, or Express would treat "version" as a download target and 404 it.
+    app.get('/downloads/devbox/version', (_req, res) => {
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json(devboxDownloads.versionJson());
+    });
+    app.get('/downloads/devbox/:target', (req, res) => {
+      const url = devboxDownloads.redirectFor(req.params.target);
+      if (!url) return res.fail('unknown_target', 404, { targets: Object.keys(devboxDownloads.latestJson().assets) });
+      res.set('Cache-Control', 'public, max-age=60');
+      res.redirect(302, url);
+    });
+  }
+
+  // Standalone `bongos` CLI downloads + the one-line installer (task 1248,
+  // V4.R81). Same off-repo release pattern as the Dev Box block above: the
+  // compiled per-platform binaries live as release assets on the public releases
+  // repo (config/bongos-cli.json → src/bongos-downloads.js), and these routes keep
+  // every user-facing URL on the apex. The installer scripts are served with the
+  // server's PINNED origin substituted for __GDS_API_BASE__ — never a request
+  // header, so a spoofed Host can't redirect a `curl | sh` (the box-connect.sh rule).
+  const bongosCfg = tryRequireConfig('../../config/bongos-cli.json');
+  if (bongosCfg) {
+    const bongosDownloads = buildBongosDownloads(bongosCfg);
+    // Pinned public origin for the served installer scripts (never a request header —
+    // a spoofed Host can't redirect a `curl | sh`). The fallback comes from the
+    // branding pack, not a hardcoded host brand (ADR 0062 §3).
+    const BONGOS_PUBLIC_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || branding().domains.publicOrigin;
+    const readBongosInstallScript = (name) => {
+      try {
+        return fs.readFileSync(path.join(ROOT, 'infra', name), 'utf8').split('__GDS_API_BASE__').join(BONGOS_PUBLIC_ORIGIN);
+      } catch { return null; }
+    };
+    app.get('/downloads/bongos/latest.json', (_req, res) => {
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json(bongosDownloads.latestJson());
+    });
+    app.get('/downloads/bongos/version', (_req, res) => {
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json(bongosDownloads.versionJson());
+    });
+    // The one-line installers — text/plain so `curl | sh` and `irm | iex` receive
+    // raw script bytes. Registered BEFORE the :target catch-all so their literal
+    // paths win (Express matches in registration order).
+    app.get('/downloads/bongos/install.sh', (_req, res) => {
+      const script = readBongosInstallScript('bongos-install.sh');
+      if (script == null) return res.status(404).type('text/plain').send('# bongos-install.sh not found on the server');
+      res.type('text/plain').send(script);
+    });
+    app.get('/downloads/bongos/install.ps1', (_req, res) => {
+      const script = readBongosInstallScript('bongos-install.ps1');
+      if (script == null) return res.status(404).type('text/plain').send('# bongos-install.ps1 not found on the server');
+      res.type('text/plain').send(script);
+    });
+    app.get('/downloads/bongos/:target', (req, res) => {
+      const url = bongosDownloads.redirectFor(req.params.target);
+      if (!url) return res.fail('unknown_target', 404, { targets: Object.keys(bongosDownloads.latestJson().assets) });
+      res.set('Cache-Control', 'public, max-age=60');
+      res.redirect(302, url);
+    });
+  }
+
+  // Module-contributed HOST-ROUTED web surfaces (BV1.R84, ADR 0093 §1 /
+  // 02-module-map §6). A module that owns a web surface declares
+  // contributes.webSurfaces:[{ host, dir }] and ships the static dir at
+  // modules/<key>/<dir>/; the loader's moduleWebSurfaces() resolves the enabled set
+  // to [{ key, host, dir(abs) }]. This GENERALIZES the former hardcoded status-host
+  // block (the surface that moved to modules/status-ui/ in BV1.R84): serve-internal
+  // serves each surface on its Host prefix with the SAME machinery the status page
+  // always used — the in-memory content-hash-
+  // stamped index (#521, defeats Cloudflare's 4h TTL) + the per-instance branding/
+  // theme injection — and falls through to an on-disk static handler for assets.
+  // The status dashboard (modules/status-ui/, host "status.") is served here; a
+  // disabled module's surface is never built here, so its host routes nowhere
+  // (server.js/platform-server.js then 404 it on the apex tail). No module key is
+  // named — the kernel stays module-agnostic (ADR 0083 §Decision #4).
+  //
+  // The HALL (modules/hall-ui/, host "builders.", BV1.R85) is itself a declared
+  // web-surface module, but it is NOT served by this GENERIC static loop — it has
+  // far richer serving (the apex /builders/* shim, the canonical-URL redirects,
+  // the citizen/Archon page gates, asset-stamping per page, and the module
+  // hall-widget injection) in its DEDICATED block below. So we PARTITION the
+  // resolved set on the builders-host predicate: the generic loop owns every
+  // surface EXCEPT the hall; the dedicated block owns the hall. The filter is on
+  // the host (isBuildersHost), not the "hall-ui" key, so the kernel still names no
+  // module key — a future surface that wants the generic treatment just declares a
+  // non-builders host. (The webSurfaces manifest declaration still makes the hall a
+  // loader-DISCOVERED module — it feeds the scope map, the fitness keys, docs, and
+  // window.__MODULES__; it is the dedicated serving below that reads the bytes.)
+  const buildersHostReq = (host) => ({ headers: { host } });
+  const allWebSurfaces = moduleWebSurfaces({ isEnabled: isModuleEnabled });
+  const webSurfaces = allWebSurfaces
+    .filter((s) => !isBuildersHost(buildersHostReq(s.host)))   // hall served by the dedicated block, not here
+    .map((s) => ({
+      key: s.key,
+      host: s.host,
+      static: express.static(s.dir, { extensions: ['html'], maxAge: '5m' }),
+      // Stamp + brand the index in memory at boot (a boot-time singleton, like the
+      // hall's). urlPrefix '/' because the surface is served at the host root.
+      html: injectBrandingInto(buildStampedHtml(s.dir, '/')),
+    }));
+  // True iff this request's Host matches a GENERIC module web surface (status-style,
+  // served by the loop below) — replaces the literal isStatusHost() guard the
+  // /builders middleware used, so those guards skip every generic surface host with
+  // zero hardcoded host string. The hall's own host is deliberately EXCLUDED (it was
+  // partitioned out above), so the dedicated /builders blocks below do NOT self-skip
+  // the builders host — they are what serves it.
+  function isModuleSurfaceHost(req) {
+    const host = (req.headers.host || '').toLowerCase().split(':')[0];
+    return webSurfaces.some((s) => host.startsWith(s.host));
+  }
+
+  app.use((req, res, next) => {
+    const host = (req.headers.host || '').toLowerCase().split(':')[0];
+    const surface = webSurfaces.find((s) => host.startsWith(s.host));
+    if (!surface) return next();
+    // /api/* already handled above; everything else on a surface host serves from
+    // the module's static dir. The index page comes from the stamped in-memory copy
+    // (asset ?v= = content hash); everything else falls through to the on-disk
+    // static handler.
+    if ((req.method === 'GET' || req.method === 'HEAD') &&
+        (req.path === '/' || req.path === '/index.html') &&
+        surface.html['index.html']) {
+      res.set('Cache-Control', 'public, max-age=60');
+      res.type('html');
+      return res.send(surface.html['index.html']);
+    }
+    return surface.static(req, res, next);
+  });
+
+  // builders.<apex> canonical-URL redirect (#744). On the subdomain the
+  // /builders prefix is redundant — the page lives at the root. Old links/bookmarks
+  // (and the legacy in-page hrefs) point at /builders[/<page>]; 301 them to the
+  // clean path so the address bar never shows ".../builders". PAGE paths only —
+  // the slug is [a-z0-9-]+ with no dot, so asset URLs the pages emit
+  // (/builders/style.css, /builders/*.js, /builders/diagrams/*.png) and the API
+  // (/api/gds/builders/*) never match and pass through to the shim below.
+  const BUILDERS_CANONICAL_RE = /^\/builders(?:\/([a-z0-9-]+))?\/?$/i;
+  app.use((req, res, next) => {
+    if (!isBuildersHost(req)) return next();
+    if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+    const m = req.path.match(BUILDERS_CANONICAL_RE);
+    if (!m) return next();
+    const qs = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+    return res.redirect(301, `/${m[1] || ''}${qs}`);  // /builders → /, /builders/watch → /watch
+  });
+
+  // builders.<apex> rewrite shim (#726). The dedicated builder subdomain serves
+  // the SAME surface as the main host's /builders/* tree, just rooted at "/".
+  // Rather than duplicate the serving + gating + asset-stamping logic below, this
+  // shim rewrites every non-API path on the builders host onto the existing
+  // /builders/* path so all of that logic is reused verbatim:
+  //   GET https://builders.<apex>/         → /builders/        (hall)
+  //   GET https://builders.<apex>/watch    → /builders/watch   (Archon)
+  //   GET https://builders.<apex>/settings → /builders/settings
+  //   GET https://builders.<apex>/builders/style.css → unchanged
+  // Paths already under /builders pass through untouched, so absolute asset URLs
+  // the pages emit (/builders/style.css, /builders/*.js) resolve on this host too.
+  app.use((req, res, next) => {
+    if (!isBuildersHost(req)) return next();
+    if (req.path.startsWith('/api/') || req.path === '/healthz') return next();
+    if (req.path === '/builders' || req.path.startsWith('/builders/')) return next();
+    // Prefix with /builders so the handlers below match. req.url carries the
+    // query string; preserve it. '/' → '/builders/', '/watch' → '/builders/watch'.
+    req.url = '/builders/' + req.url.replace(/^\/+/, '');
+    next();
+  });
+
+  // #739 (ADR 0036 cutover): the builder surface's canonical home is now the
+  // subdomain. On the apex/game host, redirect /builders and /builders/* to
+  // builders.<apex>/<rest> so old links keep working while the subdomain becomes
+  // the front door. Runs ONLY on the apex (skipped on the status + builders
+  // hosts; /api is host-agnostic and mounted earlier, and never starts /builders).
+  // 301 (permanent) — the cutover is proven live + verified end-to-end (#741;
+  // started as a 302 in #739). The URL fragment (#/task/N deep-links) is preserved
+  // by the browser across the redirect; the query string is carried explicitly.
+  // The redirect target apex is read from the request host (strip a leading
+  // "builders."/"status." if present) so it stays brand-agnostic.
+  app.use((req, res, next) => {
+    if (isModuleSurfaceHost(req) || isBuildersHost(req)) return next();
+    if (req.path !== '/builders' && !req.path.startsWith('/builders/')) return next();
+    const apex = (req.headers.host || '').toLowerCase().split(':')[0];
+    const rest = req.path.replace(/^\/builders\/?/, '');            // '/builders'→'', '/builders/watch'→'watch'
+    const qs = req.url.includes('?') ? req.url.slice(req.url.indexOf('?')) : '';
+    return res.redirect(301, `https://builders.${apex}/${rest}${qs}`);
+  });
+
+  // The /watch monitoring page and the /harbor dev-box management page (idea 257)
+  // and the /gate page (task 1179) are all Archon-only. Same server-side page
+  // gate, same posture: a non-Archon never receives the shell (requireArchonPage
+  // redirects a signed-in non-Archon to the hall, an unauthenticated visitor into
+  // sign-in). The subdomain shim above has already rewritten the bare
+  // /watch + /harbor + /gate onto /builders/*. (Defense in depth: every data
+  // endpoint these pages call is independently requireRank('archon').)
+  const WATCH_PAGE_RE = /^\/builders\/watch(?:\.html)?\/?$/;
+  const HARBOR_PAGE_RE = /^\/builders\/harbor(?:\.html)?\/?$/;
+  const GATE_PAGE_RE = /^\/builders\/gate(?:\.html)?\/?$/;
+  app.use((req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    if (!req.path.startsWith('/builders')) return next();
+    const norm = path.posix.normalize(req.path);
+    if (WATCH_PAGE_RE.test(norm) || HARBOR_PAGE_RE.test(norm) || GATE_PAGE_RE.test(norm)) {
+      return gdsAuth.requireArchonPage(req, res, next);
+    }
+    next();
+  });
+
+  // The /builders surface — authenticated single-page UI for active builders.
+  // Served from the hall-ui module's public/ dir (modules/hall-ui/public/, carved
+  // out of the repo-root public-builders/ in BV1.R85). The Caddy reverse-proxy
+  // passes the request through; this handler short-circuits before any entrypoint
+  // tail so /builders/* does not fall into the game's public/.
+  //
+  // This is the hall's DEDICATED serving — the richer twin of the generic
+  // web-surface loop above (which the hall is partitioned out of): the apex
+  // /builders/* shim, the canonical-URL redirects, the citizen/Archon page gates,
+  // per-page asset-stamping, and the module hall-widget injection all live here and
+  // read from BUILDERS_DIR. The module key is NOT named — the path is the
+  // hall-ui module's public dir, resolved once here.
+  //
+  // Auth is handled client-side: the page calls /api/gds/me; on 401 it redirects
+  // the browser to /api/gds/auth/web/start, which (per src/bongos/routes/auth.js)
+  // loops back to /builders with a gds_session cookie set.
+  const BUILDERS_DIR = path.join(ROOT, 'modules', 'hall-ui', 'public');
+  const buildersStatic = express.static(BUILDERS_DIR, {
+    extensions: ['html'],
+    setHeaders: (res, filePath) => {
+      if (/\.(html|js|json)$/.test(filePath)) {
+        res.setHeader('Cache-Control', 'public, max-age=60');
+      } else {
+        res.setHeader('Cache-Control', 'public, max-age=300');
+      }
+    },
+  });
+
+  // Task #521: content-hash the hall HTML pages' asset ?v= queries at boot, in
+  // memory. This is the durable fix for the stale-asset bug — a changed
+  // builders.js/style.css gets a new ?v= automatically, so browsers + Cloudflare
+  // fetch it fresh instead of serving the pre-deploy bytes for hours. Keyed by
+  // basename; the page-serving middleware below maps a request path to a file.
+  const buildersHtml = injectBrandingInto(buildStampedHtml(BUILDERS_DIR, '/builders/'));
+  // BV1.R75 (ADR 0062 §4): inject each enabled module's hall-widget client script
+  // into the hall index page so a module's contributed UI section appears. No-op when
+  // no enabled module ships one (the default today). Only the index hall carries the
+  // registry-driven <main>, so this targets index.html alone.
+  if (buildersHtml['index.html']) {
+    buildersHtml['index.html'] = injectModuleHallWidgets(buildersHtml['index.html']);
+  }
+
+  // Serve enabled modules' browser assets at /modules/<key>/public/* — the URL the
+  // loader's hallWidgetScripts projection points at. Mounted BEFORE the /builders
+  // static handler. Gated per-request on the live enabled set so a disabled module's
+  // assets 404 (defense in depth behind the no-injection above). Same Cache-Control
+  // posture as the hall's own scripts.
+  const MODULE_ASSET_RE = /^\/modules\/([a-z][a-z0-9-]*)\/public\/(.+)$/;
+  const MODULES_ROOT = path.join(ROOT, 'modules');
+  app.get(MODULE_ASSET_RE, (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    const m = req.path.match(MODULE_ASSET_RE);
+    const key = m[1];
+    let enabled = false;
+    try { enabled = isModuleEnabled(key); } catch { enabled = false; } // unknown key → not enabled
+    if (!enabled) return res.status(404).type('text/plain').send('not found');
+    // Normalize the asset sub-path to keep it inside modules/<key>/public.
+    const rel = path.posix.normalize(m[2]);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return res.status(404).type('text/plain').send('not found');
+    res.set('Cache-Control', 'public, max-age=60');
+    return res.sendFile(path.join(MODULES_ROOT, key, 'public', rel), (err) => {
+      if (err) { if (!res.headersSent) res.status(404).type('text/plain').send('not found'); }
+    });
+  });
+
+  // Resolve a /builders/* request path to a stamped HTML basename, mirroring
+  // express.static's `extensions: ['html']` resolution. Returns null for any
+  // path that isn't one of our HTML pages (assets, unknown paths) so it falls
+  // through to the static handler.
+  const BUILDERS_PAGE_RE = /^\/builders\/([a-z0-9-]+)(?:\.html)?\/?$/i;
+  // task 751: the task-detail page is the one hall page addressed by a SECOND
+  // path segment (an id) rather than a bare slug — /builders/task/:id — so it
+  // needs its own two-segment match ahead of the single-segment resolution
+  // below. Same gate tier as Work/Roadmap/Goals (SIGNEDIN_BUILDERS_PAGE_RE).
+  const TASK_DETAIL_PAGE_RE = /^\/builders\/task\/(\d+)\/?$/;
+  function buildersHtmlName(reqPath) {
+    if (reqPath === '/builders' || reqPath === '/builders/') return 'index.html';
+    if (TASK_DETAIL_PAGE_RE.test(reqPath)) return buildersHtml['task.html'] ? 'task.html' : null;
+    // e.g. /builders/ranks or /builders/ranks.html → ranks.html
+    const m = reqPath.match(BUILDERS_PAGE_RE);
+    if (m) {
+      const name = `${m[1].toLowerCase()}.html`;
+      if (buildersHtml[name]) return name;
+    }
+    return null;
+  }
+
+  // #488: server-side sign-in gate for the citizen primer + the system-maps.
+  // These pages — and their content assets (the primer markdown + the diagram
+  // PNGs) — are citizen-only: an unauthenticated request must NOT be served the
+  // file. Mounted BEFORE every /builders static handler below so the gate runs
+  // first; gdsAuth.requireBuilderPage redirects an unauthenticated request into
+  // the web sign-in flow instead of returning the content. This is the real
+  // access control (curl-proof / no-JS-proof) — the link-hiding in builders.js
+  // is only cosmetic.
+  //
+  // Scope is deliberately narrow: the hall index (/builders), the shared assets
+  // (style.css, *.js, fonts, cursors), the not-ready notice, and the sign-in flow
+  // itself stay PUBLIC so the landing card + GitHub button render for a stranger.
+  //
+  // Two tiers of gate (#770):
+  //   * NON-XENOS (Thetes+) — the orientation reading rooms (primer, diagrams).
+  //     A Xenos's path is action-only; an unauth visitor is sent to sign-in, a
+  //     Xenos to the friendly /builders/not-ready notice.
+  //   * ANY SIGNED-IN BUILDER — the Work Board, Roadmap, the Goals page, the
+  //     task-detail page, the Repo Atlas, the Dev Box pair page,
+  //     and Settings (#748, #904, task 1293, task 1757, task 751): a Xenos IS
+  //     allowed, but an unauthenticated visitor is bounced into sign-in rather
+  //     than served the page shell. Settings sits in THIS tier (not the
+  //     reading-room tier) because a newcomer needs it for first-time setup —
+  //     CLI re-auth (the "CLI Access" section) and choosing their craft both
+  //     live there (task 1291). It must still stay behind sign-in: it shows
+  //     personal prefs and mints CLI tokens.
+  // The link-hiding in builders.js is only cosmetic; these are the real gates.
+  const NONXENOS_BUILDERS_PAGE_RE =
+    /^\/builders\/(?:primer(?:\.md|\.html)?|diagrams(?:\.html)?)\/?$/;
+  const NONXENOS_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;
+  const SIGNEDIN_BUILDERS_PAGE_RE = /^\/builders\/(?:work|pair|settings|atlas|modules|goals|roadmap)(?:\.html)?\/?$/;
+  app.use((req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    // Cheap early-out: only /builders/* paths can ever be gated, so skip the
+    // work entirely for game / API / asset requests.
+    if (!req.path.startsWith('/builders')) return next();
+    // Match the NORMALIZED path. express.static (send) calls path.normalize on
+    // the sub-path before resolving the file, so '/builders//primer' and
+    // '/builders/./primer' both serve primer.html — but those raw forms slip
+    // past anchored regexes. Normalizing here (collapse '//', resolve './..')
+    // closes that bypass so the gate holds at the application layer, not just
+    // behind the proxy's path normalization.
+    const norm = path.posix.normalize(req.path);
+    if (NONXENOS_BUILDERS_PAGE_RE.test(norm) || NONXENOS_BUILDERS_PREFIX_RE.test(norm)) {
+      return gdsAuth.requireNonXenosPage(req, res, next);
+    }
+    if (SIGNEDIN_BUILDERS_PAGE_RE.test(norm) || TASK_DETAIL_PAGE_RE.test(norm)) {
+      return gdsAuth.requireBuilderPage(req, res, next);
+    }
+    next();
+  });
+
+  // V3.R13-followup-2 (#411): /builders/diagrams/ (with trailing slash) used to
+  // fall through to the game's catch-all because express.static can't resolve a
+  // directory request without an index. Redirect to /builders/diagrams (no slash)
+  // so the diagrams.html page actually renders. The no-slash form already works
+  // via the extensions: ['html'] resolution on buildersStatic.
+  //
+  // Implementation notes:
+  //   - REGEX route, not a string. With Express's default non-strict routing,
+  //     the string form '/builders/diagrams/' matches both '/.../diagrams' AND
+  //     '/.../diagrams/', which would cause a redirect loop. Anchoring with
+  //     ^…$ + a literal trailing slash gates the match to the with-slash form.
+  //   - Registered BEFORE the diagramsStatic wrapper below — that wrapper
+  //     mutates req.url for /builders/diagrams/* paths, which would prevent
+  //     this exact-path redirect from matching if it ran first.
+  app.get(/^\/builders\/diagrams\/$/, (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    res.redirect(301, '/builders/diagrams');
+  });
+
+  // task 1965: the read-only Task Board (/board, task 751) was consolidated into
+  // the Work page (/work) — the hall keeps one task-listing surface. 301 old
+  // bookmarks + deep-links (the apex /builders/board and the bare subdomain
+  // /board form, with or without a .html suffix) to the surviving Work page,
+  // preserving the /builders prefix and any query string.
+  app.get(/^(?:\/builders)?\/board(?:\.html)?\/?$/, (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    const prefix = req.path.startsWith('/builders') ? '/builders' : '';
+    const qi = req.url.indexOf('?');
+    const qs = qi >= 0 ? req.url.slice(qi) : '';
+    res.redirect(301, `${prefix}/work${qs}`);
+  });
+
+  // Onboarding diagram PNGs (V3.R76 #295) live in docs/onboarding/diagrams as the
+  // single source of truth alongside their Mermaid sources. Serve them here so the
+  // builders'-hall diagrams page can embed them without duplicating the binaries.
+  // Mounted before buildersStatic so /builders/diagrams/*.png resolves to docs/.
+  const diagramsStatic = express.static(path.join(ROOT, 'docs/onboarding/diagrams'), {
+    setHeaders: (res) => res.setHeader('Cache-Control', 'public, max-age=300'),
+  });
+  app.use((req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    if (req.path.startsWith('/builders/diagrams/')) {
+      req.url = req.url.replace(/^\/builders\/diagrams\/?/, '/') || '/';
+      return diagramsStatic(req, res, next);
+    }
+    next();
+  });
+
+  // Citizen's primer (V3.R13-followup #406) — the long-form reading source for
+  // the /builders/primer page. The canonical markdown lives at
+  // docs/onboarding/primer.md (single source of truth, also linked from the CLI
+  // nudges + the repo). Mounted as a single static file so primer.js can fetch
+  // and render it client-side without a build step. Same mount pattern as
+  // diagramsStatic above.
+  app.get('/builders/primer.md', (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    res.set('Cache-Control', 'public, max-age=300');
+    res.set('Content-Type', 'text/markdown; charset=utf-8');
+    res.sendFile(path.join(ROOT, 'docs/onboarding/primer.md'));
+  });
+
+  // Drachmae & karma reader (task 1472) — the builder-facing "how you get paid"
+  // doc. The canonical markdown lives at docs/onboarding/drachmae-and-karma.md
+  // (single source of truth, also linked from the primer + the repo); the
+  // /builders/drachmae page (drachmae.js + md-reader.js) fetches + renders it
+  // client-side. Same static-file mount pattern as primer.md above; public
+  // like the /ranks page — economy transparency, no sign-in gate.
+  app.get('/builders/drachmae-and-karma.md', (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    res.set('Cache-Control', 'public, max-age=300');
+    res.set('Content-Type', 'text/markdown; charset=utf-8');
+    res.sendFile(path.join(ROOT, 'docs/onboarding/drachmae-and-karma.md'));
+  });
+
+  // Rendered API docs (task 1918, BONGOS-V1). A self-describing OpenAPI 3.1 site
+  // at /docs — cloudbongos.com/docs is the advertised canonical URL, and it works
+  // on the apex of every instance (mounted in the SHARED surface, so a self-hosted
+  // Cloud Bongos is self-documenting for free). Served on the apex host; the
+  // status./builders. module hosts skip it (isModuleSurfaceHost). The renderer
+  // (Redoc) + the generated spec are vendored/generated static assets — no CDN, no
+  // external fetch (matches the /vendor/* self-hosting convention; CSP-safe).
+  //   GET /docs                    → the Redoc host page (branding-injected)
+  //   GET /docs/redoc.standalone.js → the vendored renderer (long-cached)
+  //   GET /docs/openapi.json        → the generated spec (CORS-open so Postman/Swagger/AI can fetch it)
+  app.get('/docs', (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    const html = docsIndexHtml();
+    if (!html) return next(); // instance ships no docs page → fall through to 404
+    res.set('Cache-Control', 'public, max-age=60');
+    res.type('html');
+    res.send(html);
+  });
+  app.get('/docs/redoc.standalone.js', (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    res.set('Cache-Control', 'public, max-age=86400');
+    res.type('application/javascript');
+    res.sendFile(path.join(ROOT, 'public-docs/redoc.standalone.js'));
+  });
+  app.get('/docs/openapi.json', (req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    res.set('Access-Control-Allow-Origin', '*'); // read-only spec — tools fetch it cross-origin
+    res.set('Cache-Control', 'public, max-age=60');
+    res.type('application/json');
+    res.sendFile(path.join(ROOT, 'docs/api/openapi.json'));
+  });
+
+  app.use((req, res, next) => {
+    if (isModuleSurfaceHost(req)) return next();
+    if (req.path === '/builders' || req.path.startsWith('/builders/')) {
+      // Serve HTML pages from the stamped in-memory copy (asset ?v= = content
+      // hash). Gated pages (primer, diagrams) have already passed the sign-in
+      // gate above before reaching here. Everything else (js/css/png/json,
+      // unknown paths) falls through to the on-disk static handler.
+      if (req.method === 'GET' || req.method === 'HEAD') {
+        const htmlName = buildersHtmlName(req.path);
+        if (htmlName) {
+          res.set('Cache-Control', 'public, max-age=60');
+          res.type('html');
+          return res.send(buildersHtml[htmlName]);
+        }
+      }
+      // Strip the /builders prefix so index.html resolves at the root.
+      req.url = req.url.replace(/^\/builders\/?/, '/') || '/';
+      return buildersStatic(req, res, next);
+    }
+    next();
+  });
+
+  return app;
+}
+
+module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens };